@orthacms/content-server 0.0.0-reserve.0

package/dist/lib/mcp/content-tools.provider.js

@@ -0,0 +1,441 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ContentToolProvider = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const identity_server_1 = require("@orthacms/identity-server");
+const tools_server_1 = require("@orthacms/tools-server");
+const content_tokens_1 = require("../content.tokens");
+const workspace_grants_query_1 = require("../content-types/queries/workspace-grants.query");
+const resolve_granted_type_1 = require("../public-api/http/controllers/resolve-granted-type");
+const public_entries_query_1 = require("../public-api/infrastructure/public-entries.query");
+const public_entry_writes_service_1 = require("../public-api/infrastructure/public-entry-writes.service");
+const public_list_entries_query_dto_1 = require("../public-api/http/dto/public-list-entries-query.dto");
+const public_save_entry_dto_1 = require("../public-api/http/dto/public-save-entry.dto");
+const public_bulk_dto_1 = require("../public-api/http/dto/public-bulk.dto");
+const relation_link_service_1 = require("../entries/infrastructure/persistence/relation-link.service");
+const field_schema_1 = require("../docs/field-schema");
+const tool_input_1 = require("./tool-input");
+const tool_schemas_1 = require("./tool-schemas");
+/** URI prefix for the per-content-type schema resources. */
+const TYPE_RESOURCE_PREFIX = 'ortha://content-type/';
+/**
+ * The content plugin's contribution to the shared agent tool registry — the
+ * same CRUD the public HTTP API serves, reachable by an MCP client or the
+ * copilot's tool loop.
+ *
+ * **Every handler delegates to the objects the HTTP controllers call**:
+ * `resolveGrantedType` for the grant gate, `PublicEntriesQuery` for reads,
+ * `PublicEntryWritesService` for writes. That is the whole design. The rules
+ * that make the public API safe — published-only by default, soft-deleted rows
+ * invisible, an ungranted type indistinguishable from an unknown one, relations
+ * that may not cross locales, validation at publish time, revision numbering
+ * under an advisory lock, the outbox — are not restated here and therefore
+ * cannot drift from the HTTP surface. This class contributes the tool
+ * descriptions, argument validation, and the mapping from arguments to those
+ * calls, and nothing else.
+ *
+ * **Authorization is declared, not implemented.** Each tool names the
+ * permissions it needs in `requires`, and `ToolRegistry.call` enforces them
+ * before dispatch — the analogue of `@RequirePermissions(...)` on a route. A
+ * `read`-scoped token cannot reach a write tool, and no handler below contains
+ * a line of code saying so. The one authorization decision a handler *does*
+ * make is the draft-visibility widening, because it is a rule about an argument
+ * rather than about the operation.
+ *
+ * Registration is `@Optional()`: MCP is a plugin, so a deployment that omits it
+ * must still boot. The tools simply go unregistered.
+ */
+let ContentToolProvider = class ContentToolProvider {
+    registry;
+    grants;
+    entries;
+    writes;
+    toolRegistry;
+    constructor(registry, grants, entries, writes, toolRegistry) {
+        this.registry = registry;
+        this.grants = grants;
+        this.entries = entries;
+        this.writes = writes;
+        this.toolRegistry = toolRegistry;
+    }
+    /**
+     * Register with the tool registry once the DI graph is built. A call rather
+     * than a DI binding because Nest has no multi-provider token — see
+     * `ToolProvider`.
+     */
+    onModuleInit() {
+        this.toolRegistry?.register(this);
+    }
+    /**
+     * The sixteen content tools. @see ToolProvider.tools
+     *
+     * Every one is stamped `surfaces: ['mcp']` below rather than tool by tool:
+     * they are uniformly the **public-API** set — published-only reads through
+     * `PublicEntriesQuery`, writes through `PublicEntryWritesService` attributed
+     * to a token. The copilot's content tools are the admin-scoped counterpart
+     * (a viewer must see drafts; a write records the accepting human), so the
+     * two sets share the registry and not each other's callers.
+     */
+    tools() {
+        return this.mcpTools().map((tool) => ({
+            ...tool,
+            surfaces: ['mcp']
+        }));
+    }
+    /** The tool definitions themselves, before the surface stamp. */
+    mcpTools() {
+        return [
+            // ---- discovery ------------------------------------------------
+            // A model cannot type a `values` bag it has not seen, so discovery
+            // is the entry point of every authoring conversation, not a
+            // nicety. These two are why the write tools can take an open
+            // object and still be usable.
+            {
+                name: 'content_types_list',
+                title: 'List content types',
+                description: 'List the content types available in this workspace: machine name, label, kind (collection or single), and whether each is publishable, localized, or soft-deleting. Start here — the names it returns are exactly the ones the other tools accept.',
+                inputSchema: tool_schemas_1.LIST_TYPES_SCHEMA,
+                requires: [identity_server_1.PERMISSIONS.CONTENT_READ],
+                readOnly: true,
+                handler: async (_input, context) => ({
+                    items: await this.grantedSummaries(context)
+                })
+            },
+            {
+                name: 'content_type_get',
+                title: 'Get a content type’s schema',
+                description: 'The full field schema of one content type — every field with its type, validation rules and options, as JSON Schema. Call this before `content_create` or `content_update` so the `values` you send match the type.',
+                inputSchema: tool_schemas_1.GET_TYPE_SCHEMA,
+                requires: [identity_server_1.PERMISSIONS.CONTENT_READ],
+                readOnly: true,
+                handler: async (input, context) => {
+                    const typeName = (0, tool_input_1.requireTypeName)(input);
+                    await this.resolve(typeName, context);
+                    return this.describeType(typeName);
+                }
+            },
+            // ---- reads ----------------------------------------------------
+            {
+                name: 'content_list',
+                title: 'List entries',
+                description: 'One page of a content type’s entries — published only unless you pass `status`. Supports free-text `search`, a structured `filter`, `sort`, and paging. Serves single/page types too: take `items[0]`. Prefer naming `fields` to keep the result small.',
+                inputSchema: tool_schemas_1.LIST_ENTRIES_SCHEMA,
+                requires: [identity_server_1.PERMISSIONS.CONTENT_READ],
+                readOnly: true,
+                handler: async (input, context) => {
+                    (0, tool_input_1.assertDraftVisibility)(input, context);
+                    const { type, granted } = await this.resolve((0, tool_input_1.requireTypeName)(input), context);
+                    const query = await (0, tool_input_1.validateToolInput)(public_list_entries_query_dto_1.PublicListEntriesQueryDto, input);
+                    return this.entries.list(type, query, context.workspaceId, granted);
+                }
+            },
+            {
+                name: 'content_get',
+                title: 'Get one entry',
+                description: 'Read a single entry by `id`, or by `localeGroupId` plus `locale`. Optionally expands relations, media, and sibling translations. A draft, a deleted entry, one in another workspace, and an unknown id all read the same: not found.',
+                inputSchema: tool_schemas_1.GET_ENTRY_SCHEMA,
+                requires: [identity_server_1.PERMISSIONS.CONTENT_READ],
+                readOnly: true,
+                handler: async (input, context) => {
+                    (0, tool_input_1.assertDraftVisibility)(input, context);
+                    const { type, granted } = await this.resolve((0, tool_input_1.requireTypeName)(input), context);
+                    const query = await (0, tool_input_1.validateToolInput)(public_list_entries_query_dto_1.PublicEntryQueryDto, input);
+                    return this.entries.getOne(type, (0, tool_input_1.requireLocator)(input), context.workspaceId, query, granted);
+                }
+            },
+            {
+                name: 'content_relations',
+                title: 'Page one relation field',
+                description: 'One ordered page of a single relation field’s links — the way past the cap that `content_get`’s relation preview applies. Only published targets are shown or counted.',
+                inputSchema: tool_schemas_1.RELATIONS_SCHEMA,
+                requires: [identity_server_1.PERMISSIONS.CONTENT_READ],
+                readOnly: true,
+                handler: async (input, context) => {
+                    (0, tool_input_1.assertDraftVisibility)(input, context);
+                    const { type, granted } = await this.resolve((0, tool_input_1.requireTypeName)(input), context);
+                    const query = await (0, tool_input_1.validateToolInput)(public_list_entries_query_dto_1.PublicListEntriesQueryDto, input);
+                    return this.entries.relationField(type, (0, tool_input_1.requireLocator)(input), requireField(input), query.page ?? 1, query.pageSize ?? relation_link_service_1.RELATION_PAGE_SIZE, context.workspaceId, granted, query.locale, query.status);
+                }
+            },
+            {
+                name: 'content_media',
+                title: 'Get an entry’s media',
+                description: 'Every media field of one entry, keyed by field name and resolved to asset metadata (name, kind, MIME type, alt) and URLs.',
+                inputSchema: tool_schemas_1.MEDIA_SCHEMA,
+                requires: [identity_server_1.PERMISSIONS.CONTENT_READ, identity_server_1.PERMISSIONS.MEDIA_READ],
+                readOnly: true,
+                handler: async (input, context) => {
+                    (0, tool_input_1.assertDraftVisibility)(input, context);
+                    const { type } = await this.resolve((0, tool_input_1.requireTypeName)(input), context);
+                    const query = await (0, tool_input_1.validateToolInput)(public_list_entries_query_dto_1.PublicEntryQueryDto, input);
+                    return {
+                        media: await this.entries.mediaOf(type, (0, tool_input_1.requireLocator)(input), context.workspaceId, query.locale, query.mediaLimit, query.status)
+                    };
+                }
+            },
+            {
+                name: 'content_translations',
+                title: 'Get an entry’s translations',
+                description: 'The entry’s other locale rows — the rest of its translation group, ordered by locale slug. The entry itself is not repeated. An error on a type that is not localized.',
+                inputSchema: tool_schemas_1.TRANSLATIONS_SCHEMA,
+                requires: [identity_server_1.PERMISSIONS.CONTENT_READ],
+                readOnly: true,
+                handler: async (input, context) => {
+                    (0, tool_input_1.assertDraftVisibility)(input, context);
+                    const { type } = await this.resolve((0, tool_input_1.requireTypeName)(input), context);
+                    const query = await (0, tool_input_1.validateToolInput)(public_list_entries_query_dto_1.PublicEntryQueryDto, input);
+                    return {
+                        translations: await this.entries.translationsOf(type, (0, tool_input_1.requireLocator)(input), context.workspaceId, query)
+                    };
+                }
+            },
+            // ---- writes ---------------------------------------------------
+            {
+                name: 'content_create',
+                title: 'Create an entry',
+                description: 'Create an entry. On a publishable type it lands as a **draft** — publishing is a separate call (`content_publish`), so every create has a reviewable state. Required fields are required *to publish*, not to create, so a draft may be incomplete. Read it back with `status: "any"`; the published-only default will not find it.',
+                inputSchema: tool_schemas_1.CREATE_SCHEMA,
+                requires: [identity_server_1.PERMISSIONS.CONTENT_CREATE],
+                readOnly: false,
+                handler: async (input, context) => {
+                    const { type, granted } = await this.resolve((0, tool_input_1.requireTypeName)(input), context);
+                    const body = await (0, tool_input_1.validateToolInput)(public_save_entry_dto_1.PublicSaveEntryDto, input);
+                    return this.writes.create(type, body, context.workspaceId, granted);
+                }
+            },
+            {
+                name: 'content_update',
+                title: 'Update an entry',
+                description: 'A **partial** update — the `values` you send are merged over the stored ones, so omitting a field leaves it alone and an explicit `null` clears it. You never need to send the whole record. On a publishable type this returns a published entry to draft while its published version stays live; call `content_publish` to ship the change.',
+                inputSchema: tool_schemas_1.UPDATE_SCHEMA,
+                requires: [identity_server_1.PERMISSIONS.CONTENT_UPDATE],
+                readOnly: false,
+                handler: async (input, context) => {
+                    const { type, granted } = await this.resolve((0, tool_input_1.requireTypeName)(input), context);
+                    // The save body carries only `values` + `relations`: the
+                    // addressing locale is a separate argument, exactly as the
+                    // HTTP route keeps it in the query string. Folding them
+                    // together is how a group-addressed update to the German
+                    // row silently retargets the English one.
+                    const body = await (0, tool_input_1.validateToolInput)(public_save_entry_dto_1.PublicSaveEntryDto, {
+                        values: input['values'],
+                        ...(input['relations'] === undefined
+                            ? {}
+                            : { relations: input['relations'] })
+                    });
+                    return this.writes.update(type, (0, tool_input_1.requireLocator)(input), body, context.workspaceId, granted, localeArg(input));
+                }
+            },
+            {
+                name: 'content_publish',
+                title: 'Publish an entry',
+                description: 'Re-validate the stored entry and take it live. A draft that does not pass the type’s validation rules fails here with the offending fields named — that is the moment `required` bites.',
+                inputSchema: tool_schemas_1.ENTRY_ACTION_SCHEMA,
+                requires: [identity_server_1.PERMISSIONS.CONTENT_PUBLISH],
+                readOnly: false,
+                handler: async (input, context) => {
+                    const { type, granted } = await this.resolve((0, tool_input_1.requireTypeName)(input), context);
+                    return this.writes.publish(type, (0, tool_input_1.requireLocator)(input), context.workspaceId, granted, localeArg(input));
+                }
+            },
+            {
+                name: 'content_unpublish',
+                title: 'Unpublish an entry',
+                description: 'Revert an entry to a draft. It leaves the published reads immediately; a write-scoped caller can still see it with `status: "draft"`.',
+                inputSchema: tool_schemas_1.ENTRY_ACTION_SCHEMA,
+                requires: [identity_server_1.PERMISSIONS.CONTENT_PUBLISH],
+                readOnly: false,
+                handler: async (input, context) => {
+                    const { type, granted } = await this.resolve((0, tool_input_1.requireTypeName)(input), context);
+                    return this.writes.unpublish(type, (0, tool_input_1.requireLocator)(input), context.workspaceId, granted, localeArg(input));
+                }
+            },
+            {
+                name: 'content_delete',
+                title: 'Delete an entry',
+                description: 'Remove an entry — recoverable from the admin’s trash on a soft-deleting type, permanent otherwise. Deletes exactly one row: on a localized type the other translations stay live.',
+                inputSchema: tool_schemas_1.ENTRY_ACTION_SCHEMA,
+                requires: [identity_server_1.PERMISSIONS.CONTENT_DELETE],
+                readOnly: false,
+                destructive: true,
+                handler: async (input, context) => {
+                    const { type } = await this.resolve((0, tool_input_1.requireTypeName)(input), context);
+                    await this.writes.remove(type, (0, tool_input_1.requireLocator)(input), context.workspaceId, localeArg(input));
+                    return { deleted: true };
+                }
+            },
+            // ---- batches ---------------------------------------------------
+            //
+            // The single-entry writes above stay exactly as they are; these are
+            // for the case a model has a *list*. Without them, "publish these
+            // twelve drafts" is twelve tool calls — twelve round trips through
+            // the model, each spending context on a result nobody reads, and on
+            // the copilot's side twelve steps against a bounded run. Each one
+            // runs the same use-case its single-entry sibling does.
+            {
+                name: 'content_bulk_save',
+                title: 'Save many entries',
+                description: 'Create and/or update many entries of one type in a single call. An item with an `id` updates that entry (a **partial** update, exactly like `content_update`); an item without one creates a draft. Always succeeds as a call: each item gets its own verdict in the same position, and a failure carries the reason that item would have failed with on its own — so read `failed` and the per-item `error`, and do not report the batch as saved without checking them.',
+                inputSchema: tool_schemas_1.BULK_SAVE_SCHEMA,
+                requires: [
+                    identity_server_1.PERMISSIONS.CONTENT_CREATE,
+                    identity_server_1.PERMISSIONS.CONTENT_UPDATE
+                ],
+                readOnly: false,
+                handler: async (input, context) => {
+                    const { type, granted } = await this.resolve((0, tool_input_1.requireTypeName)(input), context);
+                    const body = await (0, tool_input_1.validateToolInput)(public_bulk_dto_1.PublicBulkSaveDto, {
+                        items: input['items']
+                    });
+                    return this.writes.bulkSave(type, body.items, context.workspaceId, granted);
+                }
+            },
+            {
+                name: 'content_bulk_publish',
+                title: 'Publish many entries',
+                description: 'Re-validate and publish many drafts at once. Publishes the ones that pass and reports the rest in `skipped` with why — `already-published`, `blocked` (it fails the type’s validation rules), or `not-found`. A partly-skipped batch is the normal outcome, so say what actually went live rather than assuming all of it did.',
+                inputSchema: tool_schemas_1.BULK_IDS_SCHEMA,
+                requires: [identity_server_1.PERMISSIONS.CONTENT_PUBLISH],
+                readOnly: false,
+                handler: async (input, context) => {
+                    const { type } = await this.resolve((0, tool_input_1.requireTypeName)(input), context);
+                    const body = await (0, tool_input_1.validateToolInput)(public_bulk_dto_1.PublicBulkIdsDto, {
+                        ids: input['ids']
+                    });
+                    return this.writes.bulkPublish(type, body.ids, context.workspaceId);
+                }
+            },
+            {
+                name: 'content_bulk_unpublish',
+                title: 'Unpublish many entries',
+                description: 'Revert many entries to drafts. `count` is how many actually changed — an id that was not a live published entry here changes nothing and is not counted.',
+                inputSchema: tool_schemas_1.BULK_IDS_SCHEMA,
+                requires: [identity_server_1.PERMISSIONS.CONTENT_PUBLISH],
+                readOnly: false,
+                handler: async (input, context) => {
+                    const { type } = await this.resolve((0, tool_input_1.requireTypeName)(input), context);
+                    const body = await (0, tool_input_1.validateToolInput)(public_bulk_dto_1.PublicBulkIdsDto, {
+                        ids: input['ids']
+                    });
+                    return this.writes.bulkUnpublish(type, body.ids, context.workspaceId);
+                }
+            },
+            {
+                name: 'content_bulk_delete',
+                title: 'Delete many entries',
+                description: 'Remove many entries — recoverable from the admin’s trash on a soft-deleting type, permanent otherwise. Deletes exactly the listed rows: on a localized type the other translations stay live. `count` is how many were removed.',
+                inputSchema: tool_schemas_1.BULK_IDS_SCHEMA,
+                requires: [identity_server_1.PERMISSIONS.CONTENT_DELETE],
+                readOnly: false,
+                destructive: true,
+                handler: async (input, context) => {
+                    const { type } = await this.resolve((0, tool_input_1.requireTypeName)(input), context);
+                    const body = await (0, tool_input_1.validateToolInput)(public_bulk_dto_1.PublicBulkIdsDto, {
+                        ids: input['ids']
+                    });
+                    return this.writes.bulkRemove(type, body.ids, context.workspaceId);
+                }
+            }
+        ];
+    }
+    /**
+     * Each readable content type as a resource, so a client that supports them
+     * can pull a schema into context without spending a tool call. Pruned to
+     * the workspace's grants, exactly like `content_types_list`.
+     */
+    async resources(context) {
+        const summaries = await this.grantedSummaries(context);
+        return summaries.map((summary) => ({
+            uri: `${TYPE_RESOURCE_PREFIX}${summary.name}`,
+            name: `${summary.label} schema`,
+            description: `Field schema of the \`${summary.name}\` content type.`,
+            mimeType: 'application/json'
+        }));
+    }
+    /** @see ToolProvider.readResource */
+    async readResource(uri, context) {
+        if (!uri.startsWith(TYPE_RESOURCE_PREFIX)) {
+            return undefined;
+        }
+        const typeName = uri.slice(TYPE_RESOURCE_PREFIX.length);
+        // Through the same grant gate as the tools, so an ungranted type is a
+        // 404 here exactly as it is there — a resource read must not be a way
+        // around the gate that guards the equivalent tool call.
+        await this.resolve(typeName, context);
+        return {
+            uri,
+            mimeType: 'application/json',
+            text: JSON.stringify(this.describeType(typeName), null, 2)
+        };
+    }
+    /** The workspace's granted type summaries. */
+    async grantedSummaries(context) {
+        const granted = await this.grants.grantedSlugs(context.workspaceId);
+        return this.registry
+            .summaries()
+            .filter((summary) => granted.has(summary.name));
+    }
+    /** Resolve a type through the shared registry + grant gate. */
+    resolve(typeName, context) {
+        return (0, resolve_granted_type_1.resolveGrantedType)(this.registry, this.grants, typeName, context.workspaceId);
+    }
+    /**
+     * One type's serialized schema, plus a JSON Schema for its `values` bag.
+     *
+     * Both, because they answer different questions: the serialized fields
+     * carry the CMS's own vocabulary (which field is a relation, what a select's
+     * options are), while the JSON Schema is what a model needs to construct a
+     * valid `values` object. `fieldSchema` is the same generator the OpenAPI
+     * document uses, so the two descriptions of a type cannot disagree.
+     */
+    describeType(typeName) {
+        const type = this.registry.serialize(typeName);
+        const properties = {};
+        for (const field of type.fields.filter(field_schema_1.isValueField)) {
+            properties[field.name] = (0, field_schema_1.fieldSchema)(field);
+        }
+        return {
+            ...type,
+            valuesSchema: {
+                type: 'object',
+                properties,
+                // Required fields are listed only on a type that is always
+                // live: on a publishable one they are required *to publish*,
+                // and declaring them required here would tell a model it
+                // cannot save the incomplete draft it is allowed to save.
+                ...(type.publishable
+                    ? {}
+                    : {
+                        required: type.fields
+                            .filter((field) => (0, field_schema_1.isValueField)(field) && field.required)
+                            .map((field) => field.name)
+                    }),
+                additionalProperties: false
+            }
+        };
+    }
+};
+exports.ContentToolProvider = ContentToolProvider;
+exports.ContentToolProvider = ContentToolProvider = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__param(0, (0, content_tokens_1.InjectContentRegistry)()),
+    tslib_1.__param(4, (0, common_1.Optional)()),
+    tslib_1.__metadata("design:paramtypes", [Function, workspace_grants_query_1.WorkspaceGrantsQuery,
+        public_entries_query_1.PublicEntriesQuery,
+        public_entry_writes_service_1.PublicEntryWritesService,
+        tools_server_1.ToolRegistry])
+], ContentToolProvider);
+/** The `field` argument, required by `content_relations`. */
+function requireField(input) {
+    const field = input['field'];
+    if (typeof field !== 'string' || field.length === 0) {
+        throw new common_1.BadRequestException('`field` is required — the relation field to page, e.g. `tags`.');
+    }
+    return field;
+}
+/** The addressing `locale` argument, when present. */
+function localeArg(input) {
+    const locale = input['locale'];
+    return typeof locale === 'string' ? locale : undefined;
+}

