@tickernelz/paperclip-pro-mcp-server 2026.926.1 → 2026.926.3

package/README.md

@@ -23,7 +23,10 @@ Inside an active heartbeat, Paperclip also injects `PAPERCLIP_RUNTIME_TOOLS_*` v
 
 The tool surface is generated from the server's OpenAPI registry, so it tracks the API. Two independent filters decide what a client sees:
 
-- **Toolset.** `core` is the default: the curated hand-written tools plus the everyday generated ones (61 tools, ~94 KB of `tools/list` JSON). `extended` adds the rest of the generated surface (all toolsets, management role: 715 tools, ~537 KB). Select with `PAPERCLIP_MCP_TOOLSETS=core,extended` or `--toolsets core,extended`; the CLI flag wins, an empty or unknown value falls back to `core`.
+- **Toolset.** `core` is the default: the curated hand-written tools plus the everyday generated ones (61 tools, ~36 KB of `tools/list` JSON, ~9k tokens). `extended` is a **superset of `core`**, not a sibling: selecting it registers `core` plus the rest of the generated surface (442 tools, ~210 KB; an agent carrying company authority also sees the board-authority tools, 719 tools, ~344 KB). `all` is the same union of everything. Select with `PAPERCLIP_MCP_TOOLSETS=core,extended` or `--toolsets core,extended`; the CLI flag wins, an empty or unknown value falls back to `core`. Requesting `extended` alone therefore never drops a core-only tool such as `paperclipCreateChildIssue` or the watchdog pair.
+- **Names.** Generated tool names are capped at 40 characters (`NAME_LENGTH_LIMIT` in `scripts/generate-mcp-tools.ts`) because a host that truncates an over-long name cannot call the truncated form. An over-long name is shortened by dropping redundant path words, then by a deterministic six-hex path digest, so a name is stable across regenerations.
+- **Parameter names.** A bare `{id}` or `{key}` path placeholder is renamed after the resource segment that precedes it (`/issues/{id}` becomes `issueId`, `/cases/{key}` becomes `caseId`), so a caller never has to guess which `id` a tool wants. The rename is internal: the request path substitution and the wire path are unchanged.
+- **Shared description text.** Statements a route repeats on every one of its operations are lifted out of the per-tool descriptions into `src/generated/shared-tool-notes.json`, surfaced once through `sharedToolNotes()` on the MCP `initialize` result. Each tool description keeps only what is specific to that operation.
 - **Authority.** Every generated tool carries `authority`: `agent` for routes an ordinary agent key can call, `board` for routes whose handler asserts board authority (the deciding guard and its `file:line` are recorded in `src/generated/api-tools.json`). Board-authority tools are registered only when the caller has a management role, taken from `PAPERCLIP_AGENT_ROLE` or, when that is unset, from `GET /api/agents/me` at startup.
 
 Instance-admin, auth/setup/cli-auth, protocol/websocket and credential-reveal routes are excluded for everyone; `src/generated/excluded-operations.json` records each excluded operation with its reason and guard evidence.
@@ -56,15 +59,33 @@ The Paperclip server hosts the same tool surface at `POST /api/mcp/paperclip`, s
 
 - Authentication is the REST API's: `Authorization: Bearer <run agent key>` plus `X-Paperclip-Run-Id`. Only agent actors are accepted; a board actor gets `403`, a missing credential `401`.
 - `companyId` and `agentId` come from the authenticated agent, never from a request header, and board-authority tools are exposed only when that agent's `agentAuthorityCapabilities` include company-level authority.
-- Toolsets come from `?toolsets=core,extended`; absent, empty or unknown values fall back to `core`.
+- Toolsets come from `?toolsets=core,extended`; absent, empty or unknown values fall back to `core`, and `extended` implies `core` rather than replacing it.
 - Each `tools/call` re-enters the REST API over the server's own loopback address with the caller's bearer token, so every route guard, record rule and audit hook runs exactly as it does for a direct API call.
 
 Tool definitions are built once per process and per (toolset, authority) variant; the `tools/list` payload is memoized with them.
 
