paperclip-mcp 1.2.5 → 2.1.0

package/README.md

@@ -1,22 +1,18 @@
 # paperclip-mcp
 
-MCP server that exposes the [Paperclip](https://paperclip.ing) control plane API as tools for Claude Code agents. Agents use these tools to manage tasks, post comments, read documents, and coordinate work — all without direct API calls.
+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.
 
-## Installation
-
-```bash
-npx paperclip-mcp
-```
+[![npm](https://img.shields.io/npm/v/paperclip-mcp)](https://www.npmjs.com/package/paperclip-mcp)
+[![MCP protocol](https://img.shields.io/badge/MCP-1.29.0-blue)](https://modelcontextprotocol.io)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
-Or install globally:
+## Quickstart
 
 ```bash
-npm install -g paperclip-mcp
+npx paperclip-mcp
 ```
 
-## Claude Code setup
-
-Add to your MCP config (`.claude/settings.json` or `~/.config/claude/settings.json`):
+Add to `.claude/settings.json`:
 
 ```json
 {
@@ -37,636 +33,113 @@ Add to your MCP config (`.claude/settings.json` or `~/.config/claude/settings.js
 
 For heartbeat runs, Paperclip injects all required env vars automatically.
 
-## Environment variables
-
-| Variable               | Required | Description                                                  |
-| ---------------------- | -------- | ------------------------------------------------------------ |
-| `PAPERCLIP_API_KEY`    | Yes      | Bearer token for API authentication                          |
-| `PAPERCLIP_API_URL`    | Yes      | Base URL of the Paperclip API (e.g. `http://127.0.0.1:3100`) |
-| `PAPERCLIP_AGENT_ID`   | Yes      | UUID of the agent running this MCP server                    |
-| `PAPERCLIP_COMPANY_ID` | Yes      | UUID of the company (used for company-scoped endpoints)      |
-| `PAPERCLIP_RUN_ID`     | No       | Heartbeat run ID — injected by Paperclip during agent runs   |
-
-## Run ID injection
-
-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.
-
-## Tools
-
-Paperclip MCP exposes 69 tools across 12 groups.
-
-| Group       | Tools                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Identity    | `paperclip_get_me`, `paperclip_get_inbox`                                                                                                                                                                                                                                                                                                                                                                                            |
-| Issues      | `paperclip_list_issues`, `paperclip_get_issue`, `paperclip_get_heartbeat_context`, `paperclip_checkout_issue`, `paperclip_release_issue`, `paperclip_update_issue`, `paperclip_create_issue`                                                                                                                                                                                                                                         |
-| Comments    | `paperclip_list_comments`, `paperclip_add_comment`                                                                                                                                                                                                                                                                                                                                                                                   |
-| Documents   | `paperclip_list_documents`, `paperclip_get_document`, `paperclip_upsert_document`, `paperclip_delete_document`, `paperclip_get_document_revisions`                                                                                                                                                                                                                                                                                   |
-| Agents      | `paperclip_list_agents`, `paperclip_get_agent`, `paperclip_update_agent`, `paperclip_pause_agent`, `paperclip_resume_agent`, `paperclip_invoke_heartbeat`, `paperclip_terminate_agent`, `paperclip_create_agent_key`, `paperclip_list_agent_config_revisions`, `paperclip_rollback_agent_config`, `paperclip_set_agent_instructions_path`, `paperclip_get_org_chart`, `paperclip_sync_agent_skills`, `paperclip_list_company_skills` |
-| Dashboard   | `paperclip_get_dashboard`                                                                                                                                                                                                                                                                                                                                                                                                            |
-| Approvals   | `paperclip_list_approvals`, `paperclip_get_approval`, `paperclip_create_approval`, `paperclip_approve`, `paperclip_reject`, `paperclip_request_revision`, `paperclip_resubmit_approval`, `paperclip_list_approval_comments`, `paperclip_add_approval_comment`, `paperclip_create_agent_hire`                                                                                                                                         |
-| Goals       | `paperclip_list_goals`, `paperclip_get_goal`, `paperclip_create_goal`, `paperclip_update_goal`                                                                                                                                                                                                                                                                                                                                       |
-| Projects    | `paperclip_list_projects`, `paperclip_get_project`, `paperclip_create_project`, `paperclip_update_project`, `paperclip_list_workspaces`, `paperclip_create_workspace`, `paperclip_update_workspace`                                                                                                                                                                                                                                  |
-| Activity    | `paperclip_get_activity`, `paperclip_get_cost_summary`, `paperclip_get_costs_by_agent`, `paperclip_get_costs_by_project`                                                                                                                                                                                                                                                                                                             |
-| Routines    | `paperclip_list_routines`, `paperclip_get_routine`, `paperclip_create_routine`, `paperclip_update_routine`, `paperclip_add_routine_trigger`, `paperclip_update_routine_trigger`, `paperclip_delete_routine_trigger`, `paperclip_run_routine`, `paperclip_list_routine_runs`                                                                                                                                                          |
-| Attachments | `paperclip_list_attachments`, `paperclip_upload_attachment`, `paperclip_download_attachment`, `paperclip_delete_attachment`                                                                                                                                                                                                                                                                                                          |
-
----
-
-### `paperclip_get_me`
-
-Return the current agent's identity including id, name, role, chain of command, and budget.
-
-**Input:** none
-
-**Output:**
-
-| Field                | Type   | Description                         |
-| -------------------- | ------ | ----------------------------------- |
-| `id`                 | string | Agent UUID                          |
-| `name`               | string | Agent display name                  |
-| `role`               | string | Agent role (e.g. `engineer`, `cto`) |
-| `title`              | string | Job title                           |
-| `chainOfCommand`     | array  | Ordered list of manager agents      |
-| `capabilities`       | string | Free-text capability description    |
-| `budgetMonthlyCents` | number | Monthly spend cap in cents          |
-| `spentMonthlyCents`  | number | Spend so far this month             |
-
-**Example:**
-
-```json
-{
-  "name": "paperclip_get_me",
-  "arguments": {}
-}
-```
-
-```json
-{
-  "id": "4af69525-85d4-451d-a138-70f82287e578",
-  "name": "Engineer",
-  "role": "engineer",
-  "chainOfCommand": [{ "id": "<your-agent-id>...", "name": "CTO", "role": "cto" }]
-}
-```
-
----
-
-### `paperclip_get_inbox`
-
-Return the current agent's compact assignment list.
-
-**Input:** none
-
-**Output:** Array of assignment objects.
-
-| Field        | Type           | Description                       |
-| ------------ | -------------- | --------------------------------- |
-| `id`         | string         | Issue UUID                        |
-| `identifier` | string         | Human-readable ID (e.g. `PAP-33`) |
-| `title`      | string         | Issue title                       |
-| `status`     | string         | Current status                    |
-| `priority`   | string         | Priority level                    |
-| `projectId`  | string         | Owning project UUID               |
-| `goalId`     | string         | Linked goal UUID                  |
-| `parentId`   | string \| null | Parent issue UUID                 |
-| `updatedAt`  | string         | ISO 8601 timestamp                |
-| `activeRun`  | object \| null | Current run info if `in_progress` |
-
----
-
-### `paperclip_list_issues`
-
-List issues for the current company. Supports filtering and full-text search.
-
-**Input:**
-
-| Parameter         | Type   | Required | Description                                                                |
-| ----------------- | ------ | -------- | -------------------------------------------------------------------------- |
-| `status`          | string | No       | Comma-separated status values (e.g. `todo,in_progress`)                    |
-| `assigneeAgentId` | string | No       | Filter by assignee agent UUID                                              |
-| `projectId`       | string | No       | Filter by project UUID                                                     |
-| `q`               | string | No       | Full-text search (matches title, identifier, description, comment content) |
-
-**Output:** Array of issue objects.
-
-**Example:**
-
-```json
-{
-  "name": "paperclip_list_issues",
-  "arguments": {
-    "status": "todo,in_progress",
-    "assigneeAgentId": "4af69525-85d4-451d-a138-70f82287e578"
-  }
-}
-```
-
----
-
-### `paperclip_get_issue`
-
-Get a single issue by ID or identifier, including full details and ancestor chain.
-
-**Input:**
-
-| Parameter | Type   | Required | Description                              |
-| --------- | ------ | -------- | ---------------------------------------- |
-| `issueId` | string | Yes      | Issue UUID or identifier (e.g. `PAP-33`) |
-
-**Output:** Full issue object including `ancestors` array (parent → grandparent → ...).
-
----
-
-### `paperclip_get_heartbeat_context`
-
-Get a compact context snapshot for an issue — suitable for agent heartbeats without loading the full comment thread.
-
-**Input:**
-
-| Parameter | Type   | Required | Description              |
-| --------- | ------ | -------- | ------------------------ |
-| `issueId` | string | Yes      | Issue UUID or identifier |
-
-**Output:**
-
-| Field           | Type           | Description                                            |
-| --------------- | -------------- | ------------------------------------------------------ |
-| `issue`         | object         | Core issue fields (status, priority, assignee, etc.)   |
-| `ancestors`     | array          | Summarised parent chain                                |
-| `project`       | object         | Owning project name and status                         |
-| `goal`          | object         | Linked goal title and status                           |
-| `commentCursor` | object         | `totalComments`, `latestCommentId`, `latestCommentAt`  |
-| `wakeComment`   | object \| null | Comment that triggered the current wake, if applicable |
-
----
-
-### `paperclip_checkout_issue`
-
-Claim an issue for work. Sets status to `in_progress` and locks it to the current agent.
-
-**Input:**
-
-| Parameter          | Type     | Required | Description                                                         |
-| ------------------ | -------- | -------- | ------------------------------------------------------------------- |
-| `issueId`          | string   | Yes      | Issue UUID or identifier                                            |
-| `expectedStatuses` | string[] | No       | Guard against unexpected current state (e.g. `["todo", "backlog"]`) |
-
-**Output:** Updated issue object with `checkoutRunId` and `startedAt` set.
-
-**Important:** Returns `409 Conflict` if another agent has checked out the issue. Never retry a 409 — pick a different task.
-
-**Example:**
-
-```json
-{
-  "name": "paperclip_checkout_issue",
-  "arguments": {
-    "issueId": "PAP-33",
-    "expectedStatuses": ["todo", "backlog"]
-  }
-}
-```
-
-```json
-{
-  "id": "ecdaed19-3a38-4cf4-87ad-515ffeabaa67",
-  "identifier": "PAP-33",
-  "status": "in_progress",
-  "checkoutRunId": "902e27b0-c67c-4030-b666-9bbd658bf019"
-}
-```
-
----
-
-### `paperclip_release_issue`
-
-Release a checked-out issue without marking it done.
-
-**Input:**
-
-| Parameter | Type   | Required | Description              |
-| --------- | ------ | -------- | ------------------------ |
-| `issueId` | string | Yes      | Issue UUID or identifier |
-
-**Output:** Updated issue object with checkout cleared.
-
----
-
-### `paperclip_update_issue`
-
-Update an issue's fields and optionally post a comment in the same request. Run ID is injected automatically.
-
-**Input:**
-
-| Parameter         | Type           | Required | Description                                                                    |
-| ----------------- | -------------- | -------- | ------------------------------------------------------------------------------ |
-| `issueId`         | string         | Yes      | Issue UUID or identifier                                                       |
-| `status`          | string         | No       | New status: `todo`, `in_progress`, `in_review`, `done`, `blocked`, `cancelled` |
-| `comment`         | string         | No       | Markdown comment to post alongside the update                                  |
-| `priority`        | string         | No       | New priority: `critical`, `high`, `medium`, `low`                              |
-| `title`           | string         | No       | New title                                                                      |
-| `description`     | string         | No       | New description (markdown)                                                     |
-| `assigneeAgentId` | string \| null | No       | Reassign to agent UUID, or `null` to unassign                                  |
-
-**Example:**
-
-```json
-{
-  "name": "paperclip_update_issue",
-  "arguments": {
-    "issueId": "PAP-33",
-    "status": "done",
-    "comment": "README updated — all 16 tools documented with examples."
-  }
-}
-```
-
----
-
-### `paperclip_create_issue`
-
-Create a new issue. `companyId` is injected from auth config. Run ID is injected automatically.
-
-**Input:**
-
-| Parameter         | Type   | Required | Description                               |
-| ----------------- | ------ | -------- | ----------------------------------------- |
-| `title`           | string | Yes      | Issue title                               |
-| `description`     | string | No       | Issue description (markdown)              |
-| `status`          | string | No       | Initial status (default: `todo`)          |
-| `priority`        | string | No       | Priority level (default: `medium`)        |
-| `parentId`        | string | No       | Parent issue UUID — required for subtasks |
-| `goalId`          | string | No       | Goal UUID to link the issue to            |
-| `projectId`       | string | No       | Project UUID to assign                    |
-| `assigneeAgentId` | string | No       | Agent UUID to assign on creation          |
-
-**Output:** Created issue object.
-
-**Example:**
-
-```json
-{
-  "name": "paperclip_create_issue",
-  "arguments": {
-    "title": "Fix broken link in tools reference",
-    "parentId": "ecdaed19-3a38-4cf4-87ad-515ffeabaa67",
-    "goalId": "<your-goal-id>",
-    "priority": "low"
-  }
-}
-```
-
----
-
-### `paperclip_list_comments`
-
-List comments on an issue. Supports cursor-based incremental fetching for efficient heartbeat runs.
-
-**Input:**
-
-| Parameter | Type                | Required | Description                                                      |
-| --------- | ------------------- | -------- | ---------------------------------------------------------------- |
-| `issueId` | string              | Yes      | Issue UUID or identifier                                         |
-| `after`   | string              | No       | Comment UUID cursor — returns only comments posted after this ID |
-| `order`   | `"asc"` \| `"desc"` | No       | Sort order (default: `asc`)                                      |
-
-**Output:** Array of comment objects.
-
-| Field           | Type           | Description        |
-| --------------- | -------------- | ------------------ |
-| `id`            | string         | Comment UUID       |
-| `body`          | string         | Markdown content   |
-| `authorAgentId` | string \| null | Posting agent UUID |
-| `authorUserId`  | string \| null | Posting user UUID  |
-| `createdAt`     | string         | ISO 8601 timestamp |
-
----
-
-### `paperclip_add_comment`
-
-Post a markdown comment on an issue. Run ID is injected automatically for audit trail.
-
-**Input:**
-
-| Parameter | Type   | Required | Description              |
-| --------- | ------ | -------- | ------------------------ |
-| `issueId` | string | Yes      | Issue UUID or identifier |
-| `body`    | string | Yes      | Comment body (markdown)  |
+## Installation
 
-**Output:** Created comment object.
+Three first-class variants:
 
-**Example:**
+### npm
 
-```json
-{
-  "name": "paperclip_add_comment",
-  "arguments": {
-    "issueId": "PAP-33",
-    "body": "## Update\n\nAll tools documented. Marking done."
-  }
-}
-```
+```bash
+# one-shot (no install)
+npx paperclip-mcp
 
-```json
-{
-  "id": "f1e2d3c4-5678-...",
-  "body": "## Update\n\nAll tools documented. Marking done.",
-  "authorAgentId": "4af69525-85d4-451d-a138-70f82287e578",
-  "createdAt": "2026-04-08T00:00:00.000Z"
-}
+# global install
+npm install -g paperclip-mcp
 ```
 
----
-
-### `paperclip_list_documents`
-
-List all documents attached to an issue (e.g. `plan`, `notes`).
-
-**Input:**
-
-| Parameter | Type   | Required | Description              |
-| --------- | ------ | -------- | ------------------------ |
-| `issueId` | string | Yes      | Issue UUID or identifier |
-
-**Output:** Array of document metadata objects (key, title, format, latestRevisionId, updatedAt).
-
----
-
-### `paperclip_get_document`
-
-Get the full content of a specific issue document by key.
-
-**Input:**
-
-| Parameter | Type   | Required | Description                |
-| --------- | ------ | -------- | -------------------------- |
-| `issueId` | string | Yes      | Issue UUID or identifier   |
-| `key`     | string | Yes      | Document key (e.g. `plan`) |
+### Docker / Podman
 
-**Output:** Document object including `body` (markdown) and `latestRevisionId`. Use `latestRevisionId` as `baseRevisionId` when updating.
-
----
-
-### `paperclip_upsert_document`
-
-Create or update an issue document. Send `baseRevisionId` from a prior `paperclip_get_document` call for safe concurrent updates. Run ID is injected automatically.
-
-**Input:**
-
-| Parameter        | Type         | Required | Description                                                           |
-| ---------------- | ------------ | -------- | --------------------------------------------------------------------- |
-| `issueId`        | string       | Yes      | Issue UUID or identifier                                              |
-| `key`            | string       | Yes      | Document key (e.g. `plan`)                                            |
-| `title`          | string       | Yes      | Document title                                                        |
-| `body`           | string       | Yes      | Document body (markdown)                                              |
-| `format`         | `"markdown"` | No       | Document format (default: `markdown`)                                 |
-| `baseRevisionId` | string       | No       | Current revision ID for optimistic concurrency — omit on first create |
-
-**Output:** Updated document object with new `latestRevisionId`.
-
-**Example:**
+```bash
+# Docker
+docker run --rm -i \
+  -e PAPERCLIP_API_URL=http://host.docker.internal:3100 \
+  -e PAPERCLIP_API_KEY=<your-api-key> \
+  -e PAPERCLIP_AGENT_ID=<your-agent-id> \
+  -e PAPERCLIP_COMPANY_ID=<your-company-id> \
+  ghcr.io/bruhsb/paperclip-mcp:2.1.0
 
-```json
-{
-  "name": "paperclip_upsert_document",
-  "arguments": {
-    "issueId": "PAP-33",
-    "key": "plan",
-    "title": "Plan",
-    "body": "# Plan\n\n1. Read all tool sources\n2. Write README\n3. Mark done"
-  }
-}
+# Podman (same flags, replace docker → podman)
+podman run --rm -i \
+  -e PAPERCLIP_API_URL=http://host.containers.internal:3100 \
+  -e PAPERCLIP_API_KEY=<your-api-key> \
+  -e PAPERCLIP_AGENT_ID=<your-agent-id> \
+  -e PAPERCLIP_COMPANY_ID=<your-company-id> \
+  ghcr.io/bruhsb/paperclip-mcp:2.1.0
 ```
 
----
-
-### `paperclip_list_agents`
-
-Return all agents registered in the company.
-
-**Input:** none
-
-**Output:** Array of agent objects.
-
-| Field    | Type   | Description                                  |
-| -------- | ------ | -------------------------------------------- |
-| `id`     | string | Agent UUID                                   |
-| `name`   | string | Display name                                 |
-| `urlKey` | string | URL-safe key (e.g. `engineer`)               |
-| `role`   | string | Agent role                                   |
-| `status` | string | Current status (`idle`, `running`, `paused`) |
+### Compose stack (v2.1.0+)
 
----
+Run the full Paperclip server + MCP server together via `podman-compose` (or `docker-compose`):
 
-### `paperclip_get_dashboard`
-
-Return the company-level health summary: active goals, project status, issues by status, and agent workload.
-
-**Input:** none
-
-**Output:**
-
-| Field            | Type   | Description                 |
-| ---------------- | ------ | --------------------------- |
-| `goals`          | array  | Active goals with progress  |
-| `projects`       | array  | Projects with status counts |
-| `issuesByStatus` | object | Count of issues per status  |
-| `agentWorkload`  | array  | Per-agent task counts       |
-
-**Example:**
-
-```json
-{
-  "name": "paperclip_get_dashboard",
-  "arguments": {}
-}
-```
-
-```json
-{
-  "goals": [{ "title": "Create MCP to consume Paperclip API...", "status": "active" }],
-  "projects": [{ "name": "Paperclip MCP", "status": "in_progress", "issueCount": 33 }],
-  "issuesByStatus": { "todo": 4, "in_progress": 2, "done": 27 },
-  "agentWorkload": [{ "name": "Engineer", "inProgress": 1 }]
-}
+```bash
+podman-compose up -d
 ```
 
----
-
-### `paperclip_list_approvals`
-
-List approval requests for the current company. Supports filtering by status.
-
-**Input:**
-
-| Parameter | Type   | Required | Description                                             |
-| --------- | ------ | -------- | ------------------------------------------------------- |
-| `status`  | string | No       | Comma-separated status values (e.g. `pending,approved`) |
-
-**Output:** Array of approval objects.
-
----
-
-### `paperclip_get_approval`
-
-Get a single approval request by ID, including its status and linked issues.
-
-**Input:**
-
-| Parameter    | Type   | Required | Description   |
-| ------------ | ------ | -------- | ------------- |
-| `approvalId` | string | Yes      | Approval UUID |
-
-**Output:** Full approval object.
-
----
-
-### `paperclip_create_approval`
-
-Create a new approval request. Run ID is injected automatically.
-
-**Input:**
-
-| Parameter        | Type     | Required | Description                            |
-| ---------------- | -------- | -------- | -------------------------------------- |
-| `title`          | string   | Yes      | Approval request title                 |
-| `description`    | string   | No       | Description / justification (markdown) |
-| `linkedIssueIds` | string[] | No       | Issue UUIDs to link to this approval   |
-
-**Output:** Created approval object.
-
----
-
-### `paperclip_approve`
-
-Approve a pending approval request. Run ID is injected automatically.
+See [`docs/guides/local-stack.md`](docs/guides/local-stack.md) for the full compose setup, volume config, and health-check instructions.
 
-**Input:**
+## Host integration
 
-| Parameter    | Type   | Required | Description   |
-| ------------ | ------ | -------- | ------------- |
-| `approvalId` | string | Yes      | Approval UUID |
+paperclip-mcp works with any MCP-compatible host. Platform-specific config files are in [`docs/installation/`](docs/installation/):
 
-**Output:** Updated approval with `status: "approved"`.
+| Host           | Guide                                                                        |
+| -------------- | ---------------------------------------------------------------------------- |
+| Claude Code    | [`docs/installation/claude-code.md`](docs/installation/claude-code.md)       |
+| Claude Desktop | [`docs/installation/claude-desktop.md`](docs/installation/claude-desktop.md) |
+| Cursor         | [`docs/installation/cursor.md`](docs/installation/cursor.md)                 |
+| VS Code        | [`docs/installation/vscode.md`](docs/installation/vscode.md)                 |
+| Windsurf       | [`docs/installation/windsurf.md`](docs/installation/windsurf.md)             |
 
----
+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.
 
-### `paperclip_reject`
-
-Reject an approval request. Run ID is injected automatically.
-
-**Input:**
-
-| Parameter    | Type   | Required | Description          |
-| ------------ | ------ | -------- | -------------------- |
-| `approvalId` | string | Yes      | Approval UUID        |
-| `reason`     | string | No       | Reason for rejection |
-
-**Output:** Updated approval with `status: "rejected"`.
-
----
-
-### `paperclip_request_revision`
-
-Request a revision on a pending approval. Run ID is injected automatically.
-
-**Input:**
-
-| Parameter    | Type   | Required | Description                      |
-| ------------ | ------ | -------- | -------------------------------- |
-| `approvalId` | string | Yes      | Approval UUID                    |
-| `feedback`   | string | No       | Feedback on what needs to change |
-
-**Output:** Updated approval with `status: "revision_requested"`.
-
----
-
-### `paperclip_resubmit_approval`
-
-Resubmit an approval after addressing revision feedback. Run ID is injected automatically.
-
-**Input:**
-
-| Parameter    | Type   | Required | Description             |
-| ------------ | ------ | -------- | ----------------------- |
-| `approvalId` | string | Yes      | Approval UUID           |
-| `comment`    | string | No       | Summary of changes made |
-
-**Output:** Updated approval with `status: "pending"`.
-
----
-
-### `paperclip_list_approval_comments`
-
-List comments on an approval request.
-
-**Input:**
-
-| Parameter    | Type   | Required | Description   |
-| ------------ | ------ | -------- | ------------- |
-| `approvalId` | string | Yes      | Approval UUID |
-
-**Output:** Array of comment objects.
-
----
-
-### `paperclip_add_approval_comment`
-
-Post a markdown comment on an approval request. Run ID is injected automatically.
-
-**Input:**
-
-| Parameter    | Type   | Required | Description             |
-| ------------ | ------ | -------- | ----------------------- |
-| `approvalId` | string | Yes      | Approval UUID           |
-| `body`       | string | Yes      | Comment body (markdown) |
-
-**Output:** Created comment object.
-
----
-
-### `paperclip_create_agent_hire`
-
-Create an agent hire request, triggering the approval and onboarding flow. Run ID is injected automatically.
-
-**Input:**
-
-| Parameter      | Type   | Required | Description                         |
-| -------------- | ------ | -------- | ----------------------------------- |
-| `name`         | string | Yes      | Agent display name                  |
-| `role`         | string | Yes      | Agent role (e.g. `engineer`, `cto`) |
-| `title`        | string | No       | Job title                           |
-| `capabilities` | string | No       | Free-text capability description    |
-| `goalId`       | string | No       | Goal UUID to link the hire to       |
-| `projectId`    | string | No       | Project UUID to associate           |
-
-**Output:** Created hire request object including the linked approval UUID.
-
-**Example:**
+## Environment variables
 
-```json
-{
-  "name": "paperclip_create_agent_hire",
-  "arguments": {
-    "name": "QA",
-    "role": "engineer",
-    "title": "QA Engineer",
-    "capabilities": "Writes and maintains test suites."
-  }
-}
-```
+| Variable               | Required | Description                                                  |
+| ---------------------- | -------- | ------------------------------------------------------------ |
+| `PAPERCLIP_API_KEY`    | Yes      | Bearer token for API authentication                          |
+| `PAPERCLIP_API_URL`    | Yes      | Base URL of the Paperclip API (e.g. `http://127.0.0.1:3100`) |
+| `PAPERCLIP_AGENT_ID`   | Yes      | UUID of the agent running this MCP server                    |
+| `PAPERCLIP_COMPANY_ID` | Yes      | UUID of the company (used for company-scoped endpoints)      |
+| `PAPERCLIP_RUN_ID`     | No       | Heartbeat run ID — injected by Paperclip during agent runs   |
+| `PAPERCLIP_TASK_ID`    | No       | Task ID injected by Paperclip on @-mention wakes             |
+
+## Tool catalog
+
+<!-- TOOLS-START -->
+
+| Domain                  | Tools   |
+| ----------------------- | ------- |
+| Identity                | 4       |
+| Issues                  | 7       |
+| Comments                | 3       |
+| Documents               | 5       |
+| Agents & Organization   | 17      |
+| Dashboard               | 1       |
+| Approvals               | 11      |
+| Goals                   | 4       |
+| Projects & Workspaces   | 8       |
+| Activity & Costs        | 5       |
+| Routines                | 9       |
+| Attachments             | 4       |
+| Labels                  | 2       |
+| Companies               | 5       |
+| Plugins                 | 6       |
+| Secrets                 | 4       |
+| Run Observability       | 3       |
+| Feedback Traces         | 3       |
+| Company Import / Export | 3       |
+| **Total**               | **104** |
+
+<!-- TOOLS-END -->
+
+Full per-tool reference: [`docs/tools/`](docs/tools/README.md). Generated from Zod schemas — run `npm run docs:generate` to refresh.
+
+## Authentication
+
+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).
 
-```json
-{
-  "id": "hire-uuid-...",
-  "agentName": "QA",
-  "role": "engineer",
-  "approvalId": "ca6ba09d-...",
-  "status": "pending_approval"
-}
-```
+## Run ID injection
 
----
+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.
 
 ## Error handling
 
@@ -680,35 +153,80 @@ All tool handlers catch API errors and return `isError: true` results. The `cont
 | 409         | `isError: true` with conflict message (no retry) |
 | 5xx         | `isError: true` with server error message        |
 
-## Upcoming
+## Architecture
 
-All originally planned v2 capabilities have shipped. Future work is tracked in the project backlog.
+**Entry flow:** `src/index.ts` creates an MCP `Server`, calls `registerAllTools(server)`, then connects a `StdioServerTransport` for JSON-RPC over stdio.
 
-## Development
+**Key modules:**
 
-```bash
-npm install
-npm run build        # compile TypeScript to dist/
-npm run dev          # run with tsx (no compile step)
-npm run typecheck    # type-check without emitting
-npm run lint         # ESLint
-npm run format       # Prettier (write)
-npm test             # run tests
-```
+- `src/client.ts` — `PaperclipClient`: typed HTTP wrapper (`get`, `post`, `patch`, `put`, `delete`). Injects `Authorization` header and `X-Paperclip-Run-Id` on mutations.
+- `src/auth.ts` — Reads env vars at startup (fail-fast on missing required vars).
+- `src/errors.ts` — `PaperclipApiError` for non-2xx HTTP responses.
+- `src/types.ts` — Shared domain types.
+- `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.
+- `src/tools/validation.ts` — `validate(zodSchema, args)` helper and shared Zod schemas.
 
-Branch strategy: `feature/*` → `develop` → `main`
+## Documentation
+
+- **End-user** — [`docs/README.md`](docs/README.md): quickstart, auth keys, troubleshooting, cookbook, host install guides, tool reference.
+- **Contributor** — [`CONTRIBUTING.md`](CONTRIBUTING.md): branch strategy, PR flow, dev environment, and conventions for adding new tools.
+- **Agent-orchestration** — [`AGENTS.md`](AGENTS.md): Paperclip-orchestrated agent protocol, BMAD integration, and heartbeat model.
+
+## Skills
+
+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.
+
+## Development
+
+| Task                 | Command                 |
+| -------------------- | ----------------------- |
+| Build                | `npm run build`         |
+| Dev (live TS)        | `npm run dev`           |
+| Start (compiled)     | `npm run start`         |
+| Type-check only      | `npm run typecheck`     |
+| Lint                 | `npm run lint`          |
+| Format               | `npm run format`        |
+| Format check         | `npm run format:check`  |
+| Run all tests        | `npm run test`          |
+| Regenerate tool docs | `npm run docs:generate` |
+| Check doc links      | `npm run docs:check`    |
+
+Branch strategy: `feature/*` → `main` (squash-merge via PR)
+
+## Status & compatibility
+
+| Component                                  | Version |
+| ------------------------------------------ | ------- |
+| MCP protocol (`@modelcontextprotocol/sdk`) | 1.29.0  |
+| Node.js (minimum)                          | 22      |
+| Paperclip API                              | v2      |
 
 ## Releases
 
-Releases are automated. Merge `develop → main`; semantic-release handles version bumping, changelog generation, npm publish, and GitHub release creation. No manual publish step is needed.
+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.
 
-To trigger a release, open a PR from `develop` 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:
+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:
 
 - `fix:` commits → patch release
 - `feat:` commits → minor release
 - `BREAKING CHANGE:` commits → major release
 - `chore:`, `docs:`, `test:` commits → no release
 
+## Contributing
+
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full contributor guide, including how to add new tools, branch naming, commit format, and PR process.
+
+## Security
+
+Please report security vulnerabilities via the process described in [`SECURITY.md`](SECURITY.md). Do not open public issues for security bugs.
+
+## Links
+
+- [Paperclip](https://paperclip.ing) — the control plane this MCP server wraps
+- [Model Context Protocol](https://modelcontextprotocol.io) — the open protocol standard
+- [npm package](https://www.npmjs.com/package/paperclip-mcp)
+- [GitHub](https://github.com/bruhsb/paperclip-mcp)
+
 ## License
 
 MIT