package/dist/lib/mcp/tool-input.d.ts

@@ -0,0 +1,43 @@
+import { type ClassConstructor } from 'class-transformer';
+import type { ToolContext } from '@orthacms/tools-server';
+import type { EntryLocator } from '../public-api/infrastructure/public-entries.query';
+/**
+ * Validate a tool's arguments through the **same DTO class the HTTP route
+ * uses**.
+ *
+ * The alternative — hand-checking each tool's arguments — would fork the
+ * accepted contract the first time a bound moved: `pageSize` would cap at 100
+ * on `GET /v1/content/:typeName` and at whatever this file said on
+ * `content_list`. Running the real DTO means a rule is written once, in the
+ * place that documents it, and both callers get it.
+ *
+ * The options mirror the host's global `ValidationPipe` exactly
+ * (`whitelist` + `forbidNonWhitelisted` + `transform`), so an unknown argument
+ * is an error rather than being silently ignored. That matters more for a model
+ * than for a developer: a typo'd argument that is quietly dropped produces a
+ * plausible-looking wrong answer, which is the failure mode hardest to notice.
+ */
+export declare function validateToolInput<T extends object>(dto: ClassConstructor<T>, raw: Record<string, unknown>): Promise<T>;
+/** The required `typeName` argument. */
+export declare function requireTypeName(raw: Record<string, unknown>): string;
+/**
+ * The entry locator: **exactly one** of `id` or `localeGroupId`.
+ *
+ * Both spellings exist for the same reason they do on the HTTP routes — a
+ * localized front-end holds one stable group id per story rather than one id
+ * per language — and requiring exactly one keeps a call from silently
+ * preferring whichever the implementation happened to check first.
+ */
+export declare function requireLocator(raw: Record<string, unknown>): EntryLocator;
+/**
+ * Enforce the draft-visibility rule for a tool call — the job
+ * `DraftVisibilityGuard` does for the HTTP routes.
+ *
+ * Restated here rather than reused because a guard gates a *route*, and every
+ * tool arrives through one route. The rule is identical and deliberately so:
+ * a read defaults to published-only, and only a caller that could have
+ * published the row may widen it. `content:update` is the probe rather than
+ * `content:read`, because read is exactly what both scopes hold.
+ */
+export declare function assertDraftVisibility(raw: Record<string, unknown>, context: ToolContext): void;
+//# sourceMappingURL=tool-input.d.ts.map

