@orthacms/mcp-server 0.0.0-reserve.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ortha CMS contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+# @orthacms/mcp-server
+
+Part of [Ortha CMS](https://github.com/ortha-source/ortha-cms).
+
+```sh
+npm install @orthacms/mcp-server
+```

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/** Public API of @orthacms/mcp-server. */
+export { McpPlugin } from './lib/utils/mcp-plugin';
+export type { McpPluginOptions, McpServerPluginDefinition } from './lib/utils/mcp-plugin';
+export { McpModule } from './lib/mcp.module';
+export { MCP_CONFIG, InjectMcpConfig } from './lib/mcp.tokens';
+export type { McpPluginConfig } from './lib/types/mcp-config';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAE1C,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,YAAY,EACR,gBAAgB,EAChB,yBAAyB,EAC5B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAC/D,YAAY,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+"use strict";
+/** Public API of @orthacms/mcp-server. */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InjectMcpConfig = exports.MCP_CONFIG = exports.McpModule = exports.McpPlugin = void 0;
+var mcp_plugin_1 = require("./lib/utils/mcp-plugin");
+Object.defineProperty(exports, "McpPlugin", { enumerable: true, get: function () { return mcp_plugin_1.McpPlugin; } });
+var mcp_module_1 = require("./lib/mcp.module");
+Object.defineProperty(exports, "McpModule", { enumerable: true, get: function () { return mcp_module_1.McpModule; } });
+var mcp_tokens_1 = require("./lib/mcp.tokens");
+Object.defineProperty(exports, "MCP_CONFIG", { enumerable: true, get: function () { return mcp_tokens_1.MCP_CONFIG; } });
+Object.defineProperty(exports, "InjectMcpConfig", { enumerable: true, get: function () { return mcp_tokens_1.InjectMcpConfig; } });
+// The tool seam moved to `@orthacms/tools-server`. It is no longer MCP's to
+// own: the copilot's in-process loop injects the same registry, and importing
+// it from here would make a deployment that wants only the copilot pull the MCP
+// SDK through this barrel. Import `ToolRegistry`, `ToolDefinition`,
+// `ToolProvider`, `createToolContext` and `toToolError` from there.

package/dist/lib/http/mcp-auth.service.d.ts

@@ -0,0 +1,50 @@
+import { ApiTokenService } from '@orthacms/identity-server';
+import type { ToolContext } from '@orthacms/tools-server';
+/** The headers this service reads, as Node delivers them. */
+export interface McpRequestHeaders {
+    authorization?: string;
+    [key: string]: string | string[] | undefined;
+}
+/**
+ * Authenticates an MCP request and resolves the workspace it acts in, yielding
+ * the {@link ToolContext} every tool call runs under.
+ *
+ * **The same credential and the same rules as `/api/v1/*`** — deliberately, and
+ * to the letter. MCP is a second front door onto the content API, not a second
+ * security model: it takes the bearer tokens the admin's API Tokens page
+ * already mints, resolves them through the same `ApiTokenService.verify`, and
+ * derives permissions through the same `scopePermissions`. An operator revoking
+ * a token revokes its MCP access in the same instant, and there is no second
+ * credential store to audit.
+ *
+ * This class is the MCP counterpart of three guards that cannot be reused
+ * directly, because Nest gates *routes* and MCP is one route carrying many
+ * operations:
+ *
+ * - `ApiTokenGuard` → {@link authenticate}'s bearer half.
+ * - `ApiTokenWorkspaceGuard` → {@link authenticate}'s workspace half, rule for
+ *   rule.
+ * - The per-route `@RequirePermissions(...)` → `ToolDefinition.requires`,
+ *   enforced centrally by `ToolRegistry.call`.
+ *
+ * A **session cookie is not accepted**, exactly as on `/api/v1/*`. Cookies ride
+ * along ambiently, which is what makes cookie-authenticated writes CSRF-able; a
+ * bearer token never does. Accepting both here would reintroduce that on an
+ * endpoint whose whole purpose is letting an agent write content.
+ */
+export declare class McpAuthService {
+    private readonly tokens;
+    constructor(tokens: ApiTokenService);
+    /**
+     * Verify the bearer credential and resolve the target workspace.
+     *
+     * `workspaceQuery` is the optional `?workspaceId=` on the endpoint URL. It
+     * exists because MCP clients are configured with a **URL**, and several
+     * make custom headers awkward or impossible — while a multi-workspace token
+     * has to name one somehow. The header wins when both are present, and both
+     * are checked against the token's bucket identically, so the query string
+     * is a spelling of the same rule and never a way around it.
+     */
+    authenticate(headers: McpRequestHeaders, workspaceQuery?: string): Promise<ToolContext>;
+}
+//# sourceMappingURL=mcp-auth.service.d.ts.map

package/dist/lib/http/mcp-auth.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-auth.service.d.ts","sourceRoot":"","sources":["../../../src/lib/http/mcp-auth.service.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,eAAe,EAAoB,MAAM,2BAA2B,CAAC;AAK9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAM1D,6DAA6D;AAC7D,MAAM,WAAW,iBAAiB;IAC9B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBACa,cAAc;IACX,OAAO,CAAC,QAAQ,CAAC,MAAM;gBAAN,MAAM,EAAE,eAAe;IAEpD;;;;;;;;;OASG;IACG,YAAY,CACd,OAAO,EAAE,iBAAiB,EAC1B,cAAc,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,WAAW,CAAC;CAiC1B"}

package/dist/lib/http/mcp-auth.service.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpAuthService = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const identity_server_1 = require("@orthacms/identity-server");
+const workspaces_server_1 = require("@orthacms/workspaces-server");
+const tools_server_1 = require("@orthacms/tools-server");
+/** The scheme the `Authorization` header must use, case-insensitively. */
+const BEARER = 'bearer';
+/**
+ * Authenticates an MCP request and resolves the workspace it acts in, yielding
+ * the {@link ToolContext} every tool call runs under.
+ *
+ * **The same credential and the same rules as `/api/v1/*`** — deliberately, and
+ * to the letter. MCP is a second front door onto the content API, not a second
+ * security model: it takes the bearer tokens the admin's API Tokens page
+ * already mints, resolves them through the same `ApiTokenService.verify`, and
+ * derives permissions through the same `scopePermissions`. An operator revoking
+ * a token revokes its MCP access in the same instant, and there is no second
+ * credential store to audit.
+ *
+ * This class is the MCP counterpart of three guards that cannot be reused
+ * directly, because Nest gates *routes* and MCP is one route carrying many
+ * operations:
+ *
+ * - `ApiTokenGuard` → {@link authenticate}'s bearer half.
+ * - `ApiTokenWorkspaceGuard` → {@link authenticate}'s workspace half, rule for
+ *   rule.
+ * - The per-route `@RequirePermissions(...)` → `ToolDefinition.requires`,
+ *   enforced centrally by `ToolRegistry.call`.
+ *
+ * A **session cookie is not accepted**, exactly as on `/api/v1/*`. Cookies ride
+ * along ambiently, which is what makes cookie-authenticated writes CSRF-able; a
+ * bearer token never does. Accepting both here would reintroduce that on an
+ * endpoint whose whole purpose is letting an agent write content.
+ */
+let McpAuthService = class McpAuthService {
+    tokens;
+    constructor(tokens) {
+        this.tokens = tokens;
+    }
+    /**
+     * Verify the bearer credential and resolve the target workspace.
+     *
+     * `workspaceQuery` is the optional `?workspaceId=` on the endpoint URL. It
+     * exists because MCP clients are configured with a **URL**, and several
+     * make custom headers awkward or impossible — while a multi-workspace token
+     * has to name one somehow. The header wins when both are present, and both
+     * are checked against the token's bucket identically, so the query string
+     * is a spelling of the same rule and never a way around it.
+     */
+    async authenticate(headers, workspaceQuery) {
+        const secret = bearerFrom(headers.authorization);
+        if (!secret) {
+            throw new common_1.UnauthorizedException('Missing `Authorization: Bearer <token>` header.');
+        }
+        const token = await this.tokens.verify(secret);
+        if (!token) {
+            // Unknown, revoked, and expired are one flat 401 — the endpoint
+            // must not be usable to probe which tokens exist.
+            throw new common_1.UnauthorizedException('Invalid API token.');
+        }
+        const workspaceId = resolveWorkspace(token.workspaceIds, headerValue(headers[workspaces_server_1.WORKSPACE_HEADER]) ?? workspaceQuery);
+        return (0, tools_server_1.createToolContext)({
+            kind: 'token',
+            id: token.id,
+            displayName: token.name,
+            grantedPermissions: new Set((0, identity_server_1.scopePermissions)(token.scope)),
+            // Attribution only — the minting user's own role grants are
+            // never consulted, so revoking the token is always sufficient.
+            userId: token.createdBy ?? null
+        }, workspaceId);
+    }
+};
+exports.McpAuthService = McpAuthService;
+exports.McpAuthService = McpAuthService = tslib_1.__decorate([
+    (0, common_1.Injectable)(),
+    tslib_1.__metadata("design:paramtypes", [identity_server_1.ApiTokenService])
+], McpAuthService);
+/**
+ * Which of the token's workspaces this request targets — the rule
+ * `ApiTokenWorkspaceGuard` applies, restated for a non-Nest call site:
+ *
+ * - named → must be well-formed (400) and in the bucket (403);
+ * - unnamed with a single-workspace token → that workspace, so the common case
+ *   needs no configuration at all;
+ * - unnamed with a multi-workspace token → 400. Picking one silently would
+ *   surface as "why is this empty?", which is a far worse failure than an
+ *   error that says exactly what to do.
+ */
+function resolveWorkspace(bucket, requested) {
+    if (!requested) {
+        if (bucket.length === 1) {
+            return bucket[0];
+        }
+        throw new common_1.BadRequestException(`This token covers ${bucket.length} workspaces — name the one you want with the ${workspaces_server_1.WORKSPACE_HEADER} header or a ?workspaceId= query parameter on the MCP endpoint URL.`);
+    }
+    if (!workspaces_server_1.WORKSPACE_ID_PATTERN.test(requested)) {
+        throw new common_1.BadRequestException(`Malformed ${workspaces_server_1.WORKSPACE_HEADER}.`);
+    }
+    if (!bucket.includes(requested)) {
+        // Not-in-bucket and no-such-workspace are the same 403, so a token
+        // can't be used to probe which workspace ids exist.
+        throw new common_1.ForbiddenException('This token does not cover that workspace.');
+    }
+    return requested;
+}
+/** First value of a possibly-repeated header. */
+function headerValue(raw) {
+    return Array.isArray(raw) ? raw[0] : raw;
+}
+/**
+ * The raw token out of an `Authorization` header, or `undefined` when the
+ * header is absent, uses another scheme, or carries no value.
+ *
+ * Surrounding and repeated whitespace around the scheme is tolerated, because
+ * RFC 9110 allows it and clients emit it. Whitespace *inside* the value is not:
+ * a credential never contains any, so joining the pieces back together would
+ * invent a token the caller never sent — and then report the reinvention as
+ * `Invalid API token`, which reads as a wrong secret rather than a malformed
+ * header. Exactly one value after the scheme, or nothing.
+ */
+function bearerFrom(header) {
+    if (!header) {
+        return undefined;
+    }
+    const [scheme, ...rest] = header.trim().split(/\s+/);
+    if (scheme.toLowerCase() !== BEARER || rest.length !== 1) {
+        return undefined;
+    }
+    return rest[0].length > 0 ? rest[0] : undefined;
+}

package/dist/lib/http/mcp.controller.d.ts

@@ -0,0 +1,54 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { ToolRegistry } from '@orthacms/tools-server';
+import type { McpPluginConfig } from '../types/mcp-config';
+import { McpAuthService } from './mcp-auth.service';
+/** The express-shaped request this controller reads. */
+type McpHttpRequest = IncomingMessage & {
+    body?: unknown;
+    query?: Record<string, unknown>;
+};
+/**
+ * `POST /api/v1/mcp` — the **Model Context Protocol endpoint**. An external
+ * agent (Claude Desktop, Cursor, an SDK-built client) connects here and gets
+ * the CMS's content tools.
+ *
+ * **Stateless.** Every request carries its own bearer token and is authenticated
+ * from scratch, so there is no session to store, nothing to expire, and nothing
+ * requiring sticky routing across replicas — the endpoint scales exactly like
+ * the rest of `/api/v1`. The transport and protocol server are per-request and
+ * torn down with it, which is also what lets the tool list reflect *this*
+ * caller's scope.
+ *
+ * `GET` (the server-initiated SSE stream) and `DELETE` (session teardown) are
+ * answered **here** with a 405. Both exist to serve a persistent session, and
+ * there isn't one, which is exactly the case the specification reserves 405
+ * for. `@All()` routes them to this controller so the answer comes from the
+ * protocol layer rather than Nest's generic 404, which a client cannot
+ * interpret.
+ *
+ * The transport is deliberately not asked. Handed a `GET` in stateless mode it
+ * opens a standalone SSE stream and holds it **forever** — nothing on this
+ * endpoint ever pushes a server-initiated message, so the client waits on a
+ * connection that will never carry anything while a socket, a transport and a
+ * protocol server stay pinned per attempt. Answering 405 turns the commonest
+ * first-connection mistake into a sentence a client can act on.
+ *
+ * `@Public()` opts out of the session `AuthGuard`, exactly as the `/api/v1`
+ * controllers do — {@link McpAuthService} is the whole authentication story,
+ * and a session cookie is not accepted.
+ *
+ * Excluded from the OpenAPI document: JSON-RPC over one route is not describable
+ * as REST operations, and a single `POST /v1/mcp` entry in the reference would
+ * tell a reader nothing about the tools. The `AGENTS.md` documents the surface.
+ */
+export declare class McpController {
+    private readonly auth;
+    private readonly registry;
+    private readonly config;
+    private readonly logger;
+    constructor(auth: McpAuthService, registry: ToolRegistry, config: McpPluginConfig);
+    /** Handles one JSON-RPC exchange. */
+    handle(request: McpHttpRequest, response: ServerResponse): Promise<void>;
+}
+export {};
+//# sourceMappingURL=mcp.controller.d.ts.map

package/dist/lib/http/mcp.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.controller.d.ts","sourceRoot":"","sources":["../../../src/lib/http/mcp.controller.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AACjE,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAGtD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEpD,wDAAwD;AACxD,KAAK,cAAc,GAAG,eAAe,GAAG;IACpC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,qBAGa,aAAa;IAIlB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACL,OAAO,CAAC,QAAQ,CAAC,MAAM;IAL/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkC;gBAGpC,IAAI,EAAE,cAAc,EACpB,QAAQ,EAAE,YAAY,EACF,MAAM,EAAE,eAAe;IAGhE,qCAAqC;IAE/B,MAAM,CACD,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,cAAc,GAChC,OAAO,CAAC,IAAI,CAAC;CAsFnB"}

package/dist/lib/http/mcp.controller.js

@@ -0,0 +1,178 @@
+"use strict";
+var McpController_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpController = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+const identity_server_1 = require("@orthacms/identity-server");
+const tools_server_1 = require("@orthacms/tools-server");
+const mcp_tokens_1 = require("../mcp.tokens");
+const build_mcp_server_1 = require("../protocol/build-mcp-server");
+const mcp_auth_service_1 = require("./mcp-auth.service");
+/**
+ * `POST /api/v1/mcp` — the **Model Context Protocol endpoint**. An external
+ * agent (Claude Desktop, Cursor, an SDK-built client) connects here and gets
+ * the CMS's content tools.
+ *
+ * **Stateless.** Every request carries its own bearer token and is authenticated
+ * from scratch, so there is no session to store, nothing to expire, and nothing
+ * requiring sticky routing across replicas — the endpoint scales exactly like
+ * the rest of `/api/v1`. The transport and protocol server are per-request and
+ * torn down with it, which is also what lets the tool list reflect *this*
+ * caller's scope.
+ *
+ * `GET` (the server-initiated SSE stream) and `DELETE` (session teardown) are
+ * answered **here** with a 405. Both exist to serve a persistent session, and
+ * there isn't one, which is exactly the case the specification reserves 405
+ * for. `@All()` routes them to this controller so the answer comes from the
+ * protocol layer rather than Nest's generic 404, which a client cannot
+ * interpret.
+ *
+ * The transport is deliberately not asked. Handed a `GET` in stateless mode it
+ * opens a standalone SSE stream and holds it **forever** — nothing on this
+ * endpoint ever pushes a server-initiated message, so the client waits on a
+ * connection that will never carry anything while a socket, a transport and a
+ * protocol server stay pinned per attempt. Answering 405 turns the commonest
+ * first-connection mistake into a sentence a client can act on.
+ *
+ * `@Public()` opts out of the session `AuthGuard`, exactly as the `/api/v1`
+ * controllers do — {@link McpAuthService} is the whole authentication story,
+ * and a session cookie is not accepted.
+ *
+ * Excluded from the OpenAPI document: JSON-RPC over one route is not describable
+ * as REST operations, and a single `POST /v1/mcp` entry in the reference would
+ * tell a reader nothing about the tools. The `AGENTS.md` documents the surface.
+ */
+let McpController = McpController_1 = class McpController {
+    auth;
+    registry;
+    config;
+    logger = new common_1.Logger(McpController_1.name);
+    constructor(auth, registry, config) {
+        this.auth = auth;
+        this.registry = registry;
+        this.config = config;
+    }
+    /** Handles one JSON-RPC exchange. */
+    async handle(request, response) {
+        if (!this.config.enabled) {
+            // The controller is only registered when enabled, so this is a
+            // belt-and-braces guard against a future wiring change.
+            throw new common_1.ServiceUnavailableException('The MCP endpoint is disabled.');
+        }
+        // Authenticate BEFORE handing anything to the protocol layer: an
+        // unauthenticated caller must not be able to drive the JSON-RPC state
+        // machine at all, not even to `initialize`. A plain HTTP status is also
+        // the right answer here — a 401 is what tells an MCP client its
+        // credential is wrong, where a JSON-RPC error would read as a working
+        // connection returning a failure.
+        const context = await this.auth.authenticate(request.headers, workspaceQuery(request));
+        // After authentication, so a verb answer is never reachable without a
+        // credential — an unauthenticated probe learns 401 and nothing else.
+        if (request.method !== 'POST') {
+            methodNotAllowed(response);
+            return;
+        }
+        const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({
+            // Stateless: no session id is issued, and none is validated.
+            sessionIdGenerator: undefined,
+            // Answer with a single JSON body rather than opening an SSE stream.
+            // Nothing here streams — a tool call returns once — and a plain
+            // JSON response is what every client and every proxy handles best.
+            enableJsonResponse: true
+        });
+        const server = (0, build_mcp_server_1.buildMcpServer)(this.registry, context, { name: this.config.name, version: this.config.version }, {
+            callTimeoutMs: this.config.callTimeoutMs,
+            maxResultBytes: this.config.maxResultBytes
+        });
+        // Tear both down when the exchange ends, however it ends. Without this
+        // every request leaks a protocol server and its handler closures.
+        response.on('close', () => {
+            void transport.close();
+            void server.close();
+        });
+        try {
+            await server.connect(transport);
+            // The body is already parsed by the host's express json middleware;
+            // handing it over avoids the transport re-reading a consumed stream.
+            await transport.handleRequest(request, response, request.body);
+        }
+        catch (error) {
+            this.logger.error(`MCP request failed for token ${context.actor.id}`, error instanceof Error ? error.stack : String(error));
+            if (!response.headersSent) {
+                response.writeHead(500, {
+                    'content-type': 'application/json'
+                });
+                response.end(JSON.stringify({
+                    jsonrpc: '2.0',
+                    error: {
+                        code: -32603,
+                        message: 'Internal server error'
+                    },
+                    id: null
+                }));
+            }
+            else {
+                // The transport had already started writing, so there is no
+                // status left to set — but an unterminated response is a client
+                // waiting on a body that will never arrive until its socket
+                // times out. End it; a truncated answer is diagnosable and a
+                // hang is not.
+                response.end();
+            }
+        }
+    }
+};
+exports.McpController = McpController;
+tslib_1.__decorate([
+    (0, common_1.All)(),
+    tslib_1.__param(0, (0, common_1.Req)()),
+    tslib_1.__param(1, (0, common_1.Res)()),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [Object, Function]),
+    tslib_1.__metadata("design:returntype", Promise)
+], McpController.prototype, "handle", null);
+exports.McpController = McpController = McpController_1 = tslib_1.__decorate([
+    (0, identity_server_1.Public)(),
+    (0, swagger_1.ApiExcludeController)(),
+    (0, common_1.Controller)('v1/mcp'),
+    tslib_1.__param(2, (0, common_1.Inject)(mcp_tokens_1.MCP_CONFIG)),
+    tslib_1.__metadata("design:paramtypes", [mcp_auth_service_1.McpAuthService,
+        tools_server_1.ToolRegistry, Object])
+], McpController);
+/** 405 for the verbs a stateless, non-streaming endpoint does not serve. */
+function methodNotAllowed(response) {
+    response.writeHead(405, {
+        'content-type': 'application/json',
+        allow: 'POST'
+    });
+    response.end(JSON.stringify({
+        jsonrpc: '2.0',
+        error: {
+            code: -32000,
+            message: 'Method Not Allowed: this MCP endpoint is stateless and serves POST only. There is no server-initiated stream to open (GET) and no session to end (DELETE).'
+        },
+        id: null
+    }));
+}
+/**
+ * The optional `?workspaceId=` on the endpoint URL.
+ *
+ * Repeating it — `?workspaceId=a&workspaceId=b`, or the `?workspaceId[]=a`
+ * spelling — parses to an array, and treating that as "unnamed" made a
+ * single-workspace token quietly succeed against its own workspace while the
+ * caller had named two others. A request that names more than one workspace has
+ * no answer that is not a guess, so it is refused.
+ */
+function workspaceQuery(request) {
+    const raw = request.query?.['workspaceId'];
+    if (raw === undefined) {
+        return undefined;
+    }
+    if (typeof raw !== 'string') {
+        throw new common_1.BadRequestException('Repeat `?workspaceId=` names more than one workspace. Pass it exactly once, or use the x-workspace-id header.');
+    }
+    return raw;
+}

