@labelgrid/mcp 0.1.0

package/dist/tools/reference.js

@@ -0,0 +1,36 @@
+/** Reference toolset: one tool serving all read-only lookup datasets. */
+import { z } from 'zod';
+/** Maps the public `type` selector to its reference endpoint. */
+const REFERENCE_PATHS = {
+    genres: '/genres',
+    genre_categories: '/genre-categories',
+    languages: '/languages',
+    contributor_roles: '/contributor-roles',
+    instruments: '/instruments',
+    distro_outlets: '/distro-outlets',
+    territories: '/territories',
+};
+const listReferenceData = {
+    name: 'list_reference_data',
+    toolset: 'reference',
+    gate: 'read',
+    title: 'List reference data',
+    description: 'Fetch a LabelGrid reference dataset used to resolve the IDs and codes that catalog and release tools expect. Pick ONE dataset with `type`: ' +
+        '`genres` and `genre_categories` (values for primary/secondary/tertiary genre IDs), `languages` (audio and metadata language codes), ' +
+        '`contributor_roles` (valid role names for track contributors), `instruments`, `distro_outlets` (the distribution outlets/stores available to your account), ' +
+        'or `territories` (country/territory codes). Call this before creating or updating a release or track when you need a valid ID or code.',
+    inputShape: {
+        type: z.enum([
+            'genres',
+            'genre_categories',
+            'languages',
+            'contributor_roles',
+            'instruments',
+            'distro_outlets',
+            'territories',
+        ]),
+    },
+    annotations: { readOnlyHint: true },
+    handler: (args, { client }) => client.get(REFERENCE_PATHS[args.type]),
+};
+export const referenceTools = [listReferenceData];

package/dist/tools/release-write.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Release write toolset (safe writes): the release/track draft lifecycle plus
+ * validate, quality-report refresh, landing-page config, a short URL, and
+ * review-issue notes.
+ *
+ * create_release and create_track send an auto-generated Idempotency-Key so a
+ * retried creation cannot duplicate the entity. Release/track create+update
+ * forward a permissive `fields` object straight to the API, which owns all
+ * validation; the descriptions name the required fields.
+ */
+import type { ToolDef } from './types.js';
+export declare const releaseWriteTools: ToolDef[];

package/dist/tools/release-write.js