package/dist/lib/mcp/tool-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-input.d.ts","sourceRoot":"","sources":["../../../src/lib/mcp/tool-input.ts"],"names":[],"mappings":"AACA,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mDAAmD,CAAC;AAUtF;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EACpD,GAAG,EAAE,gBAAgB,CAAC,CAAC,CAAC,EACxB,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC,CAmBZ;AAaD,wCAAwC;AACxC,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAQpE;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,YAAY,CAqBzE;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACjC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,OAAO,EAAE,WAAW,GACrB,IAAI,CAiBN"}

package/dist/lib/mcp/tool-input.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateToolInput = validateToolInput;
+exports.requireTypeName = requireTypeName;
+exports.requireLocator = requireLocator;
+exports.assertDraftVisibility = assertDraftVisibility;
+const common_1 = require("@nestjs/common");
+const class_transformer_1 = require("class-transformer");
+const class_validator_1 = require("class-validator");
+const identity_server_1 = require("@orthacms/identity-server");
+const public_list_entries_query_dto_1 = require("../public-api/http/dto/public-list-entries-query.dto");
+/**
+ * Keys that address *which* record a tool acts on rather than *how*. Stripped
+ * before DTO validation, because they are the tool's own parameters and the
+ * query DTOs — which describe an HTTP query string — know nothing about them.
+ */
+const LOCATOR_KEYS = ['typeName', 'id', 'localeGroupId', 'field'];
+/**
+ * Validate a tool's arguments through the **same DTO class the HTTP route
+ * uses**.
+ *
+ * The alternative — hand-checking each tool's arguments — would fork the
+ * accepted contract the first time a bound moved: `pageSize` would cap at 100
+ * on `GET /v1/content/:typeName` and at whatever this file said on
+ * `content_list`. Running the real DTO means a rule is written once, in the
+ * place that documents it, and both callers get it.
+ *
+ * The options mirror the host's global `ValidationPipe` exactly
+ * (`whitelist` + `forbidNonWhitelisted` + `transform`), so an unknown argument
+ * is an error rather than being silently ignored. That matters more for a model
+ * than for a developer: a typo'd argument that is quietly dropped produces a
+ * plausible-looking wrong answer, which is the failure mode hardest to notice.
+ */
+async function validateToolInput(dto, raw) {
+    const instance = (0, class_transformer_1.plainToInstance)(dto, withoutLocatorKeys(raw), {
+        enableImplicitConversion: false
+    });
+    const errors = await (0, class_validator_1.validate)(instance, {
+        whitelist: true,
+        forbidNonWhitelisted: true,
+        forbidUnknownValues: true
+    });
+    if (errors.length > 0) {
+        throw new common_1.BadRequestException({
+            message: 'Invalid arguments.',
+            issues: errors.map((error) => ({
+                field: error.property,
+                problems: Object.values(error.constraints ?? {})
+            }))
+        });
+    }
+    return instance;
+}
+/** The argument bag minus the addressing keys. */
+function withoutLocatorKeys(raw) {
+    const rest = { ...raw };
+    for (const key of LOCATOR_KEYS) {
+        delete rest[key];
+    }
+    return rest;
+}
+/** The required `typeName` argument. */
+function requireTypeName(raw) {
+    const typeName = raw['typeName'];
+    if (typeof typeName !== 'string' || typeName.length === 0) {
+        throw new common_1.BadRequestException('`typeName` is required. Call `content_types_list` to see the readable types.');
+    }
+    return typeName;
+}
+/**
+ * The entry locator: **exactly one** of `id` or `localeGroupId`.
+ *
+ * Both spellings exist for the same reason they do on the HTTP routes — a
+ * localized front-end holds one stable group id per story rather than one id
+ * per language — and requiring exactly one keeps a call from silently
+ * preferring whichever the implementation happened to check first.
+ */
+function requireLocator(raw) {
+    const id = raw['id'];
+    const localeGroupId = raw['localeGroupId'];
+    const hasId = typeof id === 'string' && id.length > 0;
+    const hasGroup = typeof localeGroupId === 'string' && localeGroupId.length > 0;
+    if (hasId && hasGroup) {
+        throw new common_1.BadRequestException('Pass either `id` or `localeGroupId`, not both — they are two ways of naming the same row.');
+    }
+    if (hasId) {
+        return { id: id };
+    }
+    if (hasGroup) {
+        return { localeGroupId: localeGroupId };
+    }
+    throw new common_1.BadRequestException('Pass either `id` (one entry) or `localeGroupId` (the entry’s translation group, with `locale`).');
+}
+/**
+ * Enforce the draft-visibility rule for a tool call — the job
+ * `DraftVisibilityGuard` does for the HTTP routes.
+ *
+ * Restated here rather than reused because a guard gates a *route*, and every
+ * tool arrives through one route. The rule is identical and deliberately so:
+ * a read defaults to published-only, and only a caller that could have
+ * published the row may widen it. `content:update` is the probe rather than
+ * `content:read`, because read is exactly what both scopes hold.
+ */
+function assertDraftVisibility(raw, context) {
+    const requested = raw['status'];
+    if (typeof requested !== 'string' ||
+        requested === 'published' ||
+        !public_list_entries_query_dto_1.ENTRY_VISIBILITY.includes(requested)) {
+        // Absent, the default, or unrecognised. The last is left alone on
+        // purpose: the DTO's `@IsIn` turns it into a clear 400, and refusing
+        // it here first would report the wrong problem.
+        return;
+    }
+    if (!context.can(identity_server_1.PERMISSIONS.CONTENT_UPDATE)) {
+        throw new common_1.ForbiddenException(`status=${requested} requires a token with write scope; this one may only read published content.`);
+    }
+}