package/dist/lib/mcp.module.d.ts

@@ -0,0 +1,19 @@
+import { DynamicModule } from '@nestjs/common';
+import type { McpPluginConfig } from './types/mcp-config';
+/**
+ * NestJS module for the MCP plugin. Registered globally, like every other
+ * plugin module here, so a capability plugin can inject {@link ToolRegistry}
+ * and contribute tools without an explicit import.
+ *
+ * **The registry is available even when the endpoint is disabled**, and the
+ * controller is the only thing the kill switch removes. Two reasons: the
+ * copilot's in-process tool loop consumes the same registry and has nothing to
+ * do with whether an *external* endpoint is exposed, and a contributing plugin
+ * should not have to care either way — it registers its tools unconditionally
+ * and the composition root decides who may reach them.
+ */
+export declare class McpModule {
+    /** Creates the global dynamic module around a validated config. */
+    static forRoot(config: McpPluginConfig): DynamicModule;
+}
+//# sourceMappingURL=mcp.module.d.ts.map

package/dist/lib/mcp.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.module.d.ts","sourceRoot":"","sources":["../../src/lib/mcp.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAU,MAAM,gBAAgB,CAAC;AAKvD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAE1D;;;;;;;;;;;GAWG;AACH,qBACa,SAAS;IAClB,mEAAmE;IACnE,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,eAAe,GAAG,aAAa;CAgBzD"}