@@ -0,0 +1,184 @@
+/**
+ * Release write toolset (safe writes): the release/track draft lifecycle plus
+ * validate, quality-report refresh, landing-page config, a short URL, and
+ * review-issue notes.
+ *
+ * create_release and create_track send an auto-generated Idempotency-Key so a
+ * retried creation cannot duplicate the entity. Release/track create+update
+ * forward a permissive `fields` object straight to the API, which owns all
+ * validation; the descriptions name the required fields.
+ */
+import { z } from 'zod';
+/** A permissive body of API fields, forwarded verbatim to the endpoint. */
+function fieldsBody(desc) {
+    return z.record(z.string(), z.unknown()).describe(desc);
+}
+/** Optional caller-supplied idempotency key, plumbed to the Idempotency-Key header. */
+const idempotencyKey = z
+    .string()
+    .min(8)
+    .max(128)
+    .optional()
+    .describe('Optional idempotency key. The server deduplicates by this key for 24h — pass the SAME key when retrying a call whose outcome you did not observe. Without it, each call is a new operation.');
+const createRelease = {
+    name: 'create_release',
+    toolset: 'releases',
+    gate: 'safe_write',
+    title: 'Create a release (draft)',
+    description: 'Create a new release in DRAFT state. Pass its metadata in `fields`. Required: content_type, label_id, artists, titles, cat (catalog number), artwork_ai_usage, primary_genre_id. Pass idempotency_key and reuse the SAME value if you retry a call whose outcome you did not observe — the server deduplicates by it for 24h; without a key each call is a new operation. Add tracks with create_track, then validate_release before distributing.',
+    inputShape: {
+        fields: fieldsBody('Release metadata. Required: content_type, label_id, artists, titles, cat, artwork_ai_usage, primary_genre_id. Many optional fields (dates, copyright lines, genres, per-outlet URLs) are supported — see the API docs.'),
+        idempotency_key: idempotencyKey,
+    },
+    annotations: {},
+    handler: (args, { client }) => client.post('/releases', args.fields, {
+        idempotency: true,
+        idempotencyKey: args.idempotency_key,
+    }),
+};
+const updateRelease = {
+    name: 'update_release',
+    toolset: 'releases',
+    gate: 'safe_write',
+    title: 'Update a release',
+    description: 'Update a release’s metadata. Supply only the fields you want to change in `fields`. Once a release has been submitted or distributed, some fields are locked: attempting to change a locked field returns a 403 with code RELEASE_LOCKED_FIELDS, surfaced verbatim so you can see exactly which fields cannot be changed.',
+    inputShape: {
+        release_id: z.number().int().positive(),
+        fields: fieldsBody('Release fields to change (same field set as create_release).'),
+    },
+    annotations: {},
+    handler: (args, { client }) => client.patch(`/releases/${args.release_id}`, args.fields),
+};
+const deleteRelease = {
+    name: 'delete_release',
+    toolset: 'releases',
+    gate: 'safe_write',
+    title: 'Delete a release',
+    description: 'Delete a release. The API only allows deleting a draft that has never been submitted; it refuses to delete a release that has been submitted or distributed.',
+    inputShape: { release_id: z.number().int().positive() },
+    annotations: { destructiveHint: true },
+    handler: (args, { client }) => client.delete(`/releases/${args.release_id}`),
+};
+const createTrack = {
+    name: 'create_track',
+    toolset: 'releases',
+    gate: 'safe_write',
+    title: 'Create a track',
+    description: 'Create a track on a release. Pass its metadata in `fields`. Required: release_id, disc, track_num, composition_type, artists, audio_ai_usage, composition_ai_usage, commercial_samples, audio_language, contributors, and recording_country (a required ISO 3166-1 alpha-2 country code, e.g. "US"). Pass idempotency_key and reuse the SAME value if you retry a call whose outcome you did not observe — the server deduplicates by it for 24h; without a key each call is a new operation.',
+    inputShape: {
+        fields: fieldsBody('Track metadata. Required: release_id, disc, track_num, composition_type, artists, audio_ai_usage, composition_ai_usage, commercial_samples, audio_language, contributors, recording_country (ISO 3166-1 alpha-2). Optional: titles, isrc, iswc, writers, publishers, splits, and more — see the API docs.'),
+        idempotency_key: idempotencyKey,
+    },
+    annotations: {},
+    handler: (args, { client }) => client.post('/tracks', args.fields, {
+        idempotency: true,
+        idempotencyKey: args.idempotency_key,
+    }),
+};
+const updateTrack = {
+    name: 'update_track',
+    toolset: 'releases',
+    gate: 'safe_write',
+    title: 'Update a track',
+    description: 'Update a track’s metadata. Supply only the fields you want to change in `fields`. As with releases, some fields lock once the parent release is submitted or distributed.',
+    inputShape: {
+        track_id: z.number().int().positive(),
+        fields: fieldsBody('Track fields to change (same field set as create_track).'),
+    },
+    annotations: {},
+    handler: (args, { client }) => client.patch(`/tracks/${args.track_id}`, args.fields),
+};
+const deleteTrack = {
+    name: 'delete_track',
+    toolset: 'releases',
+    gate: 'safe_write',
+    title: 'Delete a track',
+    description: 'Delete a track. Allowed while the parent release is an editable draft; the API refuses once the release is submitted or distributed.',
+    inputShape: { track_id: z.number().int().positive() },
+    annotations: { destructiveHint: true },
+    handler: (args, { client }) => client.delete(`/tracks/${args.track_id}`),
+};
+const validateRelease = {
+    name: 'validate_release',
+    toolset: 'releases',
+    gate: 'safe_write',
+    title: 'Validate a release',
+    description: 'Run validation on a release and return any problems that would block distribution, as both a human-readable `errors` list and a machine-readable `errors_structured` list. This is a near-read check: it changes nothing and is safe to repeat. Run it before distributing.',
+    inputShape: { release_id: z.number().int().positive() },
+    annotations: { idempotentHint: true },
+    handler: (args, { client }) => client.post(`/releases/${args.release_id}/validate`),
+};
+const refreshQualityReport = {
+    name: 'refresh_quality_report',
+    toolset: 'releases',
+    gate: 'safe_write',
+    title: 'Refresh the quality report',
+    description: 'Re-run the Preflight QC automated checks and refresh the release’s quality report. Read the results with get_quality_report. The server applies an hourly refresh budget, so frequent calls may be rate-limited. Preflight QC is an optional add-on.',
+    inputShape: { release_id: z.number().int().positive() },
+    annotations: { idempotentHint: true },
+    handler: (args, { client }) => client.post(`/releases/${args.release_id}/quality-report/refresh`),
+};
+const updateLandingConfig = {
+    name: 'update_landing_config',
+    toolset: 'releases',
+    gate: 'safe_write',
+    title: 'Update a release landing-page config',
+    description: 'Set the smart-link landing-page configuration for a release. `actions` uses the current (v2) action-list contract — each entry describes one call-to-action on the page. You can also set links_page_enabled, config_mode, page_style, custom_cta_text, custom_description, and pre_order_links. This replaces the landing configuration.',
+    inputShape: {
+        release_id: z.number().int().positive(),
+        links_page_enabled: z
+            .union([z.boolean(), z.string()])
+            .optional()
+            .describe('Whether the smart-link page is enabled.'),
+        config_mode: z.string().optional(),
+        page_style: z.string().optional(),
+        custom_cta_text: z.string().optional(),
+        custom_description: z.string().optional(),
+        actions: z
+            .array(z.record(z.string(), z.unknown()))
+            .optional()
+            .describe('The v2 action list — one object per call-to-action on the landing page.'),
+        pre_order_links: z.array(z.record(z.string(), z.unknown())).optional(),
+    },
+    annotations: {},
+    handler: (args, { client }) => {
+        const { release_id, ...body } = args;
+        return client.put(`/releases/${release_id}/landing-config`, body);
+    },
+};
+const createReleaseShortUrl = {
+    name: 'create_release_short_url',
+    toolset: 'releases',
+    gate: 'safe_write',
+    title: 'Create a release short URL',
+    description: 'Create (or return the existing) short URL for a release’s smart-link landing page. Safe to repeat.',
+    inputShape: { release_id: z.number().int().positive() },
+    annotations: { idempotentHint: true },
+    handler: (args, { client }) => client.post('/releases/short-url', { release_id: args.release_id }),
+};
+const addReviewIssueNote = {
+    name: 'add_review_issue_note',
+    toolset: 'releases',
+    gate: 'safe_write',
+    title: 'Add a note to a review issue',
+    description: 'Add a note to a release review issue — for example to explain a fix or add context for the reviewer. `review_issue_id` is the id of the issue (from list_review_issues).',
+    inputShape: {
+        review_issue_id: z.number().int().positive(),
+        note: z.string().describe('The note text to attach to the issue.'),
+    },
+    annotations: {},
+    handler: (args, { client }) => client.post(`/review-issues/${args.review_issue_id}/notes`, { note: args.note }),
+};
+export const releaseWriteTools = [
+    createRelease,
+    updateRelease,
+    deleteRelease,
+    createTrack,
+    updateTrack,
+    deleteTrack,
+    validateRelease,
+    refreshQualityReport,
+    updateLandingConfig,
+    createReleaseShortUrl,
+    addReviewIssueNote,
+];

