@papi-ai/server

AI-powered sprint planning, build execution, and strategy review for software projects. PAPI is an MCP (Model Context Protocol) server that connects to Claude Code to manage your project's planning lifecycle.

Installation

From npm (recommended)

npm install -g @papi/server

From source

git clone https://github.com/cathalos92/papi-ui.git
cd papi-ui
npm install
npm run mcp-build

The server bundles @papi-ai/adapter-md at build time — no separate adapter install needed.

Claude Code Setup

Add PAPI to your project's .mcp.json file:

If installed from npm

{
  "mcpServers": {
    "papi": {
      "command": "npx",
      "args": ["papi-server", "--project", "/path/to/your/project"],
      "env": {
        "PAPI_ADAPTER": "pg",
        "DATABASE_URL": "postgresql://...",
        "PAPI_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

If installed from source

{
  "mcpServers": {
    "papi": {
      "command": "node",
      "args": ["/path/to/papi-ui/packages/server/dist/index.js", "--project", "/path/to/your/project"],
      "env": {
        "PAPI_ADAPTER": "pg",
        "DATABASE_URL": "postgresql://...",
        "PAPI_PROJECT_ID": "your-project-uuid"
      }
    }
  }
}

For local-only usage with markdown files (no database), omit the PAPI_ADAPTER, DATABASE_URL, and PAPI_PROJECT_ID variables — the server defaults to the markdown adapter.

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | PAPI_PROJECT_DIR | Yes* | — | Project root directory (alternative to --project flag) | | PAPI_ADAPTER | No | md | Storage adapter: md (local markdown files) or pg (PostgreSQL/Supabase) | | DATABASE_URL | For pg | — | PostgreSQL connection string (required when PAPI_ADAPTER=pg) | | PAPI_PROJECT_ID | For pg | — | Project UUID in the database (required when PAPI_ADAPTER=pg) | | PAPI_API_KEY | No** | — | Anthropic API key for AI-powered commands (plan, strategy, setup) | | PAPI_AUTO_COMMIT | No | true | Auto-commit .papi/ changes after plans and builds | | PAPI_AUTO_PR | No | true | Auto-create pull requests after completed builds | | PAPI_BASE_BRANCH | No | main | Base branch for PR creation and plan sync (pull/push) | | PAPI_SLACK_WEBHOOK_URL | No | — | Slack incoming webhook URL for sprint notifications |

* Either PAPI_PROJECT_DIR or --project flag is required.

** Not required when using the prepare/apply pattern (default). Only needed if calling the Anthropic API directly from the server.

Quick Start

Once configured in Claude Code, initialise your project:

1. Setup — setup creates a .papi/ directory with your Product Brief and planning files
2. Plan — plan runs a sprint planning cycle, generates BUILD HANDOFFs for recommended tasks
3. Build — build list shows available tasks, build execute <task-id> starts implementation
4. Report — After building, call build execute <task-id> again with completion details
5. Repeat — Run plan again when all sprint tasks are done

Commands

| Command | Description | Requires API Key | |---------|-------------|:----------------:| | setup | Initialise a new PAPI project or regenerate Product Brief | Yes | | plan | Run sprint planning — generates BUILD HANDOFFs for 1-5 tasks | Yes | | build | List, describe, and execute build tasks | No | | board | View sprint board, filter tasks, deprioritise stale work | No | | strategy | Run strategy review or apply a strategic change | Yes | | idea | Capture a backlog idea without interrupting the current sprint | No | | health | Sprint health dashboard — cadence, board stats, next action | No | | release | Cut a versioned release with git tag and changelog | No |

How It Works

PAPI manages your project through markdown files in a .papi/ directory:

• PRODUCT_BRIEF.md — Your project's vision, users, and roadmap
• PLANNING_LOG.md — Sprint health, active decisions, sprint history
• SPRINT_BOARD.md — All tasks with status, priority, and build handoffs
• BUILD_REPORTS.md — Post-build reports tracking effort and discoveries

The AI planner reads this context each sprint to make informed recommendations that compound over time — sprint 20 is smarter than sprint 1 because it has 19 sprints of history to learn from.

License

MIT