package/dist/lib/mcp.module.js

@@ -0,0 +1,45 @@
+"use strict";
+var McpModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpModule = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const tools_server_1 = require("@orthacms/tools-server");
+const mcp_auth_service_1 = require("./http/mcp-auth.service");
+const mcp_controller_1 = require("./http/mcp.controller");
+const mcp_tokens_1 = require("./mcp.tokens");
+/**
+ * NestJS module for the MCP plugin. Registered globally, like every other
+ * plugin module here, so a capability plugin can inject {@link ToolRegistry}
+ * and contribute tools without an explicit import.
+ *
+ * **The registry is available even when the endpoint is disabled**, and the
+ * controller is the only thing the kill switch removes. Two reasons: the
+ * copilot's in-process tool loop consumes the same registry and has nothing to
+ * do with whether an *external* endpoint is exposed, and a contributing plugin
+ * should not have to care either way — it registers its tools unconditionally
+ * and the composition root decides who may reach them.
+ */
+let McpModule = McpModule_1 = class McpModule {
+    /** Creates the global dynamic module around a validated config. */
+    static forRoot(config) {
+        return {
+            module: McpModule_1,
+            global: true,
+            // The registry is *imported*, not provided: it is shared with the
+            // copilot, and whichever consumer a deployment runs must see the
+            // same instance.
+            imports: [tools_server_1.ToolsModule],
+            controllers: config.enabled ? [mcp_controller_1.McpController] : [],
+            providers: [
+                { provide: mcp_tokens_1.MCP_CONFIG, useValue: config },
+                mcp_auth_service_1.McpAuthService
+            ],
+            exports: [mcp_tokens_1.MCP_CONFIG, tools_server_1.ToolsModule]
+        };
+    }
+};
+exports.McpModule = McpModule;
+exports.McpModule = McpModule = McpModule_1 = tslib_1.__decorate([
+    (0, common_1.Module)({})
+], McpModule);