package/dist/tools/review-read.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Review reads: release quality-check issues, the issue-definition catalog,
+ * the Preflight QC quality report, and Stream Radar early-warning flags. All
+ * read-only, in the `review` toolset.
+ */
+import type { ToolDef } from './types.js';
+export declare const reviewReadTools: ToolDef[];

package/dist/tools/review-read.js

@@ -0,0 +1,78 @@
+/**
+ * Review reads: release quality-check issues, the issue-definition catalog,
+ * the Preflight QC quality report, and Stream Radar early-warning flags. All
+ * read-only, in the `review` toolset.
+ */
+import { z } from 'zod';
+const listReviewIssues = {
+    name: 'list_review_issues',
+    toolset: 'review',
+    gate: 'read',
+    title: 'List release review issues',
+    description: 'List the review issues raised against a release during its automated quality checks. `release_id` is required. Each issue carries a code (see list_issue_definitions for what each code means), severity, and whether it blocks distribution. Use this to see what a customer must fix before a release can go out.',
+    inputShape: {
+        release_id: z.number().int().positive().describe('The release whose issues to list. Required.'),
+    },
+    annotations: { readOnlyHint: true },
+    handler: (args, { client }) => client.get('/review-issues', { release_id: args.release_id }),
+};
+const listIssueDefinitions = {
+    name: 'list_issue_definitions',
+    toolset: 'review',
+    gate: 'read',
+    title: 'List issue definitions',
+    description: 'Retrieve the catalog of review issue definitions: each code’s human-readable title, description, severity and whether it blocks distribution. Use it to interpret the codes returned by list_review_issues and the quality report. Issue codes are string slugs.',
+    inputShape: {},
+    annotations: { readOnlyHint: true },
+    handler: (_args, { client }) => client.get('/issue-definitions'),
+};
+const getQualityReport = {
+    name: 'get_quality_report',
+    toolset: 'review',
+    gate: 'read',
+    title: 'Get a release quality report',
+    description: 'Retrieve the Preflight QC quality report for a release: the customer-facing issues found by the automated checks so you can review them before confirming the release into distribution. Preflight QC is an optional add-on — if your account does not have it enabled the API returns a 403, which is surfaced verbatim.',
+    inputShape: { release_id: z.number().int().positive() },
+    annotations: { readOnlyHint: true },
+    handler: (args, { client }) => client.get(`/releases/${args.release_id}/quality-report`),
+};
+const listStreamRadarFlags = {
+    name: 'list_stream_radar_flags',
+    toolset: 'review',
+    gate: 'read',
+    title: 'List Stream Radar flags',
+    description: 'List Stream Radar flags for your releases, paginated — early-warning flags from streaming-integrity monitoring that surface possible artificial-streaming activity so you can act early. Filter by status, severity, dsp, isrc, release_id, and the last-detected date range (detected_from/detected_to). Stream Radar is an optional add-on; without it the API returns a 403, surfaced verbatim.',
+    inputShape: {
+        page: z.number().int().positive().optional(),
+        per_page: z.number().int().positive().optional(),
+        status: z.string().optional().describe('Filter by flag status.'),
+        severity: z.string().optional().describe('Filter by severity.'),
+        dsp: z.string().optional().describe('Filter by platform/DSP.'),
+        isrc: z.string().optional(),
+        release_id: z.number().int().positive().optional(),
+        detected_from: z.string().optional().describe('Earliest last-detected date, YYYY-MM-DD.'),
+        detected_to: z.string().optional().describe('Latest last-detected date, YYYY-MM-DD.'),
+    },
+    annotations: { readOnlyHint: true },
+    handler: (args, { client }) => {
+        const { page, per_page, ...filter } = args;
+        return client.get('/stream-radar/flags', { page, per_page, filter });
+    },
+};
+const getStreamRadarFlag = {
+    name: 'get_stream_radar_flag',
+    toolset: 'review',
+    gate: 'read',
+    title: 'Get a Stream Radar flag',
+    description: 'Retrieve one Stream Radar flag by id, with its full detail. Stream Radar is an optional add-on; without it the API returns a 403, surfaced verbatim.',
+    inputShape: { flag_id: z.number().int().positive() },
+    annotations: { readOnlyHint: true },
+    handler: (args, { client }) => client.get(`/stream-radar/flags/${args.flag_id}`),
+};
+export const reviewReadTools = [
+    listReviewIssues,
+    listIssueDefinitions,
+    getQualityReport,
+    listStreamRadarFlags,
+    getStreamRadarFlag,
+];

