@carlonicora/nestjs-neo4jsonapi 1.111.0 → 1.112.0

package/dist/mcp/controllers/mcp.controller.d.ts

@@ -0,0 +1,34 @@
+import { ConfigService } from "@nestjs/config";
+import { FastifyReply, FastifyRequest } from "fastify";
+import { ClsService } from "nestjs-cls";
+import { UserModulesRepository } from "../../agents/graph/repositories/user-modules.repository";
+import { McpServerFactory } from "../services/mcp.server.factory";
+/**
+ * MCP (Model Context Protocol) endpoint — stateless Streamable HTTP.
+ *
+ * Each `POST /mcp` request is authenticated by the existing OAuthTokenGuard
+ * (which populates CLS `userId`/`companyId`), then handed to a fresh per-request
+ * MCP Server + StreamableHTTPServerTransport pair (`sessionIdGenerator:
+ * undefined` — stateless mode, no session tracking). GET/DELETE are rejected
+ * with 405: stateless servers expose no SSE notification channel and no
+ * session to terminate.
+ *
+ * Uses `@Res()` with raw reply writing (the SDK transport writes directly to
+ * `res.raw`), which opts this handler out of Nest response serialization —
+ * the MCP wire format is JSON-RPC, not JSON:API, matching how the OAuth
+ * controllers speak their own RFC-mandated wire formats.
+ */
+export declare class McpController {
+    private readonly factory;
+    private readonly cls;
+    private readonly userModules;
+    private readonly configService;
+    constructor(factory: McpServerFactory, cls: ClsService, userModules: UserModulesRepository, configService: ConfigService);
+    /** Handles one stateless MCP Streamable-HTTP request (initialize, tools/list, tools/call, ...). */
+    handle(req: FastifyRequest, res: FastifyReply): Promise<void>;
+    /** Stateless server: no SSE notification stream is offered. */
+    rejectGet(): never;
+    /** Stateless server: there is no session to terminate. */
+    rejectDelete(): never;
+}
+//# sourceMappingURL=mcp.controller.d.ts.map

package/dist/mcp/controllers/mcp.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.controller.d.ts","sourceRoot":"","sources":["../../../src/mcp/controllers/mcp.controller.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AACvD,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,qBAAqB,EAAE,MAAM,yDAAyD,CAAC;AAKhG,OAAO,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAElE;;;;;;;;;;;;;;GAcG;AACH,qBAGa,aAAa;IAEtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAHb,OAAO,EAAE,gBAAgB,EACzB,GAAG,EAAE,UAAU,EACf,WAAW,EAAE,qBAAqB,EAClC,aAAa,EAAE,aAAa;IAG/C,mGAAmG;IAE7F,MAAM,CAAQ,GAAG,EAAE,cAAc,EAAS,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC;IAyBjF,+DAA+D;IAE/D,SAAS,IAAI,KAAK;IAIlB,0DAA0D;IAE1D,YAAY,IAAI,KAAK;CAGtB"}

package/dist/mcp/controllers/mcp.controller.js

