Skip to main content
Glama

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

Available Tools

7 tools
compact_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

    B3.3/5.0

    Scored across 7 tools

    Disambiguation4/5

    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).

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers