@withpica/mcp-server 1.3.0

package/dist/tools/gap-hints.js

@@ -0,0 +1,245 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+/**
+ * Read MCP_GAP_HINTS_ENABLED at call time. Not cached so tests can flip
+ * it per-case. Returns true only for the explicit "1" value, mirroring
+ * the MCP_LAYERED_DISCOVERY pattern at mcp-server/src/config.ts.
+ */
+export function gapHintsEnabled() {
+    return process.env.MCP_GAP_HINTS_ENABLED === "1";
+}
+// ---------------------------------------------------------------------------
+// pica_works_inspect
+// ---------------------------------------------------------------------------
+/**
+ * A work is missing an executed agreement when:
+ *  - the `agreements` section is empty, OR
+ *  - none of its agreements have a fully-executed status
+ *
+ * We stay conservative — only fire when there's a clear gap, not when
+ * the caller just didn't request the agreements section.
+ */
+export function computeWorkGapHints(workResult) {
+    if (!gapHintsEnabled())
+        return [];
+    const hints = [];
+    const work = (workResult.work ?? {});
+    const workId = work.id ?? null;
+    const agreements = Array.isArray(workResult.agreements)
+        ? workResult.agreements
+        : null;
+    const hasExecutedAgreement = agreements !== null &&
+        agreements.some((a) => {
+            const status = a.status || "";
+            return status === "fully_executed" || status === "active";
+        });
+    if (agreements !== null && !hasExecutedAgreement && workId) {
+        hints.push({
+            gap: "missing_executed_agreement",
+            capability: "email_search",
+            rationale: "find the signed co-writer or collaborator agreement so the work has provenance",
+            query_shape: "from:{writer_emails} subject:(agreement OR contract OR split) has:attachment",
+            then_call: "pica_enrichment_propose",
+            then_args_shape: {
+                entity_type: "agreement",
+                proposal_action: "create",
+                parent_entity_type: "work",
+                parent_entity_id: workId,
+                proposed_fields: {
+                    title: "<from attachment>",
+                    agreement_type: "<from content>",
+                    other_party_name: "<counterparty>",
+                    fully_executed_date: "<ISO date from signatures>",
+                },
+                sources: [
+                    {
+                        url: "gmail://thread-id/<id>",
+                        fields: [
+                            "title",
+                            "agreement_type",
+                            "other_party_name",
+                            "fully_executed_date",
+                        ],
+                        accessed_at: "<iso>",
+                    },
+                ],
+            },
+        });
+    }
+    return hints;
+}
+// ---------------------------------------------------------------------------
+// pica_agreements_inspect
+// ---------------------------------------------------------------------------
+export function computeAgreementGapHints(agreementResult) {
+    if (!gapHintsEnabled())
+        return [];
+    const hints = [];
+    const agreement = (agreementResult.agreement ?? {});
+    const agreementId = agreement.id ?? null;
+    const status = agreement.status ?? "";
+    const executedDate = agreement.fully_executed_date;
+    const documentUrl = agreement.document_url;
+    if (!agreementId)
+        return [];
+    const isExecuted = status === "fully_executed" || status === "active";
+    if (!executedDate && !isExecuted) {
+        hints.push({
+            gap: "missing_execution_date",
+            capability: "email_search",
+            rationale: "find the countersigned copy of this agreement to confirm the execution date",
+            query_shape: `subject:("${agreement.title || "agreement"}" OR countersigned) has:attachment`,
+            then_call: "pica_enrichment_propose",
+            then_args_shape: {
+                entity_type: "agreement",
+                entity_id: agreementId,
+                proposal_action: "update",
+                proposed_fields: {
+                    fully_executed_date: "<ISO date from attachment>",
+                    status: "fully_executed",
+                },
+                sources: [
+                    {
+                        url: "gmail://thread-id/<id>",
+                        fields: ["fully_executed_date", "status"],
+                        accessed_at: "<iso>",
+                    },
+                ],
+            },
+        });
+    }
+    if (!documentUrl) {
+        hints.push({
+            gap: "missing_document",
+            capability: "drive_search",
+            rationale: "the agreement has no stored document — locate the signed copy in shared storage",
+            query_shape: `name:("${agreement.title || "agreement"}" OR contract) type:pdf`,
+            then_call: "pica_enrichment_propose",
+            then_args_shape: {
+                entity_type: "agreement",
+                entity_id: agreementId,
+                proposal_action: "update",
+                proposed_fields: {
+                    document_url: "<gdrive:// or https:// url>",
+                },
+                sources: [
+                    {
+                        url: "gdrive://file-id/<id>",
+                        fields: ["document_url"],
+                        accessed_at: "<iso>",
+                    },
+                ],
+            },
+        });
+    }
+    return hints;
+}
+// ---------------------------------------------------------------------------
+// pica_people_inspect
+// ---------------------------------------------------------------------------
+export function computePersonGapHints(personResult) {
+    if (!gapHintsEnabled())
+        return [];
+    const hints = [];
+    const person = (personResult.person ?? {});
+    const personId = person.id ?? null;
+    const email = person.email;
+    const name = person.name || "this person";
+    const identifiers = Array.isArray(personResult.identifiers)
+        ? personResult.identifiers
+        : [];
+    const identifierTypes = new Set(identifiers.map((i) => i.type || ""));
+    if (!personId)
+        return [];
+    if (!email) {
+        hints.push({
+            gap: "missing_email",
+            capability: "email_search",
+            rationale: `find an email thread that mentions ${name} so their contact can be captured with provenance`,
+            query_shape: `"${name}" in:anywhere`,
+            then_call: "pica_enrichment_propose",
+            then_args_shape: {
+                entity_type: "person",
+                entity_id: personId,
+                proposal_action: "update",
+                proposed_fields: {
+                    email: "<extracted address>",
+                },
+                sources: [
+                    {
+                        url: "gmail://message-id/<id>",
+                        fields: ["email"],
+                        accessed_at: "<iso>",
+                    },
+                ],
+            },
+        });
+    }
+    const hasAnyIndustryId = identifierTypes.has("ipi") ||
+        identifierTypes.has("isni") ||
+        identifierTypes.has("ipn");
+    if (!hasAnyIndustryId) {
+        hints.push({
+            gap: "missing_industry_identifier",
+            capability: "web_search",
+            rationale: `find ${name}'s IPI, ISNI, or IPN in a public registry so downstream registration can complete`,
+            query_shape: `"${name}" (IPI OR ISNI) site:(isni.org OR musicbrainz.org OR themlc.com)`,
+            then_call: "pica_enrichment_propose",
+            then_args_shape: {
+                entity_type: "person",
+                entity_id: personId,
+                proposal_action: "update",
+                proposed_fields: {
+                    ipi: "<11-digit IPI>",
+                },
+                sources: [
+                    {
+                        url: "web://https://isni.org/isni/<id>",
+                        fields: ["ipi"],
+                        accessed_at: "<iso>",
+                    },
+                ],
+            },
+        });
+    }
+    return hints;
+}
+// ---------------------------------------------------------------------------
+// pica_enrichment_proposals_list
+// ---------------------------------------------------------------------------
+/**
+ * When the pending-proposals list is empty, surface a hint reminding
+ * the agent that peer MCPs may hold evidence that would produce
+ * proposals. This is the weakest of the four surfaces — the list tool
+ * doesn't know which entity's proposals are missing — so we only fire
+ * on the empty case and cite the generic flow.
+ */
+export function computeProposalListGapHints(listResult) {
+    if (!gapHintsEnabled())
+        return [];
+    if (!Array.isArray(listResult) || listResult.length > 0)
+        return [];
+    return [
+        {
+            gap: "no_pending_proposals",
+            capability: "email_search",
+            rationale: "no proposals are queued — if the user mentioned missing splits or contracts, check their mailbox for correspondence and file evidence via pica_enrichment_propose",
+            query_shape: "subject:(split OR agreement OR royalty) newer_than:90d",
+            then_call: "pica_enrichment_propose",
+            then_args_shape: {
+                entity_type: "<work|recording|person|agreement>",
+                entity_id: "<target id>",
+                proposed_fields: {
+                /* from the email */
+                },
+                sources: [
+                    {
+                        url: "gmail://thread-id/<id>",
+                        fields: ["..."],
+                        accessed_at: "<iso>",
+                    },
+                ],
+            },
+        },
+    ];
+}
+//# sourceMappingURL=gap-hints.js.map