@@ -0,0 +1,108 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpController = void 0;
+const common_1 = require("@nestjs/common");
+const config_1 = require("@nestjs/config");
+const streamableHttp_js_1 = require("@modelcontextprotocol/sdk/server/streamableHttp.js");
+const nestjs_cls_1 = require("nestjs-cls");
+const user_modules_repository_1 = require("../../agents/graph/repositories/user-modules.repository");
+const oauth_token_guard_1 = require("../../foundations/oauth/guards/oauth.token.guard");
+const mcp_auth_filter_1 = require("../filters/mcp.auth.filter");
+const mcp_server_factory_1 = require("../services/mcp.server.factory");
+/**
+ * MCP (Model Context Protocol) endpoint — stateless Streamable HTTP.
+ *
+ * Each `POST /mcp` request is authenticated by the existing OAuthTokenGuard
+ * (which populates CLS `userId`/`companyId`), then handed to a fresh per-request
+ * MCP Server + StreamableHTTPServerTransport pair (`sessionIdGenerator:
+ * undefined` — stateless mode, no session tracking). GET/DELETE are rejected
+ * with 405: stateless servers expose no SSE notification channel and no
+ * session to terminate.
+ *
+ * Uses `@Res()` with raw reply writing (the SDK transport writes directly to
+ * `res.raw`), which opts this handler out of Nest response serialization —
+ * the MCP wire format is JSON-RPC, not JSON:API, matching how the OAuth
+ * controllers speak their own RFC-mandated wire formats.
+ */
+let McpController = class McpController {
+    constructor(factory, cls, userModules, configService) {
+        this.factory = factory;
+        this.cls = cls;
+        this.userModules = userModules;
+        this.configService = configService;
+    }
+    /** Handles one stateless MCP Streamable-HTTP request (initialize, tools/list, tools/call, ...). */
+    async handle(req, res) {
+        if (!this.configService.get("mcp")?.enabled) {
+            throw new common_1.NotFoundException();
+        }
+        const userId = this.cls.get("userId");
+        const companyId = this.cls.get("companyId");
+        const ctx = {
+            userId,
+            companyId,
+            userModuleIds: await this.userModules.findModuleIdsForUser(userId),
+        };
+        const server = this.factory.create(ctx);
+        const transport = new streamableHttp_js_1.StreamableHTTPServerTransport({ sessionIdGenerator: undefined }); // stateless
+        res.raw.on("close", () => {
+            void transport.close();
+            void server.close();
+        });
+        await server.connect(transport);
+        // Fastify has already parsed the JSON body — pass it through so the SDK
+        // does not attempt to re-read the (already consumed) request stream.
+        await transport.handleRequest(req.raw, res.raw, req.body);
+    }
+    /** Stateless server: no SSE notification stream is offered. */
+    rejectGet() {
+        throw new common_1.HttpException("Method Not Allowed", 405);
+    }
+    /** Stateless server: there is no session to terminate. */
+    rejectDelete() {
+        throw new common_1.HttpException("Method Not Allowed", 405);
+    }
+};
+exports.McpController = McpController;
+__decorate([
+    (0, common_1.Post)(),
+    __param(0, (0, common_1.Req)()),
+    __param(1, (0, common_1.Res)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object, Object]),
+    __metadata("design:returntype", Promise)
+], McpController.prototype, "handle", null);
+__decorate([
+    (0, common_1.Get)(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", void 0)
+], McpController.prototype, "rejectGet", null);
+__decorate([
+    (0, common_1.Delete)(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", void 0)
+], McpController.prototype, "rejectDelete", null);
+exports.McpController = McpController = __decorate([
+    (0, common_1.Controller)("mcp"),
+    (0, common_1.UseFilters)(mcp_auth_filter_1.McpAuthFilter),
+    (0, common_1.UseGuards)(oauth_token_guard_1.OAuthTokenGuard),
+    __metadata("design:paramtypes", [mcp_server_factory_1.McpServerFactory,
+        nestjs_cls_1.ClsService,
+        user_modules_repository_1.UserModulesRepository,
+        config_1.ConfigService])
+], McpController);
+//# sourceMappingURL=mcp.controller.js.map

package/dist/mcp/controllers/mcp.controller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.controller.js","sourceRoot":"","sources":["../../../src/mcp/controllers/mcp.controller.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAWwB;AACxB,2CAA+C;AAC/C,0FAAmG;AAEnG,2CAAwC;AACxC,qGAAgG;AAEhG,wFAAmF;AACnF,gEAA2D;AAE3D,uEAAkE;AAElE;;;;;;;;;;;;;;GAcG;AAII,IAAM,aAAa,GAAnB,MAAM,aAAa;IACxB,YACmB,OAAyB,EACzB,GAAe,EACf,WAAkC,EAClC,aAA4B;QAH5B,YAAO,GAAP,OAAO,CAAkB;QACzB,QAAG,GAAH,GAAG,CAAY;QACf,gBAAW,GAAX,WAAW,CAAuB;QAClC,kBAAa,GAAb,aAAa,CAAe;IAC5C,CAAC;IAEJ,mGAAmG;IAE7F,AAAN,KAAK,CAAC,MAAM,CAAQ,GAAmB,EAAS,GAAiB;QAC/D,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAqB,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;YAChE,MAAM,IAAI,0BAAiB,EAAE,CAAC;QAChC,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACtC,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;QAC5C,MAAM,GAAG,GAAmB;YAC1B,MAAM;YACN,SAAS;YACT,aAAa,EAAE,MAAM,IAAI,CAAC,WAAW,CAAC,oBAAoB,CAAC,MAAM,CAAC;SACnE,CAAC;QAEF,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACxC,MAAM,SAAS,GAAG,IAAI,iDAA6B,CAAC,EAAE,kBAAkB,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,YAAY;QACpG,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACvB,KAAK,SAAS,CAAC,KAAK,EAAE,CAAC;YACvB,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC;QACtB,CAAC,CAAC,CAAC;QACH,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAChC,wEAAwE;QACxE,qEAAqE;QACrE,MAAM,SAAS,CAAC,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5D,CAAC;IAED,+DAA+D;IAE/D,SAAS;QACP,MAAM,IAAI,sBAAa,CAAC,oBAAoB,EAAE,GAAG,CAAC,CAAC;IACrD,CAAC;IAED,0DAA0D;IAE1D,YAAY;QACV,MAAM,IAAI,sBAAa,CAAC,oBAAoB,EAAE,GAAG,CAAC,CAAC;IACrD,CAAC;CACF,CAAA;AA9CY,sCAAa;AAUlB;IADL,IAAA,aAAI,GAAE;IACO,WAAA,IAAA,YAAG,GAAE,CAAA;IAAuB,WAAA,IAAA,YAAG,GAAE,CAAA;;;;2CAuB9C;AAID;IADC,IAAA,YAAG,GAAE;;;;8CAGL;AAID;IADC,IAAA,eAAM,GAAE;;;;iDAGR;wBA7CU,aAAa;IAHzB,IAAA,mBAAU,EAAC,KAAK,CAAC;IACjB,IAAA,mBAAU,EAAC,+BAAa,CAAC;IACzB,IAAA,kBAAS,EAAC,mCAAe,CAAC;qCAGG,qCAAgB;QACpB,uBAAU;QACF,+CAAqB;QACnB,sBAAa;GALpC,aAAa,CA8CzB"}

package/dist/mcp/filters/mcp.auth.filter.d.ts

@@ -0,0 +1,21 @@
+import { ArgumentsHost, HttpException } from "@nestjs/common";
+import { ConfigService } from "@nestjs/config";
+import { HttpExceptionFilter } from "../../common/filters/http-exception.filter";
+import { AppLoggingService } from "../../core/logging/services/logging.service";
+/**
+ * MCP-scoped exception filter.
+ *
+ * RFC 9728 requires 401 responses from a protected resource to carry a
+ * `WWW-Authenticate` header pointing at the protected-resource metadata so MCP
+ * clients can discover the authorization server. On 401 this filter sets that
+ * header, then delegates the JSON error body to the library's standard
+ * HttpExceptionFilter; every other HttpException is handled identically to the
+ * global filter (non-HttpException errors fall through to the global filter
+ * because of the `@Catch(HttpException)` scope).
+ */
+export declare class McpAuthFilter extends HttpExceptionFilter {
+    private readonly configService;
+    constructor(configService: ConfigService, logger?: AppLoggingService);
+    catch(exception: HttpException, host: ArgumentsHost): void;
+}
+//# sourceMappingURL=mcp.auth.filter.d.ts.map

package/dist/mcp/filters/mcp.auth.filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.auth.filter.d.ts","sourceRoot":"","sources":["../../../src/mcp/filters/mcp.auth.filter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAS,aAAa,EAAY,MAAM,gBAAgB,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,4CAA4C,CAAC;AACjF,OAAO,EAAE,iBAAiB,EAAE,MAAM,6CAA6C,CAAC;AAEhF;;;;;;;;;;GAUG;AACH,qBACa,aAAc,SAAQ,mBAAmB;IAElD,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAAb,aAAa,EAAE,aAAa,EACjC,MAAM,CAAC,EAAE,iBAAiB;IAKxC,KAAK,CAAC,SAAS,EAAE,aAAa,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI;CAQ3D"}

package/dist/mcp/filters/mcp.auth.filter.js

@@ -0,0 +1,52 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpAuthFilter = void 0;
+const common_1 = require("@nestjs/common");
+const config_1 = require("@nestjs/config");
+const http_exception_filter_1 = require("../../common/filters/http-exception.filter");
+const logging_service_1 = require("../../core/logging/services/logging.service");
+/**
+ * MCP-scoped exception filter.
+ *
+ * RFC 9728 requires 401 responses from a protected resource to carry a
+ * `WWW-Authenticate` header pointing at the protected-resource metadata so MCP
+ * clients can discover the authorization server. On 401 this filter sets that
+ * header, then delegates the JSON error body to the library's standard
+ * HttpExceptionFilter; every other HttpException is handled identically to the
+ * global filter (non-HttpException errors fall through to the global filter
+ * because of the `@Catch(HttpException)` scope).
+ */
+let McpAuthFilter = class McpAuthFilter extends http_exception_filter_1.HttpExceptionFilter {
+    constructor(configService, logger) {
+        super(logger);
+        this.configService = configService;
+    }
+    catch(exception, host) {
+        if (exception.getStatus() === 401) {
+            const reply = host.switchToHttp().getResponse();
+            const base = (this.configService.get("api")?.url ?? "").replace(/\/$/, "");
+            reply.header("WWW-Authenticate", `Bearer resource_metadata="${base}/.well-known/oauth-protected-resource"`);
+        }
+        super.catch(exception, host);
+    }
+};
+exports.McpAuthFilter = McpAuthFilter;
+exports.McpAuthFilter = McpAuthFilter = __decorate([
+    (0, common_1.Catch)(common_1.HttpException),
+    __param(1, (0, common_1.Optional)()),
+    __metadata("design:paramtypes", [config_1.ConfigService,
+        logging_service_1.AppLoggingService])
+], McpAuthFilter);
+//# sourceMappingURL=mcp.auth.filter.js.map

package/dist/mcp/filters/mcp.auth.filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.auth.filter.js","sourceRoot":"","sources":["../../../src/mcp/filters/mcp.auth.filter.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAA+E;AAC/E,2CAA+C;AAE/C,sFAAiF;AACjF,iFAAgF;AAEhF;;;;;;;;;;GAUG;AAEI,IAAM,aAAa,GAAnB,MAAM,aAAc,SAAQ,2CAAmB;IACpD,YACmB,aAA4B,EACjC,MAA0B;QAEtC,KAAK,CAAC,MAAM,CAAC,CAAC;QAHG,kBAAa,GAAb,aAAa,CAAe;IAI/C,CAAC;IAED,KAAK,CAAC,SAAwB,EAAE,IAAmB;QACjD,IAAI,SAAS,CAAC,SAAS,EAAE,KAAK,GAAG,EAAE,CAAC;YAClC,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,EAAE,CAAC,WAAW,EAAgB,CAAC;YAC9D,MAAM,IAAI,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,GAAG,CAAkB,KAAK,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YAC5F,KAAK,CAAC,MAAM,CAAC,kBAAkB,EAAE,6BAA6B,IAAI,wCAAwC,CAAC,CAAC;QAC9G,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC/B,CAAC;CACF,CAAA;AAhBY,sCAAa;wBAAb,aAAa;IADzB,IAAA,cAAK,EAAC,sBAAa,CAAC;IAIhB,WAAA,IAAA,iBAAQ,GAAE,CAAA;qCADqB,sBAAa;QACxB,mCAAiB;GAH7B,aAAa,CAgBzB"}

package/dist/mcp/index.d.ts

@@ -0,0 +1,4 @@
+export { McpModule } from "./mcp.module";
+export { MCP_TOOLS } from "./interfaces/mcp.tool.interface";
+export type { McpToolContribution, McpToolDefinition, McpToolResult, McpUserContext, } from "./interfaces/mcp.tool.interface";
+//# sourceMappingURL=index.d.ts.map

package/dist/mcp/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAGzC,OAAO,EAAE,SAAS,EAAE,MAAM,iCAAiC,CAAC;AAC5D,YAAY,EACV,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,cAAc,GACf,MAAM,iCAAiC,CAAC"}

package/dist/mcp/index.js

@@ -0,0 +1,11 @@
+"use strict";
+// MCP (Model Context Protocol) server — public entry point.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCP_TOOLS = exports.McpModule = void 0;
+// Module (mounted via BootstrapOptions.mcp === true)
+var mcp_module_1 = require("./mcp.module");
+Object.defineProperty(exports, "McpModule", { enumerable: true, get: function () { return mcp_module_1.McpModule; } });
+// App-contribution surface: register McpToolContribution factories under MCP_TOOLS.
+var mcp_tool_interface_1 = require("./interfaces/mcp.tool.interface");
+Object.defineProperty(exports, "MCP_TOOLS", { enumerable: true, get: function () { return mcp_tool_interface_1.MCP_TOOLS; } });
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":";AAAA,4DAA4D;;;AAE5D,qDAAqD;AACrD,2CAAyC;AAAhC,uGAAA,SAAS,OAAA;AAElB,oFAAoF;AACpF,sEAA4D;AAAnD,+GAAA,SAAS,OAAA"}

package/dist/mcp/interfaces/mcp.tool.interface.d.ts

@@ -0,0 +1,37 @@
+/** Per-request user context every MCP tool executes with (company scoping + RBAC module visibility). */
+export interface McpUserContext {
+    userId: string;
+    companyId: string;
+    userModuleIds: string[];
+}
+/** MCP tool-call result: text content blocks, with `isError` set on failures. */
+export interface McpToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}
+/**
+ * A single MCP tool as exposed over tools/list + tools/call.
+ * `inputSchema` is JSON Schema (draft 2020-12); `readOnly` maps to `annotations.readOnlyHint`.
+ */
+export interface McpToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    readOnly: boolean;
+    execute(input: Record<string, unknown>, ctx: McpUserContext): Promise<McpToolResult>;
+}
+/**
+ * Factory contract for app-contributed MCP tools.
+ * Built once per request — like the built-ins — so contributed tools can
+ * apply company scoping and RBAC filtering from the request context.
+ */
+export interface McpToolContribution {
+    /** Called once per MCP request with the authenticated user context. */
+    build(ctx: McpUserContext): McpToolDefinition[];
+}
+/** Multi-provider DI token: consuming apps contribute McpToolContribution factories. */
+export declare const MCP_TOOLS: unique symbol;
+//# sourceMappingURL=mcp.tool.interface.d.ts.map

