@withpica/mcp-sdk 3.3.1 → 3.5.0

package/CHANGELOG.md

@@ -11,6 +11,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.5.0] - 2026-07-07
+
+### Added
+
+- `catalogStats()` accepts an optional `{ entity, group_by }` argument and
+  serialises it to the query string, powering the Oracle aggregation on
+  `pica_catalog_stats` (one-dimension breakdowns + entity totals). Overloaded so
+  a no-arg call still returns the precise `CatalogStats` envelope type; a call
+  with params returns the widened breakdown shape. Backward-compatible — the
+  no-arg request is byte-identical to before.
+
+## [3.4.0] - 2026-07-06
+
+### Changed
+
+- `recordings.search()` now delegates a text `query` to the server-side unified
+  search endpoint (`GET /admin/recordings/search`) instead of fetching up to 200
+  rows and filtering client-side on `title`/`isrc` only. Recordings are now
+  findable by `artist_name` (and without the 200-row ceiling). The no-query path
+  (structured/score filters) is unchanged.
+
 ## [3.3.1] - 2026-07-04
 
 ### Removed

package/dist/index.d.ts

@@ -854,6 +854,40 @@ declare class WorksResource extends BaseResource {
         sort?: "completeness_score:asc" | "completeness_score:desc" | "missing_field_count:asc" | "missing_field_count:desc" | "streaming_activity:asc" | "streaming_activity:desc";
         /** Filter to works registered with a collection society (case-insensitive code, e.g. 'ASCAP', 'PRS', 'GEMA'). */
         society_code?: string;
+        /** Filter by work type (song, instrumental, library, demo, sample). */
+        work_type?: string;
+        /** Filter by work status (demo, unreleased, released, pitched, placed, archived). */
+        work_status?: string;
+        /** Filter to works tagged with this genre (case-sensitive array-contains). */
+        genre?: string;
+        /** Filter to works whose primary recording carries this mood tag. */
+        mood?: string;
+        /** Filter to works whose primary recording tempo is >= this BPM. */
+        tempo_min?: number;
+        /** Filter to works whose primary recording tempo is <= this BPM. */
+        tempo_max?: number;
+        /** Exact primary-artist name match. */
+        primary_artist?: string;
+        /** Exact primary-artist name match (alias of primary_artist). */
+        artist?: string;
+        /** Filter by derived label (primary recording label, else primary release parent_label). */
+        label?: string;
+        /** Filter to works available (true) / not available (false) for licensing. */
+        available_for_licensing?: boolean;
+        /** Filter by the primary release's format (single, ep, album, compilation). */
+        release_format?: string;
+        /** Filter to featured (true) / non-featured (false) works. */
+        is_featured?: boolean;
+        /** Filter by directory-published state. */
+        published?: boolean;
+        /** Only works added/composed on or after this ISO date (YYYY-MM-DD). */
+        created_from?: string;
+        /** Only works added/composed on or before this ISO date (YYYY-MM-DD). */
+        created_to?: string;
+        /** Filter to works that have (true) or lack (false) an ISWC. */
+        has_iswc?: boolean;
+        /** Filter to works that have (true) or lack (false) a publisher_name. */
+        has_publisher?: boolean;
     }): Promise<PaginatedResult<Work>>;
     get(id: string): Promise<Work>;
     create(data: Partial<Work>): Promise<Work>;
@@ -960,6 +994,14 @@ declare class PeopleResource extends BaseResource {
         record_kind?: "individual" | "placeholder" | "artefact";
         /** Filter by outreach readiness. */
         outreach_state?: "ready" | "needs_email" | "needs_disambiguation" | "not_a_target" | "do_not_contact" | "previously_declined";
+        /** Filter to people who have (true) / lack (false) an email address. */
+        has_email?: boolean;
+        /** Filter to people who have (true) / lack (false) a phone number. */
+        has_phone?: boolean;
+        /** Filter to people holding ANY of these roles (array-overlap). */
+        roles?: string[];
+        /** Filter to people carrying ANY of these tags (array-overlap). */
+        tags?: string[];
     }): Promise<PaginatedResult<Person>>;
     get(id: string): Promise<Person>;
     create(data: Partial<Person>): Promise<Person>;
