Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Pathfinder MCP Serverstart research for implementing user authentication"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpFor 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 --devWhat 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 |
|
| Session storage path |
|
| Transport: |
|
| SSE server host |
|
| SSE server port |
|
| 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 |
| Any | Server health and context status |
| - | Initialize research phase |
| Research | Save research findings |
| Research → Plan | Transition to planning (requires approval) |
| Plan | Save implementation plan |
| Plan/Implement | Execute implementation phase |
| Any | Compress session context |
Resources
URI | Description |
| Research template |
| Plan template (Cursor format) |
| Implementation checklist |
| Progress tracking template |
Prompts
Prompt | Description |
| Create plan from research |
| Generate compressed summary |
| 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.mdSession 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 summaryArchitecture
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.pyDevelopment
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 buildManual 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-mcpPre-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