package/dist/mcp/interfaces/mcp.tool.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.tool.interface.d.ts","sourceRoot":"","sources":["../../../src/mcp/interfaces/mcp.tool.interface.ts"],"names":[],"mappings":"AAAA,wGAAwG;AACxG,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,QAAQ,EAAE,OAAO,CAAC;IAClB,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACtF;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,uEAAuE;IACvE,KAAK,CAAC,GAAG,EAAE,cAAc,GAAG,iBAAiB,EAAE,CAAC;CACjD;AAED,wFAAwF;AACxF,eAAO,MAAM,SAAS,eAAsB,CAAC"}

package/dist/mcp/interfaces/mcp.tool.interface.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCP_TOOLS = void 0;
+/** Multi-provider DI token: consuming apps contribute McpToolContribution factories. */
+exports.MCP_TOOLS = Symbol("MCP_TOOLS");
+//# sourceMappingURL=mcp.tool.interface.js.map

package/dist/mcp/interfaces/mcp.tool.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.tool.interface.js","sourceRoot":"","sources":["../../../src/mcp/interfaces/mcp.tool.interface.ts"],"names":[],"mappings":";;;AAmCA,wFAAwF;AAC3E,QAAA,SAAS,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC"}

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

@@ -0,0 +1,23 @@
+/**
+ * MCP (Model Context Protocol) server module.
+ *
+ * Mounted by the bootstrap gate (`BootstrapOptions.mcp === true`) and served
+ * at `POST /mcp`, OAuth-authenticated and RBAC-gated. Exports McpToolRegistry
+ * so consuming apps can contribute additional tools via the MCP_TOOLS token.
+ *
+ * Module wiring notes:
+ * - `RbacPermissionModule` supplies RbacPermissionService (the RbacModule
+ *   proper is a config-requiring dynamic module and cannot be imported here).
+ * - Audit is NOT wired here: AbstractService.create/put audits internally when
+ *   the concrete entity service injects AuditService, so MCP writes audit
+ *   exactly like HTTP writes.
+ * - `SearchDocumentsTool` is provided locally: OperatorModule declares but
+ *   does not export it, and importing OperatorModule would drag in its
+ *   forwardRef(AssistantModule) cycle. Its dependencies (ToolFactory,
+ *   ContextualiserService) are exported by AgentsModule's inner modules.
+ * - EntityServiceRegistry, Neo4jService, ClsService and ConfigService resolve
+ *   through the global core/cls/config modules.
+ */
+export declare class McpModule {
+}
+//# sourceMappingURL=mcp.module.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.module.d.ts","sourceRoot":"","sources":["../../src/mcp/mcp.module.ts"],"names":[],"mappings":"AAYA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAaa,SAAS;CAAG"}

