Execution System MCP

🚀 Execution System MCP Server

An AI-native execution system powered by Claude and the Model Context Protocol, eliminating the friction in traditional productivity tools and enabling seamless task management through natural language.

🚀 Quick Start

The Execution System MCP Server is an AI-native system powered by Claude and the Model Context Protocol. It allows you to manage your tasks and projects without the need for constant app-switching and form-filling. To get started, follow the installation and configuration steps below.

✨ Features

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

0k - Next Actions (Ground Level)

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

10k - Projects (Current Initiatives)

• Create projects: Create projects with YAML frontmatter and three templates (standard, coordination, habit).
• List projects: List projects with flexible filtering and grouping by area, due date, or flat.
• Search projects: Search projects by text in title or content.
• Complete projects: Complete projects with validation that all actions are done.
• Manage lifecycle: Activate from incubator, move back to incubator, descope.
• Update metadata: Update 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: List areas of focus from configuration.
• Automatic area validation: Automatically validate areas across all projects and goals.

30k - Goals (1 - 2 Year Objectives)

• List goals: List goals from active and incubator folders.
• Automatic filtering: Automatically filter by type: goal in YAML frontmatter.
• Support for nested goal directories: 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]"

📚 Documentation

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 Examples

Basic 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

🔧 Technical Details

Project Structure

execution-system-mcp/
├── src/
│   └── execution_system_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