Things MCPB - Claude Desktop Extension

Note: This is a fork of mbmccormick/things-mcpb with additional features and improvements.

A comprehensive Claude Desktop Extension that provides seamless integration with Things 3, enabling you to manage your complete task workflow directly from Claude conversations using AppleScript via secure JavaScript for Automation (JXA).

Fork Improvements

This fork adds the following enhancements over the original:

• Enhanced When Parameter: Support for today, tomorrow, evening, anytime, someday keywords
• Delete Operations: delete_todo, delete_project, empty_trash for complete lifecycle management
• Move Todo: move_todo to relocate todos between projects, areas, and lists
• Tag Management: get_unused_tags and delete_tag for tag cleanup
• Area CRUD: Full area management with add_area, update_area, delete_area
• Additional Tests: Unit tests for new features

Download

⬇️ Download Latest Release

Quick Start

1. Install Dependencies: npm install
2. Run Tests: npm test (optional but recommended)
3. Package Extension: mcpb pack .
4. Install in Claude Desktop: Follow Claude Desktop's extension installation process
5. Launch Things 3: Ensure Things 3 is running before using commands

💡 Pro Tip: Use when for scheduling (when to work on) and deadline for final due dates.

Recent Improvements

Version 1.6.0

• 🗓️ Enhanced When Parameter: Support for today, tomorrow, evening, anytime, someday keywords in addition to YYYY-MM-DD dates
• 🗑️ Delete Operations: New delete_todo, delete_project, and empty_trash tools for complete lifecycle management
• 📦 Move Todo: New move_todo tool to relocate todos between projects, areas, and lists
• 🏷️ Tag Management: New get_unused_tags and delete_tag tools for tag cleanup
• 📁 Area CRUD: Full area management with add_area, update_area, and delete_area tools
• 🔧 Bug Fixes: Fixed move_todo to use property assignment for projects/areas instead of move command

Version 1.4.0

• 📦 MCPB Format Migration: Updated from DXT to the new MCPB (MCP Bundle) format specification v0.2
• 📦 Package Updates: Updated @modelcontextprotocol/sdk to v1.20.1 and esbuild to v0.25.11
• 🔧 Tooling: Migrated from dxt CLI to mcpb CLI for packaging
• 📝 Documentation: Updated all documentation and references to reflect MCPB naming
• ✅ Compatibility: Maintained full backward compatibility with all existing functionality

Version 1.3.0

• 🏗️ Complete Architecture Overhaul: Migrated from AppleScript to modular JavaScript for Automation (JXA)
• 🔒 Security-First Design: Eliminated shell injection risks with execFile and JSON parameter passing
• 📦 Modular Build System: ES6 modules compiled with esbuild for maintainable, modern code
• ⚡ Performance: Pre-built bundled scripts for faster execution
• 🧪 Comprehensive Testing: Unit, integration, and regression test suites
• 🔧 Better Error Handling: Enhanced error messages and timeout protection
• 📚 Developer Experience: Improved debugging, logging, and development workflow

Features

🎯 Core Functionality

• Complete Task Management: Create, read, update, delete, and move todos
• Project Management: Full CRUD operations for projects
• Area Management: Create, update, and delete areas
• Smart List Access: Work with all Things 3 lists (Inbox, Today, Upcoming, Anytime, Someday)
• Advanced Search: Multiple search types across all your Things data

🔍 Discovery & Navigation

• Tag Management: Get, find, cleanup unused, and delete tags
• Logbook Access: View completed tasks with flexible time periods
• Trash Management: Access, review, and empty trashed items
• Recent Items: Find recently modified items

🛠️ Advanced Features

• Flexible Scheduling: Use keywords (today, tomorrow, anytime, someday) or dates
• Move Operations: Relocate todos between projects, areas, and lists
• Data Integrity: Comprehensive input validation and error handling
• Security: Built-in injection protection and safe execution

API Reference

📝 Creation Tools

add_todo - Create a new to-do

Required: title Optional: notes, when, deadline, list_title, list_id, heading, tags, checklist_items

add_project - Create a new project

Required: title Optional: notes, when, deadline, area_title, area_id, tags, todos

add_area - Create a new area

Required: title Optional: tags

📋 List Access Tools