package/dist/tools/setup.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Setup toolset: the single tool exposed when no API token is configured.
+ *
+ * In setup mode the server registers ONLY this tool. It makes no API calls —
+ * it returns a structured, human-relayable guide that the AI client walks the
+ * user through to create a LabelGrid API token and add it to their client
+ * configuration. The `setup` toolset is deliberately NOT part of the tool
+ * catalog and is not user-selectable via LABELGRID_TOOLSETS.
+ */
+import type { ToolDef } from './types.js';
+export declare const setupTools: ToolDef[];

package/dist/tools/setup.js

@@ -0,0 +1,56 @@
+/**
+ * Setup toolset: the single tool exposed when no API token is configured.
+ *
+ * In setup mode the server registers ONLY this tool. It makes no API calls —
+ * it returns a structured, human-relayable guide that the AI client walks the
+ * user through to create a LabelGrid API token and add it to their client
+ * configuration. The `setup` toolset is deliberately NOT part of the tool
+ * catalog and is not user-selectable via LABELGRID_TOOLSETS.
+ */
+// Mirrors the README Claude Desktop / Cursor snippet exactly (placeholder token).
+const CLIENT_CONFIG_JSON = `{
+  "mcpServers": {
+    "labelgrid": {
+      "command": "npx",
+      "args": ["-y", "@labelgrid/mcp"],
+      "env": {
+        "LABELGRID_API_TOKEN": "your-token-here"
+      }
+    }
+  }
+}`;
+/** The structured guide returned to the client, relayed to the user in chat. */
+const SETUP_GUIDE = {
+    status: 'not_connected',
+    summary: 'This LabelGrid MCP server is running in setup mode because no API token is configured yet. Walk the user through the steps below so their AI client can connect to their LabelGrid account. Relay the steps in plain language and never ask the user to paste their token into the chat.',
+    steps: [
+        'Make sure the account has API access: it is part of LabelGrid API plans — see the API Overview and Quickstart (https://help.labelgrid.com/en/integrations/api-overview). If the API Tokens page is missing from the dashboard, the account does not have API access yet.',
+        'Log in to your LabelGrid dashboard and open Profile → API Tokens (https://app.labelgrid.com/user/profile/api-tokens).',
+        'Create a new token and copy it.',
+        'Add the token to your MCP client configuration as the LABELGRID_API_TOKEN environment variable (do NOT paste the token into this chat).',
+        'Restart your MCP client (or the server) — the full toolset loads automatically once the token is configured.',
+    ],
+    config_examples: {
+        claude_desktop: CLIENT_CONFIG_JSON,
+        claude_code: 'claude mcp add labelgrid -e LABELGRID_API_TOKEN=your-token-here -- npx -y @labelgrid/mcp',
+        cursor: CLIENT_CONFIG_JSON,
+    },
+    security_note: 'Never paste your API token into the chat — it belongs only in your client configuration file. Anyone with the token can access your account until you revoke it in the dashboard.',
+    optional_settings: [
+        'LABELGRID_ENABLE_WRITES — safe draft-stage writes; on by default, set false for read-only (see the README Safety section).',
+        'LABELGRID_ENABLE_FULL_WRITES (plus LABELGRID_FULL_WRITES_ACK) — arm consequential distribution actions; off by default (see the README Safety section).',
+        'LABELGRID_TOOLSETS — expose only a comma-separated subset of toolsets (see the README Safety section).',
+        'LABELGRID_READ_ONLY — force reads only, overriding the write flags (see the README Safety section).',
+    ],
+};
+const setup = {
+    name: 'setup',
+    toolset: 'setup',
+    gate: 'read',
+    title: 'Set up the LabelGrid connection',
+    description: 'This LabelGrid MCP server is not connected to an account yet because no API token is configured. Call this tool to get step-by-step instructions to walk the user through creating a LabelGrid API token and adding it to their MCP client configuration. Returns the setup steps, ready-to-copy client config examples (with a placeholder token), a security note, and the optional settings. Makes no API calls.',
+    inputShape: {},
+    annotations: { readOnlyHint: true },
+    handler: () => Promise.resolve({ data: SETUP_GUIDE }),
+};
+export const setupTools = [setup];

