@withpica/mcp-server 1.3.0

package/dist/tools/access-simulate.js

@@ -0,0 +1,162 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { formatSuccess, formatValidationError } from "@withpica/mcp-utils";
+const ENTITY_TYPES = ["work", "recording", "person", "release"];
+const ACTIONS = ["view", "share_link_preview", "claim", "grant"];
+const RECIPIENT_TYPES = ["user", "anonymous", "share_link"];
+export class AccessSimulateTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_access_simulate",
+                    description: "Simulate who would see what — for any work, recording, person, or " +
+                        "release, given a hypothetical action (view, share-link preview, " +
+                        "claim, grant) and a recipient configuration, returns the visible " +
+                        "and hidden fields plus the chain of rules that produced the answer. " +
+                        "Read-only — never mutates state. Use BEFORE creating a share link " +
+                        "to verify the recipient sees what you intend, or BEFORE claiming " +
+                        "custody to see what changes. v1 ships real share_link_preview " +
+                        "logic for works; other paths return a stable scaffolded shape.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            entity_type: {
+                                type: "string",
+                                enum: [...ENTITY_TYPES],
+                                description: "Entity to simulate access for. v1 implements 'work' fully; the others return a not_yet_supported scaffold with the same shape so agents can iterate against the API.",
+                            },
+                            entity_id: {
+                                type: "string",
+                                description: "UUID of the entity. Must belong to the caller's organisation — cross-org IDs return entity_not_found rather than leaking existence.",
+                            },
+                            action: {
+                                type: "string",
+                                enum: [...ACTIONS],
+                                description: "Access action to simulate. 'share_link_preview' is the v1 real path: pass recipient.share_config and get back the field-level visibility matrix the share link would expose. The other actions return scaffolded responses.",
+                            },
+                            recipient: {
+                                type: "object",
+                                description: "Hypothetical recipient. For share_link_preview pass type='share_link' and a share_config; for view/claim/grant pass type='user'/'org' as appropriate.",
+                                properties: {
+                                    type: {
+                                        type: "string",
+                                        enum: [...RECIPIENT_TYPES],
+                                        description: "Recipient type — 'user' (authenticated user_id), 'anonymous' (no auth), 'share_link' (hypothetical share-link config).",
+                                    },
+                                    user_id: {
+                                        type: "string",
+                                        description: "Recipient user UUID, when type='user'. Optional otherwise.",
+                                    },
+                                    org_id: {
+                                        type: "string",
+                                        description: "Recipient organisation UUID, when simulating an action that targets an org (e.g. 'grant'). Optional otherwise.",
+                                    },
+                                    share_config: {
+                                        type: "object",
+                                        description: "Hypothetical share-link configuration to simulate. Fields mirror the share-links write surface — access_type, allow_*, allowed_person_ids, sent_to_emails, watermark_audio, expires_at, max_views.",
+                                        properties: {
+                                            access_type: {
+                                                type: "string",
+                                                enum: ["private", "limited", "public"],
+                                                description: "Recipient scope — 'private' (allowed_person_ids only), 'limited' (sent_to_emails only), 'public' (anyone with link).",
+                                            },
+                                            allow_download: {
+                                                type: "boolean",
+                                                description: "When true, the recipient can download original audio files. Pair with watermark_audio=true for pre-release pitches.",
+                                            },
+                                            allow_streaming: {
+                                                type: "boolean",
+                                                description: "When true, the recipient can stream audio inline.",
+                                            },
+                                            allow_comments: {
+                                                type: "boolean",
+                                                description: "When true, the recipient sees the discussion thread and can post comments.",
+                                            },
+                                            allow_view_collaborators: {
+                                                type: "boolean",
+                                                description: "When true, the recipient sees the credit lines, splits, and attestation status.",
+                                            },
+                                            allow_view_financials: {
+                                                type: "boolean",
+                                                description: "When true, the recipient sees earnings, advances, and royalty statements. The most common reason a recipient sees less than expected.",
+                                            },
+                                            watermark_audio: {
+                                                type: "boolean",
+                                                description: "When true, audio surfaces are mixed with an inaudible watermark identifier.",
+                                            },
+                                            notify_on_access: {
+                                                type: "boolean",
+                                                description: "When true, the link's creator gets notified each time the recipient accesses it.",
+                                            },
+                                            allowed_person_ids: {
+                                                type: "array",
+                                                items: { type: "string" },
+                                                description: "Person UUIDs allowed to access when access_type='private'.",
+                                            },
+                                            sent_to_emails: {
+                                                type: "array",
+                                                items: { type: "string" },
+                                                description: "Email addresses the link was sent to when access_type='limited'.",
+                                            },
+                                            max_views: {
+                                                type: "number",
+                                                description: "Cap on total views; null/omitted for unlimited. <=0 makes the link unusable.",
+                                            },
+                                            expires_at: {
+                                                type: "string",
+                                                description: "ISO timestamp; recipients see an expired page after this time.",
+                                            },
+                                        },
+                                        required: ["access_type"],
+                                    },
+                                },
+                                required: ["type"],
+                            },
+                        },
+                        required: ["entity_type", "entity_id", "action", "recipient"],
+                    },
+                    annotations: {
+                        readOnlyHint: true,
+                        idempotentHint: true,
+                    },
+                },
+                executor: this.simulate.bind(this),
+            },
+        ];
+    }
+    async simulate(args) {
+        if (!args.entity_type || !ENTITY_TYPES.includes(args.entity_type)) {
+            return formatValidationError({
+                entity_type: `must be one of: ${ENTITY_TYPES.join(", ")}`,
+            });
+        }
+        if (!args.entity_id || typeof args.entity_id !== "string") {
+            return formatValidationError({ entity_id: "is required" });
+        }
+        if (!args.action || !ACTIONS.includes(args.action)) {
+            return formatValidationError({
+                action: `must be one of: ${ACTIONS.join(", ")}`,
+            });
+        }
+        if (!args.recipient ||
+            typeof args.recipient !== "object" ||
+            !RECIPIENT_TYPES.includes(args.recipient.type)) {
+            return formatValidationError({
+                recipient: `recipient.type must be one of: ${RECIPIENT_TYPES.join(", ")}`,
+            });
+        }
+        const result = await this.pica.accessSimulate.simulate(args);
+        const summary = result.not_yet_supported
+            ? `Access simulation scaffolded (v1 stub) — ${result.reasons[0]?.detail ?? "see reasons"}`
+            : result.visible
+                ? `Access simulated — ${result.visible_fields.length} field(s) visible, ${result.hidden_fields.length} hidden, ${result.warnings.length} warning(s)`
+                : `Access denied — ${result.reasons[0]?.detail ?? "see reasons"}`;
+        return formatSuccess(summary, result);
+    }
+}
+//# sourceMappingURL=access-simulate.js.map