package/dist/mcp/mcp.module.js

@@ -0,0 +1,59 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpModule = void 0;
+const common_1 = require("@nestjs/common");
+const agents_modules_1 = require("../agents/agents.modules");
+const search_documents_tool_1 = require("../agents/operator/tools/search-documents.tool");
+const oauth_module_1 = require("../foundations/oauth/oauth.module");
+const rbac_permission_module_1 = require("../foundations/rbac/rbac-permission.module");
+const mcp_controller_1 = require("./controllers/mcp.controller");
+const mcp_entity_write_service_1 = require("./services/mcp.entity.write.service");
+const mcp_generic_tools_service_1 = require("./services/mcp.generic.tools.service");
+const mcp_promoted_tools_factory_1 = require("./services/mcp.promoted.tools.factory");
+const mcp_server_factory_1 = require("./services/mcp.server.factory");
+const mcp_tool_registry_1 = require("./services/mcp.tool.registry");
+/**
+ * MCP (Model Context Protocol) server module.
+ *
+ * Mounted by the bootstrap gate (`BootstrapOptions.mcp === true`) and served
+ * at `POST /mcp`, OAuth-authenticated and RBAC-gated. Exports McpToolRegistry
+ * so consuming apps can contribute additional tools via the MCP_TOOLS token.
+ *
+ * Module wiring notes:
+ * - `RbacPermissionModule` supplies RbacPermissionService (the RbacModule
+ *   proper is a config-requiring dynamic module and cannot be imported here).
+ * - Audit is NOT wired here: AbstractService.create/put audits internally when
+ *   the concrete entity service injects AuditService, so MCP writes audit
+ *   exactly like HTTP writes.
+ * - `SearchDocumentsTool` is provided locally: OperatorModule declares but
+ *   does not export it, and importing OperatorModule would drag in its
+ *   forwardRef(AssistantModule) cycle. Its dependencies (ToolFactory,
+ *   ContextualiserService) are exported by AgentsModule's inner modules.
+ * - EntityServiceRegistry, Neo4jService, ClsService and ConfigService resolve
+ *   through the global core/cls/config modules.
+ */
+let McpModule = class McpModule {
+};
+exports.McpModule = McpModule;
+exports.McpModule = McpModule = __decorate([
+    (0, common_1.Module)({
+        imports: [oauth_module_1.OAuthModule, rbac_permission_module_1.RbacPermissionModule, agents_modules_1.AgentsModule],
+        controllers: [mcp_controller_1.McpController],
+        providers: [
+            mcp_server_factory_1.McpServerFactory,
+            mcp_tool_registry_1.McpToolRegistry,
+            mcp_generic_tools_service_1.McpGenericToolsService,
+            mcp_entity_write_service_1.McpEntityWriteService,
+            mcp_promoted_tools_factory_1.McpPromotedToolsFactory,
+            search_documents_tool_1.SearchDocumentsTool,
+        ],
+        exports: [mcp_tool_registry_1.McpToolRegistry],
+    })
+], McpModule);
+//# sourceMappingURL=mcp.module.js.map

