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)

# No installation needed - use uvx to run directly
uvx pathfinder-mcp

For Local Development

# 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):

{
  "mcpServers": {
    "pathfinder": {
      "command": "uvx",
      "args": ["pathfinder-mcp"]
    }
  }
}

For Local Development (After uv tool install --editable .):

{
  "mcpServers": {
    "pathfinder": {
      "command": "pathfinder-mcp",
      "env": {
        "PATHFINDER_SESSIONS_DIR": "/Users/yourusername/.pathfinder-sessions"
      }
    }
  }
}

SSE Transport (Remote Server):

{
  "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:

# 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:

# 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:

# 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