Pathfinder MCP Server

# Pathfinder MCP Server A FastMCP server implementing a three-phase gated workflow: **Research → Plan → Implement** (RPI). ## Overview Pathfinder enforces intentional context compaction and explicit human approval at each phase transition. It helps maintain focus during complex coding tasks by: - **Research Phase**: Gather information, explore codebase, document findings - **Plan Phase**: Create structured implementation plan with explicit phases - **Implement Phase**: Execute plan phases with progress tracking ## Installation ### For End Users (Once Published) ```bash # No installation needed - use uvx to run directly uvx pathfinder-mcp ``` ### For Local Development ```bash # Clone the repository git clone <repository-url> cd pathfinder-mcp # Install dependencies uv sync # Install as a global uv tool (editable mode) uv tool install --editable . # Install dev dependencies (optional) uv sync --dev ``` **What does `uv tool install --editable` do?** - Installs the command globally (available system-wide) - Links to your source code (changes take effect immediately) - Isolated from other projects - No need for complex paths in MCP configs ## Configuration ### Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `PATHFINDER_SESSIONS_DIR` | `~/.pathfinder-sessions` | Session storage path | | `PATHFINDER_TRANSPORT` | `stdio` | Transport: `stdio` or `sse` | | `PATHFINDER_HOST` | `127.0.0.1` | SSE server host | | `PATHFINDER_PORT` | `8080` | SSE server port | | `PATHFINDER_MAX_TOKENS` | `128000` | Max context tokens | ### Cursor MCP Config **For Published Package (Recommended):** ```json { "mcpServers": { "pathfinder": { "command": "uvx", "args": ["pathfinder-mcp"] } } } ``` **For Local Development (After `uv tool install --editable .`):** ```json { "mcpServers": { "pathfinder": { "command": "pathfinder-mcp", "env": { "PATHFINDER_SESSIONS_DIR": "/Users/yourusername/.pathfinder-sessions" } } } } ``` **SSE Transport (Remote Server):** ```json { "mcpServers": { "pathfinder": { "command": "pathfinder-mcp", "env": { "PATHFINDER_TRANSPORT": "sse", "PATHFINDER_HOST": "0.0.0.0", "PATHFINDER_PORT": "8080" } } } } ``` > **Note**: Use absolute paths in environment variables (e.g., `/Users/username/...` instead of `~`). The `~` expansion may not work reliably in all MCP clients. ## Tools | Tool | Phase | Description | |------|-------|-------------| | `health_check` | Any | Server health and context status | | `start_research` | - | Initialize research phase | | `save_research` | Research | Save research findings | | `start_plan` | Research → Plan | Transition to planning (requires approval) | | `save_plan` | Plan | Save implementation plan | | `implement_phase` | Plan/Implement | Execute implementation phase | | `compact_context` | Any | Compress session context | ## Resources | URI | Description | |-----|-------------| | `pathfinder://templates/research` | Research template | | `pathfinder://templates/plan` | Plan template (Cursor format) | | `pathfinder://templates/checklist` | Implementation checklist | | `pathfinder://templates/progress` | Progress tracking template | ## Prompts | Prompt | Description | |--------|-------------| | `generate_plan_from_research` | Create plan from research | | `compact_session` | Generate compressed summary | | `resume_session` | Restore session context | ## Workflow ``` 1. start_research("Build auth system") └─> Creates session, research.md 2. save_research(findings) [repeat as needed] └─> Appends to research.md 3. start_plan() [asks for confirmation] └─> Creates plan.md template, transitions to PLAN 4. save_plan(plan_content) └─> Validates & saves plan 5. implement_phase() [asks for confirmation] └─> Executes phase, updates progress.md 6. compact_context() [when utilization >60%] └─> Creates session_summary.md ``` ## Session Artifacts ``` ~/.pathfinder-sessions/ {session_id}/ research.md # Research findings plan.md # Implementation plan progress.md # Implementation progress session_state.json # Session snapshot session_summary.md # Compacted summary ``` ## Architecture ``` src/pathfinder_mcp/ ├── server.py # FastMCP server + tools ├── config.py # Environment configuration ├── state.py # Phase state machine ├── session.py # Session persistence ├── artifacts.py # Markdown file writer ├── context.py # Token monitoring ├── logger.py # Structured logging ├── errors.py # Error handling ├── handlers/ # Modular phase handlers │ ├── base.py # BaseHandler ABC │ ├── research.py # ResearchHandler │ ├── plan.py # PlanHandler │ └── implement.py # ImplementHandler └── tools/ # Tool implementations ├── research.py ├── plan.py ├── implement.py └── compact.py ``` ## Development Use `just` to run common development tasks: ```bash # See all available recipes just --list # Run tests just test # Run tests with coverage report just test-coverage # Lint & format code just check # Fix linting issues just lint-fix # Run the server locally just run # Build the package just build ``` ### Manual Commands If you prefer to run commands directly: ```bash # Run tests uv run pytest # Run tests with coverage uv run pytest --cov=pathfinder_mcp # Lint & format uv run ruff check src/ tests/ uv run ruff format src/ tests/ # Run server locally uv run pathfinder-mcp ``` ### Pre-commit Hooks Setup automatic linting and formatting on every commit: ```bash # Install pre-commit hooks (one-time) just setup-hooks # Or manually: uv run pre-commit install # Run pre-commit on all files just pre-commit-all # Pre-commit will automatically run on `git commit` ``` ## Context Management Pathfinder tracks token usage and provides warnings: - **60% utilization**: Suggests compaction - **70% utilization**: Warns strongly - **compact_context**: Resets by creating summary ## License MIT