@withpica/mcp-server/dist/tools/arg-aliases.d.ts

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

/**
 * Per-tool argument aliasing for `pica_execute` (D1, 2026-09-03).
 *
 * Agents routinely pass a tool's OWN entity id under its natural name —
 * `audio_file_id` to `pica_audio_update`, `person_id` to
 * `pica_people_inspect`, `skill` to `pica_skill_get` — instead of the
 * schema's `id` (or `name`). The dispatcher's WRAPPED_ARGS_MISSING guard
 * (`discovery.ts`, `buildExecuteTool`) then rejected the call blaming
 * "client-side transport loss" — the wrong diagnosis every one of the 36
 * times it happened since July; nothing was lost in transit, the caller just
 * used a different, entirely reasonable field name.
 *
 * `applyArgAliases` renames a tool's own alias to the schema's real required
 * field name, structurally: the domain is the first segment after `pica_`
 * in the tool name, and `id` may only be filled from that domain's entry in
 * `DOMAIN_ID_ALIASES`. Anything not shaped `<domain>_id` (e.g.
 * `pica_skill_get`'s `skill` / `skill_name` → `name`) is declared explicitly
 * in `TOOL_ARG_ALIASES`, per exact tool name.
 *
 * Renaming happens ONLY when the target field is absent from the args AND
 * exactly one alias candidate is present:
 *   - a target already present is never overwritten (the caller's value
 *     wins, even if a same-named alias is also present — see the discovery
 *     dispatcher, which resolves aliases before this runs);
 *   - two or more present candidates are ambiguous ("which one is THE id?")
 *     and are left untouched rather than guessed;
 *   - a foreign entity's id (`work_id` sent to a people tool) is never a
 *     candidate for another tool's `id` — `DOMAIN_ID_ALIASES` is looked up
 *     by the TOOL'S OWN domain, not by whatever key the caller happened to
 *     send.
 *
 * Pure function: `args` is never mutated, a new object is returned.
 */
/**
 * Domain (first segment after `pica_` in the tool name) → candidate
 * spellings of "this entity's own id" an agent might send instead of the
 * schema's `id`.
 */
export declare const DOMAIN_ID_ALIASES: Record<string, readonly string[]>;
/**
 * Explicit non-id aliases, keyed by exact tool name — for fields that don't
 * follow the `<domain>_id` shape `DOMAIN_ID_ALIASES` covers. Each entry maps
 * an alias spelling to the schema's real field name.
 */
export declare const TOOL_ARG_ALIASES: Record<string, Record<string, string>>;
export interface ArgAliasResult {
    args: Record<string, unknown>;
    applied: Array<{
        from: string;
        to: string;
    }>;
}
/**
 * Rename a tool's own id / explicit alias to the schema's real required
 * field name. See module doc above for the exact ambiguity and
 * no-overwrite rules.
 */
export declare function applyArgAliases(toolName: string, args: Record<string, unknown>, required: readonly string[]): ArgAliasResult;
//# sourceMappingURL=arg-aliases.d.ts.map