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

```bash
# No installation needed - use uvx to run directly
uvx pathfinder-mcp
```

### For Local Development

```bash
# 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):**

```json
{
  "mcpServers": {
    "pathfinder": {
      "command": "uvx",
      "args": ["pathfinder-mcp"]
    }
  }
}
```

**For Local Development (After `uv tool install --editable .`):**

```json
{
  "mcpServers": {
    "pathfinder": {
      "command": "pathfinder-mcp",
      "env": {
        "PATHFINDER_SESSIONS_DIR": "/Users/yourusername/.pathfinder-sessions"
      }
    }
  }
}
```

**SSE Transport (Remote Server):**

```json
{
  "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:

```bash
# 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:

```bash
# 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:

```bash
# 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