package/dist/lib/mcp/tool-schemas.d.ts

@@ -0,0 +1,34 @@
+import type { JsonSchema } from '@orthacms/tools-server';
+/** `content_types_list` — no arguments. */
+export declare const LIST_TYPES_SCHEMA: JsonSchema;
+/** `content_type_get` */
+export declare const GET_TYPE_SCHEMA: JsonSchema;
+/** `content_list` */
+export declare const LIST_ENTRIES_SCHEMA: JsonSchema;
+/** `content_get` */
+export declare const GET_ENTRY_SCHEMA: JsonSchema;
+/** `content_relations` */
+export declare const RELATIONS_SCHEMA: JsonSchema;
+/** `content_media` */
+export declare const MEDIA_SCHEMA: JsonSchema;
+/** `content_translations` */
+export declare const TRANSLATIONS_SCHEMA: JsonSchema;
+/** `content_create` */
+export declare const CREATE_SCHEMA: JsonSchema;
+/** `content_update` */
+export declare const UPDATE_SCHEMA: JsonSchema;
+/** `content_publish` / `content_unpublish` / `content_delete` */
+export declare const ENTRY_ACTION_SCHEMA: JsonSchema;
+/**
+ * `content_bulk_save` — the batch form of create + update.
+ *
+ * One `items` array rather than a `creates` and an `updates` list: a model
+ * working from a list of records knows which ones it read an id for and which
+ * it did not, and asking it to partition them first is a step it can get wrong
+ * for no benefit. The addressing inside an item is the same addressing the
+ * single-entry tools take as top-level arguments.
+ */
+export declare const BULK_SAVE_SCHEMA: JsonSchema;
+/** `content_bulk_publish` / `content_bulk_unpublish` / `content_bulk_delete`. */
+export declare const BULK_IDS_SCHEMA: JsonSchema;
+//# sourceMappingURL=tool-schemas.d.ts.map