package/dist/tools/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The declarative tool contract every tool family produces, plus the
+ * {@link ApiResult}-to-MCP result mapper.
+ *
+ * A tool is a plain data declaration — name, gate, zod input shape, client-hint
+ * annotations and a one-call handler. The server module turns each declaration
+ * into a registered MCP tool. This keeps every tool a thin wrapper: one HTTP
+ * call, no client-side business logic.
+ */
+import type { z } from 'zod';
+import type { ApiResult, LabelGridClient } from '../api/http.js';
+import type { Config } from '../config.js';
+import type { Gate } from '../gating.js';
+export type ToolAnnotations = {
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+};
+export type ToolContext = {
+    client: LabelGridClient;
+    config: Config;
+};
+export type ToolDef = {
+    name: string;
+    toolset: string;
+    gate: Gate;
+    title: string;
+    description: string;
+    inputShape: z.ZodRawShape;
+    annotations: ToolAnnotations;
+    handler: (args: Record<string, unknown>, ctx: ToolContext) => Promise<ApiResult<unknown>>;
+};
+export type ToolResult = {
+    content: [{
+        type: 'text';
+        text: string;
+    }];
+    isError?: true;
+};
+/** Maps an {@link ApiResult} to an MCP tool result: pretty JSON, error flagged. */
+export declare function toToolResult(r: ApiResult<unknown>): ToolResult;