package/dist/tools/access-simulate.js.map

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

package/dist/tools/agent-identity.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Agent Identity Tools — MCP surface for ADR-185 Parts 1+2.
+ *
+ * Five session-auth-only tools (Part 1 shipped 1-3, Part 2 adds 4-5):
+ *   - pica_create_agent_identity
+ *   - pica_issue_agent_grant
+ *   - pica_list_my_agent_grants
+ *   - pica_revoke_agent_grant       (Part 2)
+ *   - pica_get_agent_activity       (Part 2)
+ *
+ * All five route through the PICA HTTP API. The backing routes refuse
+ * `pica_grant_` callers with 403 `session_auth_required` per AC 12, so
+ * the session-auth-only guarantee is enforced once at the API layer and
+ * honoured by both stdio and HTTP MCP transports automatically. The
+ * HTTP dispatcher in app/api/mcp/route.ts also rejects at the tool layer
+ * via the SESSION_AUTH_ONLY_TOOLS set (belt-and-braces).
+ *
+ * Subject (user_id) is derived from the auth context — never from tool
+ * arguments (ADR-184 rule 1 / ADR-185 rule 1).
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class AgentIdentityTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private createIdentity;
+    private issueGrant;
+    private listMyGrants;
+    private revokeGrant;
+    private getActivity;
+}
+//# sourceMappingURL=agent-identity.d.ts.map

package/dist/tools/agent-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-identity.d.ts","sourceRoot":"","sources":["../../src/tools/agent-identity.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAa/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAEtE,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YA2E3D,cAAc;YAmCd,UAAU;YAsEV,YAAY;YAmCZ,WAAW;YA8BX,WAAW;CAgD1B"}

package/dist/tools/agent-identity.js

