Skip to main content
Glama
jamesctucker

Pathfinder MCP Server

by jamesctucker
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

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

Install Server
A
security – no known vulnerabilities
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jamesctucker/pathfinder-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server