package/dist/tools/types.js

@@ -0,0 +1,52 @@
+/**
+ * The declarative tool contract every tool family produces, plus the
+ * {@link ApiResult}-to-MCP result mapper.
+ *
+ * A tool is a plain data declaration — name, gate, zod input shape, client-hint
+ * annotations and a one-call handler. The server module turns each declaration
+ * into a registered MCP tool. This keeps every tool a thin wrapper: one HTTP
+ * call, no client-side business logic.
+ */
+/** Hard ceiling on the serialized text of a single tool result, in characters. */
+const MAX_TOOL_TEXT = 400_000;
+/** Maps an {@link ApiResult} to an MCP tool result: pretty JSON, error flagged. */
+export function toToolResult(r) {
+    if ('data' in r) {
+        const text = JSON.stringify(r.data ?? null, null, 2);
+        if (text.length > MAX_TOOL_TEXT) {
+            // Reserve headroom for the wrapper keys so the whole envelope, not just the
+            // prefix, stays under the ceiling.
+            const wrapped = JSON.stringify({
+                truncated: true,
+                note: 'Response truncated — use pagination or filters to narrow the request.',
+                data_prefix: text.slice(0, MAX_TOOL_TEXT - 1_000),
+            }, null, 2);
+            return { content: [{ type: 'text', text: wrapped }] };
+        }
+        return { content: [{ type: 'text', text }] };
+    }
+    const errorText = JSON.stringify({ error: r.error }, null, 2);
+    if (errorText.length <= MAX_TOOL_TEXT) {
+        return { content: [{ type: 'text', text: errorText }], isError: true };
+    }
+    // The only unbounded fields are the verbatim API passthroughs; drop them so the
+    // envelope stays under the ceiling while the diagnostic core (code/message/
+    // status/suggestion) survives intact.
+    const bounded = { ...r.error };
+    if (bounded.errors !== undefined)
+        bounded.errors = '[truncated]';
+    if (bounded.errors_structured !== undefined)
+        bounded.errors_structured = '[truncated]';
+    const boundedText = JSON.stringify({ error: bounded }, null, 2);
+    if (boundedText.length <= MAX_TOOL_TEXT) {
+        return { content: [{ type: 'text', text: boundedText }], isError: true };
+    }
+    // Even after dropping the passthroughs the envelope is over the ceiling — a
+    // hostile error whose own code/message is huge. Hard-slice the serialized text
+    // at MAX_TOOL_TEXT and return it as-is: the result is no longer valid JSON, but
+    // an over-limit hostile error forfeits pretty structure to keep the hard bound.
+    return {
+        content: [{ type: 'text', text: boundedText.slice(0, MAX_TOOL_TEXT) }],
+        isError: true,
+    };
+}

