@withpica/mcp-server
Version:
MCP Server for withPICA — enables AI assistants to interact with your withPICA music catalog
332 lines • 13.5 kB
TypeScript
/**
* People Tools - MCP tools for managing people (artists, composers, etc.)
*
* ADR-174 Phase 2 item 4 — pica_people_create / pica_people_update
* write surfaces are now reconciled against public.people +
* public.person_enrichment. `additionalProperties: true` is off;
* unknown keys 400 at the route layer. Fields listed under
* SATELLITE_ROUTED live on public.person_enrichment and are fanned
* out from the service via syncPersonEnrichmentSatellite (see
* lib/services/people-admin/enrichment-satellite.ts).
*/
import { PicaClient } from "@withpica/mcp-sdk";
import { ToolDefinition, ToolExecutor } from "./index.js";
/**
* Canonical source for the pica_people_create / pica_people_update input
* shape. Mirror of PEOPLE_CORE_WRITE_FIELDS + PEOPLE_SATELLITE_ROUTED_FIELDS
* in lib/services/people-admin/write-constants.ts. Keep these two in sync:
* if a property is added here it must be added to the allow-list (so the
* HTTP route lets it through) and — if it's a satellite field — to
* ENRICHMENT_SATELLITE_FIELDS (so the service routes it to person_enrichment).
*
* Exported for future bulk-tool reuse.
*/
export declare const PEOPLE_WRITE_PROPERTIES: {
readonly first_name: {
readonly type: "string";
readonly description: "First name";
};
readonly last_name: {
readonly type: "string";
readonly description: "Last name";
};
readonly middle_name: {
readonly type: "string";
readonly description: "Middle name";
};
readonly name: {
readonly type: "string";
readonly description: "Full name. Normally derived from first_name + last_name; set explicitly only for imports where the parts aren't separable.";
};
readonly stage_name: {
readonly type: "string";
readonly description: "Primary stage / artist name (legacy singular)";
};
readonly stage_names: {
readonly type: "array";
readonly items: {
readonly type: "string";
};
readonly description: "All stage / artist names (canonical plural)";
};
readonly person_type: {
readonly type: "array";
readonly items: {
readonly type: "string";
};
readonly description: "Legacy alias — prefer record_kind and roles. A kind-of-record value (individual, placeholder, artefact) sets record_kind; any other value (e.g. collaborator, business) is added to roles. `type` is a deprecated duplicate and will be rejected.";
};
readonly biography: {
readonly type: "string";
readonly description: "Biography text";
};
readonly email: {
readonly type: "string";
readonly description: "Primary email address";
};
readonly emails: {
readonly type: "array";
readonly items: {
readonly type: "object";
readonly properties: {
readonly email: {
readonly type: "string";
};
readonly label: {
readonly type: "string";
};
readonly primary: {
readonly type: "boolean";
};
};
};
readonly description: "Additional emails with label/primary metadata";
};
readonly phone: {
readonly type: "string";
readonly description: "Phone number";
};
readonly website: {
readonly type: "string";
readonly description: "Website URL";
};
readonly social_media: {
readonly type: "object";
readonly description: "Social handles keyed by platform, e.g. { twitter: '@ada', instagram: 'ada_lovelace' }";
};
readonly roles: {
readonly type: "array";
readonly items: {
readonly type: "string";
};
readonly description: "Roles (e.g. ['artist', 'songwriter', 'producer']). Canonical column — `role` singular is a deprecated duplicate and will be rejected. Defaults to ['collaborator'] on create if omitted.";
};
readonly tags: {
readonly type: "array";
readonly items: {
readonly type: "string";
};
readonly description: "Tags for categorisation";
};
readonly is_group: {
readonly type: "boolean";
readonly description: "whether this person record represents a group/band rather than an individual";
};
readonly cae_ipi_number: {
readonly type: "string";
readonly description: "CAE/IPI number (songwriter/publisher identifier, 9-11 digits)";
};
readonly ipi: {
readonly type: "string";
readonly description: "Same as cae_ipi_number (accepted under the name other tools use). Send one or the other — if both are sent they must be the same IPI, or the call is refused.";
};
readonly ipn_number: {
readonly type: "string";
readonly description: "IPN number (performer identifier)";
};
readonly society_affiliations: {
readonly type: "array";
readonly description: "Society affiliations for this person, e.g. [{ society_code: 'PRS', membership_number: '...' }].";
readonly items: {
readonly type: "object";
readonly properties: {
readonly society_code: {
readonly type: "string";
readonly description: "collecting society code, e.g. PRS, PPL, MCPS";
};
readonly membership_number: {
readonly type: "string";
readonly description: "the person's membership number with this society (optional)";
};
readonly affiliation_kind: {
readonly type: "string";
readonly enum: readonly ["member", "origin"];
readonly description: "member (current) or origin (home-country society) — defaults to member";
};
};
readonly required: readonly ["society_code"];
};
};
readonly pro_name: {
readonly type: "string";
readonly description: "Performing rights organisation name (e.g. PRS, ASCAP, BMI, SACEM)";
};
readonly pro_member_number: {
readonly type: "string";
readonly description: "Member number at the PRO named in pro_name";
};
readonly default_publisher: {
readonly type: "string";
readonly description: "Default publisher name for this person";
};
readonly default_publisher_ipi: {
readonly type: "string";
readonly description: "Default publisher's IPI number";
};
readonly company: {
readonly type: "string";
readonly description: "Company / organisation name";
};
readonly position: {
readonly type: "string";
readonly description: "Job title / position at the company";
};
readonly territory: {
readonly type: "string";
readonly description: "Primary territory / market (e.g. 'UK', 'US East Coast')";
};
readonly origin_countries: {
readonly type: "array";
readonly items: {
readonly type: "string";
};
readonly description: "ISO 3166-1 alpha-2 heritage countries (multiple allowed) — the creator's self-identified origin";
};
readonly relationship_strength: {
readonly type: "integer";
readonly description: "Relationship strength score (caller-defined scale)";
};
readonly email_preferences: {
readonly type: "object";
readonly description: "Email opt-in preferences, e.g. { monthly_digest: true, news_announcements: false }";
};
readonly profile_image_url: {
readonly type: "string";
readonly description: "URL to profile image";
};
readonly notes: {
readonly type: "string";
readonly description: "Internal notes";
};
readonly isni: {
readonly type: readonly ["string", "null"];
readonly description: "ISNI identifier (16 digits). Stored on person_enrichment satellite. Send null to clear a wrong value.";
};
readonly musicbrainz_id: {
readonly type: readonly ["string", "null"];
readonly description: "MusicBrainz artist ID (UUID). Stored on person_enrichment satellite. Send null to clear.";
};
readonly wikidata_id: {
readonly type: readonly ["string", "null"];
readonly description: "Wikidata entity ID (e.g. Q7259). Stored on person_enrichment satellite. Send null to clear a wrong match — enrichment will then not re-apply that entity's identifiers.";
};
readonly discogs_artist_id: {
readonly type: readonly ["string", "null"];
readonly description: "Discogs artist ID. Stored on person_enrichment satellite. Send null to clear.";
};
readonly deezer_artist_id: {
readonly type: readonly ["string", "null"];
readonly description: "Deezer artist ID. Stored on person_enrichment satellite. Send null to clear.";
};
readonly imdb_id: {
readonly type: readonly ["string", "null"];
readonly description: "IMDb name ID (e.g. nm0000001). Stored on person_enrichment satellite. Send null to clear.";
};
readonly viaf_id: {
readonly type: readonly ["string", "null"];
readonly description: "VIAF identifier. Stored on person_enrichment satellite. Send null to clear.";
};
readonly date_of_birth: {
readonly type: readonly ["string", "null"];
readonly description: "Date of birth (ISO 8601, YYYY-MM-DD). Stored on person_enrichment satellite. Send null to clear.";
};
readonly date_of_death: {
readonly type: readonly ["string", "null"];
readonly description: "Date of death (ISO 8601, YYYY-MM-DD). Stored on person_enrichment satellite. Send null to clear.";
};
readonly gender: {
readonly type: readonly ["string", "null"];
readonly description: "Gender (free text; commonly 'male' / 'female' / 'non_binary'). Stored on person_enrichment satellite. Send null to clear.";
};
readonly nationality: {
readonly type: readonly ["string", "null"];
readonly description: "Nationality (free text; ISO country name preferred). Stored on person_enrichment satellite. Send null to clear.";
};
readonly nationality_wikidata_id: {
readonly type: readonly ["string", "null"];
readonly description: "Wikidata entity ID of the nationality (e.g. Q145). Stored on person_enrichment satellite. Send null to clear.";
};
readonly birth_place: {
readonly type: readonly ["string", "null"];
readonly description: "Place of birth (free text). Stored on person_enrichment satellite. Send null to clear.";
};
readonly birth_place_wikidata_id: {
readonly type: readonly ["string", "null"];
readonly description: "Wikidata entity ID of the place of birth. Stored on person_enrichment satellite. Send null to clear.";
};
readonly instruments: {
readonly type: readonly ["array", "null"];
readonly items: {
readonly type: "string";
};
readonly description: "Instruments played. Stored on person_enrichment satellite. Send [] or null to clear.";
};
readonly career_start_year: {
readonly type: readonly ["integer", "null"];
readonly description: "Year career started (4-digit). Stored on person_enrichment satellite. Send null to clear.";
};
readonly languages_spoken: {
readonly type: readonly ["array", "null"];
readonly items: {
readonly type: "string";
};
readonly description: "Languages spoken. Stored on person_enrichment satellite. Send [] or null to clear.";
};
};
export declare class PeopleTools {
private pica;
constructor(pica: PicaClient);
/**
* Get all people tools
*/
getTools(): Array<{
definition: ToolDefinition;
executor: ToolExecutor;
}>;
/**
* Query people — unified list + search
*/
private queryPeople;
/**
* Inspect person — unified get + get_full with section filtering
*/
private inspectPerson;
/**
* Create person
*/
private createPerson;
/**
* Update person
*/
private updatePerson;
/**
* Delete person
*/
private deletePerson;
/**
* Give one person a new global identity (ops 482424b7). A typed refusal
* (4xx with a SPLIT_* code) is returned as a structured error, not thrown.
*/
private splitPersonIdentity;
/**
* Bulk delete people
*/
private bulkDeletePeople;
/**
* ADR-289 Wave B2 item 4 — action-dispatched artist-projects
* management, porting the bespoke assistant's
* get_person_artist_projects / enrich_artist_projects /
* set_primary_artist_project trio into a single tool.
*
* Whole-branch review: an unrecognized action string is now explicitly
* rejected (mirrors the manageMultimedia guard added in projects.ts
* Wave C1), rather than silently falling through to 'list'.
*/
private artistProjects;
/**
* ADR-289 Wave B2 item 5 — ports the bespoke assistant's
* `triangulate_artist`. Read-only.
*/
private triangulateArtist;
}
//# sourceMappingURL=people.d.ts.map