Execution System MCP Server

An AI-native execution system powered by Claude and the Model Context Protocol.

Why This Exists

Traditional productivity tools force you to context-switch between thinking and doing. You stop your work, open an app, navigate through menus, fill out forms, and then return to what you were doing. This friction means you often don't capture things at all, or you create incomplete entries that need cleanup later.

This MCP server eliminates that friction. You stay in conversation with Claude while working, and your execution system updates naturally:

• Working on code? "Add action: refactor the auth module @macbook +api-redesign due:2025-11-15"
• In a meeting? "Add to waiting: Sarah's feedback on the proposal"
• Reviewing your week? "List all actions for the ml-refresh project"
• Planning? "Show me all Health projects that haven't been reviewed in 7 days"

No app switching. No form filling. Just natural language that keeps you in flow while maintaining a rigorous execution system.

Features

The server implements the horizons of focus model through the Model Context Protocol:

0k - Next Actions (Ground Level)

• Add actions to context files (@macbook, @phone, @errands) with automatic project validation
• Add to special lists: @waiting (for others), @deferred (specific future date), @incubating (someday/maybe)
• Complete actions by line number with automatic archival to completed.md
• List actions with flexible filtering by context, project, and state
• Search actions by text with state and context filters
• Full support for todo.txt format with creation dates, contexts, projects, due/defer dates

10k - Projects (Current Initiatives)

• Create projects with YAML frontmatter and three templates (standard, coordination, habit)
• List projects with flexible filtering and grouping by area, due date, or flat
• Search projects by text in title or content
• Complete projects with validation that all actions are done
• Manage lifecycle: activate from incubator, move back to incubator, descope
• Update metadata: due dates, areas, types, review dates (bulk updates supported)
• Audit tools: validate data quality, find orphan projects/actions, identify items needing review

20k - Areas of Focus (Responsibilities)

• List areas of focus from configuration
• Automatic area validation across all projects and goals

30k - Goals (1-2 Year Objectives)

• List goals from active and incubator folders
• Automatic filtering by type: goal in YAML frontmatter
• Support for nested goal directories with supporting materials

All tools include comprehensive validation, error handling, and JSON output for programmatic access.

Installation

# Clone the repository
git clone https://github.com/elinsky/execution-system-mcp.git
cd execution-system-mcp

# Install dependencies
pip install -e ".[dev]"

Configuration

Create a configuration file at ~/.config/execution-system-mcp/config.json:

{
  "execution_system_repo_path": "/absolute/path/to/your/execution-system-repo",
  "areas": [
    {"name": "Health", "kebab": "health"},
    {"name": "Learning", "kebab": "learning"},
    {"name": "Career", "kebab": "career"},
    {"name": "Mission", "kebab": "mission"},
    {"name": "Personal Growth Systems", "kebab": "personal-growth-systems"},
    {"name": "Social Relationships", "kebab": "social-relationships"},
    {"name": "Romance", "kebab": "romance"},
    {"name": "Emotional Health", "kebab": "emotional-health"},
    {"name": "Finance", "kebab": "finance"},
    {"name": "Character and Values", "kebab": "character-and-values"},
    {"name": "Hobbies and Recreation", "kebab": "hobbies-and-recreation"}
  ]
}

Development

# Run tests
pytest

# Run tests with coverage
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/unit/test_config.py

Usage

The MCP server integrates with Claude Desktop. Once configured, you can manage your execution system by asking Claude:

0k - Action Examples

• "Add action 'Buy groceries' to @errands context for project meal-planning"
• "Add 'Wait for package delivery' to @waiting with defer date 2025-11-15"
• "Complete the action on line 7 of contexts/@macbook.md"
• "List all actions for the ml-refresh project"

10k - Project Examples

• "Create a new project titled 'Learn Python' in the Learning area as a standard project in active folder"
• "List all active projects in the Health area"
• "Complete the project 'Learn Python'"
• "Search for projects about machine learning"

20k - Area Examples

• "List all my areas of focus"

30k - Goal Examples

• "List all active goals"
• "Show me goals in the incubator"

Claude will use the appropriate MCP tools to interact with your execution system.

Available Tools

0k - Action Tools

• add_action - Add next action to context file with project validation
• add_to_waiting - Add item to @waiting list
• add_to_deferred - Add item to @deferred list
• add_to_incubating - Add item to @incubating list
• complete_action - Complete action by line number
• list_actions - List actions with flexible filtering and grouping
• search_actions - Search actions by text with filters

10k - Project Tools

• create_project - Create new project with YAML frontmatter and template
• list_active_projects - List all active projects grouped by area
• list_projects - List projects with flexible filtering (folder, area, due date)
• complete_project - Complete project with validation for incomplete actions
• activate_project - Move project from incubator to active
• move_project_to_incubator - Move project from active to incubator
• descope_project - Move project to descoped folder
• update_project_due_date - Add or remove project due date
• update_project_area - Change project's area of focus
• update_project_type - Change project type (standard/coordination/habit)
• update_review_dates - Bulk update last_reviewed dates
• search_projects - Search projects by text with filters

20k - Area Tools

• list_areas - List all configured areas of focus

30k - Goal Tools

• list_goals - List goals from active and incubator folders

Audit & Health Check Tools

• audit_projects - Validate project data quality
• audit_orphan_projects - Find projects without actions
• audit_orphan_actions - Find actions with invalid projects/contexts
• audit_action_files - Validate action file data quality
• list_projects_needing_review - Find projects not reviewed recently
• list_actions_needing_review - Find action files not reviewed recently

Project Structure

execution-system-mcp/
├── src/
│   └── gtd_mcp/
│       ├── __init__.py
│       ├── server.py          # MCP server with all tool handlers
│       ├── config.py          # Configuration manager
│       ├── creator.py         # Project creation
│       ├── lister.py          # Project listing
│       ├── completer.py       # Project completion
│       ├── validator.py       # Validation logic
│       ├── templates.py       # Project templates
│       ├── project_manager.py # Project lifecycle management
│       ├── action_manager.py  # Action creation and completion
│       ├── action_lister.py   # Action listing
│       ├── goal_lister.py     # Goal listing
│       ├── area_lister.py     # Area listing
│       ├── searcher.py        # Search functionality
│       └── auditor.py         # Data quality audits
├── tests/
│   └── unit/                  # 185 comprehensive unit tests
├── pyproject.toml
└── README.md

License

MIT