package/dist/mcp/mcp.module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.module.js","sourceRoot":"","sources":["../../src/mcp/mcp.module.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAAwC;AACxC,6DAAwD;AACxD,0FAAqF;AACrF,oEAAgE;AAChE,uFAAkF;AAClF,iEAA6D;AAC7D,kFAA4E;AAC5E,oFAA8E;AAC9E,sFAAgF;AAChF,sEAAiE;AACjE,oEAA+D;AAE/D;;;;;;;;;;;;;;;;;;;GAmBG;AAcI,IAAM,SAAS,GAAf,MAAM,SAAS;CAAG,CAAA;AAAZ,8BAAS;oBAAT,SAAS;IAbrB,IAAA,eAAM,EAAC;QACN,OAAO,EAAE,CAAC,0BAAW,EAAE,6CAAoB,EAAE,6BAAY,CAAC;QAC1D,WAAW,EAAE,CAAC,8BAAa,CAAC;QAC5B,SAAS,EAAE;YACT,qCAAgB;YAChB,mCAAe;YACf,kDAAsB;YACtB,gDAAqB;YACrB,oDAAuB;YACvB,2CAAmB;SACpB;QACD,OAAO,EAAE,CAAC,mCAAe,CAAC;KAC3B,CAAC;GACW,SAAS,CAAG"}