Tool	Description	Parameters
get_inbox	Get todos from Inbox	None
get_today	Get todos due today	None
get_upcoming	Get upcoming todos	None
get_anytime	Get Anytime list todos	None
get_someday	Get Someday list todos	None
get_logbook	Get completed todos	period, limit
get_trash	Get trashed todos	None

get_todos - Get todos with filtering

Optional: project_uuid, include_items

get_projects - Get all projects

Optional: include_items

get_areas - Get all areas

Optional: include_items

🔍 Search & Discovery Tools

search_items - Universal search

Required: query

search_todos - Todo-specific search

Required: query

search_advanced - Multi-criteria search

Required: query
Optional: tags, completed, canceled, trashed

get_tags - Get all tags

Parameters: None

get_tagged_items - Find items by tag

Required: tag_title

get_recent - Get recent items

Optional: days (default: 7)

✏️ Update Tools

update_todo - Update existing todo

Required: id
Optional: title, notes, when, deadline, tags, checklist_items, completed, canceled

• tags: Array of tag names. Use [] to remove all tags
• checklist_items: Array of checklist items. Appends to existing notes as formatted list

update_project - Update existing project

Required: id Optional: title, notes, when, deadline, tags, completed, canceled

• tags: Array of tag names. Use [] to remove all tags

show_item - Show item details

Required: id

🗑️ Delete & Move Tools

delete_todo - Delete a to-do (move to trash)

Required: id

delete_project - Delete a project (move to trash)

Required: id

move_todo - Relocate a to-do

Required: id Optional: project_id, project_title, area_id, area_title, list_id

empty_trash - Permanently delete all trashed items

Parameters: None

🏷️ Tag Management Tools

get_unused_tags - Get tags not assigned to any item

Parameters: None

delete_tag - Remove a tag from all items

Required: tag_name

📁 Area Management Tools

update_area - Update an existing area

Required: id Optional: title, tags, collapsed

delete_area - Delete an area

Required: id

Usage Examples

Daily Workflow

Show me my inbox and today's tasks, then help me plan my day

Task Creation

Create a task "Prepare quarterly report" with notes "Include Q3 metrics and future roadmap" due next Friday in my Work project with tags "urgent" and "quarterly"

Project Management

Create a new project "Website Redesign" in my "Product Development" area with deadline March 15th and add initial todos: "Research competitors", "Create wireframes", "Design mockups"

Search & Organization

Search for all tasks containing "meeting" and show me what's tagged with "urgent"

Tag Management

Remove all tags from task ID "abc123" by updating it with tags: []

Weekly Review

Show me what I completed last week, what's in my logbook, and help me organize my upcoming tasks

Parameter Guide

Date Parameters

• when: When scheduled to work on (appears in Today/Upcoming)
  • Keywords: today, tomorrow, evening, anytime, someday
  • Or date format: YYYY-MM-DD (e.g., "2024-03-15")
  • Note: anytime/someday require THINGS_AUTH_TOKEN (see setup below)
• deadline: When actually due (final deadline)
• Format: YYYY-MM-DD (e.g., "2024-03-15")

Auth Token Setup (Required for Anytime/Someday)

The anytime and someday keywords use the Things URL scheme which requires an auth token.

1. Get your token from Things 3:

   • Things 3 → Settings → General → Enable Things URLs → Manage

2. Add to your shell profile (~/.zshrc or ~/.bashrc):

   export THINGS_AUTH_TOKEN="your-token-here"

3. Restart your terminal or run source ~/.zshrc

Organization Parameters

• list_title/area_title: Use names for easy reference
• list_id/area_id: Use IDs for precise targeting
• tags: Array of tag names (e.g., ["urgent", "work"])

Update Parameters

• id: Required for all update operations
• Status flags: completed, canceled (boolean)

Requirements

• macOS: Required for JXA integration
• Things 3: Must be installed and accessible
• Node.js: Version 18.0.0 or higher
• Claude Desktop: Compatible with MCPB specification
• esbuild: Automatically installed as dev dependency

Installation

# Clone or download the extension
cd things-mcpb

# Install dependencies
npm install

# Build JXA scripts
npm run build

# Package the extension
npm run package

# Install in Claude Desktop (follow Claude Desktop docs)

Architecture

Project Structure

