How do I use Pathfinder MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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](https://glama.ai/blog/2025-07-08-how-to-install-and-use-mcp-servers).

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

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

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

Pathfinder MCP Server

Pathfinder MCP Server

Overview

Installation

For End Users (Once Published)

For Local Development

Configuration

Environment Variables

Cursor MCP Config

Tools

Resources

Prompts

Workflow

Session Artifacts

Architecture

Development

Manual Commands

Pre-commit Hooks

Context Management

License

Resources

Tools

New MCP Servers

Latest Blog Posts

MCP directory API