@papi-ai/server

@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