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