+## Error contract
+
+A `tools/call` that fails is still a JSON-RPC success with a `result`, but the result carries the MCP error flag so a host cannot mistake it for data:
+
+- **`isError: true`** on every failure path: an API rejection (`PaperclipApiError`), a bad argument (zod validation), and any other thrown value. A successful call omits the field.
+- **`_meta["paperclip/httpStatus"]`** carries the original HTTP status when the failure came from the API, so a host can tell a `403` from a `500` without parsing the text. It is absent for argument and unknown failures.
+- **Argument failures are flattened to one line per problem**, `issueId: expected string, received undefined`, instead of a stringified JSON array inside a JSON string. API failures keep the structured `{ error, status, method, path, body }` text payload.
+
+```json
+{
+  "content": [{ "type": "text", "text": "GET /issues/X failed with 403: Board access required" }],
+  "isError": true,
+  "_meta": { "paperclip/httpStatus": 403 }
+}
+```
+
 ## Tool Surface
 
 Curated tools keep their names and behaviour: the run-scoped `connections_search` and `connection_request`, the issue/comment/document/approval/workspace helpers (`paperclipMe`, `paperclipInboxLite`, `paperclipListIssues`, `paperclipCheckoutIssue`, `paperclipGetHeartbeatContext`, `paperclipUpdateIssue`, `paperclipAddComment`, `paperclipUpsertIssueDocument`, `paperclipGetIssueWorkspaceRuntime`, `paperclipApprovalDecision`, and the rest), and the `paperclipApiRequest` escape hatch.
 
