@withpica/mcp-server 2.103.0 → 2.105.0

package/dist/tools/relationship-scope.d.ts

@@ -0,0 +1,104 @@
+/**
+ * The scope of a portfolio relationship, as the assistant tools accept it
+ * (ADR-333 D3). The main MCP server cannot import the app, so this mirrors
+ * `relationshipScopeSchema` in lib/services/portfolio-relationship-model.ts
+ * with snake_case names. lib/services/__tests__/relationship-scope-mcp-
+ * parity.test.ts fails if a field, an allowed value or a limit drifts.
+ *
+ * Every field is optional: the app fills the defaults (whole catalogue, both
+ * halves, worldwide, no end date, money on only for an administrator,
+ * directory off). The rules that join two fields (for example "worldwide
+ * cannot be combined with other territories") are enforced by the app, which
+ * refuses with a plain reason; the descriptions below state them.
+ *
+ * Deliberately has no imports, so the parity test can load it directly.
+ */
+export declare const SCOPE_HALVES: readonly ["both", "composition", "master"];
+export declare const SCOPE_CATALOGUES: readonly ["whole", "chosen"];
+export declare const SCOPE_MAX_TERRITORIES = 300;
+export declare const SCOPE_MAX_ITEMS = 5000;
+export declare const SCOPE_TERRITORY_PATTERN = "^[A-Z]{2}$";
+export declare const SCOPE_DATE_PATTERN = "^\\d{4}-\\d{2}-\\d{2}$";
+/** The tool argument name for each field of the app's scope. */
+export declare const SCOPE_FIELD_NAMES: {
+    readonly half: "half";
+    readonly territories: "territories";
+    readonly term_starts_on: "termStartsOn";
+    readonly term_ends_on: "termEndsOn";
+    readonly money: "money";
+    readonly directory: "directory";
+    readonly catalogue: "catalogue";
+    readonly work_ids: "workIds";
+    readonly recording_ids: "recordingIds";
+};
+export type ScopeArgName = keyof typeof SCOPE_FIELD_NAMES;
+/** JSON Schema for the optional `scope` argument of grant, invite and answer. */
+export declare const RELATIONSHIP_SCOPE_INPUT_SCHEMA: {
+    readonly type: "object";
+    readonly description: string;
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly half: {
+            readonly type: "string";
+            readonly enum: readonly ["both", "composition", "master"];
+            readonly description: "Which half of the songs: both, composition (the song and its publishing) or master (the recordings).";
+        };
+        readonly territories: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly pattern: "^[A-Z]{2}$";
+            };
+            readonly minItems: 1;
+            readonly maxItems: 300;
+            readonly description: "Countries covered. Only [\"WW\"] (worldwide) is accepted today: limiting a relationship to some countries is not available yet, and any other value is refused.";
+        };
+        readonly term_starts_on: {
+            readonly type: readonly ["string", "null"];
+            readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+            readonly description: "First day covered, YYYY-MM-DD (UTC). Leave out or null to start when it is accepted.";
+        };
+        readonly term_ends_on: {
+            readonly type: readonly ["string", "null"];
+            readonly pattern: "^\\d{4}-\\d{2}-\\d{2}$";
+            readonly description: "Last day covered, YYYY-MM-DD (UTC), inclusive. Leave out or null for until revoked. On that date access ends by itself.";
+        };
+        readonly money: {
+            readonly type: "boolean";
+            readonly description: "true lets the organisation see statements and earnings in scope.";
+        };
+        readonly directory: {
+            readonly type: "boolean";
+            readonly description: "true lets an administrator list or hide songs in the public directory and answer enquiries. Administrators only.";
+        };
+        readonly catalogue: {
+            readonly type: "string";
+            readonly enum: readonly ["whole", "chosen"];
+            readonly description: "whole for the whole catalogue, or chosen for only the songs and recordings named in work_ids and recording_ids.";
+        };
+        readonly work_ids: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly format: "uuid";
+            };
+            readonly maxItems: 5000;
+            readonly description: "Songs covered when catalogue is chosen (ids from pica_works_query). Not allowed for a master-only scope.";
+        };
+        readonly recording_ids: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly format: "uuid";
+            };
+            readonly maxItems: 5000;
+            readonly description: "Recordings covered when catalogue is chosen (ids from pica_recordings_query). Not allowed for a composition-only scope.";
+        };
+    };
+};
+/**
+ * Convert the tool's `scope` argument to the app's field names. Unknown keys
+ * are dropped here; the schema above already refuses them at the MCP layer.
+ */
+export declare function scopeArgToApi(scope: Record<string, unknown> | undefined): Record<string, unknown> | undefined;
+//# sourceMappingURL=relationship-scope.d.ts.map

