@withpica/mcp-server/dist/tools/relationships.d.ts

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

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