@papi-ai/server 0.2.0-alpha.2

package/README.md

@@ -0,0 +1,120 @@
+# @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)
+
+```bash
+npm install -g @papi/server
+```
+
+### From source
+
+```bash
+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
+
+```json
+{
+  "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
+
+```json
+{
+  "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