package/dist/tools/relationship-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relationship-scope.d.ts","sourceRoot":"","sources":["../../src/tools/relationship-scope.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AAEH,eAAO,MAAM,YAAY,4CAA6C,CAAC;AACvE,eAAO,MAAM,gBAAgB,8BAA+B,CAAC;AAC7D,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,eAAO,MAAM,eAAe,OAAO,CAAC;AACpC,eAAO,MAAM,uBAAuB,eAAe,CAAC;AACpD,eAAO,MAAM,kBAAkB,2BAA2B,CAAC;AAE3D,gEAAgE;AAChE,eAAO,MAAM,iBAAiB;;;;;;;;;;CAUpB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,MAAM,OAAO,iBAAiB,CAAC;AAE1D,iFAAiF;AACjF,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiElC,CAAC;AAEX;;;GAGG;AACH,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GACzC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAOrC"}

package/dist/tools/relationship-scope.js

@@ -0,0 +1,106 @@
+// Copyright (c) 2025-2026 Withpica Ltd. All rights reserved.
+/**
+ * The scope of a portfolio relationship, as the assistant tools accept it
+ * (ADR-333 D3). The main MCP server cannot import the app, so this mirrors
+ * `relationshipScopeSchema` in lib/services/portfolio-relationship-model.ts
+ * with snake_case names. lib/services/__tests__/relationship-scope-mcp-
+ * parity.test.ts fails if a field, an allowed value or a limit drifts.
+ *
+ * Every field is optional: the app fills the defaults (whole catalogue, both
+ * halves, worldwide, no end date, money on only for an administrator,
+ * directory off). The rules that join two fields (for example "worldwide
+ * cannot be combined with other territories") are enforced by the app, which
+ * refuses with a plain reason; the descriptions below state them.
+ *
+ * Deliberately has no imports, so the parity test can load it directly.
+ */
+export const SCOPE_HALVES = ["both", "composition", "master"];
+export const SCOPE_CATALOGUES = ["whole", "chosen"];
+export const SCOPE_MAX_TERRITORIES = 300;
+export const SCOPE_MAX_ITEMS = 5000;
+export const SCOPE_TERRITORY_PATTERN = "^[A-Z]{2}$";
+export const SCOPE_DATE_PATTERN = "^\\d{4}-\\d{2}-\\d{2}$";
+/** The tool argument name for each field of the app's scope. */
+export const SCOPE_FIELD_NAMES = {
+    half: "half",
+    territories: "territories",
+    term_starts_on: "termStartsOn",
+    term_ends_on: "termEndsOn",
+    money: "money",
+    directory: "directory",
+    catalogue: "catalogue",
+    work_ids: "workIds",
+    recording_ids: "recordingIds",
+};
+/** JSON Schema for the optional `scope` argument of grant, invite and answer. */
+export const RELATIONSHIP_SCOPE_INPUT_SCHEMA = {
+    type: "object",
+    description: "What the relationship covers. Leave out any field to use the default: the whole catalogue, " +
+        "both halves, worldwide, until revoked, statements hidden (shown by default only to an " +
+        "administrator), directory off.",
+    additionalProperties: false,
+    properties: {
+        half: {
+            type: "string",
+            enum: [...SCOPE_HALVES],
+            description: "Which half of the songs: both, composition (the song and its publishing) or master (the recordings).",
+        },
+        territories: {
+            type: "array",
+            items: { type: "string", pattern: SCOPE_TERRITORY_PATTERN },
+            minItems: 1,
+            maxItems: SCOPE_MAX_TERRITORIES,
+            description: 'Countries covered. Only ["WW"] (worldwide) is accepted today: limiting a relationship to some countries is not available yet, and any other value is refused.',
+        },
+        term_starts_on: {
+            type: ["string", "null"],
+            pattern: SCOPE_DATE_PATTERN,
+            description: "First day covered, YYYY-MM-DD (UTC). Leave out or null to start when it is accepted.",
+        },
+        term_ends_on: {
+            type: ["string", "null"],
+            pattern: SCOPE_DATE_PATTERN,
+            description: "Last day covered, YYYY-MM-DD (UTC), inclusive. Leave out or null for until revoked. On that date access ends by itself.",
+        },
+        money: {
+            type: "boolean",
+            description: "true lets the organisation see statements and earnings in scope.",
+        },
+        directory: {
+            type: "boolean",
+            description: "true lets an administrator list or hide songs in the public directory and answer enquiries. Administrators only.",
+        },
+        catalogue: {
+            type: "string",
+            enum: [...SCOPE_CATALOGUES],
+            description: "whole for the whole catalogue, or chosen for only the songs and recordings named in work_ids and recording_ids.",
+        },
+        work_ids: {
+            type: "array",
+            items: { type: "string", format: "uuid" },
+            maxItems: SCOPE_MAX_ITEMS,
+            description: "Songs covered when catalogue is chosen (ids from pica_works_query). Not allowed for a master-only scope.",
+        },
+        recording_ids: {
+            type: "array",
+            items: { type: "string", format: "uuid" },
+            maxItems: SCOPE_MAX_ITEMS,
+            description: "Recordings covered when catalogue is chosen (ids from pica_recordings_query). Not allowed for a composition-only scope.",
+        },
+    },
+};
+/**
+ * Convert the tool's `scope` argument to the app's field names. Unknown keys
+ * are dropped here; the schema above already refuses them at the MCP layer.
+ */
+export function scopeArgToApi(scope) {
+    if (!scope)
+        return undefined;
+    const out = {};
+    for (const [arg, api] of Object.entries(SCOPE_FIELD_NAMES)) {
+        if (scope[arg] !== undefined)
+            out[api] = scope[arg];
+    }
+    return out;
+}
+//# sourceMappingURL=relationship-scope.js.map

