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