@labelgrid/mcp 0.2.2 → 0.3.1

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/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/index.js

@@ -6,12 +6,11 @@
  * to stderr and exits 1. Otherwise the server connects over the stdio
  * transport; stdout carries the MCP protocol only, all logging goes to stderr.
  */
+import { LabelGridClient, log } from '@labelgrid/core';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { LabelGridClient } from './api/http.js';
 import { ConfigError, loadConfig } from './config.js';
 import { isToolEnabled } from './gating.js';
 import { FULL_WRITES_NOTICE, LEGAL_SUMMARY } from './legal.js';
-import { log } from './log.js';
 import { buildServer } from './server.js';
 import { allTools } from './tools/all.js';
 import { VERSION } from './version.js';

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 '@labelgrid/core';
+/** 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 { LabelGridClient } from '@labelgrid/core';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.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;

package/dist/resources.js

@@ -0,0 +1,107 @@
+/**
+ * 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.
+ */
+/** The reference dataset types as a tuple, for the tool's zod enum. */
+export const REFERENCE_TYPES = [
+    'genres',
+    'genre_categories',
+    'languages',
+    'contributor_roles',
+    'instruments',
+    'distro_outlets',
+    'territories',
+    'issue_definitions',
+    'webhook_event_types',
+];
+export const REFERENCE_DATASETS = {
+    genres: {
+        path: '/genres',
+        title: 'Genres',
+        description: 'Valid values for primary/secondary/tertiary genre IDs on releases.',
+    },
+    genre_categories: {
+        path: '/genre-categories',
+        title: 'Genre categories',
+        description: 'The genre category groupings the genre IDs belong to.',
+    },
+    languages: {
+        path: '/languages',
+        title: 'Languages',
+        description: 'Audio and metadata language codes.',
+    },
+    contributor_roles: {
+        path: '/contributor-roles',
+        title: 'Contributor roles',
+        description: 'Valid role names for track contributors.',
+    },
+    instruments: {
+        path: '/instruments',
+        title: 'Instruments',
+        description: 'Instrument names for contributor credits.',
+    },
+    distro_outlets: {
+        path: '/distro-outlets',
+        title: 'Distribution outlets',
+        description: 'The distribution outlets/stores available to your account.',
+    },
+    territories: {
+        path: '/territories',
+        title: 'Territories',
+        description: 'Country/territory codes.',
+    },
+    issue_definitions: {
+        path: '/issue-definitions',
+        title: 'Issue definitions',
+        description: 'The catalog of review issue definitions: each code’s human-readable title, description, severity and whether it blocks distribution. Issue codes are string slugs.',
+    },
+    webhook_event_types: {
+        path: '/webhooks/event-types',
+        title: 'Webhook event types',
+        description: 'Every available webhook event type, each with the schema of the payload it delivers.',
+    },
+};
+/** The URI for one reference dataset resource. */
+export function referenceUri(type) {
+    return `labelgrid://reference/${type}`;
+}
+function asJsonText(uri, value) {
+    return {
+        contents: [{ uri, mimeType: 'application/json', text: JSON.stringify(value, null, 2) }],
+    };
+}
+/**
+ * Registers the nine `labelgrid://reference/{type}` resources on the server.
+ * Reads fetch via the client; in setup mode they return NOT_CONNECTED guidance.
+ */
+export function registerReferenceResources(server, config, client) {
+    for (const type of REFERENCE_TYPES) {
+        const dataset = REFERENCE_DATASETS[type];
+        const uri = referenceUri(type);
+        server.registerResource(`reference-${type}`, uri, {
+            title: dataset.title,
+            description: dataset.description,
+            mimeType: 'application/json',
+        }, async () => {
+            if (config.setupMode) {
+                return asJsonText(uri, {
+                    error: {
+                        code: 'NOT_CONNECTED',
+                        message: 'No LabelGrid API token is configured, so this resource cannot be read yet. ' +
+                            'Call the `setup` tool for step-by-step instructions to connect your account.',
+                        status: 0,
+                    },
+                });
+            }
+            const result = await client.get(dataset.path);
+            return asJsonText(uri, 'data' in result ? result.data : { error: result.error });
+        });
+    }
+}

package/dist/server.d.ts

@@ -8,8 +8,8 @@
  * result via {@link toToolResult} (API errors become isError results, never
  * protocol errors).
  */
+import { type LabelGridClient } from '@labelgrid/core';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { LabelGridClient } from './api/http.js';
-import type { Config } from './config.js';
+import { type Config } from './config.js';
 import { type ToolDef } from './tools/types.js';
 export declare function buildServer(config: Config, client: LabelGridClient, tools: ToolDef[]): McpServer;

package/dist/server.js

@@ -8,10 +8,12 @@
  * result via {@link toToolResult} (API errors become isError results, never
  * protocol errors).
  */
+import { log } from '@labelgrid/core';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { defaultExcludedToolsets } from './config.js';
 import { isToolEnabled } from './gating.js';
 import { DATA_HANDLING_NOTE, FULL_WRITES_NOTICE, LEGAL_SUMMARY } from './legal.js';
-import { log } from './log.js';
+import { registerReferenceResources } from './resources.js';
 import { setupTools } from './tools/setup.js';
 import { toToolResult } from './tools/types.js';
 import { VERSION } from './version.js';
@@ -51,10 +53,14 @@ export function buildServer(config, client, tools) {
     for (const tool of registered) {
         const isSetupHelper = tool.toolset === 'setup';
         // Listing rule: connected mode applies the full gate matrix; setup mode
-        // lists the whole catalog (only honoring an explicit toolset narrowing),
-        // because nothing can execute without a token anyway.
+        // lists the whole catalog (honoring an explicit toolset narrowing, and
+        // otherwise the same default exclusion the connected surface applies — so
+        // the advertised surface matches reality), because nothing can execute
+        // without a token anyway.
         const listable = config.setupMode
-            ? config.toolsets === null || config.toolsets.has(tool.toolset)
+            ? config.toolsets === null
+                ? !defaultExcludedToolsets.has(tool.toolset)
+                : config.toolsets.has(tool.toolset)
             : isToolEnabled(tool, config);
         if (!isSetupHelper && !listable)
             continue;
@@ -101,5 +107,19 @@ export function buildServer(config, client, tools) {
             return toToolResult(result);
         });
     }
+    // The nine labelgrid://reference/{type} resources follow the SAME listing
+    // rule as the reference tools: they are registered only when the `reference`
+    // toolset is enabled. Reference is not default-excluded, so an unset
+    // LABELGRID_TOOLSETS (or one naming `reference`) registers them; an explicit
+    // selection omitting `reference` disables them. Setup mode keeps them
+    // registered-but-inert under the same rule (reads return NOT_CONNECTED).
+    const referenceEnabled = config.setupMode
+        ? config.toolsets === null
+            ? !defaultExcludedToolsets.has('reference')
+            : config.toolsets.has('reference')
+        : isToolEnabled({ gate: 'read', toolset: 'reference' }, config);
+    if (referenceEnabled) {
+        registerReferenceResources(server, config, client);
+    }
     return server;
 }

package/dist/tools/account.d.ts

@@ -0,0 +1,3 @@
+/** Account toolset: read the authenticated account, revoke API tokens. */
+import type { ToolDef } from './types.js';
+export declare const accountTools: ToolDef[];