Rust Things3

🦀 Rust Things

A high-performance Rust library and CLI for Things 3 integration with integrated MCP (Model Context Protocol) server support for AI/LLM environments.

📦 Version 1.0.0 - Production Ready!

[](https://github.com/GarthDB/rust-things3/actions/workflows/ci.yml) [](https://codecov.io/gh/GarthDB/rust-things3) [](https://crates.io/crates/things3-cli) [](https://opensource.org/licenses/MIT) [](https://www.rust-lang.org) [](RELEASE_NOTES.md)

✨ Features

• 🚀 High Performance: Built with Rust for maximum speed and reliability
• 🔧 CLI Tool: Command-line interface for managing Things 3 data
• 🤖 MCP Integration: Integrated MCP server for AI/LLM integration
• 📊 Safe Integration: Reads via async SQLx, mutations via AppleScript (per CulturedCode guidelines)
• 🏗️ Moon Workspace: Organized monorepo with Moon build system
• 🧪 Well Tested: Comprehensive test suite and benchmarks
• 📈 Performance Monitoring: Built-in metrics and system monitoring
• 💾 Caching Layer: High-performance caching with Moka
• 🔄 Backup & Restore: Complete backup system with metadata
• 📤 Data Export: Multiple formats (JSON, CSV, OPML, Markdown)
• 🔧 Advanced MCP Tools: 17 tools for AI/LLM integration
• ⚡ Async Database: SQLx-powered async database operations with thread safety
• 🌐 Web Servers: Health check and monitoring dashboard servers

🚀 Installation

Homebrew (macOS)

# Add the tap (when available)
brew tap GarthDB/rust-things3

# Install
brew install things3-cli

Cargo (Rust)

# Install from crates.io (when published)
cargo install things3-cli --features mcp-server

# Or install from source
cargo install --path apps/things3-cli --features mcp-server

> After upgrading: cargo install replaces the binary on disk, but any > running MCP server process still uses the old in-memory binary. Restart the > process (or your editor/agent host) after upgrading so the new version is > loaded. You can verify the running version with things3 --version.

From Source

git clone https://github.com/GarthDB/rust-things3
cd rust-things3
cargo build --release

# Add to PATH
export PATH="$PWD/target/release:$PATH"

Using Moon (Development)

# Install Moon if you haven't already
curl -fsSL https://moonrepo.dev/install | bash

# Clone and setup
git clone https://github.com/GarthDB/rust-things3
cd rust-things3
moon run :dev-pipeline

⚙️ Feature Flags

New in 1.0.0: Modular compilation with feature flags! Choose only what you need.

Library (things3-core)

[dependencies]
# Minimal (core functionality only - 24% smaller binary)
things3-core = { version = "1.0", default-features = false }

# With specific features
things3-core = { version = "1.0", features = ["export-csv", "observability"] }

# Full features (recommended for most users)
things3-core = { version = "1.0", features = ["full"] }

Available Features:

• export-csv: CSV export support
• export-opml: OPML export support
• observability: Metrics, tracing, and health checks
• full: Enable all features
• test-utils: Testing utilities (development only)

CLI (things3-cli)

[dependencies]
# CLI with all features
things3-cli = { version = "1.0", features = ["full"] }

# CLI with specific features
things3-cli = { version = "1.0", features = ["mcp-server", "export-csv"] }

Additional CLI Features:

• mcp-server: MCP server functionality (requires export features)

📚 See [FEATURES.md](docs/FEATURES.md) for detailed feature documentation and compatibility matrix.

📖 Quick Start

Get started in under 5 minutes! See the [Quick Start Guide](docs/QUICKSTART.md) for detailed instructions.

Basic Library Usage

use things3_core::{ThingsDatabase, ThingsError};

#[tokio::main]
async fn main() -> Result {
    // Connect to database
    let db_path = things3_core::get_default_database_path();
    let db = ThingsDatabase::new(&db_path).await?;
    
    // Get inbox tasks
    let tasks = db.get_inbox(Some(10)).await?;
    for task in tasks {
        println!("- {}", task.title);
    }
    
    // Search for tasks
    let results = db.search_tasks("meeting").await?;
    println!("Found {} matching tasks", results.len());
    
    Ok(())
}

CLI Commands

# Show help
things3 --help

# Health check
things3 health

# Show inbox tasks
things3 inbox
things3 inbox --limit 5

# Show today's tasks
things3 today
things3 today --limit 3

# Show all projects
things3 projects
things3 projects --area 

# Show all areas
things3 areas

# Search for tasks
things3 search "meeting"
things3 search "report" --limit 10

# Start MCP server (for AI/LLM integration)
things3 mcp

# Start health check server
things3 health-server --port 8080

# Start monitoring dashboard
things3 dashboard --port 8081

Environment Variables

# Set custom database path
export THINGS_DB_PATH="/path/to/things.db"

# Enable fallback to default path
export THINGS_FALLBACK_TO_DEFAULT=true

# Enable verbose logging
export RUST_LOG=debug

🌐 Web Servers

The CLI includes built-in web servers for monitoring and health checks:

Health Check Server

# Start health check server
things3 health-server --port 8080

# Test health endpoint
curl http://localhost:8080/health
curl http://localhost:8080/ping

Monitoring Dashboard

# Start monitoring dashboard
things3 dashboard --port 8081

# Access dashboard
open http://localhost:8081

The dashboard provides:

• Real-time metrics and statistics
• Database health monitoring
• Performance metrics
• System resource usage
• Task and project analytics

🤖 MCP Integration

The MCP (Model Context Protocol) server provides 46 tools for AI/LLM integration. Common tools:

Available MCP Tools

| Tool | Description | |------|-------------| | get_inbox | Get tasks from the inbox | | get_today | Get tasks scheduled for today | | get_projects | Get all projects, optionally filtered by area | | get_areas | Get all areas | | search_tasks | Search for tasks by title or notes | | create_task | Create a new task | | update_task | Update an existing task | | complete_task | Mark a task as completed | | delete_task | Soft delete a task | | get_productivity_metrics | Get productivity metrics | | export_data | Export data in various formats | | bulk_create_tasks | Create multiple tasks at once | | bulk_complete | Complete multiple tasks at once | | bulk_move | Move multiple tasks to a project or area | | get_recent_tasks | Get recently modified tasks | | backup_database | Create a database backup | | restore_database | Restore from a backup (requires --unsafe-direct-db) | | list_backups | List available backups | | get_performance_stats | Get performance statistics | | get_system_metrics | Get system resource metrics | | get_cache_stats | Get cache performance stats |

See [skills/things3/references/TOOLS.md](skills/things3/references/TOOLS.md) for the full 46-tool catalog.

Configuration

Cursor

// .cursor/mcp.json
{
  "mcpServers": {
    "things3": {
      "command": "things3",
      "args": ["mcp"],
      "env": {
        "THINGS_DB_PATH": "/path/to/things.db"
      }
    }
  }
}

VS Code

// .vscode/mcp.json
{
  "servers": {
    "things3": {
      "type": "stdio",
      "command": "things3",
      "args": ["mcp"],
      "cwd": "${workspaceFolder}",
      "env": {
        "THINGS_DB_PATH": "/path/to/things.db"
      }
    }
  }
}

Zed

// .zed/settings.json
{
  "mcp": {
    "things3": {
      "command": "things3",
      "args": ["mcp"],
      "env": {
        "THINGS_DB_PATH": "/path/to/things.db"
      }
    }
  }
}

Use with Claude Code / your AI agent

rust-things3 ships agent skills that let you drive Things 3 directly from Claude Code, Claude Desktop, Cursor, Zed, and any other agentskills.io-compatible host.

| Skill | What it does | |-------|-------------| | /things3 | MCP setup + full tool catalog | | /things3-daily-review | Read-only daily review — today's tasks, inbox, overdue items |

See [skills/README.md](skills/README.md) for install instructions and the full catalog.

Documentation

Getting Started

• [Quick Start Guide](docs/QUICKSTART.md) - Get started in under 5 minutes
• [User Guide](docs/USER_GUIDE.md) - Comprehensive usage guide
• [Error Handling Guide](docs/ERROR_HANDLING.md) - Error handling patterns and recovery strategies

Release Documentation (1.0.0)

• [Release Notes](RELEASE_NOTES.md) - What's new in 1.0.0
• [Migration Guide](docs/MIGRATION.md) - Upgrade from 0.x to 1.0.0
• [Feature Flags Guide](docs/FEATURES.md) - Modular compilation with feature flags
• [Security Audit](docs/SECURITY_AUDIT.md) - Security audit results
• [Post-1.0 Roadmap](docs/POST1.0ROADMAP.md) - Future development plans
• [Changelog](CHANGELOG.md) - Complete version history

Core Documentation

• [Architecture](docs/ARCHITECTURE.md) - System design and component overview
• [MCP Integration](docs/MCP_INTEGRATION.md) - Complete MCP server guide
• [Reliability Guide](docs/RELIABILITY.md) - Connection pooling, error recovery, and resilience patterns
• [Performance Guide](docs/PERFORMANCE.md) - Benchmarks and optimization strategies
• [Database Schema](docs/DATABASE_SCHEMA.md) - Things 3 database structure
• [Development Guide](docs/DEVELOPMENT.md) - Setup and development workflow
• [Coverage Analysis](docs/COVERAGE_ANALYSIS.md) - Test coverage report

Examples

Basic Examples

See the [libs/things3-core/examples/](libs/things3-core/examples/) directory for practical usage examples:

• basic_usage.rs - Basic database operations (connect, query, create, update)
• bulk_operations.rs - Bulk operation examples (move, complete, delete)
• search_tasks.rs - Advanced search functionality
• export_data.rs - Data export in multiple formats (JSON, CSV, Markdown)

cargo run --package things3-core --example basic_usage
cargo run --package things3-core --example bulk_operations
cargo run --package things3-core --example search_tasks
cargo run --package things3-core --example export_data

Integration Examples (New in 1.0.0)

Real-world integration patterns in [examples/integration/](examples/integration/):

• mcp_client.rs - Custom MCP client implementation
• cli_extension.rs - Extending the CLI with custom commands
• web_api.rs - REST API with Axum web framework
• background_service.rs - Long-running service with graceful shutdown
• custom_middleware.rs - Custom middleware for cross-cutting concerns

cd examples/integration
cargo run --example mcp_client
cargo run --example cli_extension -- today
cargo run --example web_api
cargo run --example background_service
cargo run --example custom_middleware

See [examples/integration/README.md](examples/integration/README.md) for detailed documentation.

API Documentation

Generate and view API documentation:

cargo doc --workspace --no-deps --open

Testing

Test Coverage

• Total Tests: 438 tests
• Coverage: ~85%+ (target: 85%+)
• Test Categories:
• Database operations (Phase 1)
• MCP I/O layer (Phase 2)
• Middleware chain (Phase 3)
• Observability system (Phase 4)

Running Tests

# All tests
cargo test --workspace

# Specific package
cargo test --package things3-core

# With coverage
cargo llvm-cov --workspace --all-features --html
open target/llvm-cov/html/index.html

Running live AppleScript tests (macOS only)

The AppleScriptBackend integration tests drive a real Things 3 install through osascript. They are gated and ignored by default — cargo test on CI / Linux / a Mac without Things 3 will not run them.

Prerequisites:

• macOS with Things 3 installed.
• The first invocation triggers the macOS Automation permission prompt

("rust-things3 wants to control Things3"). Grant it via System Settings → Privacy & Security → Automation, or the tests will fail with a clear permission-denied error.

Run with:

THINGS3_LIVE_TESTS=1 cargo test -p things3-core --test applescript_live \
    -- --ignored --test-threads=1

--test-threads=1 is required: every test mutates the single shared Things 3 instance, and concurrent runs would race. Each test creates entities with a unique rust-things3 e2e {ts}-{uuid}-style title and deletes them on completion (a Drop guard ensures cleanup even on panic). For background on why the project uses AppleScript instead of writing the SQLite database directly, see CulturedCode's safety article.

See [Development Guide](docs/DEVELOPMENT.md) for more testing details.

Development

Prerequisites

• Rust 1.70+
• Moon (for workspace management)
• Things 3 (for testing)
• cargo-llvm-cov (for coverage)

Setup

# Clone the repository
git clone https://github.com/GarthDB/rust-things3
cd rust-things3

# Install dependencies
moon run :local-dev-setup

# Run tests
moon run :test-all

# Run development pipeline
moon run :dev-pipeline

Quick Commands

# Format code
cargo fmt --all

# Lint code
cargo clippy --workspace -- -D warnings

# Run coverage
cargo llvm-cov --workspace --all-features --html

# Generate docs
cargo doc --workspace --no-deps

See [Development Guide](docs/DEVELOPMENT.md) for comprehensive development information.

Project Structure

rust-things3/
├── apps/
│   └── things3-cli/       # CLI application with MCP server
├── libs/
│   ├── things3-core/      # Core library
│   └── things3-common/    # Shared utilities
├── tools/
│   └── xtask/             # Development tools
└── tests/                 # Integration tests

API Reference

Core Library

Basic Usage

use things3_core::{ThingsDatabase, Task, Project, Area, ThingsConfig};
use anyhow::Result;

#[tokio::main]
async fn main() -> Result {
    // Create database connection with SQLx
    let db = ThingsDatabase::new("/path/to/things.db").await?;
    
    // Get inbox tasks
    let tasks = db.get_inbox(Some(10)).await?;
    
    // Get today's tasks
    let today_tasks = db.get_today(None).await?;
    
    // Get all projects
    let projects = db.get_projects(None).await?;
    
    // Search tasks
    let search_results = db.search_tasks("meeting").await?;
    
    Ok(())
}

Advanced Configuration

use things3_core::{ThingsDatabase, ThingsConfig};
use std::path::Path;

// Custom database path with SQLx
let db = ThingsDatabase::new(Path::new("/custom/path/to/things.db")).await?;

// From environment variables
let config = ThingsConfig::from_env();
let db = ThingsDatabase::new(&config.database_path).await?;

Error Handling

use things3_core::{ThingsDatabase, ThingsError};
use anyhow::Result;

async fn handle_errors() -> Result {
    let db = ThingsDatabase::new("/path/to/things.db").await?;
    
    match db.get_inbox(Some(5)).await {
        Ok(tasks) => println!("Found {} tasks", tasks.len()),
        Err(ThingsError::Database(msg)) => {
            eprintln!("Database error: {}", msg);
        }
        Err(e) => {
            eprintln!("Other error: {}", e);
        }
    }
    
    Ok(())
}

Caching and Performance

use things3_core::{ThingsDatabase, CacheConfig};
use std::time::Duration;

// Configure caching
let cache_config = CacheConfig {
    max_capacity: 1000,
    time_to_live: Duration::from_secs(300),
    time_to_idle: Duration::from_secs(60),
};
let db = ThingsDatabase::with_cache_config(cache_config)?;

// Get cache statistics
let stats = db.get_cache_stats()

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [GarthDB](https://github.com/GarthDB)
- **Source:** [GarthDB/rust-things3](https://github.com/GarthDB/rust-things3)
- **License:** MIT

Install and usage instructions live in the source repository linked above.