MCP Abstraction Layer for Cultured Task Management (Things3)

This package establishes a sophisticated MCP gateway, offering granular remote control over the Things3 task ecosystem. It translates standard MCP directives into secure, robust AppleScript calls, managing the creation, modification, and querying of to-dos and organizational containers (Projects).

Core Functionality

This bridge guarantees idempotent operations and secure data transmission using proper URI encoding.

Project Lifecycle Management: Full capacity to instantiate new organizational groupings within Things3.
Task Definition: Detailed creation of actionable items, supporting comprehensive metadata like deadlines, scheduling hints, descriptive narratives, assigned labels (tags), and sub-task enumerations (checklists).
Information Retrieval: Mechanisms to fetch current states from the Inbox, the 'Today' view, or across the entire project hierarchy.
State Modification: Ability to finalize tasks (mark as complete) via title-based lookup.
Intelligent Discovery: Efficient searching across all managed items based on keyword matching in titles or content.
Resilience: Advanced logging and systematic error recovery mechanisms.

Deployment Instructions

Requirements

Ensure the following dependencies are met prior to launching the synchronization agent: 1. A functional macOS environment hosting the native Things3 application. 2. A Python runtime environment (version 3.8 or newer). 3. Things3 must be active to permit real-time manipulation via scripting interfaces.

Installation Sequence

Acquire the repository source code: bash git clone cd mcp-things3
Install via editable package management: bash pip install -e .
The service executable will be accessible as mcp-server-things3.

Exposed MCP Operations

Querying Interfaces

`query-inbox-items`

Retrieves every pending action residing in the default Things3 Inbox. - Arguments: Zero required arguments. - Output: A serialized collection of Inbox entries, including scheduling data.

`enumerate-client-containers`

Lists all defined organizational structures (Projects) currently present in Things3. - Arguments: None. - Output: A structured list detailing every project's unique identifier and label.

`fetch-daily-actions`

Pulls the complete roster of items slated for execution on the present calendar day. - Arguments: None. - Output: A manifest of today's assignments with associated metadata.

Construction Interfaces

`establish-new-grouping`

Instantiates a new top-level project container. - Mandatory Fields: title (Textual identifier) - Optional Attributes: - narrative (Descriptive text) - domain (Associated organizational sphere/area) - start_date (Initiation timeframe) - due_date (Hard completion target) - labels (Collection of associated keywords/tags)

Data Schema Example:

{ "title": "Enterprise Software Upgrade Plan", "domain": "Operations", "due_date": "2024-03-15", "labels": ["critical", "deployment"] }

`inject-new-action-item`

Registers an atomic task within the Things3 environment. - Mandatory Fields: title (Primary action description) - Optional Attributes: - details (Extended notes) - scheduled_for (Start date/time hint) - hard_deadline (Final due date) - subtasks (Array of nested obligations) - keywords (Tag set) - parent_context (The project or area under which this action belongs) - subgroup (Section heading within the parent structure)

Data Schema Example:

{ "title": "Validate security audit reports", "parent_context": "Enterprise Software Upgrade Plan", "hard_deadline": "2024-02-20", "keywords": ["compliance", "security"], "subtasks": ["Review firewall logs", "Test penetration vectors", "Document findings"] }

Revision Interfaces

`finalize-task-execution`

Marks a specific item as successfully concluded, based on pattern matching against its title. - Mandatory Fields: title (Textual clue for identification) - Result: Confirmation or denial of operation.

Data Schema Example:

{ "title": "Validate security audit reports" }

`scan-task-inventory`

Performs a textual search across all indexed titles and contents. - Mandatory Fields: query (The string fragment to locate) - Result: A subset of items matching the search criteria, including their current status.

Data Schema Example:

{ "query": "budget review" }

Integration Notes for Conversational AI (Claude)

This server enables sophisticated, natural-language task orchestration with Things3. Examples of supported commands:

"Establish a new initiative named 'Year-End Reporting' due by December 1st."
"Add an assignment to the 'Reporting' project requiring me to compile expense summaries, including a sub-step to verify receipts."
"Display everything scheduled for the next seven days."
"Mark the item titled 'Finalize Q4 presentation' as complete."

Configuration Schema (MCP Client)

To enable this capability, update your client configuration file:

{ "mcpServers": { "things3_bridge": { "command": "mcp-server-things3", "args": [] } } }

System Architecture

Key Modules

server.py: Contains the main application logic and the MCP tool definitions.
applescript_handler.py: Dedicated module for safe, context-aware execution of AppleScript commands.
Data Transport: Strict adherence to encoding standards (x-callback-url conventions) for parameter passing.