package/dist/lib/mcp/tool-schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-schemas.d.ts","sourceRoot":"","sources":["../../../src/lib/mcp/tool-schemas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAsIzD,2CAA2C;AAC3C,eAAO,MAAM,iBAAiB,EAAE,UAAuB,CAAC;AAExD,yBAAyB;AACzB,eAAO,MAAM,eAAe,EAAE,UAE5B,CAAC;AAEH,qBAAqB;AACrB,eAAO,MAAM,mBAAmB,EAAE,UAoCjC,CAAC;AAEF,oBAAoB;AACpB,eAAO,MAAM,gBAAgB,EAAE,UAU9B,CAAC;AAEF,0BAA0B;AAC1B,eAAO,MAAM,gBAAgB,EAAE,UAmB9B,CAAC;AAEF,sBAAsB;AACtB,eAAO,MAAM,YAAY,EAAE,UAS1B,CAAC;AAEF,6BAA6B;AAC7B,eAAO,MAAM,mBAAmB,EAAE,UASjC,CAAC;AAkBF,uBAAuB;AACvB,eAAO,MAAM,aAAa,EAAE,UAkB3B,CAAC;AAEF,uBAAuB;AACvB,eAAO,MAAM,aAAa,EAAE,UAa3B,CAAC;AAEF,iEAAiE;AACjE,eAAO,MAAM,mBAAmB,EAAE,UAOjC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,EAAE,UAkC9B,CAAC;AAEF,iFAAiF;AACjF,eAAO,MAAM,eAAe,EAAE,UAY7B,CAAC"}