paperclip-mcp 2.0.0 → 2.1.0

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 (2) hide show
  1. package/README.md +155 -136
  2. package/package.json +5 -4
package/README.md CHANGED
@@ -1,36 +1,18 @@
1
1
  # paperclip-mcp
2
2
 
3
- [![npm version](https://img.shields.io/npm/v/paperclip-mcp)](https://www.npmjs.com/package/paperclip-mcp)
4
- [![license](https://img.shields.io/npm/l/paperclip-mcp)](./LICENSE)
5
- [![node](https://img.shields.io/node/v/paperclip-mcp)](https://nodejs.org)
3
+ MCP server that exposes the [Paperclip](https://paperclip.ing) control plane API as tools for Claude Code agents — manage issues, coordinate agents, post comments, and orchestrate work without direct API calls.
6
4
 
7
- An [MCP](https://modelcontextprotocol.io) stdio server that exposes the [Paperclip](https://paperclip.ing) control plane API as callable tools for Claude Code agents.
8
-
9
- Agents use these tools to manage issues, post comments, read documents, coordinate with other agents, track goals and projects, and operate the full Paperclip control plane — all without writing direct API calls. The server handles authentication, run-ID injection, input validation, pagination, and error formatting transparently.
10
-
11
- ---
5
+ [![npm](https://img.shields.io/npm/v/paperclip-mcp)](https://www.npmjs.com/package/paperclip-mcp)
6
+ [![MCP protocol](https://img.shields.io/badge/MCP-1.29.0-blue)](https://modelcontextprotocol.io)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
12
8
 
13
9
  ## Quickstart
14
10
 
15
- **Install and run via npx (no global install needed):**
16
-
17
11
  ```bash
18
12
  npx paperclip-mcp
19
13
  ```
20
14
 
21
- **Or install globally:**
22
-
23
- ```bash
24
- npm install -g paperclip-mcp
25
- ```
26
-
27
- **Docker / Podman:** see [`docs/guides/docker.md`](docs/guides/docker.md) for the production image (`paperclip-mcp:2.0.0`), `.mcp.json` snippet, and security notes.
28
-
29
- ---
30
-
31
- ## Claude Code setup
32
-
33
- Add the server to your Claude Code MCP config. The recommended location is `~/.config/claude/settings.json` for user-wide access, or `.claude/settings.json` for project-local config.
15
+ Add to `.claude/settings.json`:
34
16
 
35
17
  ```json
36
18
  {
@@ -40,174 +22,211 @@ Add the server to your Claude Code MCP config. The recommended location is `~/.c
40
22
  "args": ["paperclip-mcp"],
41
23
  "env": {
42
24
  "PAPERCLIP_API_URL": "http://127.0.0.1:3100",
43
- "PAPERCLIP_API_KEY": "<your-agent-api-key>",
44
- "PAPERCLIP_AGENT_ID": "<your-agent-uuid>",
45
- "PAPERCLIP_COMPANY_ID": "<your-company-uuid>"
25
+ "PAPERCLIP_API_KEY": "<your-api-key>",
26
+ "PAPERCLIP_AGENT_ID": "<your-agent-id>",
27
+ "PAPERCLIP_COMPANY_ID": "<your-company-id>"
46
28
  }
47
29
  }
48
30
  }
49
31
  }
50
32
  ```
51
33
 
52
- When running under Paperclip's heartbeat system, all required env vars are injected automatically — no manual configuration needed for orchestrated runs.
34
+ For heartbeat runs, Paperclip injects all required env vars automatically.
53
35
 
54
- ---
36
+ ## Installation
55
37
 
56
- ## Environment variables
38
+ Three first-class variants:
57
39
 
58
- | Variable | Required | Description |
59
- | ------------------------------ | -------- | ------------------------------------------------------------ |
60
- | `PAPERCLIP_API_KEY` | Yes | Bearer token for API authentication |
61
- | `PAPERCLIP_API_URL` | Yes | Base URL of the Paperclip API (e.g. `http://127.0.0.1:3100`) |
62
- | `PAPERCLIP_AGENT_ID` | Yes | UUID of the agent running this server |
63
- | `PAPERCLIP_COMPANY_ID` | Yes | UUID of the company (for company-scoped endpoints) |
64
- | `PAPERCLIP_RUN_ID` | No | Heartbeat run ID — injected by Paperclip during agent runs |
65
- | `PAPERCLIP_REQUEST_TIMEOUT_MS` | No | Per-request timeout in ms (default: `30000`) |
40
+ ### npm
66
41
 
67
- ---
42
+ ```bash
43
+ # one-shot (no install)
44
+ npx paperclip-mcp
68
45
 
69
- ## Run ID injection
46
+ # global install
47
+ npm install -g paperclip-mcp
48
+ ```
70
49
 
71
- When `PAPERCLIP_RUN_ID` is set, the server automatically adds `X-Paperclip-Run-Id: <runId>` to all mutating requests (POST, PATCH, PUT, DELETE). This links every write action to the current heartbeat run for audit trail and traceability. No action is needed from the agent — injection is transparent.
50
+ ### Docker / Podman
72
51
 
73
- ---
52
+ ```bash
53
+ # Docker
54
+ docker run --rm -i \
55
+ -e PAPERCLIP_API_URL=http://host.docker.internal:3100 \
56
+ -e PAPERCLIP_API_KEY=<your-api-key> \
57
+ -e PAPERCLIP_AGENT_ID=<your-agent-id> \
58
+ -e PAPERCLIP_COMPANY_ID=<your-company-id> \
59
+ ghcr.io/bruhsb/paperclip-mcp:2.1.0
60
+
61
+ # Podman (same flags, replace docker → podman)
62
+ podman run --rm -i \
63
+ -e PAPERCLIP_API_URL=http://host.containers.internal:3100 \
64
+ -e PAPERCLIP_API_KEY=<your-api-key> \
65
+ -e PAPERCLIP_AGENT_ID=<your-agent-id> \
66
+ -e PAPERCLIP_COMPANY_ID=<your-company-id> \
67
+ ghcr.io/bruhsb/paperclip-mcp:2.1.0
68
+ ```
74
69
 
75
- ## Authentication
70
+ ### Compose stack (v2.1.0+)
76
71
 
77
- Paperclip supports two key types:
72
+ Run the full Paperclip server + MCP server together via `podman-compose` (or `docker-compose`):
73
+
74
+ ```bash
75
+ podman-compose up -d
76
+ ```
78
77
 
79
- - **Agent keys** — issued per agent via `paperclip_create_agent_key`. Scoped to that agent's identity. Required for `paperclip_get_me`, `paperclip_get_inbox`, and all issue workflow tools. Tools marked `Board-only` will return `403` with agent keys.
80
- - **Board keys** — issued to human operators via the Paperclip dashboard CLI auth flow. Required for administrative tools (company management, plugin installation, secrets, agent termination, feedback traces).
78
+ See [`docs/guides/local-stack.md`](docs/guides/local-stack.md) for the full compose setup, volume config, and health-check instructions.
81
79
 
82
- For Paperclip-orchestrated agents, agent keys are provisioned automatically. For local development, obtain your key from the Paperclip dashboard settings.
80
+ ## Host integration
83
81
 
84
- ---
82
+ paperclip-mcp works with any MCP-compatible host. Platform-specific config files are in [`docs/installation/`](docs/installation/):
83
+
84
+ | Host | Guide |
85
+ | -------------- | ---------------------------------------------------------------------------- |
86
+ | Claude Code | [`docs/installation/claude-code.md`](docs/installation/claude-code.md) |
87
+ | Claude Desktop | [`docs/installation/claude-desktop.md`](docs/installation/claude-desktop.md) |
88
+ | Cursor | [`docs/installation/cursor.md`](docs/installation/cursor.md) |
89
+ | VS Code | [`docs/installation/vscode.md`](docs/installation/vscode.md) |
90
+ | Windsurf | [`docs/installation/windsurf.md`](docs/installation/windsurf.md) |
91
+
92
+ Each guide includes the exact config block, where to place it, and verification steps. Do not copy configs from this README — use the host-specific guides so you get the right file paths and format.
93
+
94
+ ## Environment variables
95
+
96
+ | Variable | Required | Description |
97
+ | ---------------------- | -------- | ------------------------------------------------------------ |
98
+ | `PAPERCLIP_API_KEY` | Yes | Bearer token for API authentication |
99
+ | `PAPERCLIP_API_URL` | Yes | Base URL of the Paperclip API (e.g. `http://127.0.0.1:3100`) |
100
+ | `PAPERCLIP_AGENT_ID` | Yes | UUID of the agent running this MCP server |
101
+ | `PAPERCLIP_COMPANY_ID` | Yes | UUID of the company (used for company-scoped endpoints) |
102
+ | `PAPERCLIP_RUN_ID` | No | Heartbeat run ID — injected by Paperclip during agent runs |
103
+ | `PAPERCLIP_TASK_ID` | No | Task ID injected by Paperclip on @-mention wakes |
85
104
 
86
105
  ## Tool catalog
87
106
 
88
- Paperclip MCP v2.0.0 exposes **104 tools** across **19 domains**.
89
-
90
- | Domain | Tools |
91
- | ----------------------- | ----- |
92
- | Identity & session | 4 |
93
- | Issues | 9 |
94
- | Comments | 3 |
95
- | Labels | 3 |
96
- | Documents | 5 |
97
- | Attachments | 4 |
98
- | Agents & org | 17 |
99
- | Approvals & hiring | 11 |
100
- | Goals | 4 |
101
- | Projects & workspaces | 7 |
102
- | Dashboard | 1 |
103
- | Activity & costs | 5 |
104
- | Routines | 9 |
105
- | Companies | 5 |
106
- | Plugins | 6 |
107
- | Secrets | 4 |
108
- | Run observability | 3 |
109
- | Feedback traces | 3 |
110
- | Company import / export | 3 |
111
-
112
- Full endpoint x tool matrix: [`docs/guides/api-coverage.md`](docs/guides/api-coverage.md)
113
-
114
- ---
107
+ <!-- TOOLS-START -->
108
+
109
+ | Domain | Tools |
110
+ | ----------------------- | ------- |
111
+ | Identity | 4 |
112
+ | Issues | 7 |
113
+ | Comments | 3 |
114
+ | Documents | 5 |
115
+ | Agents & Organization | 17 |
116
+ | Dashboard | 1 |
117
+ | Approvals | 11 |
118
+ | Goals | 4 |
119
+ | Projects & Workspaces | 8 |
120
+ | Activity & Costs | 5 |
121
+ | Routines | 9 |
122
+ | Attachments | 4 |
123
+ | Labels | 2 |
124
+ | Companies | 5 |
125
+ | Plugins | 6 |
126
+ | Secrets | 4 |
127
+ | Run Observability | 3 |
128
+ | Feedback Traces | 3 |
129
+ | Company Import / Export | 3 |
130
+ | **Total** | **104** |
131
+
132
+ <!-- TOOLS-END -->
133
+
134
+ Full per-tool reference: [`docs/tools/`](docs/tools/README.md). Generated from Zod schemas — run `npm run docs:generate` to refresh.
115
135
 
116
- ## Error handling
136
+ ## Authentication
137
+
138
+ paperclip-mcp authenticates every request with a Bearer token derived from `PAPERCLIP_API_KEY`. The agent identity (`PAPERCLIP_AGENT_ID`) and company scope (`PAPERCLIP_COMPANY_ID`) are resolved at startup — the server will exit immediately if any required variable is missing. For details on generating API keys and scoping them to a specific agent, see [`docs/auth-keys.md`](docs/auth-keys.md).
139
+
140
+ ## Run ID injection
117
141
 
118
- All tool handlers catch API errors and return `isError: true` with a human-readable message in `content[0].text`. The server never propagates uncaught exceptions to the MCP transport.
142
+ When `PAPERCLIP_RUN_ID` is set, the server automatically adds `X-Paperclip-Run-Id: <runId>` to all mutating requests (POST, PATCH, PUT, DELETE). This links every write action to the current heartbeat run for audit trail and traceability. No action is needed from the agent — injection is transparent.
119
143
 
120
- | HTTP status | Behavior |
121
- | ----------- | ------------------------------------------------- |
122
- | 400 | `isError: true` with validation message |
123
- | 401 / 403 | `isError: true` with auth error |
124
- | 404 | `isError: true` with not-found message |
125
- | 409 | `isError: true` with conflict message (no retry) |
126
- | 5xx | `isError: true` with transient error + retry hint |
144
+ ## Error handling
127
145
 
128
- ---
146
+ All tool handlers catch API errors and return `isError: true` results. The `content[0].text` field contains a human-readable message.
147
+
148
+ | HTTP status | Behaviour |
149
+ | ----------- | ------------------------------------------------ |
150
+ | 400 | `isError: true` with validation message |
151
+ | 401 / 403 | `isError: true` with auth error |
152
+ | 404 | `isError: true` with not-found message |
153
+ | 409 | `isError: true` with conflict message (no retry) |
154
+ | 5xx | `isError: true` with server error message |
129
155
 
130
156
  ## Architecture
131
157
 
132
- - **Transport:** MCP stdio (JSON-RPC over stdin/stdout). No network ports opened.
133
- - **Entry point:** `src/index.ts` — creates an MCP `Server`, registers all tools via `registerAllTools`, connects `StdioServerTransport`.
134
- - **Client:** `src/client.ts` — typed HTTP wrapper with `Authorization` header and run-ID injection on mutations. Per-request `AbortSignal.timeout(30_000)`.
135
- - **Input validation:** Zod schemas are the single source of truth. All inputs validated before reaching the API client. Unknown fields rejected (`.strict()`).
136
- - **Tool descriptions:** Structured with `Args / Returns / Examples / Error Handling` sections. Board-only tools prefixed with `⚠ Board-only:`.
137
- - **Pagination:** All `list_*` tools return `{ items, total, count, offset, limit, has_more }`. Default limit: 50; max: 100.
138
- - **Response formatting:** Large responses are truncated at 25,000 characters with an actionable hint.
158
+ **Entry flow:** `src/index.ts` creates an MCP `Server`, calls `registerAllTools(server)`, then connects a `StdioServerTransport` for JSON-RPC over stdio.
139
159
 
140
- For the conventions used to add new tools, see [`docs/guides/mcp-tool-conventions.md`](docs/guides/mcp-tool-conventions.md).
160
+ **Key modules:**
141
161
 
142
- ---
162
+ - `src/client.ts` — `PaperclipClient`: typed HTTP wrapper (`get`, `post`, `patch`, `put`, `delete`). Injects `Authorization` header and `X-Paperclip-Run-Id` on mutations.
163
+ - `src/auth.ts` — Reads env vars at startup (fail-fast on missing required vars).
164
+ - `src/errors.ts` — `PaperclipApiError` for non-2xx HTTP responses.
165
+ - `src/types.ts` — Shared domain types.
166
+ - `src/tools/index.ts` — Tool registry. Collects `ToolDefinition[]` arrays from each tool module into `ALL_TOOLS`, builds a dispatch map, and registers MCP `ListTools` / `CallTool` handlers.
167
+ - `src/tools/validation.ts` — `validate(zodSchema, args)` helper and shared Zod schemas.
143
168
 
144
- ## Development
169
+ ## Documentation
145
170
 
146
- **Prerequisites:** Node.js >=22, npm >=10
171
+ - **End-user** — [`docs/README.md`](docs/README.md): quickstart, auth keys, troubleshooting, cookbook, host install guides, tool reference.
172
+ - **Contributor** — [`CONTRIBUTING.md`](CONTRIBUTING.md): branch strategy, PR flow, dev environment, and conventions for adding new tools.
173
+ - **Agent-orchestration** — [`AGENTS.md`](AGENTS.md): Paperclip-orchestrated agent protocol, BMAD integration, and heartbeat model.
147
174
 
148
- ```bash
149
- git clone https://github.com/bruhsb/paperclip-mcp.git
150
- cd paperclip-mcp
151
- npm install
152
- ```
175
+ ## Skills
153
176
 
154
- | Task | Command |
155
- | --------------- | -------------------- |
156
- | Build | `npm run build` |
157
- | Dev (live TS) | `npm run dev` |
158
- | Type-check | `npm run typecheck` |
159
- | Lint | `npm run lint` |
160
- | Format | `npm run format` |
161
- | Run tests | `npm run test` |
162
- | Check doc links | `npm run docs:check` |
177
+ paperclip-mcp ships public Claude Code skills under `skills/` — `paperclip-triage-inbox`, `paperclip-close-epic`, `paperclip-audit-approvals`, `paperclip-release-flow`. Copy the relevant skill directory to `~/.claude/skills/` to use it in your Claude Code session. See [`skills/README.md`](skills/README.md) for the full list and usage notes.
163
178
 
164
- See [CONTRIBUTING.md](CONTRIBUTING.md) for branch strategy, commit format, and how to add new tools.
179
+ ## Development
165
180
 
166
- ---
181
+ | Task | Command |
182
+ | -------------------- | ----------------------- |
183
+ | Build | `npm run build` |
184
+ | Dev (live TS) | `npm run dev` |
185
+ | Start (compiled) | `npm run start` |
186
+ | Type-check only | `npm run typecheck` |
187
+ | Lint | `npm run lint` |
188
+ | Format | `npm run format` |
189
+ | Format check | `npm run format:check` |
190
+ | Run all tests | `npm run test` |
191
+ | Regenerate tool docs | `npm run docs:generate` |
192
+ | Check doc links | `npm run docs:check` |
193
+
194
+ Branch strategy: `feature/*` → `main` (squash-merge via PR)
167
195
 
168
196
  ## Status & compatibility
169
197
 
170
- | Component | Version / info |
171
- | ------------- | ----------------------------------------------- |
172
- | paperclip-mcp | 2.0.0 |
173
- | Paperclip API | v2 (tested against local dev server 2026-04-16) |
174
- | Node.js | >=22 |
175
- | MCP SDK | ^1.26.0 (`@modelcontextprotocol/sdk`) |
176
-
177
- ---
198
+ | Component | Version |
199
+ | ------------------------------------------ | ------- |
200
+ | MCP protocol (`@modelcontextprotocol/sdk`) | 1.29.0 |
201
+ | Node.js (minimum) | 22 |
202
+ | Paperclip API | v2 |
178
203
 
179
204
  ## Releases
180
205
 
181
- Releases are automated via semantic-release. Merge `develop → main`; the `release.yml` workflow handles version bumping, changelog generation, npm publish, and GitHub release creation.
206
+ Releases are automated. Squash-merge a PR to `main`; semantic-release handles version bumping, changelog generation, npm publish, and GitHub release creation. No manual publish step is needed.
207
+
208
+ To trigger a release, open a PR from your feature branch to `main`. Once merged, the `release.yml` workflow runs `npx semantic-release` automatically. The version bump is determined by the commit types since the last release:
182
209
 
183
210
  - `fix:` commits → patch release
184
211
  - `feat:` commits → minor release
185
- - `BREAKING CHANGE:` in commit footer → major release
186
-
187
- ---
212
+ - `BREAKING CHANGE:` commits → major release
213
+ - `chore:`, `docs:`, `test:` commits → no release
188
214
 
189
215
  ## Contributing
190
216
 
191
- Bug reports and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for how to get started. Please read our [Code of Conduct](CODE_OF_CONDUCT.md) before participating.
192
-
193
- ---
217
+ See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full contributor guide, including how to add new tools, branch naming, commit format, and PR process.
194
218
 
195
219
  ## Security
196
220
 
197
- To report a security vulnerability, use [GitHub Security Advisories](https://github.com/bruhsb/paperclip-mcp/security/advisories/new) — do not open a public issue. See [SECURITY.md](SECURITY.md) for scope and response expectations.
198
-
199
- ---
221
+ Please report security vulnerabilities via the process described in [`SECURITY.md`](SECURITY.md). Do not open public issues for security bugs.
200
222
 
201
223
  ## Links
202
224
 
225
+ - [Paperclip](https://paperclip.ing) — the control plane this MCP server wraps
226
+ - [Model Context Protocol](https://modelcontextprotocol.io) — the open protocol standard
203
227
  - [npm package](https://www.npmjs.com/package/paperclip-mcp)
204
- - [GitHub issues](https://github.com/bruhsb/paperclip-mcp/issues)
205
- - [API coverage matrix](docs/guides/api-coverage.md)
206
- - [Tool conventions guide](docs/guides/mcp-tool-conventions.md)
207
- - [Paperclip](https://paperclip.ing)
208
-
209
- ---
228
+ - [GitHub](https://github.com/bruhsb/paperclip-mcp)
210
229
 
211
230
  ## License
212
231
 
213
- [MIT](LICENSE) — Copyright (c) 2026 Bruno S. Brasil
232
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "paperclip-mcp",
3
- "version": "2.0.0",
3
+ "version": "2.1.0",
4
4
  "description": "Paperclip MCP server for Claude Code agents",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -33,13 +33,14 @@
33
33
  "check:no-raw-inputschema": "node scripts/check-no-raw-inputschema.mjs",
34
34
  "dev": "tsx src/index.ts",
35
35
  "start": "node dist/index.js",
36
- "lint": "eslint src",
37
- "format": "prettier --write .",
38
- "format:check": "prettier --check .",
36
+ "lint": "eslint --cache --cache-location .eslintcache --cache-strategy content src",
37
+ "format": "prettier --cache --write .",
38
+ "format:check": "prettier --cache --check .",
39
39
  "typecheck": "tsc --noEmit",
40
40
  "test": "node --import tsx/esm --test 'src/**/*.test.ts'",
41
41
  "test:coverage": "node --import tsx/esm --experimental-test-coverage --test-coverage-lines=80 --test-coverage-branches=70 --test 'src/**/*.test.ts'",
42
42
  "docs:check": "find docs -name '*.md' | xargs markdown-link-check -c .markdown-link-check.json",
43
+ "docs:generate": "tsx scripts/generate-tool-docs.ts && prettier --log-level=warn --write docs/tools/",
43
44
  "test:functional": "node --import tsx/esm scripts/functional-test.mjs",
44
45
  "docker:build": "podman build -t paperclip-mcp:2.0.0 -t paperclip-mcp:latest .",
45
46
  "docker:smoke": "node scripts/smoke-docker.mjs",