@papi-ai/server 0.6.1-alpha.1 → 0.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +26 -130
  2. package/dist/index.js +1312 -985
  3. package/dist/prompts.js +9 -1
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -1,148 +1,44 @@
1
1
  # @papi-ai/server
2
2
 
3
- 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.
4
-
5
- ## Installation
6
-
7
- ### From npm (recommended)
8
-
9
- ```bash
10
- npm install -g @papi/server
11
- ```
12
-
13
- ### From source
14
-
15
- ```bash
16
- git clone https://github.com/cathalos92/papi-ui.git
17
- cd papi-ui
18
- npm install
19
- npm run mcp-build
20
- ```
21
-
22
- The server bundles `@papi-ai/adapter-md` at build time — no separate adapter install needed.
23
-
24
- ## Claude Code Setup
25
-
26
- Add PAPI to your project's `.mcp.json` file:
27
-
28
- ### If installed from npm
29
-
30
- ```json
31
- {
32
- "mcpServers": {
33
- "papi": {
34
- "command": "npx",
35
- "args": ["papi-server", "--project", "/path/to/your/project"],
36
- "env": {
37
- "PAPI_ADAPTER": "pg",
38
- "DATABASE_URL": "postgresql://...",
39
- "PAPI_PROJECT_ID": "your-project-uuid"
40
- }
41
- }
42
- }
43
- }
44
- ```
45
-
46
- ### If installed from source
47
-
48
- ```json
49
- {
50
- "mcpServers": {
51
- "papi": {
52
- "command": "node",
53
- "args": ["/path/to/papi-ui/packages/server/dist/index.js", "--project", "/path/to/your/project"],
54
- "env": {
55
- "PAPI_ADAPTER": "pg",
56
- "DATABASE_URL": "postgresql://...",
57
- "PAPI_PROJECT_ID": "your-project-uuid"
58
- }
59
- }
60
- }
61
- }
62
- ```
63
-
64
- 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.
65
-
66
- ## Environment Variables
67
-
68
- | Variable | Required | Default | Description |
69
- |----------|----------|---------|-------------|
70
- | `PAPI_PROJECT_DIR` | Yes* | — | Project root directory (alternative to `--project` flag) |
71
- | `PAPI_ADAPTER` | No | `md` | Storage adapter: `md` (local markdown files) or `pg` (PostgreSQL/Supabase) |
72
- | `DATABASE_URL` | For pg | — | PostgreSQL connection string (required when `PAPI_ADAPTER=pg`) |
73
- | `PAPI_PROJECT_ID` | For pg | — | Project UUID in the database (required when `PAPI_ADAPTER=pg`) |
74
- | `PAPI_API_KEY` | No** | — | Anthropic API key for AI-powered commands (plan, strategy, setup) |
75
- | `PAPI_AUTO_COMMIT` | No | `true` | Auto-commit `.papi/` changes after plans and builds |
76
- | `PAPI_AUTO_PR` | No | `true` | Auto-create pull requests after completed builds |
77
- | `PAPI_BASE_BRANCH` | No | `main` | Base branch for PR creation and plan sync (pull/push) |
78
- | `PAPI_SLACK_WEBHOOK_URL` | No | — | Slack incoming webhook URL for sprint notifications |
79
- | `PAPI_TELEMETRY` | No | `on` | Set to `off` to disable anonymous usage telemetry |
80
-
81
- \* Either `PAPI_PROJECT_DIR` or `--project` flag is required.
82
-
83
- \*\* Not required when using the prepare/apply pattern (default). Only needed if calling the Anthropic API directly from the server.
3
+ **Structured planning for AI-assisted development.** PAPI gives Claude Code a persistent planning layer — every cycle builds on the last, so your project gets smarter over time instead of starting fresh every session.
84
4
 
85
5
  ## Quick Start
86
6
 
87
- Once configured in Claude Code, initialise your project:
7
+ **Takes about 2 minutes.**
88
8
 