+`paperclipListIssues` returns at most `limit` issues and defaults to **25**, not the route's 500, so one call cannot pull the whole board into context. It accepts `limit` (max 1000), `offset`, `view: "compact"`, `updatedSince`, `sortField`, `sortDir` and `includeConversations`, alongside the existing filters. Raise `limit` explicitly when a complete listing is genuinely needed.
+
 Everything else is generated from the OpenAPI registry into `src/generated/api-tools.json`, one tool per operation, with a zod input schema built from its path parameters, query parameters and JSON body, `companyId` filled from `PAPERCLIP_COMPANY_ID` when the route is company-scoped, and MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`).
 
 `paperclipApiRequest` is limited to paths under `/api` and JSON bodies. It is

package/dist/board-surface.d.ts

@@ -0,0 +1,11 @@
+import type { GeneratedToolSpec } from "./generated-tools.js";
+export declare const AGENT_ADMITTING_GUARDS: Readonly<Record<string, true>>;
+export declare const BOARD_ONLY_GUARDS: Readonly<Record<string, true>>;
+export declare const ACTOR_NEUTRAL_GUARDS: Readonly<Record<string, true>>;
+export declare function classifiedGuards(): string[];
+export type BoardSurfaceContext = {
+    capabilities: readonly string[];
+    permissionKeys: ReadonlySet<string>;
+};
+export declare function boardToolAdvertised(spec: Pick<GeneratedToolSpec, "authority" | "authorityCapability" | "authoritySource" | "guards" | "permissions">, context: BoardSurfaceContext): boolean;
+//# sourceMappingURL=board-surface.d.ts.map

package/dist/board-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"board-surface.d.ts","sourceRoot":"","sources":["../src/board-surface.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D,eAAO,MAAM,sBAAsB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAmBjE,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CA2B5D,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAiB/D,CAAC;AAEF,wBAAgB,gBAAgB,IAAI,MAAM,EAAE,CAM3C;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IAChC,cAAc,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;CACrC,CAAC;AAWF,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,CACR,iBAAiB,EACjB,WAAW,GAAG,qBAAqB,GAAG,iBAAiB,GAAG,QAAQ,GAAG,aAAa,CACnF,EACD,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAUT"}

package/dist/board-surface.js

@@ -0,0 +1,96 @@
+import { AGENT_MEMBER_AUTHORITY_PERMISSION_KEYS } from "@tickernelz/paperclip-pro-shared";
+export const AGENT_ADMITTING_GUARDS = {
+    assertBoardCanManageAgentsForCompany: true,
+    assertBoardOrAgent: true,
+    assertBoardOrAgentAuthority: true,
+    assertBoardOrgOrAgentAuthority: true,
+    assertCanGenerateOpenClawInvitePrompt: true,
+    assertCanReadConfigurations: true,
+    assertCanResolveProposal: true,
+    assertCompanyAccess: true,
+    assertCompanyPermission: true,
+    assertIssueThreadInteractionWithdrawalAllowed: true,
+    assertIssueWriteInfluenceAllowed: true,
+    assertPendingReviewInteractionVerdictAllowed: true,
+    assertSameCompanyCeoAgentOrBoard: true,
+    assertScopedApiAuth: true,
+    assertSuggestedTaskEffectsAllowed: true,
+    hasAgentAuthority: true,
+    hasCompanyAccess: true,
+    requirePluginConfigCompanyId: true,
+};
+export const BOARD_ONLY_GUARDS = {
+    assertAgentAuditPermission: true,
+    assertAiConnectionCreateAccess: true,
+    assertBoard: true,
+    assertBoardAnyToolPermission: true,
+    assertBoardMutationAccess: true,
+    assertBoardOrgAccess: true,
+    assertBoardPermission: true,
+    assertCanAccessInstanceEnvironments: true,
+    assertCanManageCompanyMember: true,
+    assertCanManageInstanceSettings: true,
+    assertCanReadInstanceEnvironments: true,
+    assertConnectionManager: true,
+    assertEndpointAccess: true,
+    assertEndpointManagementAccess: true,
+    assertIdentityLinkAccess: true,
+    assertImportTargetAccess: true,
+    assertInstanceAdmin: true,
+    assertLocalOperator: true,
+    assertPluginBridgeScope: true,
+    assertToolAppMutationAccess: true,
+    assertToolConnectionAccess: true,
+    assertToolConnectionConfigureAccess: true,
+    assertToolsAdmin: true,
+    assertToolsRuntimeManage: true,
+    requireBoardUser: true,
+    requireBoardUserId: true,
+};
+export const ACTOR_NEUTRAL_GUARDS = {
+    assertAccessAdminVisible: true,
+    assertAdapterCodeInstallAllowed: true,
+    assertAdapterManagementVisible: true,
+    assertAuthenticated: true,
+    assertCanTestAsAgent: true,
+    assertCompanyScopeReadAllowed: true,
+    assertEnvironmentSelectionForCompany: true,
+    assertLocalLoginAvailable: true,
+    assertNoHiddenSettingChanges: true,
+    assertPluginManagementVisible: true,
+    assertQueueMutationTarget: true,
+    assertRuntimeManageAllowed: true,
+    getActorInfo: true,
+    requireEnabled: true,
+    requireImportTransferRun: true,
+    requireLocalFolderDeclaration: true,
+};
+export function classifiedGuards() {
+    return [
+        ...Object.keys(AGENT_ADMITTING_GUARDS),
+        ...Object.keys(BOARD_ONLY_GUARDS),
+        ...Object.keys(ACTOR_NEUTRAL_GUARDS),
+    ].sort();
+}
+const IMPLICIT_MEMBER_PERMISSION_KEYS = new Set(AGENT_MEMBER_AUTHORITY_PERMISSION_KEYS);
+function permissionHeld(key, context) {
+    if (context.permissionKeys.has(key))
+        return true;
+    return IMPLICIT_MEMBER_PERMISSION_KEYS.has(key) && context.capabilities.includes("company:members");
+}
+export function boardToolAdvertised(spec, context) {
+    if (spec.authority !== "board")
+        return true;
+    if (spec.authoritySource === "handler")
+        return false;
+    if (spec.guards.some((guard) => BOARD_ONLY_GUARDS[guard] === true))
+        return false;
+    if (!spec.guards.some((guard) => AGENT_ADMITTING_GUARDS[guard] === true))
+        return false;
+    const capability = spec.authorityCapability;
+    if (capability !== null && capability !== undefined && !context.capabilities.includes(capability)) {
+        return false;
+    }
+    return spec.permissions.every((key) => permissionHeld(key, context));
+}
+//# sourceMappingURL=board-surface.js.map

package/dist/board-surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"board-surface.js","sourceRoot":"","sources":["../src/board-surface.ts"],"names":[],"mappings":"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"}

package/dist/board-surface.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=board-surface.test.d.ts.map

package/dist/board-surface.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"board-surface.test.d.ts","sourceRoot":"","sources":["../src/board-surface.test.ts"],"names":[],"mappings":""}

package/dist/board-surface.test.js

@@ -0,0 +1,216 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { describe, expect, it } from "vitest";
+import { AGENT_MEMBER_AUTHORITY_PERMISSION_KEYS, agentAuthorityCapabilities, } from "@tickernelz/paperclip-pro-shared";
+import { ACTOR_NEUTRAL_GUARDS, AGENT_ADMITTING_GUARDS, BOARD_ONLY_GUARDS, boardToolAdvertised, classifiedGuards, } from "./board-surface.js";
+import { generatedToolSpecs } from "./generated-tools.js";
+const GUARD_DIRS = [
+    new URL("../../../server/src/routes/", import.meta.url),
+    new URL("../../../server/src/services/", import.meta.url),
+];
+function routeSource() {
+    return GUARD_DIRS.flatMap((dir) => readdirSync(dir)
+        .filter((name) => name.endsWith(".ts") && !name.endsWith(".test.ts"))
+        .map((name) => readFileSync(new URL(name, dir), "utf8"))).join("\n");
+}
+const CEO = {
+    capabilities: agentAuthorityCapabilities("ceo"),
+    permissionKeys: new Set(),
+};
+function probeOnlyBoardSpecs() {
+    return generatedToolSpecs().filter((spec) => spec.authority === "board" && (spec.boardGuard ?? "").startsWith("probe:"));
+}
+function grantsAdmitActor(spec, context) {
+    if (spec.guards.some((guard) => BOARD_ONLY_GUARDS[guard] === true))
+        return false;
+    if (!spec.guards.some((guard) => AGENT_ADMITTING_GUARDS[guard] === true))
+        return false;
+    const capability = spec.authorityCapability;
+    if (capability != null && !context.capabilities.includes(capability))
+        return false;
+    return spec.permissions.every((key) => context.permissionKeys.has(key) ||
+        (AGENT_MEMBER_AUTHORITY_PERMISSION_KEYS.includes(key) &&
+            context.capabilities.includes("company:members")));
+}
+function actorHoldingEverything(spec) {
+    return {
+        capabilities: spec.authorityCapability == null
+            ? CEO.capabilities
+            : [...CEO.capabilities, spec.authorityCapability],
+        permissionKeys: new Set(spec.permissions),
+    };
+}
+describe("board surface classification", () => {
+    it("classifies every guard that can decide whether a board tool is advertised", () => {
+        const classified = new Set(classifiedGuards());
+        const seen = new Set();
+        for (const spec of generatedToolSpecs()) {
+            if (spec.authority !== "board")
+                continue;
+            for (const guard of spec.guards) {
+                if (!classified.has(guard))
+                    seen.add(guard);
+            }
+        }
+        expect([...seen].sort()).toEqual([]);
+    });
+    it("names guards that exist in the route source", () => {
+        const source = routeSource();
+        const missing = classifiedGuards().filter((guard) => !source.includes(`function ${guard}(`) && !source.includes(`const ${guard} =`));
+        expect(missing).toEqual([]);
+    });
+    it("classifies each guard exactly once", () => {
+        const groups = [
+            Object.keys(AGENT_ADMITTING_GUARDS),
+            Object.keys(BOARD_ONLY_GUARDS),
+            Object.keys(ACTOR_NEUTRAL_GUARDS),
+        ];
+        const all = groups.flat();
+        expect(new Set(all).size).toBe(all.length);
+    });
+    it("records only capabilities the agent authority list can grant", () => {
+        const source = readFileSync(new URL("../../../packages/shared/src/agent-authority.ts", import.meta.url), "utf8");
+        for (const spec of generatedToolSpecs()) {
+            if (spec.authorityCapability === null)
+                continue;
+            expect(source).toContain(`"${spec.authorityCapability}"`);
+        }
+    });
+    it("records a capability only where the handler asserts an authority guard", () => {
+        const authorityGuards = [
+            "assertAgentAuthority",
+            "assertBoardOrAgentAuthority",
+            "assertBoardOrgOrAgentAuthority",
+        ];
+        for (const spec of generatedToolSpecs()) {
+            if (spec.authorityCapability === null)
+                continue;
+            expect(spec.guards.some((guard) => authorityGuards.includes(guard))).toBe(true);
+        }
+    });
+});
+describe("boardToolAdvertised", () => {
+    const spec = (overrides) => ({
+        operationId: "GET /api/x",
+        authority: "board",
+        authorityCapability: null,
+        authoritySource: "default",
+        guards: [],
+        permissions: [],
+        boardGuard: null,
+        ...overrides,
+    });
+    it("advertises non-board tools regardless of grants", () => {
+        expect(boardToolAdvertised(spec({ authority: "agent" }), { capabilities: [], permissionKeys: new Set() })).toBe(true);
+    });
+    it("withholds a board tool whose handler asserts a board-only guard", () => {
+        expect(boardToolAdvertised(spec({
+            authoritySource: "handler",
+            guards: ["assertBoard"],
+            boardGuard: "assertBoard@chat-channels.ts:1",
+        }), CEO)).toBe(false);
+    });
+    it("withholds a board tool whose handler guards no agent past, even with a granting capability", () => {
+        expect(boardToolAdvertised(spec({
+            authoritySource: "handler",
+            guards: ["assertSameCompanyCeoAgentOrBoard"],
+            authorityCapability: "company:settings",
+            boardGuard: "assertSameCompanyCeoAgentOrBoard@export.ts:1",
+        }), CEO)).toBe(false);
+    });
+    it("withholds a board tool that no agent-admitting guard reaches", () => {
+        expect(boardToolAdvertised(spec({ guards: ["assertAuthenticated"] }), CEO)).toBe(false);
+    });
+    it("advertises a board tool the agent authority guard reaches", () => {
+        expect(boardToolAdvertised(spec({ guards: ["assertBoardOrAgentAuthority"] }), CEO)).toBe(true);
+    });
+    it("withholds a board tool whose recorded capability the actor lacks", () => {
+        const tool = spec({ guards: ["assertBoardOrAgentAuthority"], authorityCapability: "company:agents" });
+        expect(boardToolAdvertised(tool, CEO)).toBe(true);
+        expect(boardToolAdvertised(tool, {
+            capabilities: ["work:read", "work:issues", "work:routines"],
+            permissionKeys: new Set(),
+        })).toBe(false);
+    });
+    it("withholds a board tool whose permission key the actor lacks", () => {
+        const tool = spec({ guards: ["assertCompanyPermission"], permissions: ["users:manage_permissions"] });
+        expect(boardToolAdvertised(tool, {
+            capabilities: CEO.capabilities,
+            permissionKeys: new Set(["users:manage_permissions"]),
+        })).toBe(true);
+        expect(boardToolAdvertised(tool, { capabilities: CEO.capabilities, permissionKeys: new Set() })).toBe(false);
+    });
+    it("honours the implicit member grant the permission guard really allows", () => {
+        const tool = spec({ guards: ["assertCompanyPermission"], permissions: ["users:invite"] });
+        expect(boardToolAdvertised(tool, CEO)).toBe(true);
+        expect(boardToolAdvertised(tool, {
+            capabilities: CEO.capabilities.filter((capability) => capability !== "company:members"),
+            permissionKeys: new Set(),
+        })).toBe(false);
+    });
+    it("keeps the implicit member keys in step with the shared list", () => {
+        expect([...AGENT_MEMBER_AUTHORITY_PERMISSION_KEYS]).toContain("users:invite");
+    });
+});
+describe("probe-derived board evidence", () => {
+    it("records the probe reason as evidence about the probe actor, never as a board guard", () => {
+        for (const spec of probeOnlyBoardSpecs()) {
+            expect(spec.authoritySource).toBe("probe");
+            expect(spec.boardGuard).toMatch(/^probe:/);
+        }
+    });
+    it("advertises a ceo the export-fidelity tool a ceo agent really reaches", () => {
+        const spec = generatedToolSpecs().find((entry) => entry.name === "paperclipGetExportFidelity");
+        expect(spec).toBeDefined();
+        expect(spec.guards).toContain("assertSameCompanyCeoAgentOrBoard");
+        expect(boardToolAdvertised(spec, CEO)).toBe(true);
+    });
+    it("keeps a probe-only tool that no agent-admitting guard reaches hidden", () => {
+        const spec = generatedToolSpecs().find((entry) => entry.name === "paperclipListIssueFeedbackTraces");
+        expect(spec).toBeDefined();
+        expect(spec.boardGuard).toMatch(/^probe:/);
+        expect(spec.guards).toEqual([]);
+        expect(boardToolAdvertised(spec, CEO)).toBe(false);
+    });
+    it("decides every probe-only board tool from its recorded guards alone", () => {
+        const specs = probeOnlyBoardSpecs();
+        expect(specs.length).toBe(19);
+        for (const spec of specs) {
+            const actor = actorHoldingEverything(spec);
+            expect(boardToolAdvertised(spec, actor), spec.name).toBe(grantsAdmitActor(spec, actor));
+        }
+    });
+    it("advertises exactly the probe-only board tools a ceo really reaches", () => {
+        const advertised = probeOnlyBoardSpecs()
+            .filter((spec) => boardToolAdvertised(spec, CEO))
+            .map((spec) => spec.name)
+            .sort();
+        expect(advertised).toEqual([
+            "paperclipGetExportFidelity",
+            "paperclipGetUserMeInboxAgentPolicy",
+            "paperclipListAgentConfigurations",
+        ]);
+    });
+});
+describe("board pruning effect", () => {
+    it("drops the bulk of the board-authority surface for a ceo actor", () => {
+        const board = generatedToolSpecs().filter((spec) => spec.authority === "board");
+        const advertised = board.filter((spec) => boardToolAdvertised(spec, CEO));
+        expect(board.length).toBeGreaterThan(250);
+        expect(advertised.length).toBeLessThan(40);
+        const before = JSON.stringify(board).length;
+        const after = JSON.stringify(advertised).length;
+        expect(after / before).toBeLessThan(0.15);
+    });
+    it("grows the ceo listing by exactly the probe-only tools its own guards admit", () => {
+        const board = generatedToolSpecs().filter((spec) => spec.authority === "board");
+        const advertised = board.filter((spec) => boardToolAdvertised(spec, CEO));
+        const fromProbe = advertised.filter((spec) => (spec.boardGuard ?? "").startsWith("probe:"));
+        const fromRegistry = advertised.filter((spec) => spec.authoritySource === "registry");
+        expect(advertised.length).toBe(fromProbe.length + fromRegistry.length);
+        expect(fromProbe.map((spec) => spec.name).sort()).toEqual(probeOnlyBoardSpecs()
+            .filter((spec) => grantsAdmitActor(spec, CEO))
+            .map((spec) => spec.name)
+            .sort());
+    });
+});
+//# sourceMappingURL=board-surface.test.js.map

package/dist/board-surface.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"board-surface.test.js","sourceRoot":"","sources":["../src/board-surface.test.ts"],"names":[],"mappings":"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"}

package/dist/catalog.d.ts

@@ -1,9 +1,12 @@
+import { type BoardSurfaceContext } from "./board-surface.js";
 import type { PaperclipApiClient } from "./client.js";
 import { type JsonSchemaObject } from "./lean-schema.js";
 import type { ToolsetName } from "./tool-overrides.js";
 import { type ToolAnnotations, type ToolDefinition } from "./tools.js";
 export { PaperclipApiClient } from "./client.js";
 export { hasManagementAuthority, parseToolsets } from "./config.js";
+export { ACTOR_NEUTRAL_GUARDS, AGENT_ADMITTING_GUARDS, BOARD_ONLY_GUARDS, boardToolAdvertised, classifiedGuards, } from "./board-surface.js";
+export type { BoardSurfaceContext } from "./board-surface.js";
 export type { ToolsetName } from "./tool-overrides.js";
 export type { ToolDefinition } from "./tools.js";
 export type ToolListing = {
@@ -13,9 +16,21 @@ export type ToolListing = {
         inputSchema: JsonSchemaObject;
         annotations?: ToolAnnotations;
     }>;
+    nextCursor?: string;
+};
+export declare const DEFAULT_PAGE_SIZE = 1000;
+export declare class InvalidCursorError extends Error {
+    constructor(cursor: string);
+}
+export declare function resolvePageSize(env?: NodeJS.ProcessEnv): number;
+export declare function paginateListing(listing: ToolListing, cursor: string | null | undefined, pageSize: number): ToolListing;
+export type CatalogOptions = {
+    boardSurface?: BoardSurfaceContext;
+    cursor?: string | null;
+    pageSize?: number;
 };
 /** Tool definitions bound to one caller, sharing schema and listing work per variant. */
-export declare function paperclipToolCatalog(client: PaperclipApiClient, toolsets: ReadonlyArray<ToolsetName>, management: boolean): {
+export declare function paperclipToolCatalog(client: PaperclipApiClient, toolsets: ReadonlyArray<ToolsetName>, management: boolean, options?: CatalogOptions): {
     definitions: ToolDefinition[];
     listing: ToolListing;
 };

package/dist/catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAyB,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAE9F,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACpE,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,KAAK,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,gBAAgB,CAAC;QAC9B,WAAW,CAAC,EAAE,eAAe,CAAC;KAC/B,CAAC,CAAC;CACJ,CAAC;AAIF,yFAAyF;AACzF,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,aAAa,CAAC,WAAW,CAAC,EACpC,UAAU,EAAE,OAAO,GAClB;IAAE,WAAW,EAAE,cAAc,EAAE,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CAuBzD"}
+{"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AACA,OAAO,EAAuB,KAAK,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AACnF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGtD,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,EAAyB,KAAK,eAAe,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAE9F,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,iBAAiB,EACjB,mBAAmB,EACnB,gBAAgB,GACjB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,YAAY,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACvD,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,EAAE,KAAK,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,gBAAgB,CAAC;QAC9B,WAAW,CAAC,EAAE,eAAe,CAAC;KAC/B,CAAC,CAAC;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,MAAM,EAAE,MAAM,EAGzB;CACF;AAED,wBAAgB,eAAe,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAG5E;AAYD,wBAAgB,eAAe,CAC7B,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACjC,QAAQ,EAAE,MAAM,GACf,WAAW,CAQb;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,YAAY,CAAC,EAAE,mBAAmB,CAAC;IACnC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,CAAC;AAyBF,yFAAyF;AACzF,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,aAAa,CAAC,WAAW,CAAC,EACpC,UAAU,EAAE,OAAO,EACnB,OAAO,GAAE,cAAmB,GAC3B;IAAE,WAAW,EAAE,cAAc,EAAE,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE,CA+BzD"}

package/dist/catalog.js

@@ -1,29 +1,85 @@
 import { z } from "zod";
+import { boardToolAdvertised } from "./board-surface.js";
+import { expandToolsetUnion } from "./config.js";
 import { bindGeneratedTools, prepareGeneratedTools } from "./generated-tools.js";
 import { leanJsonSchema } from "./lean-schema.js";
 import { createToolDefinitions } from "./tools.js";
 export { PaperclipApiClient } from "./client.js";
 export { hasManagementAuthority, parseToolsets } from "./config.js";
+export { ACTOR_NEUTRAL_GUARDS, AGENT_ADMITTING_GUARDS, BOARD_ONLY_GUARDS, boardToolAdvertised, classifiedGuards, } from "./board-surface.js";
+export const DEFAULT_PAGE_SIZE = 1000;
+export class InvalidCursorError extends Error {
+    constructor(cursor) {
+        super(`Invalid tools/list cursor: ${cursor}`);
+        this.name = "InvalidCursorError";
+    }
+}
+export function resolvePageSize(env = process.env) {
+    const parsed = Number.parseInt(env.PAPERCLIP_MCP_PAGE_SIZE?.trim() ?? "", 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : DEFAULT_PAGE_SIZE;
+}
+function encodeCursor(offset) {
+    return Buffer.from(String(offset), "utf8").toString("base64url");
+}
+function decodeCursor(cursor) {
+    const decoded = Buffer.from(cursor, "base64url").toString("utf8");
+    if (!/^\d+$/.test(decoded))
+        throw new InvalidCursorError(cursor);
+    return Number.parseInt(decoded, 10);
+}
+export function paginateListing(listing, cursor, pageSize) {
+    const offset = cursor ? decodeCursor(cursor) : 0;
+    if (offset > listing.tools.length)
+        throw new InvalidCursorError(cursor ?? "");
+    const tools = listing.tools.slice(offset, offset + pageSize);
+    const nextOffset = offset + tools.length;
+    return nextOffset < listing.tools.length
+        ? { tools, nextCursor: encodeCursor(nextOffset) }
+        : { tools };
+}
 const listings = new Map();
+function listingKey(toolsets, management, surface) {
+    const base = `${[...toolsets].sort().join(",")}|${management ? "management" : "agent"}`;
+    if (!management || !surface)
+        return base;
+    return `${base}|${[...surface.capabilities].sort().join(",")}|${[...surface.permissionKeys].sort().join(",")}`;
+}
+function toListingEntries(definitions) {
+    return definitions.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: leanJsonSchema(z.toJSONSchema(tool.schema, { target: "draft-7", io: "input" })),
+        ...(tool.annotations ? { annotations: tool.annotations } : {}),
+    }));
+}
 /** Tool definitions bound to one caller, sharing schema and listing work per variant. */
-export function paperclipToolCatalog(client, toolsets, management) {
+export function paperclipToolCatalog(client, toolsets, management, options = {}) {
+    const selected = expandToolsetUnion(toolsets);
     const curated = createToolDefinitions(client);
     const curatedNames = new Set(curated.map((tool) => tool.name));
-    const generated = bindGeneratedTools(prepareGeneratedTools(toolsets, management), client).filter((tool) => !curatedNames.has(tool.name));
-    const definitions = [...curated, ...generated];
-    const key = `${[...toolsets].sort().join(",")}|${management ? "management" : "agent"}`;
+    const prepared = prepareGeneratedTools(selected, management);
+    const definitions = [
+        ...curated,
+        ...bindGeneratedTools(prepared, client).filter((tool) => !curatedNames.has(tool.name)),
+    ];
+    const key = listingKey(selected, management, options.boardSurface);
     let listing = listings.get(key);
     if (!listing) {
-        listing = {
-            tools: definitions.map((tool) => ({
-                name: tool.name,
-                description: tool.description,
-                inputSchema: leanJsonSchema(z.toJSONSchema(tool.schema, { target: "draft-7", io: "input" })),
-                ...(tool.annotations ? { annotations: tool.annotations } : {}),
-            })),
-        };
+        const surface = management ? options.boardSurface : undefined;
+        const advertisedNames = surface
+            ? new Set(prepared
+                .filter(({ spec }) => boardToolAdvertised(spec, surface))
+                .map(({ spec }) => spec.name))
+            : null;
+        const visible = advertisedNames
+            ? definitions.filter((tool) => curatedNames.has(tool.name) || advertisedNames.has(tool.name))
+            : definitions;
+        listing = { tools: toListingEntries(visible) };
         listings.set(key, listing);
     }
-    return { definitions, listing };
+    return {
+        definitions,
+        listing: paginateListing(listing, options.cursor, options.pageSize ?? resolvePageSize()),
+    };
 }
 //# sourceMappingURL=catalog.js.map

package/dist/catalog.js.map

@@ -1 +1 @@
-{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AACjF,OAAO,EAAE,cAAc,EAAyB,MAAM,kBAAkB,CAAC;AAEzE,OAAO,EAAE,qBAAqB,EAA6C,MAAM,YAAY,CAAC;AAE9F,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAapE,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAuB,CAAC;AAEhD,yFAAyF;AACzF,MAAM,UAAU,oBAAoB,CAClC,MAA0B,EAC1B,QAAoC,EACpC,UAAmB;IAEnB,MAAM,OAAO,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC9C,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/D,MAAM,SAAS,GAAG,kBAAkB,CAAC,qBAAqB,CAAC,QAAQ,EAAE,UAAU,CAAC,EAAE,MAAM,CAAC,CAAC,MAAM,CAC9F,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CACvC,CAAC;IACF,MAAM,WAAW,GAAG,CAAC,GAAG,OAAO,EAAE,GAAG,SAAS,CAAC,CAAC;IAC/C,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,UAAU,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;IACvF,IAAI,OAAO,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,GAAG;YACR,KAAK,EAAE,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBAChC,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,WAAW,EAAE,cAAc,CACzB,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,CAC5C;gBACrB,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aAC/D,CAAC,CAAC;SACJ,CAAC;QACF,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC;AAClC,CAAC"}
+{"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -11,6 +11,7 @@ export interface PaperclipMcpConfig {
 export declare const MANAGEMENT_ROLES: Record<string, true>;
 export declare function hasManagementAuthority(role: string | null | undefined): boolean;
 export declare const TOOLSET_NAMES: ToolsetName[];
+export declare function expandToolsetUnion(selected: ReadonlyArray<ToolsetName>): ToolsetName[];
 export declare function parseToolsets(requested: string | null | undefined): ToolsetName[];
 export declare function resolveToolsets(env?: NodeJS.ProcessEnv, argv?: string[]): ToolsetName[];
 export declare function normalizeApiUrl(apiUrl: string): string;

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAA8B,CAAC;AAEjF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE/E;AAED,eAAO,MAAM,aAAa,EAAE,WAAW,EAAyB,CAAC;AAEjE,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,EAAE,CAQjF;AAED,wBAAgB,eAAe,CAC7B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,IAAI,GAAE,MAAM,EAA0B,GACrC,WAAW,EAAE,CAaf;AAUD,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,kBAAkB,CAmB1F"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAA8B,CAAC;AAEjF,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE/E;AAED,eAAO,MAAM,aAAa,EAAE,WAAW,EAAyB,CAAC;AAEjE,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,aAAa,CAAC,WAAW,CAAC,GAAG,WAAW,EAAE,CAEtF;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,WAAW,EAAE,CASjF;AAED,wBAAgB,eAAe,CAC7B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,IAAI,GAAE,MAAM,EAA0B,GACrC,WAAW,EAAE,CAaf;AAUD,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGtD;AAED,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,kBAAkB,CAmB1F"}

package/dist/config.js

@@ -3,6 +3,9 @@ export function hasManagementAuthority(role) {
     return typeof role === "string" && MANAGEMENT_ROLES[role.trim().toLowerCase()] === true;
 }
 export const TOOLSET_NAMES = ["core", "extended"];
+export function expandToolsetUnion(selected) {
+    return selected.includes("extended") ? [...TOOLSET_NAMES] : ["core"];
+}
 export function parseToolsets(requested) {
     const requestedNames = (requested ?? "")
         .split(",")
@@ -10,8 +13,7 @@ export function parseToolsets(requested) {
         .filter(Boolean);
     if (requestedNames.includes("all"))
         return [...TOOLSET_NAMES];
-    const selected = TOOLSET_NAMES.filter((name) => requestedNames.includes(name));
-    return selected.length > 0 ? selected : ["core"];
+    return expandToolsetUnion(TOOLSET_NAMES.filter((name) => requestedNames.includes(name)));
 }
 export function resolveToolsets(env = process.env, argv = process.argv.slice(2)) {
     const flagIndex = argv.indexOf("--toolsets");