package/dist/tools/webhooks.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Webhooks toolset: read your webhook subscriptions and delivery logs, and
+ * manage them (create/update/delete/test/rotate-secret). Reads are always on;
+ * the mutations are safe writes.
+ */
+import type { ToolDef } from './types.js';
+export declare const webhookTools: ToolDef[];

package/dist/tools/webhooks.js

@@ -0,0 +1,124 @@
+/**
+ * Webhooks toolset: read your webhook subscriptions and delivery logs, and
+ * manage them (create/update/delete/test/rotate-secret). Reads are always on;
+ * the mutations are safe writes.
+ */
+import { z } from 'zod';
+const webhookId = z.number().int().positive().describe('The webhook id.');
+const eventsShape = z
+    .record(z.string(), z.unknown())
+    .describe('The event subscription object selecting which event types this webhook receives. Call list_webhook_event_types for the available types and each payload shape.');
+const listWebhooks = {
+    name: 'list_webhooks',
+    toolset: 'webhooks',
+    gate: 'read',
+    title: 'List webhooks',
+    description: 'List the webhook subscriptions configured on your account, each with its URL, subscribed events and active state.',
+    inputShape: {},
+    annotations: { readOnlyHint: true },
+    handler: (_args, { client }) => client.get('/webhooks'),
+};
+const getWebhook = {
+    name: 'get_webhook',
+    toolset: 'webhooks',
+    gate: 'read',
+    title: 'Get a webhook',
+    description: 'Retrieve one webhook subscription by id.',
+    inputShape: { webhook_id: webhookId },
+    annotations: { readOnlyHint: true },
+    handler: (args, { client }) => client.get(`/webhooks/${args.webhook_id}`),
+};
+const getWebhookLogs = {
+    name: 'get_webhook_logs',
+    toolset: 'webhooks',
+    gate: 'read',
+    title: 'Get webhook delivery logs',
+    description: 'Retrieve the recent delivery log for a webhook — the attempts, response codes and outcomes — to debug why events did or did not reach your endpoint.',
+    inputShape: { webhook_id: webhookId },
+    annotations: { readOnlyHint: true },
+    handler: (args, { client }) => client.get(`/webhooks/${args.webhook_id}/logs`),
+};
+const listWebhookEventTypes = {
+    name: 'list_webhook_event_types',
+    toolset: 'webhooks',
+    gate: 'read',
+    title: 'List webhook event types',
+    description: 'List every available webhook event type, each with the schema of the payload it delivers. Use it to decide which events to subscribe a webhook to.',
+    inputShape: {},
+    annotations: { readOnlyHint: true },
+    handler: (_args, { client }) => client.get('/webhooks/event-types'),
+};
+const createWebhook = {
+    name: 'create_webhook',
+    toolset: 'webhooks',
+    gate: 'safe_write',
+    title: 'Create a webhook',
+    description: 'Create a webhook subscription. `name` and `url` (the HTTPS endpoint that will receive events) are required, along with `events` selecting which event types to deliver. The API returns a signing secret once on creation — store it to verify incoming payloads.',
+    inputShape: {
+        name: z.string().describe('A label for this webhook.'),
+        url: z.string().describe('The HTTPS endpoint that will receive event deliveries.'),
+        events: eventsShape,
+    },
+    annotations: {},
+    handler: (args, { client }) => client.post('/webhooks', { name: args.name, url: args.url, events: args.events }),
+};
+const updateWebhook = {
+    name: 'update_webhook',
+    toolset: 'webhooks',
+    gate: 'safe_write',
+    title: 'Update a webhook',
+    description: 'Update a webhook subscription. Supply only the fields you want to change: `name`, `url`, `events`, or `is_active` (set false to pause deliveries).',
+    inputShape: {
+        webhook_id: webhookId,
+        name: z.string().optional(),
+        url: z.string().optional(),
+        events: eventsShape.optional(),
+        is_active: z.boolean().optional().describe('Set false to pause deliveries.'),
+    },
+    annotations: {},
+    handler: (args, { client }) => {
+        const { webhook_id, ...body } = args;
+        return client.patch(`/webhooks/${webhook_id}`, body);
+    },
+};
+const deleteWebhook = {
+    name: 'delete_webhook',
+    toolset: 'webhooks',
+    gate: 'safe_write',
+    title: 'Delete a webhook',
+    description: 'Delete a webhook subscription permanently. It will stop receiving events.',
+    inputShape: { webhook_id: webhookId },
+    annotations: { destructiveHint: true },
+    handler: (args, { client }) => client.delete(`/webhooks/${args.webhook_id}`),
+};
+const testWebhook = {
+    name: 'test_webhook',
+    toolset: 'webhooks',
+    gate: 'safe_write',
+    title: 'Send a test webhook event',
+    description: 'Send a test event to a webhook’s endpoint so you can confirm it is reachable and your signature verification works. Safe to repeat.',
+    inputShape: { webhook_id: webhookId },
+    annotations: { idempotentHint: true },
+    handler: (args, { client }) => client.post(`/webhooks/${args.webhook_id}/test`),
+};
+const rotateWebhookSecret = {
+    name: 'rotate_webhook_secret',
+    toolset: 'webhooks',
+    gate: 'safe_write',
+    title: 'Rotate a webhook signing secret',
+    description: 'Generate a new signing secret for a webhook and return it. WARNING: the old secret stops working immediately — update your endpoint’s signature verification with the new secret right away or deliveries will fail verification.',
+    inputShape: { webhook_id: webhookId },
+    annotations: { destructiveHint: true },
+    handler: (args, { client }) => client.post(`/webhooks/${args.webhook_id}/regenerate-secret`),
+};
+export const webhookTools = [
+    listWebhooks,
+    getWebhook,
+    getWebhookLogs,
+    listWebhookEventTypes,
+    createWebhook,
+    updateWebhook,
+    deleteWebhook,
+    testWebhook,
+    rotateWebhookSecret,
+];

package/dist/version.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The package version, read from package.json at runtime so it stays the single
+ * source of truth. Resolved relative to this module: `dist/version.js` → the
+ * package-root `package.json` when built, `src/version.ts` → repo-root in tests.
+ */
+export declare const VERSION: string;

package/dist/version.js

@@ -0,0 +1,17 @@
+/**
+ * The package version, read from package.json at runtime so it stays the single
+ * source of truth. Resolved relative to this module: `dist/version.js` → the
+ * package-root `package.json` when built, `src/version.ts` → repo-root in tests.
+ */
+import { readFileSync } from 'node:fs';
+function readVersion() {
+    try {
+        const raw = readFileSync(new URL('../package.json', import.meta.url), 'utf8');
+        const pkg = JSON.parse(raw);
+        return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+export const VERSION = readVersion();