@@ -0,0 +1,274 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { CREATE_AGENT_IDENTITY_WRITE_PROPERTIES, CREATE_AGENT_IDENTITY_REQUIRED, ISSUE_AGENT_GRANT_WRITE_PROPERTIES, ISSUE_AGENT_GRANT_REQUIRED, LIST_MY_AGENT_GRANTS_WRITE_PROPERTIES, LIST_MY_AGENT_GRANTS_REQUIRED, REVOKE_AGENT_GRANT_WRITE_PROPERTIES, REVOKE_AGENT_GRANT_REQUIRED, GET_AGENT_ACTIVITY_WRITE_PROPERTIES, GET_AGENT_ACTIVITY_REQUIRED, } from "@withpica/mcp-utils";
+export class AgentIdentityTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_create_agent_identity",
+                    description: "Create a named agent identity (e.g. 'Claude on laptop') that grants can be issued against. Session-auth only — refused if called with a pica_grant_ token. Subject is the authenticated user; caller-supplied user_id is dropped.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: CREATE_AGENT_IDENTITY_WRITE_PROPERTIES,
+                        required: CREATE_AGENT_IDENTITY_REQUIRED,
+                    },
+                },
+                executor: this.createIdentity.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_issue_agent_grant",
+                    description: "Issue a capability grant against an identity you own. Returns a one-time grant_token (format pica_grant_<random>) — save it immediately; it is never shown again. Default expiry 90 days, max 365. Session-auth only.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: ISSUE_AGENT_GRANT_WRITE_PROPERTIES,
+                        required: ISSUE_AGENT_GRANT_REQUIRED,
+                    },
+                },
+                executor: this.issueGrant.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_list_my_agent_grants",
+                    description: "List your active agent grants. Returns non-secret fields only — tokens are never re-exposed after issue. Session-auth only.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: LIST_MY_AGENT_GRANTS_WRITE_PROPERTIES,
+                        required: LIST_MY_AGENT_GRANTS_REQUIRED,
+                    },
+                },
+                executor: this.listMyGrants.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_revoke_agent_grant",
+                    description: "Revoke one of your agent grants. Idempotent — revoking an already-revoked grant returns the same row. Revocation takes effect on the next request (within 60s). Session-auth only.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: REVOKE_AGENT_GRANT_WRITE_PROPERTIES,
+                        required: REVOKE_AGENT_GRANT_REQUIRED,
+                    },
+                },
+                executor: this.revokeGrant.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_get_agent_activity",
+                    description: "List agent_action_log rows whose grant's identity you own — your own provenance-stamped agent writes, sorted newest first. Optionally narrow by agent_identity_id or agent_grant_id. Paginated (default 50, max 500 per call). Session-auth only.",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: GET_AGENT_ACTIVITY_WRITE_PROPERTIES,
+                        required: GET_AGENT_ACTIVITY_REQUIRED,
+                    },
+                },
+                executor: this.getActivity.bind(this),
+            },
+        ];
+    }
+    async createIdentity(args) {
+        const displayName = typeof args.display_name === "string" ? args.display_name.trim() : "";
+        if (!displayName) {
+            return {
+                content: [{ type: "text", text: "Error: display_name is required." }],
+                isError: true,
+            };
+        }
+        const clientFingerprint = typeof args.client_fingerprint === "string" &&
+            args.client_fingerprint.trim()
+            ? args.client_fingerprint.trim()
+            : null;
+        const result = await this.pica.agentIdentity.createIdentity({
+            displayName,
+            clientFingerprint,
+        });
+        const data = result?.data ?? result;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Agent identity created: "${displayName}" (id: ${data?.id ?? "unknown"}). Issue a grant with pica_issue_agent_grant to start using it.`,
+                },
+            ],
+            structuredContent: {
+                kind: "pica.card.agent_identity_created",
+                version: 1,
+                data,
+            },
+        };
+    }
+    async issueGrant(args) {
+        const agentIdentityId = typeof args.agent_identity_id === "string"
+            ? args.agent_identity_id.trim()
+            : "";
+        if (!agentIdentityId) {
+            return {
+                content: [
+                    { type: "text", text: "Error: agent_identity_id is required." },
+                ],
+                isError: true,
+            };
+        }
+        if (!Array.isArray(args.scopes) || args.scopes.length === 0) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "Error: scopes must be a non-empty array of strings.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const scopes = args.scopes.filter((s) => typeof s === "string");
+        if (scopes.length !== args.scopes.length) {
+            return {
+                content: [{ type: "text", text: "Error: scopes must be strings." }],
+                isError: true,
+            };
+        }
+        const expiresAt = typeof args.expires_at === "string" && args.expires_at.trim()
+            ? args.expires_at
+            : null;
+        const result = await this.pica.agentIdentity.issueGrant({
+            agentIdentityId,
+            scopes,
+            expiresAt,
+        });
+        const data = result?.data ?? result;
+        // The plaintext token is in data.grant_token and is shown once.
+        // Surface it prominently in the text block so the caller (and
+        // through it the user) sees it without having to drill into the
+        // structured card.
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Grant issued (id: ${data?.id ?? "unknown"}). ` +
+                        `Expires: ${data?.expires_at ?? "n/a"}. ` +
+                        `Scopes: ${scopes.join(", ")}.\n\n` +
+                        `grant_token: ${data?.grant_token ?? ""}\n\n` +
+                        `Save this token now — it will not be shown again. ` +
+                        `Present it as Authorization: Bearer <token> on MCP requests.`,
+                },
+            ],
+            structuredContent: {
+                kind: "pica.card.agent_grant_issued",
+                version: 1,
+                data,
+            },
+        };
+    }
+    async listMyGrants(_args) {
+        const result = await this.pica.agentIdentity.listMyGrants();
+        const data = result?.data ?? result;
+        const rows = Array.isArray(data) ? data : [];
+        const lines = rows.length
+            ? rows
+                .map((row) => {
+                const name = row?.identity?.display_name ?? "unnamed";
+                const scopes = Array.isArray(row?.scopes)
+                    ? row.scopes.join(", ")
+                    : "";
+                const expiry = row?.expires_at
+                    ? `expires ${row.expires_at}`
+                    : "no expiry";
+                const revoked = row?.revoked_at ? " [revoked]" : "";
+                return `- ${name} (${row?.id ?? "unknown"}): ${scopes}; ${expiry}${revoked}`;
+            })
+                .join("\n")
+            : "(no grants)";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Your agent grants (${rows.length}):\n${lines}`,
+                },
+            ],
+            structuredContent: {
+                kind: "pica.card.agent_grants_list",
+                version: 1,
+                data: rows,
+            },
+        };
+    }
+    async revokeGrant(args) {
+        const grantId = typeof args.grant_id === "string" ? args.grant_id.trim() : "";
+        if (!grantId) {
+            return {
+                content: [{ type: "text", text: "Error: grant_id is required." }],
+                isError: true,
+            };
+        }
+        const result = await this.pica.agentIdentity.revokeGrant({ grantId });
+        const data = result?.data ?? result;
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Grant ${data?.id ?? grantId} revoked at ${data?.revoked_at ?? "now"}. ` +
+                        `The next request using this token will be refused with 401 ` +
+                        `within 60 seconds.`,
+                },
+            ],
+            structuredContent: {
+                kind: "pica.card.agent_grant_revoked",
+                version: 1,
+                data,
+            },
+        };
+    }
+    async getActivity(args) {
+        const agentIdentityId = typeof args.agent_identity_id === "string" &&
+            args.agent_identity_id.trim()
+            ? args.agent_identity_id.trim()
+            : null;
+        const agentGrantId = typeof args.agent_grant_id === "string" && args.agent_grant_id.trim()
+            ? args.agent_grant_id.trim()
+            : null;
+        const limit = typeof args.limit === "number" ? args.limit : undefined;
+        const offset = typeof args.offset === "number" ? args.offset : undefined;
+        const result = await this.pica.agentIdentity.getActivity({
+            agentIdentityId,
+            agentGrantId,
+            limit,
+            offset,
+        });
+        const data = result?.data ?? result;
+        const rows = Array.isArray(data) ? data : [];
+        const lines = rows.length
+            ? rows
+                .map((row) => {
+                const name = row?.grant?.identity?.display_name ?? "unnamed";
+                const action = row?.action ?? "?";
+                const table = row?.target_table ?? "?";
+                const tool = row?.tool_name ?? "?";
+                const when = row?.created_at ?? "";
+                return `- ${when}  ${name}  ${action} ${table} via ${tool}`;
+            })
+                .join("\n")
+            : "(no activity yet — provenance is stamped once Part 3 wraps write tools)";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Your agent activity (${rows.length}):\n${lines}`,
+                },
+            ],
+            structuredContent: {
+                kind: "pica.card.agent_activity",
+                version: 1,
+                data: rows,
+            },
+        };
+    }
+}
+//# sourceMappingURL=agent-identity.js.map

package/dist/tools/agent-identity.js.map

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

package/dist/tools/agreement-types.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Agreement Types Tools — templates, producer agreements, and work-for-hire
+ *
+ * Unified CRUD via type-routed tools, plus template-specific operations
+ * (render, duplicate, set_default).
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class AgreementTypesTools {
+    private pica;
+    constructor(pica: PicaClient);
+    private getResource;
+    private labelFor;
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private query;
+    private inspect;
+    private create;
+    private update;
+    private delete;
+    private renderTemplate;
+    private duplicateTemplate;
+    private setDefaultTemplate;
+}
+//# sourceMappingURL=agreement-types.d.ts.map

package/dist/tools/agreement-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agreement-types.d.ts","sourceRoot":"","sources":["../../src/tools/agreement-types.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAetE,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,QAAQ;IAWhB,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YAiN3D,KAAK;YAML,OAAO;YAMP,MAAM;YA8CN,MAAM;YAON,MAAM;YASN,cAAc;YAMd,iBAAiB;YAOjB,kBAAkB;CAMjC"}