@withpica/mcp-server/dist/tools/relationship-scope.d.ts

MCP Server for withPICA — enables AI assistants to interact with your withPICA music catalog

/**
 * 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