89
- 1. **Setup** — `setup` creates a `.papi/` directory with your Product Brief and planning files
90
- 2. **Plan** — `plan` runs a sprint planning cycle, generates BUILD HANDOFFs for recommended tasks
91
- 3. **Build** — `build list` shows available tasks, `build execute <task-id>` starts implementation
92
- 4. **Report** — After building, call `build execute <task-id>` again with completion details
93
- 5. **Repeat** — Run `plan` again when all sprint tasks are done
9
+ 1. **Get your config** — Sign up at [PAPI](https://papi-web-three.vercel.app/landing) and copy your `.mcp.json` snippet
10
+ 2. **Add to your project** — paste it into `.mcp.json` in your project root
11
+ 3. **Restart Claude Code** — it will detect the PAPI server automatically
12
+ 4. **In Claude Code:** say `run setup`, then `run plan`
94
13
 
95
- ## Commands
14
+ That's it. You're planning.
96
15
 
97
- | Command | Description | Requires API Key |
98
- |---------|-------------|:----------------:|
99
- | `setup` | Initialise a new PAPI project or regenerate Product Brief | Yes |
100
- | `plan` | Run sprint planning — generates BUILD HANDOFFs for 1-5 tasks | Yes |
101
- | `build` | List, describe, and execute build tasks | No |
102
- | `board` | View sprint board, filter tasks, deprioritise stale work | No |
103
- | `strategy` | Run strategy review or apply a strategic change | Yes |
104
- | `idea` | Capture a backlog idea without interrupting the current sprint | No |
105
- | `health` | Sprint health dashboard — cadence, board stats, next action | No |
106
- | `release` | Cut a versioned release with git tag and changelog | No |
16
+ ## What You Get
107
17
 
108
- ## How It Works
18
+ - **Cycle planning** — the AI planner reads your project history and recommends what to build next, with detailed BUILD HANDOFFs for each task
19
+ - **Build tracking** — every task gets a build report: actual effort, surprises, discovered issues, architecture decisions
20
+ - **Strategy reviews** — every 5 cycles, a deep analysis of velocity, estimation accuracy, and project direction
21
+ - **Compounding intelligence** — cycle 20 is sharper than cycle 1 because it has 19 cycles of context to learn from
109
22
 
110
- PAPI manages your project through markdown files in a `.papi/` directory:
23
+ ## Before / After
111
24
 
112
- - `PRODUCT_BRIEF.md` — Your project's vision, users, and roadmap
113
- - `PLANNING_LOG.md` — Sprint health, active decisions, sprint history
114
- - `SPRINT_BOARD.md` — All tasks with status, priority, and build handoffs
115
- - `BUILD_REPORTS.md` — Post-build reports tracking effort and discoveries
25
+ | Without PAPI | With PAPI |
26
+ |---|---|
27
+ | Start every session by re-explaining the project | Orient in one call — cycle state, next action, blocked tasks |
28
+ | Tasks grow in scope mid-build | BUILD HANDOFFs define scope boundary and acceptance criteria upfront |
29
+ | Architectural decisions get forgotten | Active Decisions persist across cycles with confidence levels |
30
+ | No way to know if you're going faster or slower | Estimation accuracy tracked every cycle |
116
31
 
117
- 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.
32
+ ## Links
118
33
 
119
- ## Telemetry
120
-
121
- PAPI collects anonymous usage data to help improve the product. This includes:
122
-
123
- - Tool name (e.g. `plan`, `build_execute`)
124
- - Call duration in milliseconds
125
- - Your project ID (a UUID, not your project name or code)
34
+ - **Dashboard** — [PAPI](https://papi-web-three.vercel.app/landing)
35
+ - **GitHub** — [cathalos92/papi-ui](https://github.com/cathalos92/papi-ui)
36
+ - **Install guide** — [docs/install-guide.md](https://github.com/cathalos92/papi-ui/blob/main/docs/install-guide.md)
126
37
 
127
- No source code, file contents, task titles, or personal data is ever collected. All data is sent to PAPI's hosted Supabase instance.
128
-
129
- **To opt out**, add `PAPI_TELEMETRY=off` to the `env` block in your `.mcp.json`:
38
+ ## Telemetry
130
39
 
131
- ```json
132
- {
133
- "mcpServers": {
134
- "papi": {
135
- "command": "npx",
136
- "args": ["-y", "@papi-ai/server"],
137
- "env": {
138
- "PAPI_DATA_API_KEY": "your-key",
139
- "PAPI_TELEMETRY": "off"
140
- }
141
- }
142
- }
143
- }
144
- ```
40
+ PAPI collects anonymous usage data (tool name, duration, project UUID — no code or task content). To opt out, add `PAPI_TELEMETRY=off` to your `.mcp.json` env block.
145
41
 
146
42
  ## License
147
43
 
148
- MIT
44
+ [Elastic License 2.0](https://www.elastic.co/licensing/elastic-license) — free to use, self-host, and modify. Commercial hosting requires a license.