🦀 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!

✨ 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
• 📊 Comprehensive API: Full access to Things 3 database with async SQLx
• 🏗️ 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

# Or install from source
cargo install --git https://github.com/GarthDB/rust-things3

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 for detailed feature documentation and compatibility matrix.

📖 Quick Start

Get started in under 5 minutes! See the Quick Start Guide for detailed instructions.

Basic Library Usage

use things3_core::{ThingsDatabase, ThingsError};

#[tokio::main]
async fn main() -> Result<(), ThingsError> {
    // 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 <AREA_UUID>

# 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 21 tools for AI/LLM integration:

Available MCP Tools

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"
      }
    }
  }
}

Documentation

Getting Started

• Quick Start Guide - Get started in under 5 minutes
• User Guide - Comprehensive usage guide
• Error Handling Guide - Error handling patterns and recovery strategies

Release Documentation (1.0.0)

• Release Notes - What's new in 1.0.0
• Migration Guide - Upgrade from 0.x to 1.0.0
• Feature Flags Guide - Modular compilation with feature flags
• Security Audit - Security audit results
• Post-1.0 Roadmap - Future development plans
• Changelog - Complete version history

Core Documentation

• Architecture - System design and component overview
• MCP Integration - Complete MCP server guide
• Reliability Guide - Connection pooling, error recovery, and resilience patterns
• Performance Guide - Benchmarks and optimization strategies
• Database Schema - Things 3 database structure
• Development Guide - Setup and development workflow
• Coverage Analysis - Test coverage report

Examples

Basic Examples

See the 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/:

• 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 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

See Development Guide 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 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().await?;
println!("Cache hits: {}, misses: {}", stats.hits, stats.misses);

Data Export

use things3_core::{DataExporter, ExportFormat, ExportConfig};

// Export to JSON
let exporter = DataExporter::new_default();
let json_data = exporter.export_json(&tasks, &projects, &areas).await?;

// Export to CSV
let csv_data = exporter.export_csv(&tasks, &projects, &areas).await?;

// Custom export configuration
let config = ExportConfig {
    include_completed: false,
    date_format: "%Y-%m-%d".to_string(),
    time_format: "%H:%M:%S".to_string(),
};
let exporter = DataExporter::new(config);

MCP Server Integration

use things3_cli::mcp::{ThingsMcpServer, CallToolRequest};
use serde_json::json;

// Create MCP server
let server = ThingsMcpServer::new(config)?;

// List available tools
let tools = server.list_tools().await?;
println!("Available tools: {:?}", tools.tools);

// Call a tool
let request = CallToolRequest {
    name: "get_inbox".to_string(),
    arguments: Some(json!({
        "limit": 10
    })),
};
let result = server.call_tool(request).await?;

CLI Library

use things3_cli::{Cli, Commands, print_tasks, print_projects};
use std::io::stdout;

// Parse CLI arguments
let cli = Cli::parse();

// Use CLI functions programmatically
match cli.command {
    Commands::Inbox { limit } => {
        let tasks = db.get_inbox(limit).await?;
        print_tasks(&mut stdout(), &tasks)?;
    }
    Commands::Projects { area_uuid, limit } => {
        let projects = db.get_projects(area_uuid, limit).await?;
        print_projects(&mut stdout(), &projects)?;
    }
    // ... other commands
}

Common Utilities

use things3_common::utils::{
    get_default_database_path,
    format_date,
    format_datetime,
    parse_date,
    is_valid_uuid,
    truncate_string
};

// Get default database path
let db_path = get_default_database_path();
println!("Default path: {}", db_path.display());

// Format dates
let formatted = format_date(chrono::Utc::now().date_naive());
println!("Today: {}", formatted);

// Parse dates
let date = parse_date("2024-01-15")?;
println!("Parsed date: {}", date);

// Validate UUIDs
let is_valid = is_valid_uuid("550e8400-e29b-41d4-a716-446655440000");
println!("Valid UUID: {}", is_valid);

// Truncate strings
let truncated = truncate_string("Very long string", 10);
println!("Truncated: {}", truncated);

Architecture

The project is organized as a Moon-managed Rust workspace:

rust-things3/
├── apps/things3-cli/      # CLI application with MCP server
├── libs/things3-core/     # Core database and business logic
├── libs/things3-common/   # Shared utilities
├── examples/              # Usage examples
├── docs/                  # Documentation
└── tests/                 # Integration tests

Key features:

• Async-first: Built on Tokio for concurrent operations
• Type-safe: SQLx for compile-time SQL verification
• MCP Protocol: Industry-standard AI agent communication
• Middleware: Extensible request/response processing
• Observability: Built-in metrics, logging, and tracing

See Architecture Documentation for detailed system design.

Troubleshooting

Database Not Found

# Find your Things 3 database
find ~/Library/Group\ Containers -name "main.sqlite" 2>/dev/null

# Set custom path
export THINGS_DB_PATH="/path/to/main.sqlite"

Permission Issues

Ensure Things 3 is closed when running the CLI:

killall Things3

Test Failures

Run tests single-threaded if experiencing database lock issues:

cargo test -- --test-threads=1

See Development Guide for more troubleshooting tips.

Contributing

We welcome contributions! Please see our Contributing Guidelines for detailed information on:

• Development setup
• Code style guidelines
• Testing requirements
• Pull request process
• Issue reporting

Quick Start

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests (maintain 85%+ coverage)
5. Run the development pipeline: moon run :dev-pipeline
6. Submit a pull request

For more details, see CONTRIBUTING.md and Development Guide.

License

MIT License - see LICENSE file for details.

Acknowledgments

• Inspired by things3
• Built with Moon workspace management
• Follows evelion-apps/things-api patterns