package/dist/lib/mcp.tokens.d.ts

@@ -0,0 +1,11 @@
+/**
+ * DI tokens and their inject decorators for the MCP plugin. Kept in a
+ * dependency-free module (imports only `@nestjs/common`) so providers can
+ * reference them without forming an import cycle with `mcp.module.ts` — the
+ * same arrangement as `copilot.tokens.ts`.
+ */
+/** Injection token for the resolved MCP configuration. */
+export declare const MCP_CONFIG: unique symbol;
+/** Parameter decorator that injects the MCP configuration. */
+export declare const InjectMcpConfig: () => ParameterDecorator;
+//# sourceMappingURL=mcp.tokens.d.ts.map

package/dist/lib/mcp.tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.tokens.d.ts","sourceRoot":"","sources":["../../src/lib/mcp.tokens.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AAEH,0DAA0D;AAC1D,eAAO,MAAM,UAAU,eAAuB,CAAC;AAE/C,8DAA8D;AAC9D,eAAO,MAAM,eAAe,QAAO,kBAAwC,CAAC"}

package/dist/lib/mcp.tokens.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.InjectMcpConfig = exports.MCP_CONFIG = void 0;
+const common_1 = require("@nestjs/common");
+/**
+ * DI tokens and their inject decorators for the MCP plugin. Kept in a
+ * dependency-free module (imports only `@nestjs/common`) so providers can
+ * reference them without forming an import cycle with `mcp.module.ts` — the
+ * same arrangement as `copilot.tokens.ts`.
+ */
+/** Injection token for the resolved MCP configuration. */
+exports.MCP_CONFIG = Symbol('MCP_CONFIG');
+/** Parameter decorator that injects the MCP configuration. */
+const InjectMcpConfig = () => (0, common_1.Inject)(exports.MCP_CONFIG);
+exports.InjectMcpConfig = InjectMcpConfig;

