Pathfinder MCP Server
Click on "Deploy 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 Server start 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
Related MCP server: mcp-micromanage
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 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 |
|
| 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 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 |
| 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
Available Tools
7 toolscompact_contextB
Compress session context into summary artifacts.
Use when context utilization exceeds 60%.
Args: session_id: Session ID
Inputs: session_id (required). Returns: object
health_checkC
Check server health and return status.
Inputs: no named parameters. Returns: object
implement_phaseB
Execute an implementation phase from the plan.
Args: session_id: Session ID phase_number: Specific phase to execute (defaults to next uncompleted)
Inputs: session_id (required), phase_number (required). Returns: object
save_planB
Save implementation plan.
Validates plan follows Cursor plan format with YAML frontmatter.
Args: session_id: Session ID plan_content: Plan content in Cursor plan format
Inputs: session_id (required), plan_content (required). Returns: object
save_researchC
Save research findings to the session.
Args: session_id: Session ID findings: Research findings to save
Inputs: session_id (required), findings (required). Returns: object
start_planA
Transition from research to plan phase.
Creates plan.md template. Requires research to be complete.
Args: session_id: Session ID
Inputs: session_id (required). Returns: object
start_researchC
Start a new research session.
Args: task_description: Description of the task to research session_id: Optional session ID (auto-generated if not provided)
Inputs: task_description (required), session_id. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Most tools have clearly distinct purposes: health_check, compact_context, save_research, start_research, start_plan, save_plan, and implement_phase each target different phases or actions in a workflow. However, save_research and save_plan could be slightly confused as both involve saving content, but their descriptions clarify they handle different types of data (research findings vs. implementation plans).
The naming follows a consistent verb_noun pattern throughout (e.g., compact_context, health_check, implement_phase, save_plan, save_research, start_plan, start_research), which is predictable and readable. There are no deviations in style or convention, making it easy for agents to understand the action each tool performs.
With 7 tools, the count is well-scoped for a server focused on managing research and implementation workflows. Each tool appears to earn its place by covering distinct steps in the process, from starting research to executing phases, without being overly sparse or bloated.
The tool set covers key phases like research, planning, and implementation, but there are notable gaps. For example, there are no tools for updating or deleting saved plans or research, and operations like reviewing or listing existing sessions are missing. This could lead to dead ends for agents trying to manage ongoing work comprehensively.
Maintenance
Related MCP Connectors
Adaptive plan/build/review cycles for AI coding assistants, persisted across sessions.
Coordinate coding agents through MCP using existing AI plans, saved work, and independent checks.
Preventive human-approval write-gate for AI agents: writes commit only after a human approves.
Brand strategy and content-calendar context for agents, with human-confirmed approval gates.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnforces disciplined programming practices by requiring AI assistants to audit their work and produce verified outputs at each phase of development, following structured workflows for refactoring, feature development, and testing.2035 npm12MIT
- AlicenseNot gradedqualityDmaintenanceControls coding agents by enforcing structured implementation plans with PRs and commits as work units, requiring user review at each commit checkpoint to prevent agents from going off track. Includes a visualization dashboard for tracking progress in real-time.1MIT
- AlicenseAqualityCmaintenanceEnables AI coding tools to follow a structured spec-driven development workflow with three phases: requirements, design, and tasks, ensuring approval before advancing.10MIT
- FlicenseNot gradedqualityDmaintenanceEnforces a rigorous spec-driven engineering workflow for AI coding assistants, requiring requirements, design, and task planning before any code is written.-