package/dist/tools/relationship-scope.js.map

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

package/dist/tools/relationships.d.ts

@@ -0,0 +1,64 @@
+/**
+ * ADR-333 — who looks after whose catalogue, for assistants.
+ *
+ * Owner side: pica_relationships_list, _answer, _grant, _revoke, _activity.
+ * Organisation side: pica_portfolio_list, _briefing, _invite and
+ * pica_relationships_step_down (list, answer and activity serve both sides).
+ *
+ * Each tool calls one of pica-b5's /api/admin/relationships/** or
+ * /api/admin/portfolio routes, which hold no rules of their own: the 1.1
+ * service decides every step and refuses with a code and a plain sentence,
+ * which these tools pass on as they are.
+ *
+ * Accepting, changing, revoking and an owner's invitation give or take away
+ * access, so they are the person's own decision (ADR-333 D1):
+ *  - from a connected app or agent grant, pica_relationships_answer, _grant
+ *    and _revoke are `approvalMode: "human"`: the MCP route stages an
+ *    approval for the person, and on approval
+ *    lib/services/relationship-approvals.ts runs the step through the
+ *    service, never this file;
+ *  - from the in-app assistant (not staged), the route refuses those steps
+ *    as HUMAN_CONFIRMATION_REQUIRED and the tool gives the screen to do it on.
+ * Declining, stepping down and an organisation's invitation take nothing
+ * from anyone, so an agent may do them.
+ *
+ * Every step sends the version of the relationship the caller read
+ * (expected_version). If the terms changed since, nothing happens and the
+ * tool returns the current terms to read again.
+ */
+import { type PicaClient } from "@withpica/mcp-sdk";
+import type { PortfolioClientRecord } from "@withpica/mcp-sdk";
+import type { ToolDefinition, ToolExecutor } from "./index.js";
+/** 1.1's MAX_PAGE_LIMIT: a relationship page reads limit + 1 rows. */
+export declare const RELATIONSHIP_PAGE_MAX = 999;
+/** pica-2f's 1.4 page cap. */
+export declare const PORTFOLIO_PAGE_MAX = 25;
+/** The scope fields a client can be asked for: what they cover comes from the client. */
+export declare const INVITE_SCOPE_FIELDS: readonly ["half", "territories", "term_starts_on", "term_ends_on"];
+/** `https://withpica.com/api` → `https://withpica.com`. */
+export declare function webOrigin(apiUrl: string | undefined): string;
+/** One client as a line: who, as what, and what needs attention. */
+export declare function portfolioLine(c: PortfolioClientRecord): string;
+export declare class RelationshipTools {
+    private readonly pica;
+    private readonly origin;
+    constructor(pica: PicaClient, apiUrl?: string);
+    getTools(): Array<{
+        definition: ToolDefinition;
+        executor: ToolExecutor;
+    }>;
+    private list;
+    private activity;
+    private portfolioList;
+    private portfolioBriefing;
+    private portfolio;
+    private answer;
+    private stepResult;
+    private grant;
+    private invite;
+    private sendInvite;
+    private revoke;
+    private stepDown;
+    private end;
+}
+//# sourceMappingURL=relationships.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"relationships.d.ts","sourceRoot":"","sources":["../../src/tools/relationships.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAY,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,KAAK,EAGV,qBAAqB,EAKtB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAc,MAAM,YAAY,CAAC;AA0B3E,sEAAsE;AACtE,eAAO,MAAM,qBAAqB,MAAM,CAAC;AACzC,8BAA8B;AAC9B,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAGrC,yFAAyF;AACzF,eAAO,MAAM,mBAAmB,oEAKtB,CAAC;AAIX,2DAA2D;AAC3D,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAG5D;AAiSD,oEAAoE;AACpE,wBAAgB,aAAa,CAAC,CAAC,EAAE,qBAAqB,GAAG,MAAM,CAsC9D;AAED,qBAAa,iBAAiB;IAI1B,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAGb,IAAI,EAAE,UAAU,EACjC,MAAM,CAAC,EAAE,MAAM;IAKjB,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YA4V3D,IAAI;YAmFJ,QAAQ;YAyER,aAAa;YAIb,iBAAiB;YAIjB,SAAS;YAiET,MAAM;IA4HpB,OAAO,CAAC,UAAU;YAoBJ,KAAK;YAIL,MAAM;YAIN,UAAU;YA+CV,MAAM;YAIN,QAAQ;YAIR,GAAG;CAqDlB"}