package/dist/lib/protocol/build-mcp-server.d.ts

@@ -0,0 +1,50 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ToolRegistry } from '@orthacms/tools-server';
+import type { ToolContext } from '@orthacms/tools-server';
+/** Identity this server reports to clients during `initialize`. */
+export interface McpServerInfo {
+    /** Server name shown in client UIs. */
+    name: string;
+    /** Server version. */
+    version: string;
+}
+/** The transport's own ceilings on one exchange. See {@link McpPluginConfig}. */
+export interface McpServerLimits {
+    /** Ceiling on one `tools/call`, in milliseconds. */
+    callTimeoutMs: number;
+    /** Ceiling on the serialised size of one tool result, in bytes. */
+    maxResultBytes: number;
+}
+/**
+ * Build the MCP protocol server for **one** authenticated request.
+ *
+ * Per-request rather than one long-lived instance, because the tool list is a
+ * function of the caller: `tools/list` must show a `read`-scoped token a
+ * different set than a `full`-scoped one, and resources are pruned to the
+ * workspace's content grants. Binding the context into the handlers at
+ * construction is what makes that impossible to get wrong — there is no shared
+ * server whose handlers must remember to re-derive who is asking.
+ *
+ * The low-level `Server` is used rather than the SDK's `McpServer` helper
+ * deliberately: that helper takes Zod shapes, while every schema here is
+ * **generated JSON Schema** produced from the content registry at runtime.
+ * Converting generated JSON Schema into Zod purely to have the SDK convert it
+ * back is a lossy round-trip in service of nothing.
+ *
+ * ## Two ways a failure leaves this file, and why
+ *
+ * A `tools/call` failure rides out as an **`isError` result**; a `resources/*`
+ * failure rides out as a **JSON-RPC error**. That asymmetry is the protocol's,
+ * not an accident. A tool failure is an *outcome* the model is meant to read
+ * and act on ("title must be at most 200 characters"), so MCP models it as a
+ * successful call carrying `isError`. A resource read has no model in the loop
+ * — the client asked for bytes at a URI and either gets them or does not — so
+ * MCP models its failures as protocol errors, with `-32002` reserved for a URI
+ * that is not there.
+ *
+ * What both paths share is {@link toToolError}: whatever a handler throws is
+ * flattened the same way, so an unexpected error is opaque on either path and
+ * never puts a raw message on the wire.
+ */
+export declare function buildMcpServer(registry: ToolRegistry, context: ToolContext, info: McpServerInfo, limits: McpServerLimits): Server;
+//# sourceMappingURL=build-mcp-server.d.ts.map

package/dist/lib/protocol/build-mcp-server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-mcp-server.d.ts","sourceRoot":"","sources":["../../../src/lib/protocol/build-mcp-server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AASnE,OAAO,KAAK,EAAc,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEvE,OAAO,KAAK,EAAE,WAAW,EAAa,MAAM,wBAAwB,CAAC;AASrE,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC1B,uCAAuC;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,sBAAsB;IACtB,OAAO,EAAE,MAAM,CAAC;CACnB;AAED,iFAAiF;AACjF,MAAM,WAAW,eAAe;IAC5B,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,cAAc,EAAE,MAAM,CAAC;CAC1B;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,cAAc,CAC1B,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,WAAW,EACpB,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,eAAe,GACxB,MAAM,CAyGR"}