things-mcpb/
├── manifest.json              # MCPB extension manifest
├── package.json               # Dependencies and scripts
├── README.md                  # Documentation
├── CLAUDE.md                  # Claude Code instructions
├── server/
│   ├── index.js               # Main MCP server
│   ├── tool-definitions.js    # MCP tool schemas
│   ├── jxa-executor.js        # Secure JXA execution engine
│   ├── server-config.js       # Configuration constants
│   ├── utils.js               # Validation and utilities
│   └── response-formatter.js  # Response formatting
├── jxa/
│   ├── build.js               # Build system for JXA scripts
│   ├── src/                   # Modular JXA source files
│   │   ├── main.js            # Entry point and router
│   │   ├── utils.js           # Shared utilities
│   │   ├── todos.js           # Todo operations
│   │   ├── projects.js        # Project operations
│   │   ├── lists.js           # List operations
│   │   ├── search.js          # Search operations
│   │   ├── tags.js            # Tag operations
│   │   └── areas.js           # Area operations
│   └── build/                 # Generated bundled scripts
└── test/
    ├── run-tests.js           # Test runner
    ├── unit/                  # Unit tests
    ├── integration/           # Integration tests
    └── regression/            # Regression tests

Key Design Principles

• Separation of Concerns: Modular architecture with clear responsibilities
• Security First: No shell injection risks with execFile and JSON parameter passing
• User-Friendly: Intuitive parameter names and helpful error messages
• Robust Error Handling: Comprehensive error catching and reporting
• Test-Driven: Comprehensive test coverage for reliability
• Performance Optimized: Pre-built scripts with efficient resource usage
• Extensible: Easy to add new tools and functionality
• Modern JavaScript: ES6 modules compiled for JXA compatibility

Security Features

• Input Validation: All parameters validated for type, length, and content
• No Shell Injection: Uses execFile instead of exec - parameters never touch shell
• JSON Parameter Passing: Parameters passed as JSON arguments, not embedded in scripts
• Pattern Detection: Dangerous patterns blocked before execution
• Error Handling: Structured error responses with detailed logging
• Timeout Management: Prevents hanging JXA operations (30s default)
• Safe Execution: Secure command execution with process isolation
• Comprehensive Testing: Security validation covered by automated test suite

Development

Testing

# Run comprehensive test suite
npm test

# Run specific test suites
npm run test:unit        # Unit tests
npm run test:integration # Integration tests
npm run test:regression  # Regression tests
npm run test:watch       # Watch mode for development

# Build JXA scripts
npm run build
npm run build:watch     # Watch mode

# Syntax validation
npm run validate

# Debug mode
DEBUG=true npm start

Test Coverage

The extension includes a comprehensive test suite covering:

• Input Validation: String, date, array, and number validation with security checks
• Parameter Processing: User-friendly parameter conversion and validation
• JXA Execution: Script loading, execution, and error handling
• Security: Pattern detection and safe parameter passing
• Error Handling: Consistent error message formatting and validation
• Date Handling: Timezone-aware date parsing and formatting
• Tag Management: Format conversion and removal scenarios
• List Operations: Built-in list ID mapping verification
• Regression Tests: Specific issue fixes (#3, #5, etc.)

Adding New Tools

1. Add operation to appropriate module in jxa/src/ (e.g., todos.js)
2. Update router in jxa/src/main.js
3. Add tool definition to server/tool-definitions.js
4. Run npm run build to generate bundled script
5. Add tests and update documentation

Contributing Guidelines

• Include comprehensive input validation
• Add structured error handling
• Write unit tests for new functionality
• Update documentation for new features
• Test thoroughly with Things 3 on macOS
• Follow established patterns and conventions
• Maintain backward compatibility when possible

Troubleshooting

Common Issues

Things 3 Not Running

Solution: Launch Things 3 application and ensure it's running (not just in dock)

Permission Errors

Solution: 
1. System Preferences > Security & Privacy > Privacy
2. Select "Automation" 
3. Grant permission for your terminal/Claude Desktop to control Things 3

Debug Information

# Enable detailed logging
DEBUG=true npm start

Getting Help

• Things 3 Issues: Contact Cultured Code support
• Claude Desktop: Follow Claude Desktop documentation
• Extension Issues: Create issue in project repository

License

MIT License - See package.json for details

Acknowledgments

• Cultured Code for Things 3 and its automation support
• Anthropic for the Model Context Protocol (MCP) SDK
• esbuild for fast, reliable JavaScript bundling

---

Built with ❤️ for the Claude Desktop ecosystem