@@ -1273,6 +1315,18 @@ declare class AgreementsResource extends BaseResource {
          * the hood.
          */
         awaiting_signature?: boolean;
+        /** Agreements with start_date on/after this ISO date (YYYY-MM-DD). */
+        start_date_from?: string;
+        /** Agreements with start_date on/before this ISO date. */
+        start_date_to?: string;
+        /** Agreements with end_date on/after this ISO date. */
+        end_date_from?: string;
+        /** Agreements with end_date on/before this ISO date. */
+        end_date_to?: string;
+        /** Active agreements whose end_date falls within N days from today. */
+        expiring_within_days?: number;
+        /** true → only agreements that have an end_date; false → only open-ended. */
+        has_end_date?: boolean;
         limit?: number;
         offset?: number;
     }): Promise<Agreement[]>;
@@ -1467,8 +1521,17 @@ declare class RecordingsResource extends BaseResource {
         limit?: number;
     }): Promise<Recording[]>;
     /**
-     * Search recordings. The recordings API doesn't support text search,
-     * so we fetch all and filter client-side for text queries.
+     * Search recordings. A text `query` delegates to the server-side unified
+     * catalog matcher (`GET /admin/recordings/search`, backed by
+     * `chainService.searchFlat`) which matches title + artist_name + isrc —
+     * replacing the old fetch-200-and-filter-client-side-on-title/isrc
+     * approach, which both capped results at 200 rows and never matched on
+     * artist_name (e.g. a query for an artist whose name doesn't appear in
+     * the recording title, like "gwazai" against `artist_name: 'Gwazai'`,
+     * returned zero results).
+     *
+     * Without a `query`, behaviour is unchanged: forward filter/sort params
+     * to the plain list route.
      *
      * ADR-270 Phase (b): sort, streaming_activity_gt, streaming_activity_lt
      * are forwarded as query params to the server-side filter/sort path.
@@ -1487,6 +1550,18 @@ declare class RecordingsResource extends BaseResource {
         missing_field_count_gt?: number;
         /** ADR-270 §3.4 — filter: missing_field_count strictly less than this */
         missing_field_count_lt?: number;
+        /** Structured Recall — filter to recordings with (true) or without (false) an ISRC */
+        has_isrc?: boolean;
+        /** Structured Recall — filter by version type */
+        version_type?: string;
+        /** Structured Recall — inclusive ISO date range on recordings.recorded_at */
+        recorded_from?: string;
+        /** Structured Recall — inclusive ISO date range on recordings.recorded_at */
+        recorded_to?: string;
+        /** Structured Recall — inclusive ISO date range on recordings.created_at */
+        created_from?: string;
+        /** Structured Recall — inclusive ISO date range on recordings.created_at */
+        created_to?: string;
     }): Promise<PaginatedResult<Recording>>;
     get(id: string): Promise<Recording>;
     create(data: Partial<Recording>): Promise<Recording>;
@@ -3643,6 +3718,8 @@ declare class ReleasesResource extends BaseResource {
         query?: string;
         upc?: string;
         spotify_album_id?: string;
+        release_date_from?: string;
+        release_date_to?: string;
     }): Promise<any>;
     get(id: string): Promise<any>;
     /**
@@ -4202,6 +4279,10 @@ export declare class PicaClient {
      * Get accurate catalog stats via SQL counts (no pagination limits)
      */
     catalogStats(): Promise<CatalogStats>;
+    catalogStats(params: {
+        entity?: string;
+        group_by?: string;
+    }): Promise<CatalogStats | Record<string, unknown>>;
     constructor(config: PicaClientConfig);
 }
 export type { Work, Person, Recording, PaginatedResult, PicaClientConfig, SyncSearchParams, SyncTrack, SyncSearchResult, LicenseEnquiryInput, LicenseEnquiry, BookingEnquiry, WorkCredit, WorkCreditsInput, PicaScore, PicaScorePillar, AudioFile, AudioAnalysisStatus, PresignedUploadResult, CompleteUploadResult, IdentifyResult, MultimediaItem, Agreement, AgreementWorkLink, CreateAgreementFromTemplateParams, AgreementSendForSignatureResult, AgreementSendForSignatureSentEntry, AgreementSendForSignatureSkippedEntry, AgreementSendForSignatureSkipReason, SyncPlacement, SyncPlacementSource, SyncPlacementRecording, SyncPlacementWithRelations, SyncPlacementContactInput, SyncPlacementRecordingInput, SyncPlacementSourceInput, CreateSyncPlacementInput, UpdateSyncPlacementInput, SyncPlacementQueryParams, SyncPlacementStatus, SyncPlacementVerificationStatus, SyncPlacementConfidentialityLevel, SyncPlacementSourceKind, CatalogStats, NotificationsSummary, CreateUploadSessionInput, CreateUploadSessionResult, };