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