package/dist/tools/gap-hints.js.map

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

package/dist/tools/groups.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Groups Tools — ADR-223 Phase 5
+ *
+ * MCP write/read surface for group → member relationships on people.
+ * Four tools:
+ *   - pica_group_add_member       (write, Tier 1)
+ *   - pica_group_remove_member    (write, Tier 1)
+ *   - pica_group_list_members     (read)
+ *   - pica_person_list_groups     (read)
+ *
+ * Server-side trigger tg_pgm_assert_parent enforces parent.is_group=true
+ * and same-org constraint on every insert. Errors map to friendly
+ * messages on the route layer.
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class GroupsTools {
+    private pica;
+    constructor(pica: PicaClient);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private addMember;
+    private removeMember;
+    private listMembers;
+    private listGroups;
+}
+//# sourceMappingURL=groups.d.ts.map

package/dist/tools/groups.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"groups.d.ts","sourceRoot":"","sources":["../../src/tools/groups.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAiBtE,qBAAa,WAAW;IACtB,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;YAiJ3D,SAAS;YAmBT,YAAY;YAcZ,WAAW;YAWX,UAAU;CASzB"}

package/dist/tools/groups.js

@@ -0,0 +1,186 @@
+// Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
+import { formatSuccess, formatStructuredList, withBillingGate, } from "@withpica/mcp-utils";
+const ROLE_ENUM = [
+    "member",
+    "founder",
+    "lead",
+    "touring_member",
+    "session",
+    "guest",
+    "producer_in_residence",
+];
+export class GroupsTools {
+    pica;
+    constructor(pica) {
+        this.pica = pica;
+    }
+    getTools() {
+        return [
+            {
+                definition: {
+                    name: "pica_group_add_member",
+                    description: "Add a person as a member of a group person row. The group must already have is_group=true on its people record. " +
+                        "Defaults: role='member', receive_notifications=true. " +
+                        "→ before: pica_people_query (find both people) → then: pica_group_list_members (verify roster)",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            group_person_id: {
+                                type: "string",
+                                description: "ID of the group person row (must have is_group=true)",
+                            },
+                            member_person_id: {
+                                type: "string",
+                                description: "ID of the member person row",
+                            },
+                            role: {
+                                type: "string",
+                                enum: [...ROLE_ENUM],
+                                description: "Constrained role within the group. Default 'member'.",
+                            },
+                            role_label: {
+                                type: "string",
+                                description: "Free-text label for variants outside the enum (e.g. 'lead vocalist for tour 2025'). Optional.",
+                            },
+                            joined_at: {
+                                type: "string",
+                                description: "When the member joined (ISO 8601). Omit for unknown.",
+                            },
+                            receive_notifications: {
+                                type: "boolean",
+                                description: "Whether the member's linked user account (if any) gets notifications about group activity. Default true.",
+                            },
+                            notification_filter: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "Optional subset of original event types to be notified about (e.g. ['work_credit_added','agreement_party_linked']). Omit for all.",
+                            },
+                        },
+                        required: ["group_person_id", "member_person_id"],
+                    },
+                },
+                executor: withBillingGate(this.pica, "group member add", this.addMember.bind(this)),
+            },
+            {
+                definition: {
+                    name: "pica_group_remove_member",
+                    description: "Remove a member from a group by setting left_at on the active row. The row is preserved — never deleted — so member history survives. " +
+                        "→ then: pica_group_list_members (with include_inactive=true to see history)",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            group_person_id: {
+                                type: "string",
+                                description: "Group person ID",
+                            },
+                            member_person_id: {
+                                type: "string",
+                                description: "Member person ID",
+                            },
+                            left_at: {
+                                type: "string",
+                                description: "When they left (ISO 8601). Defaults to now.",
+                            },
+                        },
+                        required: ["group_person_id", "member_person_id"],
+                    },
+                },
+                executor: withBillingGate(this.pica, "group member remove", this.removeMember.bind(this)),
+            },
+            {
+                definition: {
+                    name: "pica_group_list_members",
+                    description: "List members of a group person. Active members only by default; pass include_inactive=true for history. " +
+                        "→ then: pica_people_inspect (get details for a specific member)",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            group_person_id: {
+                                type: "string",
+                                description: "Group person ID (must have is_group=true)",
+                            },
+                            include_inactive: {
+                                type: "boolean",
+                                description: "Include rows with left_at set (past members). Default false.",
+                            },
+                        },
+                        required: ["group_person_id"],
+                    },
+                },
+                executor: this.listMembers.bind(this),
+            },
+            {
+                definition: {
+                    name: "pica_person_list_groups",
+                    description: "List the groups a person is (or was) a member of. Active memberships only by default. " +
+                        "→ then: pica_people_inspect (get group details)",
+                    workflows: "infrastructure",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            person_id: {
+                                type: "string",
+                                description: "Person ID",
+                            },
+                            include_inactive: {
+                                type: "boolean",
+                                description: "Include rows with left_at set (past memberships). Default false.",
+                            },
+                        },
+                        required: ["person_id"],
+                    },
+                },
+                executor: this.listGroups.bind(this),
+            },
+        ];
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- args bag from MCP transport
+    async addMember(args) {
+        const result = await this.pica.groups.addMember({
+            group_person_id: args.group_person_id,
+            member_person_id: args.member_person_id,
+            role: args.role,
+            role_label: args.role_label,
+            joined_at: args.joined_at,
+            receive_notifications: args.receive_notifications,
+            notification_filter: args.notification_filter,
+        });
+        const data = result?.data ?? result;
+        const role = data?.role ?? "member";
+        return formatSuccess(`Member added to group as ${role}${data?.role_label ? ` (${data.role_label})` : ""}.`, data);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- args bag from MCP transport
+    async removeMember(args) {
+        const result = await this.pica.groups.removeMember({
+            group_person_id: args.group_person_id,
+            member_person_id: args.member_person_id,
+            left_at: args.left_at,
+        });
+        const data = result?.data ?? result;
+        return formatSuccess(`Member removed from group (left_at=${data?.left_at ?? "now"}). Row preserved for history.`, data);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- args bag from MCP transport
+    async listMembers(args) {
+        const result = await this.pica.groups.listMembers(args.group_person_id, {
+            include_inactive: !!args.include_inactive,
+        });
+        const items = (result?.data ?? result ?? []);
+        return formatStructuredList(items, "group_membership", {
+            total: items.length,
+        });
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- args bag from MCP transport
+    async listGroups(args) {
+        const result = await this.pica.groups.listGroupsForPerson(args.person_id, {
+            include_inactive: !!args.include_inactive,
+        });
+        const items = (result?.data ?? result ?? []);
+        return formatStructuredList(items, "group_membership", {
+            total: items.length,
+        });
+    }
+}
+//# sourceMappingURL=groups.js.map

package/dist/tools/groups.js.map

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

package/dist/tools/import-documents.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Import Documents Tools - MCP tools for canonical ingestion documents
+ */
+import { PicaClient } from "@withpica/mcp-sdk";
+import { ToolDefinition, ToolExecutor } from "./index.js";
+export declare class ImportDocumentTools {
+    private pica;
+    constructor(pica: PicaClient);
+    /**
+     * Get all import document tools
+     */
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private queryImportDocuments;
+    private inspectImportDocument;
+    private ingestStatement;
+    private computeDiff;
+}
+//# sourceMappingURL=import-documents.d.ts.map

package/dist/tools/import-documents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-documents.d.ts","sourceRoot":"","sources":["../../src/tools/import-documents.ts"],"names":[],"mappings":"AAEA;;GAEG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AAGtE,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B;;OAEG;IACH,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YA6F3D,oBAAoB;YAOpB,qBAAqB;YA+DrB,eAAe;IAgB7B,OAAO,CAAC,WAAW;CAyDpB"}