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

Setup — setup creates a .papi/ directory with your Product Brief and planning files
Plan — plan runs a sprint planning cycle, generates BUILD HANDOFFs for recommended tasks
Build — build list shows available tasks, build execute <task-id> starts implementation
Report — After building, call build execute <task-id> again with completion details
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