package/dist/mcp/services/mcp.entity.write.service.d.ts

@@ -0,0 +1,79 @@
+import { GraphCatalogService } from "../../agents/graph/services/graph.catalog.service";
+import { EntityServiceRegistry } from "../../common/registries/entity.service.registry";
+import { RbacPermissionService } from "../../foundations/rbac/services/rbac-permission.service";
+import type { McpToolDefinition, McpToolResult, McpUserContext } from "../interfaces/mcp.tool.interface";
+/**
+ * MCP write executors (C4): create/update entities and add/remove to-many
+ * relationship items for any JSON:API type registered in EntityServiceRegistry.
+ *
+ * Every write is gated by the catalog (type visible to the user's modules) and
+ * RBAC (`create`/`update` permission on the entity's module), dispatched through
+ * the framework's `AbstractService.*FromDTO` path (never hand-built JSON:API
+ * beyond the `JsonApiDTOData` framework type). Audit is NOT performed here:
+ * `AbstractService.create/put` audits internally when the concrete entity
+ * service injects AuditService, so MCP writes audit exactly like HTTP writes.
+ */
+export declare class McpEntityWriteService {
+    private readonly registry;
+    private readonly catalog;
+    private readonly rbac;
+    constructor(registry: EntityServiceRegistry, catalog: GraphCatalogService, rbac: RbacPermissionService);
+    /**
+     * The four write McpToolDefinitions (all `readOnly: false`) with hand-written
+     * JSON Schemas matching the C4 method params. Consumed by McpGenericToolsService.
+     */
+    buildTools(_ctx: McpUserContext): McpToolDefinition[];
+    /** Create a new entity of the given type. RBAC action: `create`. */
+    createEntity(params: {
+        type: string;
+        attributes: Record<string, unknown>;
+        relationships?: Record<string, {
+            data: Array<{
+                type: string;
+                id: string;
+            }>;
+        }>;
+    }, ctx: McpUserContext): Promise<McpToolResult>;
+    /**
+     * Update an existing entity. RBAC action: `update`.
+     *
+     * PATCH semantics via `patchFromDTO` — only the provided attributes change.
+     * Deliberately NOT `putFromDTO`: the framework's PUT maps every descriptor
+     * relationship and treats the ones absent from the DTO as "delete all
+     * edges". The HTTP path is safe because the frontend model always sends the
+     * complete relationship set on PUT, but an MCP caller sends attributes only —
+     * a PUT here would silently strip every mutable relationship off the record.
+     */
+    updateEntity(params: {
+        type: string;
+        id: string;
+        attributes: Record<string, unknown>;
+    }, ctx: McpUserContext): Promise<McpToolResult>;
+    /** Add items to a to-many relationship. RBAC action: `update`. */
+    addRelationship(params: {
+        type: string;
+        id: string;
+        relationship: string;
+        relatedType: string;
+        relatedIds: string[];
+    }, ctx: McpUserContext): Promise<McpToolResult>;
+    /** Remove items from a to-many relationship. RBAC action: `update`. */
+    removeRelationship(params: {
+        type: string;
+        id: string;
+        relationship: string;
+        relatedType: string;
+        relatedIds: string[];
+    }, ctx: McpUserContext): Promise<McpToolResult>;
+    /**
+     * Shared gate: catalog visibility (unknown_type), RBAC (forbidden), and
+     * service registration (unknown_type).
+     */
+    private gate;
+    /**
+     * Rejects attribute keys that are not in the entity's catalog field list.
+     * Catalog fields are a CatalogField[] array — keys are the `name` property.
+     */
+    private unknownAttributes;
+}
+//# sourceMappingURL=mcp.entity.write.service.d.ts.map