package/dist/lib/protocol/build-mcp-server.js

@@ -0,0 +1,248 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildMcpServer = buildMcpServer;
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const tools_server_1 = require("@orthacms/tools-server");
+/**
+ * MCP's own code for "the resource you named is not there". It is in the
+ * specification but not in the SDK's `ErrorCode` enum, so it is spelled out
+ * here rather than approximated with `InternalError`.
+ */
+const RESOURCE_NOT_FOUND = -32002;
+/**
+ * Raised when {@link callWithinDeadline} stops waiting on a handler — because
+ * the deadline passed, or because the caller hung up.
+ *
+ * A class of its own so neither reaches {@link toToolError}, which would log it
+ * as an unhandled error with a stack. A client disconnecting is routine, and a
+ * deadline is this file's own decision; neither is a bug in a tool.
+ */
+class CallAbandoned extends Error {
+    reason;
+    constructor(reason) {
+        super(`The tool call was abandoned (${reason}).`);
+        this.reason = reason;
+    }
+}
+/**
+ * Build the MCP protocol server for **one** authenticated request.
+ *
+ * Per-request rather than one long-lived instance, because the tool list is a
+ * function of the caller: `tools/list` must show a `read`-scoped token a
+ * different set than a `full`-scoped one, and resources are pruned to the
+ * workspace's content grants. Binding the context into the handlers at
+ * construction is what makes that impossible to get wrong — there is no shared
+ * server whose handlers must remember to re-derive who is asking.
+ *
+ * The low-level `Server` is used rather than the SDK's `McpServer` helper
+ * deliberately: that helper takes Zod shapes, while every schema here is
+ * **generated JSON Schema** produced from the content registry at runtime.
+ * Converting generated JSON Schema into Zod purely to have the SDK convert it
+ * back is a lossy round-trip in service of nothing.
+ *
+ * ## Two ways a failure leaves this file, and why
+ *
+ * A `tools/call` failure rides out as an **`isError` result**; a `resources/*`
+ * failure rides out as a **JSON-RPC error**. That asymmetry is the protocol's,
+ * not an accident. A tool failure is an *outcome* the model is meant to read
+ * and act on ("title must be at most 200 characters"), so MCP models it as a
+ * successful call carrying `isError`. A resource read has no model in the loop
+ * — the client asked for bytes at a URI and either gets them or does not — so
+ * MCP models its failures as protocol errors, with `-32002` reserved for a URI
+ * that is not there.
+ *
+ * What both paths share is {@link toToolError}: whatever a handler throws is
+ * flattened the same way, so an unexpected error is opaque on either path and
+ * never puts a raw message on the wire.
+ */
+function buildMcpServer(registry, context, info, limits) {
+    const server = new index_js_1.Server(info, {
+        capabilities: { tools: {}, resources: {} }
+    });
+    server.setRequestHandler(types_js_1.ListToolsRequestSchema, () => ({
+        tools: registry.visibleTo(context, 'mcp').map((tool) => ({
+            name: tool.name,
+            title: tool.title,
+            description: tool.description,
+            inputSchema: tool.inputSchema,
+            annotations: {
+                title: tool.title,
+                readOnlyHint: tool.readOnly,
+                destructiveHint: tool.destructive ?? false
+            }
+        }))
+    }));
+    server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request, extra) => {
+        const { name, arguments: args } = request.params;
+        let result;
+        try {
+            result = await callWithinDeadline(registry, name, args, context, 
+            // The SDK aborts this when the client cancels the request or
+            // the exchange closes — the only cancellation signal this
+            // surface has, and previously dropped on the floor.
+            extra.signal, limits.callTimeoutMs);
+        }
+        catch (error) {
+            // `isError` rather than a JSON-RPC error, and this is the whole
+            // point: a protocol error aborts the client's call, while an
+            // `isError` result is handed back to the *model*, which can read
+            // "title must be at most 200 characters" and fix its next call.
+            // Refusals land here too — a model that learns it lacks
+            // `content:publish` stops trying, instead of retrying blind.
+            if (error instanceof CallAbandoned) {
+                return errorResult(error.reason === 'timeout'
+                    ? {
+                        status: 504,
+                        code: 'timeout',
+                        message: `"${name}" did not finish within ${limits.callTimeoutMs}ms and was abandoned. Retry, or narrow the request.`
+                    }
+                    : // Nobody is reading this: the exchange is already
+                        // closed. It exists so the handler chain unwinds
+                        // through one shape rather than two.
+                        {
+                            status: 499,
+                            code: 'client_closed_request',
+                            message: `"${name}" was abandoned because the caller disconnected.`
+                        });
+            }
+            return errorResult((0, tools_server_1.toToolError)(error));
+        }
+        // Sized before either copy is handed to the transport, because the
+        // response costs roughly three times this on the way out: the text
+        // block, `structuredContent`, and the transport's own serialisation.
+        const text = stringify(result);
+        const bytes = Buffer.byteLength(text);
+        if (bytes > limits.maxResultBytes) {
+            return errorResult({
+                status: 413,
+                code: 'result_too_large',
+                message: `"${name}" returned ${bytes} bytes, over this endpoint's ${limits.maxResultBytes}-byte limit. Ask for less — a smaller page size, fewer fields, or a narrower filter.`
+            });
+        }
+        return {
+            // Both spellings of the same value: `structuredContent` for
+            // clients that parse it, and the text block for models that
+            // only ever see `content`. Emitting one or the other would
+            // make the tool useless to half the ecosystem.
+            content: [{ type: 'text', text }],
+            structuredContent: asStructured(result)
+        };
+    });
+    server.setRequestHandler(types_js_1.ListResourcesRequestSchema, async () => {
+        try {
+            return { resources: [...(await registry.resources(context))] };
+        }
+        catch (error) {
+            throw toMcpError(error);
+        }
+    });
+    server.setRequestHandler(types_js_1.ReadResourceRequestSchema, async (request) => {
+        try {
+            const contents = await registry.readResource(request.params.uri, context);
+            return { contents: [contents] };
+        }
+        catch (error) {
+            throw toMcpError(error);
+        }
+    });
+    return server;
+}
+/**
+ * Run one tool, giving up on it after `timeoutMs`.
+ *
+ * The handler is given a signal that fires for either reason — the deadline or
+ * the caller going away — so a tool doing real I/O can stop. A tool that
+ * ignores it keeps running: this bounds **the caller's wait**, which is the
+ * guarantee a request/response transport owes, and deliberately not the work,
+ * which nothing at this layer can end.
+ */
+async function callWithinDeadline(registry, name, args, context, callerSignal, timeoutMs) {
+    const controller = new AbortController();
+    const relay = () => controller.abort();
+    callerSignal?.addEventListener('abort', relay, { once: true });
+    let expired = false;
+    const timer = setTimeout(() => {
+        // Set before aborting, so the listener that fires as a consequence can
+        // tell a deadline from a caller who hung up.
+        expired = true;
+        controller.abort();
+    }, timeoutMs);
+    try {
+        const pending = registry.call(name, args, { ...context, signal: controller.signal }, 'mcp');
+        // The loser of the race still settles. Without this, a handler that
+        // fails *after* the deadline becomes an unhandled rejection and takes
+        // the process down — the exact failure mode this timeout exists to
+        // contain.
+        pending.catch(() => undefined);
+        return await Promise.race([
+            pending,
+            rejectWhenAborted(controller.signal, () => expired)
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+        callerSignal?.removeEventListener('abort', relay);
+    }
+}
+/** A promise that never resolves and rejects once `signal` aborts. */
+function rejectWhenAborted(signal, timedOut) {
+    return new Promise((_, reject) => {
+        const fail = () => reject(new CallAbandoned(timedOut() ? 'timeout' : 'disconnect'));
+        if (signal.aborted) {
+            fail();
+            return;
+        }
+        signal.addEventListener('abort', fail, { once: true });
+    });
+}
+/** One tool failure, in the shape a model reads. */
+function errorResult(failure) {
+    return {
+        isError: true,
+        content: [{ type: 'text', text: stringify(failure) }]
+    };
+}
+/**
+ * Whatever a resource handler threw, as the JSON-RPC error the client gets.
+ *
+ * The flattened {@link ToolError} rides along as `data`, so a client reads the
+ * same `status` / `code` / `issues` it would from a tool — and an *unexpected*
+ * throw is reported opaquely, rather than putting a driver's message on the
+ * wire under a code that calls it an internal error.
+ */
+function toMcpError(error) {
+    const failure = (0, tools_server_1.toToolError)(error);
+    return new types_js_1.McpError(jsonRpcCodeFor(failure.status), failure.message, failure);
+}
+/**
+ * Status → JSON-RPC code. A refusal shares `-32002` with an absence on
+ * purpose: for *data* the answer is deliberately uniform (an ungranted content
+ * type reads exactly like one that does not exist), and `data.code` still says
+ * `forbidden` for a client that wants to tell them apart.
+ */
+function jsonRpcCodeFor(status) {
+    if (status === 403 || status === 404) {
+        return RESOURCE_NOT_FOUND;
+    }
+    if (status === 400 || status === 422) {
+        return types_js_1.ErrorCode.InvalidParams;
+    }
+    return types_js_1.ErrorCode.InternalError;
+}
+/**
+ * MCP's `structuredContent` must be a JSON **object**. Tool results are mostly
+ * objects already (a list envelope, an entry); anything else is boxed under
+ * `value` rather than dropped.
+ */
+function asStructured(result) {
+    return typeof result === 'object' &&
+        result !== null &&
+        !Array.isArray(result)
+        ? result
+        : { value: result };
+}
+/** Pretty-printed JSON — the text rendering a model actually reads. */
+function stringify(value) {
+    return JSON.stringify(value, null, 2) ?? 'null';
+}

package/dist/lib/types/mcp-config.d.ts

@@ -0,0 +1,54 @@
+/** Runtime configuration for the MCP plugin. */
+export interface McpPluginConfig {
+    /**
+     * Whether the MCP endpoint is mounted at all.
+     *
+     * **Off by default.** The endpoint hands an external agent the same content
+     * CRUD a `full`-scope token has, and an operator who has not thought about
+     * that should not have it exposed because they upgraded. The same reasoning
+     * — and the same default — as the copilot's kill switch (ADR-0005 §10).
+     */
+    enabled: boolean;
+    /** Server name reported to MCP clients during `initialize`. */
+    name: string;
+    /** Server version reported to MCP clients. */
+    version: string;
+    /**
+     * Ceiling on **one** `tools/call`, in milliseconds.
+     *
+     * The registry deliberately has no deadline of its own — `ToolContext.signal`
+     * is documented as "a courtesy, never a correctness boundary" — so without
+     * this the only thing bounding a tool call is the query underneath it. When
+     * that blocks (a pool with no free connection, a database that went away),
+     * an MCP request hangs until the *client* gives up, holding a socket, a
+     * transport and a protocol server the whole time.
+     *
+     * The bound lives here rather than in the registry because it is a property
+     * of the transport: a request/response exchange owes its caller an answer,
+     * where the copilot's in-process loop has its own wall clock. Expiry is
+     * reported as a model-readable `isError` result (`504` / `timeout`), so an
+     * agent retries or narrows instead of stalling.
+     *
+     * **It abandons, it does not cancel.** The signal is passed to the handler,
+     * but a tool that ignores it keeps running to completion with nobody
+     * reading the answer. Bounding the *caller's* wait is the guarantee; ending
+     * the work is not one this layer can make.
+     */
+    callTimeoutMs: number;
+    /**
+     * Ceiling on the serialised size of one tool result, in bytes.
+     *
+     * A result is emitted **twice** — pretty-printed as the text block a model
+     * reads, and again as `structuredContent` for clients that parse it — and
+     * the transport then serialises the whole response a third time. Peak
+     * memory is therefore a multiple of the payload, per concurrent request,
+     * and nothing in the tool catalogue caps how much a handler may return.
+     *
+     * Over the ceiling the call answers `413` / `result_too_large` naming the
+     * two sizes, which is strictly more useful to a model than the payload
+     * would have been: a result that does not fit here does not fit in its
+     * context window either, and the message tells it to narrow the query.
+     */
+    maxResultBytes: number;
+}
+//# sourceMappingURL=mcp-config.d.ts.map

package/dist/lib/types/mcp-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-config.d.ts","sourceRoot":"","sources":["../../../src/lib/types/mcp-config.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC5B;;;;;;;OAOG;IACH,OAAO,EAAE,OAAO,CAAC;IACjB,+DAA+D;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;;;;;;;;;;;OAaG;IACH,cAAc,EAAE,MAAM,CAAC;CAC1B"}

package/dist/lib/types/mcp-config.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/lib/utils/mcp-plugin.d.ts

@@ -0,0 +1,31 @@
+import type { ServerPlugin } from '@orthacms/bootstrap-server';
+import type { McpPluginConfig } from '../types/mcp-config';
+/** The MCP plugin shape, with its config attached. */
+export type McpServerPluginDefinition = ServerPlugin & {
+    mcpConfig: McpPluginConfig;
+};
+/** Options the host passes to {@link McpPlugin}. */
+export interface McpPluginOptions {
+    /** Host config — kill switch plus the identity reported to clients. */
+    config: McpPluginConfig;
+}
+/**
+ * Creates the MCP plugin — the Model Context Protocol front door onto the CMS.
+ *
+ * Register it **after** `IdentityPlugin` (bearer tokens are verified through
+ * its `ApiTokenService`) and after every plugin that contributes tools, so the
+ * intent reads top-to-bottom. DI itself is order-independent: every plugin
+ * module is global, and contributors register into {@link ToolRegistry} during
+ * `onModuleInit`, which Nest runs once the whole graph is built.
+ *
+ * The plugin owns **no tables**, so it declares no migrations, and it owns no
+ * tools — `content/server` contributes those. Adding another capability's tools
+ * is a `ToolProvider` in that plugin plus nothing at all here.
+ *
+ * @example
+ * ```typescript
+ * McpPlugin({ config: config.plugins.mcp });
+ * ```
+ */
+export declare function McpPlugin(options: McpPluginOptions): McpServerPluginDefinition;
+//# sourceMappingURL=mcp-plugin.d.ts.map

package/dist/lib/utils/mcp-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-plugin.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/mcp-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAE3D,sDAAsD;AACtD,MAAM,MAAM,yBAAyB,GAAG,YAAY,GAAG;IACnD,SAAS,EAAE,eAAe,CAAC;CAC9B,CAAC;AAEF,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC7B,uEAAuE;IACvE,MAAM,EAAE,eAAe,CAAC;CAC3B;AAqCD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CACrB,OAAO,EAAE,gBAAgB,GAC1B,yBAAyB,CAO3B"}

package/dist/lib/utils/mcp-plugin.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpPlugin = McpPlugin;
+const mcp_module_1 = require("../mcp.module");
+/**
+ * Validate the wiring **eagerly**, like every other plugin factory here: a
+ * blank server name or version is a misconfiguration that should fail at
+ * construction rather than surface as a malformed `initialize` response, where
+ * it is far more expensive to diagnose.
+ */
+function assertOptions(options) {
+    if (!options.config.name) {
+        throw new Error('McpPlugin requires a non-empty `config.name` — it is the server identity MCP clients display.');
+    }
+    if (!options.config.version) {
+        throw new Error('McpPlugin requires a non-empty `config.version`.');
+    }
+    assertPositiveInteger(options.config.callTimeoutMs, 'callTimeoutMs');
+    assertPositiveInteger(options.config.maxResultBytes, 'maxResultBytes');
+}
+/**
+ * A ceiling that is `0`, negative or `NaN` is worse than no ceiling: a zero
+ * timeout fails every call, and `Number(process.env[…]) || default` turns a
+ * typo into a silent default. Fail at construction, where the misconfiguration
+ * is one line away.
+ */
+function assertPositiveInteger(value, field) {
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new Error(`McpPlugin requires \`config.${field}\` to be a positive integer, got ${String(value)}.`);
+    }
+}
+/**
+ * Creates the MCP plugin — the Model Context Protocol front door onto the CMS.
+ *
+ * Register it **after** `IdentityPlugin` (bearer tokens are verified through
+ * its `ApiTokenService`) and after every plugin that contributes tools, so the
+ * intent reads top-to-bottom. DI itself is order-independent: every plugin
+ * module is global, and contributors register into {@link ToolRegistry} during
+ * `onModuleInit`, which Nest runs once the whole graph is built.
+ *
+ * The plugin owns **no tables**, so it declares no migrations, and it owns no
+ * tools — `content/server` contributes those. Adding another capability's tools
+ * is a `ToolProvider` in that plugin plus nothing at all here.
+ *
+ * @example
+ * ```typescript
+ * McpPlugin({ config: config.plugins.mcp });
+ * ```
+ */
+function McpPlugin(options) {
+    assertOptions(options);
+    return {
+        name: 'mcp',
+        module: mcp_module_1.McpModule.forRoot(options.config),
+        mcpConfig: options.config
+    };
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+    "name": "@orthacms/mcp-server",
+    "version": "0.0.0-reserve.0",
+    "description": "@orthacms/mcp-server — part of Ortha CMS.",
+    "license": "MIT",
+    "homepage": "https://github.com/ortha-source/ortha-cms/tree/main/packages/mcp/server",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/ortha-source/ortha-cms.git",
+        "directory": "packages/mcp/server"
+    },
+    "bugs": {
+        "url": "https://github.com/ortha-source/ortha-cms/issues"
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "dist"
+    ],
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.30.0",
+        "@nestjs/common": "^11.0.0",
+        "@nestjs/swagger": "^11.4.6",
+        "@orthacms/bootstrap-server": "^0.0.1",
+        "@orthacms/identity-server": "^0.0.1",
+        "@orthacms/tools-server": "^0.0.1",
+        "@orthacms/workspaces-server": "^0.0.1",
+        "tslib": "^2.3.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}