@labelgrid/mcp 0.2.1 → 0.3.0

package/dist/config.js

@@ -13,17 +13,36 @@ export const DEFAULT_BASE_URL = 'https://api.labelgrid.com/api/public';
 export const FULL_WRITES_ACK = 'I accept responsibility for AI-driven distribution actions';
 /** The valid toolset names; unknown names in LABELGRID_TOOLSETS warn and are ignored. */
 export const KNOWN_TOOLSETS = new Set([
-    'identity',
+    'account',
     'reference',
     'catalog',
     'releases',
-    'review',
-    'analytics',
-    'accounting',
-    'delivery',
+    'insights',
+    'finance',
     'webhooks',
     'distribution',
 ]);
+/**
+ * Pre-0.3.0 toolset names still accepted in LABELGRID_TOOLSETS, translated to
+ * their current toolset. Every legacy name used emits a stderr warning naming
+ * the toolset it maps to (see loadConfig). Names that survived the regroup
+ * (catalog, reference, releases, webhooks, distribution) map to themselves via
+ * KNOWN_TOOLSETS and need no alias entry.
+ */
+export const LEGACY_TOOLSET_ALIASES = {
+    identity: 'account',
+    review: 'releases',
+    delivery: 'releases',
+    analytics: 'insights',
+    accounting: 'finance',
+};
+/**
+ * Toolsets excluded from the default surface when LABELGRID_TOOLSETS is unset
+ * (`toolsets === null`). Naming one explicitly in LABELGRID_TOOLSETS enables
+ * it. Consulted by gating and by the setup-mode listing, so the advertised
+ * surface matches reality.
+ */
+export const defaultExcludedToolsets = new Set(['webhooks']);
 /** Thrown when the environment cannot produce a usable config. */
 export class ConfigError extends Error {
     constructor(message) {
@@ -72,6 +91,19 @@ export function loadConfig(env) {
             .split(',')
             .map((s) => s.trim())
             .filter((s) => s.length > 0)) {
+            const alias = LEGACY_TOOLSET_ALIASES[name];
+            if (alias !== undefined) {
+                // Legacy names still work, but warn loudly so the operator migrates —
+                // and, for the review/delivery → releases remaps, flag that `releases`
+                // also carries write tools so a read-only expectation is not violated.
+                let warning = `Legacy toolset name "${name}" in LABELGRID_TOOLSETS maps to "${alias}" — update your configuration to use "${alias}".`;
+                if (name === 'review' || name === 'delivery') {
+                    warning += ` Note: the mapped "${alias}" toolset also contains write tools (run_release_checks, manage_release_links, add_review_issue_note) — set LABELGRID_READ_ONLY=true or LABELGRID_ENABLE_WRITES=false to keep a read-only surface.`;
+                }
+                log('warn', warning);
+                toolsets.add(alias);
+                continue;
+            }
             if (!KNOWN_TOOLSETS.has(name)) {
                 log('warn', `Unknown toolset in LABELGRID_TOOLSETS: "${name}" (ignored).`);
             }

package/dist/coverage.js

@@ -15,8 +15,8 @@
  * uppercase method followed by a single space.
  */
 export const COVERAGE = {
-    // identity
-    'GET /me': 'get_me',
+    // account
+    'GET /me': 'get_account',
     'DELETE /tokens/current': 'revoke_api_token',
     'DELETE /tokens/{tokenId}': 'revoke_api_token',
     // reference
@@ -27,93 +27,93 @@ export const COVERAGE = {
     'GET /instruments': 'list_reference_data',
     'GET /distro-outlets': 'list_reference_data',
     'GET /territories': 'list_reference_data',
-    // analytics
+    // insights
     'GET /analytics/summary': 'get_analytics',
     // catalog reads
-    'GET /labels': 'list_labels',
-    'GET /labels/{label}': 'get_label',
-    'GET /artists': 'list_artists',
-    'GET /artists/{artist}': 'get_artist',
-    'GET /writers': 'list_writers',
-    'GET /writers/{writer}': 'get_writer',
-    'GET /publishers': 'list_publishers',
-    'GET /publishers/{publisher}': 'get_publisher',
-    'GET /releases': 'list_releases',
-    'GET /releases/{release}': 'get_release',
-    'GET /tracks': 'list_tracks',
-    'GET /tracks/{track}': 'get_track',
-    // files reads
-    'GET /tracks/{track}/files/{fileType}': 'get_track_file',
+    'GET /labels': 'search_catalog',
+    'GET /labels/{label}': 'get_catalog_item',
+    'GET /artists': 'search_catalog',
+    'GET /artists/{artist}': 'get_catalog_item',
+    'GET /writers': 'search_catalog',
+    'GET /writers/{writer}': 'get_catalog_item',
+    'GET /publishers': 'search_catalog',
+    'GET /publishers/{publisher}': 'get_catalog_item',
+    'GET /releases': 'search_catalog',
+    'GET /releases/{release}': 'get_catalog_item',
+    'GET /tracks': 'search_catalog',
+    'GET /tracks/{track}': 'get_catalog_item',
+    // asset reads
+    'GET /tracks/{track}/files/{fileType}': 'get_asset',
     'GET /tracks/{track}/licenses': 'list_track_licenses',
-    'GET /tracks/{track}/licenses/{trackLicense}': 'get_track_license',
-    'GET /releases/{release}/files/{assetType}': 'get_release_file',
-    // review reads
-    'GET /review-issues': 'list_review_issues',
-    'GET /issue-definitions': 'list_issue_definitions',
-    'GET /releases/{release}/quality-report': 'get_quality_report',
-    'GET /stream-radar/flags': 'list_stream_radar_flags',
-    'GET /stream-radar/flags/{streamRadarFlag}': 'get_stream_radar_flag',
+    'GET /tracks/{track}/licenses/{trackLicense}': 'list_track_licenses',
+    'GET /releases/{release}/files/{assetType}': 'get_asset',
+    // release review reads
+    'GET /review-issues': 'get_release_review',
+    'GET /issue-definitions': 'list_reference_data',
+    'GET /releases/{release}/quality-report': 'get_release_review',
+    'GET /stream-radar/flags': 'query_artificial_streaming',
+    'GET /stream-radar/flags/{streamRadarFlag}': 'query_artificial_streaming',
     // delivery
     'GET /queues/distro': 'get_delivery_queue',
     'GET /releases/{release}/landing-config': 'get_landing_config',
-    // accounting
-    'GET /statements': 'list_statements',
-    'GET /statements/{invoiceNumber}': 'get_statement',
-    'GET /statements/{invoiceNumber}/csv': 'download_statement_csv',
-    'GET /statements/export/csv': 'download_statement_csv',
-    'GET /statements/{invoiceNumber}/invoice': 'download_statement_invoice',
-    'GET /transactions': 'list_transactions',
-    'GET /royalties/breakdown': 'get_royalties_breakdown',
-    'GET /royalties/artificial-streams': 'list_artificial_streams',
-    'GET /artificial-streaming-fee/{period}': 'get_artificial_fee_breakdown',
+    // finance
+    'GET /statements': 'query_financials',
+    'GET /statements/{invoiceNumber}': 'query_financials',
+    'GET /statements/{invoiceNumber}/csv': 'download_statement',
+    'GET /statements/export/csv': 'download_statement',
+    'GET /statements/{invoiceNumber}/invoice': 'download_statement',
+    'GET /transactions': 'query_financials',
+    'GET /royalties/breakdown': 'query_financials',
+    'GET /royalties/artificial-streams': 'query_artificial_streaming',
+    'GET /artificial-streaming-fee/{period}': 'query_artificial_streaming',
     // webhooks
     'GET /webhooks': 'list_webhooks',
-    'POST /webhooks': 'create_webhook',
-    'GET /webhooks/event-types': 'list_webhook_event_types',
-    'GET /webhooks/{webhook}': 'get_webhook',
-    'PATCH /webhooks/{webhook}': 'update_webhook',
-    'DELETE /webhooks/{webhook}': 'delete_webhook',
-    'GET /webhooks/{webhook}/logs': 'get_webhook_logs',
-    'POST /webhooks/{webhook}/regenerate-secret': 'rotate_webhook_secret',
-    'POST /webhooks/{webhook}/test': 'test_webhook',
+    'POST /webhooks': 'manage_webhook',
+    'GET /webhooks/event-types': 'list_reference_data',
+    'GET /webhooks/{webhook}': 'list_webhooks',
+    'PATCH /webhooks/{webhook}': 'manage_webhook',
+    'DELETE /webhooks/{webhook}': 'manage_webhook',
+    'GET /webhooks/{webhook}/logs': 'list_webhooks',
+    'POST /webhooks/{webhook}/regenerate-secret': 'manage_webhook',
+    'POST /webhooks/{webhook}/test': 'manage_webhook',
     // catalog writes
-    'POST /labels': 'create_label',
-    'PATCH /labels/{label}': 'update_label',
-    'DELETE /labels/{label}': 'delete_label',
-    'POST /labels/{label}/images/{imageType}': 'upload_label_image',
-    'POST /artists': 'create_artist',
-    'PATCH /artists/{artist}': 'update_artist',
-    'DELETE /artists/{artist}': 'delete_artist',
-    'POST /artists/{artist}/photo': 'upload_artist_photo',
-    'POST /writers': 'create_writer',
-    'PATCH /writers/{writer}': 'update_writer',
-    'DELETE /writers/{writer}': 'delete_writer',
-    'POST /publishers': 'create_publisher',
-    'PATCH /publishers/{publisher}': 'update_publisher',
-    'DELETE /publishers/{publisher}': 'delete_publisher',
+    'POST /labels': 'create_catalog_item',
+    'PATCH /labels/{label}': 'update_catalog_item',
+    'DELETE /labels/{label}': 'delete_catalog_item',
+    'POST /labels/{label}/images/{imageType}': 'upload_image',
+    'POST /artists': 'create_catalog_item',
+    'PATCH /artists/{artist}': 'update_catalog_item',
+    'DELETE /artists/{artist}': 'delete_catalog_item',
+    'POST /artists/{artist}/photo': 'upload_image',
+    'POST /writers': 'create_catalog_item',
+    'PATCH /writers/{writer}': 'update_catalog_item',
+    'DELETE /writers/{writer}': 'delete_catalog_item',
+    'POST /publishers': 'create_catalog_item',
+    'PATCH /publishers/{publisher}': 'update_catalog_item',
+    'DELETE /publishers/{publisher}': 'delete_catalog_item',
     // release/track draft writes
-    'POST /releases': 'create_release',
-    'PATCH /releases/{release}': 'update_release',
-    'DELETE /releases/{release}': 'delete_release',
-    'POST /tracks': 'create_track',
-    'PATCH /tracks/{track}': 'update_track',
-    'DELETE /tracks/{track}': 'delete_track',
-    'POST /releases/{release}/validate': 'validate_release',
-    'POST /releases/{release}/quality-report/refresh': 'refresh_quality_report',
-    'PUT /releases/{release}/landing-config': 'update_landing_config',
-    'POST /releases/short-url': 'create_release_short_url',
+    'POST /releases': 'create_catalog_item',
+    'PATCH /releases/{release}': 'update_catalog_item',
+    'DELETE /releases/{release}': 'delete_catalog_item',
+    'POST /tracks': 'create_catalog_item',
+    'PATCH /tracks/{track}': 'update_catalog_item',
+    'DELETE /tracks/{track}': 'delete_catalog_item',
+    'POST /releases/{release}/validate': 'run_release_checks',
+    'POST /releases/{release}/quality-report/refresh': 'run_release_checks',
+    'PUT /releases/{release}/landing-config': 'manage_release_links',
+    'POST /releases/short-url': 'manage_release_links',
     'POST /review-issues/{reviewReleaseIssue}/notes': 'add_review_issue_note',
     // full writes (distribution)
-    'POST /tracks/{track}/files/{fileType}/upload-url': 'upload_track_audio',
-    'PUT /tracks/{track}/files/{fileType}': 'upload_track_audio',
-    'DELETE /tracks/{track}/files/{fileType}': 'delete_track_audio',
-    'POST /releases/{release}/files/{assetType}/upload-url': 'upload_release_asset',
-    'PUT /releases/{release}/files/{assetType}': 'upload_release_asset',
-    'DELETE /releases/{release}/files/{assetType}': 'delete_release_asset',
-    'POST /tracks/{track}/licenses': 'upload_track_license',
-    'POST /tracks/{track}/licenses/{trackLicense}': 'update_track_license',
-    'DELETE /tracks/{track}/licenses/{trackLicense}': 'delete_track_license',
-    'POST /releases/{release}/photo': 'upload_release_artwork',
+    'POST /tracks/{track}/files/{fileType}/upload-url': 'upload_asset',
+    'PUT /tracks/{track}/files/{fileType}': 'upload_asset',
+    'DELETE /tracks/{track}/files/{fileType}': 'delete_asset',
+    'POST /releases/{release}/files/{assetType}/upload-url': 'upload_asset',
+    'PUT /releases/{release}/files/{assetType}': 'upload_asset',
+    'DELETE /releases/{release}/files/{assetType}': 'delete_asset',
+    'POST /tracks/{track}/licenses': 'manage_track_license',
+    'POST /tracks/{track}/licenses/{trackLicense}': 'manage_track_license',
+    'DELETE /tracks/{track}/licenses/{trackLicense}': 'manage_track_license',
+    'POST /releases/{release}/photo': 'upload_asset',
     'POST /releases/{release}/distribute': 'distribute_release',
     'POST /releases/{release}/takedown-all': 'takedown_release',
     'POST /releases/{release}/confirm-review': 'confirm_review',
@@ -145,6 +145,6 @@ export const EXCLUDED = {
     'GET /transactions/csv': 'transaction CSV export — not exposed in v1',
 };
 export const PENDING_DOCS = {
-    'GET /account': 'get_account_summary',
-    'GET /tracks/{track}/files/{assetType}/download-url': 'get_track_audio_download_url',
+    'GET /account': 'get_account',
+    'GET /tracks/{track}/files/{assetType}/download-url': 'get_asset',
 };

package/dist/entities.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The catalog-entity registry: the six entity kinds the consolidated catalog
+ * tools operate on, each with its endpoint path and the reviewed documentation
+ * fragments (list filters, create/update fields, delete refusals) the tool
+ * descriptions are assembled from.
+ *
+ * This is data, not behavior — the catalog tools stay thin wrappers and the
+ * API owns all validation. The wording here carries the caveats from the
+ * per-entity tool descriptions it replaces (recording_country on track create,
+ * RELEASE_LOCKED_FIELDS on release update, the delete refusals).
+ */
+export type EntityName = 'label' | 'artist' | 'writer' | 'publisher' | 'release' | 'track';
+/** The entity names as a tuple, for zod enum inputs. */
+export declare const ENTITY_NAMES: readonly ["label", "artist", "writer", "publisher", "release", "track"];
+export type EntitySpec = {
+    /** The collection endpoint path, e.g. '/labels'. */
+    path: string;
+    /** One-line doc of the useful list filters for search_catalog. */
+    filtersDoc: string;
+    /** One-line doc of required + common create/update fields. */
+    fieldsDoc: string;
+    /** One-line doc of the server-side delete refusals. */
+    deleteNote: string;
+};
+export declare const ENTITIES: Record<EntityName, EntitySpec>;

package/dist/entities.js

@@ -0,0 +1,51 @@
+/**
+ * The catalog-entity registry: the six entity kinds the consolidated catalog
+ * tools operate on, each with its endpoint path and the reviewed documentation
+ * fragments (list filters, create/update fields, delete refusals) the tool
+ * descriptions are assembled from.
+ *
+ * This is data, not behavior — the catalog tools stay thin wrappers and the
+ * API owns all validation. The wording here carries the caveats from the
+ * per-entity tool descriptions it replaces (recording_country on track create,
+ * RELEASE_LOCKED_FIELDS on release update, the delete refusals).
+ */
+/** The entity names as a tuple, for zod enum inputs. */
+export const ENTITY_NAMES = ['label', 'artist', 'writer', 'publisher', 'release', 'track'];
+export const ENTITIES = {
+    label: {
+        path: '/labels',
+        filtersDoc: 'label: no documented filters — paginate with page/per_page.',
+        fieldsDoc: 'label — required: name, default_email; optional: support email, website/platform URLs, default copyright lines, isrc_base.',
+        deleteNote: 'label: refused while the label still has releases — remove or reassign its releases first.',
+    },
+    artist: {
+        path: '/artists',
+        filtersDoc: 'artist: artist_name (filter by artist name).',
+        fieldsDoc: 'artist — required: artist_name; optional: full_name, email, location, bios, isni, default_language, platform profile URLs.',
+        deleteNote: 'artist: refused while still referenced by releases or tracks.',
+    },
+    writer: {
+        path: '/writers',
+        filtersDoc: 'writer: name (writer name), ipi (IPI number).',
+        fieldsDoc: 'writer — required: first_name, last_name; optional: middle_name, display_credits, email, country, pro, ipi, isni, publisher_id (or publisher_name/publisher_pro/publisher_ipi).',
+        deleteNote: 'writer: refused while still referenced by tracks.',
+    },
+    publisher: {
+        path: '/publishers',
+        filtersDoc: 'publisher: name (publisher name), ipi (IPI number).',
+        fieldsDoc: 'publisher — required: name; optional: ipi, pro, isni, controlled_publisher.',
+        deleteNote: 'publisher: refused while still referenced by writers.',
+    },
+    release: {
+        path: '/releases',
+        filtersDoc: 'release: label_id (owning label id), is_live (1 = live/distributed only), barcode_number (UPC/EAN), cat (catalog number).',
+        fieldsDoc: 'release — required on create: content_type, label_id, artists, titles, cat (catalog number), artwork_ai_usage, primary_genre_id; many optional fields (dates, copyright lines, genres, per-outlet URLs). Once submitted or distributed some fields are locked — changing one returns a 403 with code RELEASE_LOCKED_FIELDS naming exactly which fields cannot change.',
+        deleteNote: 'release: only a never-submitted draft can be deleted.',
+    },
+    track: {
+        path: '/tracks',
+        filtersDoc: 'track: release_id (one release’s tracks), isrc (filter by ISRC).',
+        fieldsDoc: 'track — required on create: release_id, disc, track_num, composition_type, artists, audio_ai_usage, composition_ai_usage, commercial_samples, audio_language, contributors, and recording_country (ISO 3166-1 alpha-2, e.g. "US"); optional: titles, isrc, iswc, writers, publishers, splits, and more.',
+        deleteNote: 'track: allowed while the parent release is an editable draft; refused once submitted or distributed.',
+    },
+};

package/dist/gating.d.ts

@@ -5,7 +5,7 @@
  * class is armed. Anything the matrix cannot positively resolve — including an
  * unrecognized gate — is disabled.
  */
-import type { Config } from './config.js';
+import { type Config } from './config.js';
 export type Gate = 'read' | 'safe_write' | 'full_write';
 export declare function isToolEnabled(t: {
     gate: Gate;

package/dist/gating.js

@@ -5,8 +5,12 @@
  * class is armed. Anything the matrix cannot positively resolve — including an
  * unrecognized gate — is disabled.
  */
+import { defaultExcludedToolsets } from './config.js';
 export function isToolEnabled(t, c) {
-    const toolsetSelected = c.toolsets === null || c.toolsets.has(t.toolset);
+    // With no explicit LABELGRID_TOOLSETS selection, the default surface applies
+    // (which excludes the default-off toolsets, e.g. webhooks). An explicit
+    // selection wins: naming a default-off toolset enables it.
+    const toolsetSelected = c.toolsets === null ? !defaultExcludedToolsets.has(t.toolset) : c.toolsets.has(t.toolset);
     if (!toolsetSelected)
         return false;
     switch (t.gate) {

package/dist/projection.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Concise-mode field projection.
+ *
+ * Tools marked [proj] accept `response_format: 'concise' | 'detailed'`
+ * (default concise). Concise mode projects the API response down to a per-tool
+ * allowlist of high-signal fields so large payloads stop swamping the client's
+ * context window; `'detailed'` bypasses projection and returns the verbatim
+ * API response.
+ *
+ * The walk keeps, on every object: any key in the per-tool allowlist, ALWAYS
+ * `id` and any key ending `_id`, and any key whose value is an object/array
+ * (containers are what the walk traverses — this is what keeps pagination
+ * envelopes like `{ data: [...] }` intact while their leaves are filtered).
+ * Kept values are recursed into. A `"_projection": "concise"` marker is
+ * appended at the TOP level only (when the top level is an object).
+ *
+ * Pagination fidelity: a subtree keyed exactly `meta` or `links` (at ANY depth)
+ * is preserved VERBATIM — every field, unfiltered — so page counts, totals and
+ * next/prev links always survive. Top-level primitive cursor keys
+ * (`next_cursor`, `prev_cursor`, `cursor`) are likewise preserved so
+ * cursor-paginated responses stay pageable under concise mode.
+ *
+ * Projection is presentation-only — it never transforms values. The 400K
+ * toToolResult cap stays as the backstop for anything projection cannot tame.
+ */
+import type { ApiResult } from './api/http.js';
+/** Per-tool concise-mode field allowlists, keyed by tool name. */
+export declare const CONCISE_ALLOWLISTS: Record<string, readonly string[]>;
+/**
+ * Projects `value` down to the allowlisted fields (plus `id`/`*_id` and
+ * container keys), appending the `_projection: 'concise'` marker at the top
+ * level when the top level is an object.
+ */
+export declare function projectConcise(value: unknown, keep: readonly string[]): unknown;
+/**
+ * Applies a [proj] tool's concise projection to a successful result. Errors
+ * pass through untouched; `response_format: 'detailed'` bypasses projection
+ * entirely (the verbatim API response); absent or `'concise'` projects.
+ */
+export declare function applyProjection(result: ApiResult<unknown>, toolName: string, responseFormat: unknown): ApiResult<unknown>;

package/dist/projection.js

@@ -0,0 +1,145 @@
+/**
+ * Concise-mode field projection.
+ *
+ * Tools marked [proj] accept `response_format: 'concise' | 'detailed'`
+ * (default concise). Concise mode projects the API response down to a per-tool
+ * allowlist of high-signal fields so large payloads stop swamping the client's
+ * context window; `'detailed'` bypasses projection and returns the verbatim
+ * API response.
+ *
+ * The walk keeps, on every object: any key in the per-tool allowlist, ALWAYS
+ * `id` and any key ending `_id`, and any key whose value is an object/array
+ * (containers are what the walk traverses — this is what keeps pagination
+ * envelopes like `{ data: [...] }` intact while their leaves are filtered).
+ * Kept values are recursed into. A `"_projection": "concise"` marker is
+ * appended at the TOP level only (when the top level is an object).
+ *
+ * Pagination fidelity: a subtree keyed exactly `meta` or `links` (at ANY depth)
+ * is preserved VERBATIM — every field, unfiltered — so page counts, totals and
+ * next/prev links always survive. Top-level primitive cursor keys
+ * (`next_cursor`, `prev_cursor`, `cursor`) are likewise preserved so
+ * cursor-paginated responses stay pageable under concise mode.
+ *
+ * Projection is presentation-only — it never transforms values. The 400K
+ * toToolResult cap stays as the backstop for anything projection cannot tame.
+ */
+/** The shared allowlist for catalog entity reads (search_catalog / get_catalog_item). */
+const CATALOG_FIELDS = [
+    'title',
+    'name',
+    'artist_name',
+    'full_name',
+    'status',
+    'review_status',
+    'is_live',
+    'barcode_number',
+    'cat',
+    'isrc',
+    'release_date',
+    'created_at',
+    'updated_at',
+    'email',
+    'ipi',
+    'pro',
+];
+/** Per-tool concise-mode field allowlists, keyed by tool name. */
+export const CONCISE_ALLOWLISTS = {
+    search_catalog: CATALOG_FIELDS,
+    get_catalog_item: CATALOG_FIELDS,
+    get_release_review: [
+        'code',
+        'title',
+        'severity',
+        'status',
+        'requires_feedback',
+        'message',
+        'created_at',
+    ],
+    get_delivery_queue: ['status', 'outlet', 'outlet_id', 'delivered_at', 'created_at', 'type'],
+    query_artificial_streaming: [
+        'dsp',
+        'country',
+        'quantity',
+        'period',
+        'date',
+        'status',
+        'severity',
+        'isrc',
+        'upc',
+    ],
+    query_financials: [
+        'period',
+        'status',
+        'currency',
+        'gross_usd',
+        'net_usd',
+        'amount',
+        'total_due_usd',
+        'invoice_number',
+        'transaction_type',
+        'scope',
+        'date_paid',
+        'created_at',
+    ],
+};
+/** Subtrees whose entire contents are kept verbatim, at any depth. */
+const VERBATIM_ENVELOPE_KEYS = new Set(['meta', 'links']);
+/** Primitive cursor keys preserved at the TOP level only. */
+const TOP_LEVEL_CURSOR_KEYS = new Set([
+    'next_cursor',
+    'prev_cursor',
+    'cursor',
+]);
+function isContainer(value) {
+    return value !== null && typeof value === 'object';
+}
+function projectValue(value, keep, topLevel = false) {
+    if (Array.isArray(value)) {
+        return value.map((item) => projectValue(item, keep));
+    }
+    if (isContainer(value)) {
+        const out = {};
+        for (const [key, item] of Object.entries(value)) {
+            // Pagination envelopes: a `meta`/`links` subtree is kept verbatim, unfiltered.
+            if (VERBATIM_ENVELOPE_KEYS.has(key)) {
+                out[key] = item;
+                continue;
+            }
+            // Top-level primitive cursor keys survive so pagination isn't lost.
+            if (topLevel && TOP_LEVEL_CURSOR_KEYS.has(key) && !isContainer(item)) {
+                out[key] = item;
+                continue;
+            }
+            if (keep.has(key) || key === 'id' || key.endsWith('_id') || isContainer(item)) {
+                out[key] = isContainer(item) ? projectValue(item, keep) : item;
+            }
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * Projects `value` down to the allowlisted fields (plus `id`/`*_id` and
+ * container keys), appending the `_projection: 'concise'` marker at the top
+ * level when the top level is an object.
+ */
+export function projectConcise(value, keep) {
+    const keepSet = new Set(keep);
+    const projected = projectValue(value, keepSet, true);
+    if (isContainer(projected) && !Array.isArray(projected)) {
+        return { ...projected, _projection: 'concise' };
+    }
+    return projected;
+}
+/**
+ * Applies a [proj] tool's concise projection to a successful result. Errors
+ * pass through untouched; `response_format: 'detailed'` bypasses projection
+ * entirely (the verbatim API response); absent or `'concise'` projects.
+ */
+export function applyProjection(result, toolName, responseFormat) {
+    if (responseFormat === 'detailed')
+        return result;
+    if ('error' in result)
+        return result;
+    return { data: projectConcise(result.data, CONCISE_ALLOWLISTS[toolName] ?? []) };
+}

package/dist/resources.d.ts

@@ -0,0 +1,29 @@
+/**
+ * MCP resources: the nine reference datasets, exposed at
+ * `labelgrid://reference/{type}`.
+ *
+ * Each read fetches the dataset via the shared client (no caching) and returns
+ * JSON text. The same datasets are served by the `list_reference_data` tool,
+ * which is the fallback for clients that don't surface resources — the
+ * type→path map lives here as the single source for both. In setup mode the
+ * resources are still registered (so introspection shows what the server
+ * offers) but reads return the NOT_CONNECTED guidance JSON instead of data.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { LabelGridClient } from './api/http.js';
+import type { Config } from './config.js';
+/** The reference dataset types as a tuple, for the tool's zod enum. */
+export declare const REFERENCE_TYPES: readonly ["genres", "genre_categories", "languages", "contributor_roles", "instruments", "distro_outlets", "territories", "issue_definitions", "webhook_event_types"];
+export type ReferenceType = (typeof REFERENCE_TYPES)[number];
+export declare const REFERENCE_DATASETS: Record<ReferenceType, {
+    path: string;
+    title: string;
+    description: string;
+}>;
+/** The URI for one reference dataset resource. */
+export declare function referenceUri(type: ReferenceType): string;
+/**
+ * Registers the nine `labelgrid://reference/{type}` resources on the server.
+ * Reads fetch via the client; in setup mode they return NOT_CONNECTED guidance.
+ */
+export declare function registerReferenceResources(server: Pick<McpServer, 'registerResource'>, config: Config, client: LabelGridClient): void;