package/dist/mcp/services/mcp.entity.write.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.entity.write.service.d.ts","sourceRoot":"","sources":["../../../src/mcp/services/mcp.entity.write.service.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,mBAAmB,EAAE,MAAM,mDAAmD,CAAC;AACxF,OAAO,EAAE,qBAAqB,EAAE,MAAM,iDAAiD,CAAC;AAExF,OAAO,EAAE,qBAAqB,EAAE,MAAM,yDAAyD,CAAC;AAChG,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAMzG;;;;;;;;;;GAUG;AACH,qBACa,qBAAqB;IAE9B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAFJ,QAAQ,EAAE,qBAAqB,EAC/B,OAAO,EAAE,mBAAmB,EAC5B,IAAI,EAAE,qBAAqB;IAG9C;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,cAAc,GAAG,iBAAiB,EAAE;IAsHrD,oEAAoE;IAC9D,YAAY,CAChB,MAAM,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,IAAI,EAAE,KAAK,CAAC;gBAAE,IAAI,EAAE,MAAM,CAAC;gBAAC,EAAE,EAAE,MAAM,CAAA;aAAE,CAAC,CAAA;SAAE,CAAC,CAAC;KAC/E,EACD,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,aAAa,CAAC;IAoBzB;;;;;;;;;OASG;IACG,YAAY,CAChB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,EACzE,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,aAAa,CAAC;IAiBzB,kEAAkE;IAC5D,eAAe,CACnB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,EACrG,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,aAAa,CAAC;IAiBzB,uEAAuE;IACjE,kBAAkB,CACtB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,EAAE,CAAA;KAAE,EACrG,GAAG,EAAE,cAAc,GAClB,OAAO,CAAC,aAAa,CAAC;IAiBzB;;;OAGG;YACW,IAAI;IA0BlB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;CAW1B"}