@carlonicora/nestjs-neo4jsonapi 1.110.3 → 1.112.0

package/dist/mcp/services/mcp.generic.tools.service.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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpGenericToolsService = void 0;
+const common_1 = require("@nestjs/common");
+const zod_1 = require("zod");
+const describe_entity_tool_1 = require("../../agents/graph/tools/describe-entity.tool");
+const read_entity_tool_1 = require("../../agents/graph/tools/read-entity.tool");
+const resolve_entity_tool_1 = require("../../agents/graph/tools/resolve-entity.tool");
+const search_entities_tool_1 = require("../../agents/graph/tools/search-entities.tool");
+const traverse_tool_1 = require("../../agents/graph/tools/traverse.tool");
+const search_documents_tool_1 = require("../../agents/operator/tools/search-documents.tool");
+const mcp_errors_1 = require("./mcp.errors");
+const mcp_entity_write_service_1 = require("./mcp.entity.write.service");
+// Descriptions copied verbatim from each tool's build() (single source is the
+// DynamicStructuredTool literal in the tool file; not exportable without
+// restructuring those files beyond the schema-export-only change).
+const DESCRIBE_DESCRIPTION = "Returns the described fields and relationships for an entity type.";
+const RESOLVE_DESCRIPTION = "Resolve a user-named entity across every visible type. Returns ranked candidates from the highest-confidence tier that yielded any match anywhere. Use this before search_entities / read_entity / traverse whenever the user refers to a named record.";
+const SEARCH_DESCRIPTION = "Find records of a known type by filter and sort. Use this when you already have the type (from resolve_entity or because the user referred to a kind of record without identifying a specific one). To look up a specific record by its label, call resolve_entity first.";
+const READ_DESCRIPTION = "Fetches one record by id, optionally pulling related records across described relationships.";
+const TRAVERSE_DESCRIPTION = "Walks a relationship from a known record to related records, optionally filtered and sorted.";
+const SEARCH_DOCS_DESCRIPTION = "Search the company's documents (GraphRAG) for information relevant to a question. Returns the retrieved passages, each prefixed by its chunkId.";
+/**
+ * Builds the generic MCP tool set for one authenticated request:
+ * the five graph read tools, the document-retrieval tool, and the four
+ * entity write tools contributed by McpEntityWriteService.
+ */
+let McpGenericToolsService = class McpGenericToolsService {
+    constructor(resolveEntityTool, describeEntityTool, searchEntitiesTool, readEntityTool, traverseTool, searchDocumentsTool, writeService) {
+        this.resolveEntityTool = resolveEntityTool;
+        this.describeEntityTool = describeEntityTool;
+        this.searchEntitiesTool = searchEntitiesTool;
+        this.readEntityTool = readEntityTool;
+        this.traverseTool = traverseTool;
+        this.searchDocumentsTool = searchDocumentsTool;
+        this.writeService = writeService;
+    }
+    /** Builds the per-request generic tool definitions (read tools + write tools). */
+    build(ctx) {
+        const recorder = [];
+        // The graph tools enforce a describe-first contract via the recorder. That
+        // works in the operator, where one recorder spans a whole LangGraph turn —
+        // but MCP is stateless: every tools/call gets a fresh recorder, so a prior
+        // describe_entity call can never be seen and the contract would loop
+        // forever. Seed the recorder with the requested type instead (same
+        // approach as McpPromotedToolsFactory); the schema stays discoverable
+        // through the describe_entity MCP tool itself.
+        const seedDescribe = (type) => {
+            if (typeof type === "string" && type.length > 0) {
+                recorder.push({ tool: "describe_entity", input: { type }, durationMs: 0 });
+            }
+        };
+        const read = (name, description, schema, invoke, seedType) => ({
+            name,
+            description,
+            inputSchema: zod_1.z.toJSONSchema(schema),
+            readOnly: true,
+            execute: async (input) => {
+                try {
+                    const parsed = schema.parse(input);
+                    if (seedType)
+                        seedDescribe(seedType(parsed));
+                    const result = await invoke(parsed);
+                    return {
+                        content: [{ type: "text", text: typeof result === "string" ? result : JSON.stringify(result) }],
+                    };
+                }
+                catch (e) {
+                    return (0, mcp_errors_1.mcpError)(e);
+                }
+            },
+        });
+        return [
+            read("describe_entity", DESCRIBE_DESCRIPTION, describe_entity_tool_1.describeEntityInputSchema, (i) => this.describeEntityTool.invoke(i, ctx, recorder)),
+            read("resolve_entity", RESOLVE_DESCRIPTION, resolve_entity_tool_1.resolveEntityInputSchema, (i) => this.resolveEntityTool.invoke(i, ctx, recorder)),
+            read("search_entities", SEARCH_DESCRIPTION, search_entities_tool_1.searchEntitiesInputSchema, (i) => this.searchEntitiesTool.invoke(i, ctx, recorder), (parsed) => parsed.type),
+            read("read_entity", READ_DESCRIPTION, read_entity_tool_1.readEntityInputSchema, (i) => this.readEntityTool.invoke(i, ctx, recorder), (parsed) => parsed.type),
+            read("traverse", TRAVERSE_DESCRIPTION, traverse_tool_1.traverseInputSchema, (i) => this.traverseTool.invoke(i, ctx, recorder), (parsed) => parsed.fromType),
+            read("search_documents", SEARCH_DOCS_DESCRIPTION, search_documents_tool_1.searchDocumentsInputSchema, (i) => 
+            // SearchDocumentsTool needs an OperatorRetrievalContext; MCP has no
+            // conversation, so dataLimits defaults to {} (all fields optional)
+            // and messages to [] — the documented fallback.
+            this.searchDocumentsTool.invoke(i, { ...ctx, dataLimits: {}, messages: [] }, recorder)),
+            ...this.writeService.buildTools(ctx),
+        ];
+    }
+};
+exports.McpGenericToolsService = McpGenericToolsService;
+exports.McpGenericToolsService = McpGenericToolsService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [resolve_entity_tool_1.ResolveEntityTool,
+        describe_entity_tool_1.DescribeEntityTool,
+        search_entities_tool_1.SearchEntitiesTool,
+        read_entity_tool_1.ReadEntityTool,
+        traverse_tool_1.TraverseTool,
+        search_documents_tool_1.SearchDocumentsTool,
+        mcp_entity_write_service_1.McpEntityWriteService])
+], McpGenericToolsService);
+//# sourceMappingURL=mcp.generic.tools.service.js.map

package/dist/mcp/services/mcp.generic.tools.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.generic.tools.service.js","sourceRoot":"","sources":["../../../src/mcp/services/mcp.generic.tools.service.ts"],"names":[],"mappings":"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"}

package/dist/mcp/services/mcp.promoted.tools.factory.d.ts

@@ -0,0 +1,58 @@
+import { ConfigService } from "@nestjs/config";
+import { GraphCatalogService } from "../../agents/graph/services/graph.catalog.service";
+import { ReadEntityTool } from "../../agents/graph/tools/read-entity.tool";
+import { SearchEntitiesTool } from "../../agents/graph/tools/search-entities.tool";
+import type { McpToolDefinition, McpUserContext } from "../interfaces/mcp.tool.interface";
+import { McpEntityWriteService } from "./mcp.entity.write.service";
+/**
+ * Maps an entity-descriptor field (as exposed by the graph catalog) to a JSON
+ * Schema property for MCP tool input schemas.
+ *
+ * Date and datetime fields are advertised as ISO strings on the wire
+ * (`format: "date"` / `format: "date-time"`); storage stays native Neo4j
+ * `Date`/`DateTime` because writes flow through the standard
+ * `AbstractService.createFromDTO`/`putFromDTO` path, which auto-casts —
+ * no custom Cypher is involved.
+ *
+ * Unknown descriptor types fall back to `{ type: "string" }`. The field's
+ * catalog description is carried through when present.
+ */
+export declare function descriptorFieldToJsonSchema(field: {
+    type: string;
+    description?: string;
+}): Record<string, unknown>;
+/**
+ * Generates dedicated per-entity MCP tools (`search_<type>`, `get_<type>`,
+ * `create_<type>`, `update_<type>`) for every JSON:API type listed in
+ * `ConfigMcpInterface.promotedEntities`.
+ *
+ * Types the user cannot access (unknown type or module not granted) are
+ * skipped: `GraphCatalogService.getEntityDetail` returns `null` for both
+ * cases. Read tools delegate straight to the graph tool classes with the
+ * `type` pre-bound; write tools delegate to {@link McpEntityWriteService},
+ * which enforces RBAC and attribute validation.
+ */
+export declare class McpPromotedToolsFactory {
+    private readonly config;
+    private readonly catalog;
+    private readonly searchTool;
+    private readonly readTool;
+    private readonly writeService;
+    constructor(config: ConfigService, catalog: GraphCatalogService, searchTool: SearchEntitiesTool, readTool: ReadEntityTool, writeService: McpEntityWriteService);
+    /**
+     * Builds the promoted per-entity tool definitions for the given user
+     * context. Returns an empty array when no promoted entities are configured
+     * or none are accessible.
+     */
+    build(ctx: McpUserContext): McpToolDefinition[];
+    private buildSearchTool;
+    private buildGetTool;
+    private buildCreateTool;
+    private buildUpdateTool;
+    private buildAttributesSchema;
+    private buildRelationshipsSchema;
+    private entityBlurb;
+    private textResult;
+    private internalError;
+}
+//# sourceMappingURL=mcp.promoted.tools.factory.d.ts.map

package/dist/mcp/services/mcp.promoted.tools.factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.promoted.tools.factory.d.ts","sourceRoot":"","sources":["../../../src/mcp/services/mcp.promoted.tools.factory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,mDAAmD,CAAC;AACxF,OAAO,EAAE,cAAc,EAAE,MAAM,2CAA2C,CAAC;AAC3E,OAAO,EAAE,kBAAkB,EAAE,MAAM,+CAA+C,CAAC;AAGnF,OAAO,KAAK,EAAE,iBAAiB,EAAiB,cAAc,EAAE,MAAM,kCAAkC,CAAC;AACzG,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE;;;;;;;;;;;;GAYG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuBlH;AAED;;;;;;;;;;GAUG;AACH,qBACa,uBAAuB;IAEhC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,YAAY;gBAJZ,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,mBAAmB,EAC5B,UAAU,EAAE,kBAAkB,EAC9B,QAAQ,EAAE,cAAc,EACxB,YAAY,EAAE,qBAAqB;IAGtD;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,cAAc,GAAG,iBAAiB,EAAE;IAyB/C,OAAO,CAAC,eAAe;IAkCvB,OAAO,CAAC,YAAY;IA8BpB,OAAO,CAAC,eAAe;IAyBvB,OAAO,CAAC,eAAe;IAwBvB,OAAO,CAAC,qBAAqB;IAQ7B,OAAO,CAAC,wBAAwB;IAqBhC,OAAO,CAAC,WAAW;IAInB,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,aAAa;CAItB"}

package/dist/mcp/services/mcp.promoted.tools.factory.js

@@ -0,0 +1,260 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpPromotedToolsFactory = void 0;
+exports.descriptorFieldToJsonSchema = descriptorFieldToJsonSchema;
+const common_1 = require("@nestjs/common");
+const config_1 = require("@nestjs/config");
+const graph_catalog_service_1 = require("../../agents/graph/services/graph.catalog.service");
+const read_entity_tool_1 = require("../../agents/graph/tools/read-entity.tool");
+const search_entities_tool_1 = require("../../agents/graph/tools/search-entities.tool");
+const mcp_entity_write_service_1 = require("./mcp.entity.write.service");
+/**
+ * Maps an entity-descriptor field (as exposed by the graph catalog) to a JSON
+ * Schema property for MCP tool input schemas.
+ *
+ * Date and datetime fields are advertised as ISO strings on the wire
+ * (`format: "date"` / `format: "date-time"`); storage stays native Neo4j
+ * `Date`/`DateTime` because writes flow through the standard
+ * `AbstractService.createFromDTO`/`putFromDTO` path, which auto-casts —
+ * no custom Cypher is involved.
+ *
+ * Unknown descriptor types fall back to `{ type: "string" }`. The field's
+ * catalog description is carried through when present.
+ */
+function descriptorFieldToJsonSchema(field) {
+    let base;
+    switch (field.type) {
+        case "string":
+            base = { type: "string" };
+            break;
+        case "number":
+            base = { type: "number" };
+            break;
+        case "boolean":
+            base = { type: "boolean" };
+            break;
+        case "date":
+            base = { type: "string", format: "date" };
+            break;
+        case "datetime":
+            base = { type: "string", format: "date-time" };
+            break;
+        default:
+            base = { type: "string" };
+            break;
+    }
+    return field.description ? { ...base, description: field.description } : base;
+}
+/**
+ * Generates dedicated per-entity MCP tools (`search_<type>`, `get_<type>`,
+ * `create_<type>`, `update_<type>`) for every JSON:API type listed in
+ * `ConfigMcpInterface.promotedEntities`.
+ *
+ * Types the user cannot access (unknown type or module not granted) are
+ * skipped: `GraphCatalogService.getEntityDetail` returns `null` for both
+ * cases. Read tools delegate straight to the graph tool classes with the
+ * `type` pre-bound; write tools delegate to {@link McpEntityWriteService},
+ * which enforces RBAC and attribute validation.
+ */
+let McpPromotedToolsFactory = class McpPromotedToolsFactory {
+    constructor(config, catalog, searchTool, readTool, writeService) {
+        this.config = config;
+        this.catalog = catalog;
+        this.searchTool = searchTool;
+        this.readTool = readTool;
+        this.writeService = writeService;
+    }
+    /**
+     * Builds the promoted per-entity tool definitions for the given user
+     * context. Returns an empty array when no promoted entities are configured
+     * or none are accessible.
+     */
+    build(ctx) {
+        const promotedEntities = this.config.get("mcp")?.promotedEntities ?? [];
+        if (!promotedEntities.length)
+            return [];
+        // Shared per-build recorder, pre-seeded with a describe_entity record per
+        // promoted type: the graph tools refuse to run before describe_entity has
+        // been called, but promoted tools embed the schema in their own
+        // inputSchema, so the describe requirement is satisfied by construction.
+        const recorder = [];
+        const tools = [];
+        for (const type of promotedEntities) {
+            const entity = this.catalog.getEntityDetail(type, ctx.userModuleIds);
+            if (!entity)
+                continue;
+            recorder.push({ tool: "describe_entity", input: { type: entity.type }, durationMs: 0 });
+            tools.push(this.buildSearchTool(entity, ctx, recorder), this.buildGetTool(entity, ctx, recorder), this.buildCreateTool(entity, ctx), this.buildUpdateTool(entity, ctx));
+        }
+        return tools;
+    }
+    buildSearchTool(entity, ctx, recorder) {
+        const filterableFields = entity.fields.filter((f) => f.filterable).map((f) => f.name);
+        const sortableFields = entity.fields.filter((f) => f.sortable).map((f) => f.name);
+        return {
+            name: `search_${entity.type}`,
+            description: `Find ${entity.type} records by filter and sort.${this.entityBlurb(entity)}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    filters: {
+                        description: `Optional filter array: [{ field, op, value }]. Filterable fields: [${filterableFields.join(", ")}]. Operators: eq, ne, in, like (strings), gt, gte, lt, lte (numbers/dates), isNull, isNotNull.`,
+                    },
+                    sort: {
+                        description: `Optional sort array: [{ field, direction: "asc" | "desc" }]. Sortable fields: [${sortableFields.join(", ")}].`,
+                    },
+                    limit: {
+                        type: "integer",
+                        description: "Maximum number of records to return (default 10, max 50).",
+                    },
+                },
+                additionalProperties: false,
+            },
+            readOnly: true,
+            execute: async (input) => {
+                try {
+                    const result = await this.searchTool.invoke({ ...input, type: entity.type }, ctx, recorder);
+                    return this.textResult(result);
+                }
+                catch (e) {
+                    return this.internalError(e);
+                }
+            },
+        };
+    }
+    buildGetTool(entity, ctx, recorder) {
+        const relationshipNames = entity.relationships.map((r) => r.name);
+        return {
+            name: `get_${entity.type}`,
+            description: `Fetch one ${entity.type} record by id, optionally pulling one-hop related records.${this.entityBlurb(entity)}`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: `The id of the ${entity.type} record.` },
+                    include: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: `Relationship names to pull one-hop related records. Available: [${relationshipNames.join(", ")}].`,
+                    },
+                },
+                required: ["id"],
+                additionalProperties: false,
+            },
+            readOnly: true,
+            execute: async (input) => {
+                try {
+                    const result = await this.readTool.invoke({ ...input, type: entity.type }, ctx, recorder);
+                    return this.textResult(result);
+                }
+                catch (e) {
+                    return this.internalError(e);
+                }
+            },
+        };
+    }
+    buildCreateTool(entity, ctx) {
+        const relationshipNames = entity.relationships.map((r) => r.name);
+        return {
+            name: `create_${entity.type}`,
+            description: `Create a new ${entity.type} record.${this.entityBlurb(entity)} All attributes are optional in the schema; call describe_entity("${entity.type}") for field semantics.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    attributes: this.buildAttributesSchema(entity),
+                    relationships: this.buildRelationshipsSchema(relationshipNames),
+                },
+                required: ["attributes"],
+                additionalProperties: false,
+            },
+            readOnly: false,
+            execute: async (input) => {
+                try {
+                    return await this.writeService.createEntity({ ...input, type: entity.type }, ctx);
+                }
+                catch (e) {
+                    return this.internalError(e);
+                }
+            },
+        };
+    }
+    buildUpdateTool(entity, ctx) {
+        return {
+            name: `update_${entity.type}`,
+            description: `Update a ${entity.type} record by id.${this.entityBlurb(entity)} PUT semantics: replaces all attributes. Read the record first and send every field back.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    id: { type: "string", description: `The id of the ${entity.type} record to update.` },
+                    attributes: this.buildAttributesSchema(entity),
+                },
+                required: ["id", "attributes"],
+                additionalProperties: false,
+            },
+            readOnly: false,
+            execute: async (input) => {
+                try {
+                    return await this.writeService.updateEntity({ ...input, type: entity.type }, ctx);
+                }
+                catch (e) {
+                    return this.internalError(e);
+                }
+            },
+        };
+    }
+    buildAttributesSchema(entity) {
+        const properties = {};
+        for (const field of entity.fields) {
+            properties[field.name] = descriptorFieldToJsonSchema(field);
+        }
+        return { type: "object", properties, additionalProperties: false };
+    }
+    buildRelationshipsSchema(relationshipNames) {
+        return {
+            type: "object",
+            description: `Optional relationships keyed by name. Available: [${relationshipNames.join(", ")}]. Each value is { data: [{ type, id }] }.`,
+            additionalProperties: {
+                type: "object",
+                properties: {
+                    data: {
+                        type: "array",
+                        items: {
+                            type: "object",
+                            properties: { type: { type: "string" }, id: { type: "string" } },
+                            required: ["type", "id"],
+                        },
+                    },
+                },
+                required: ["data"],
+            },
+        };
+    }
+    entityBlurb(entity) {
+        return entity.description ? ` ${entity.description}.` : "";
+    }
+    textResult(result) {
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    }
+    internalError(e) {
+        const message = e instanceof Error ? e.message : "Unexpected error";
+        return { isError: true, content: [{ type: "text", text: JSON.stringify({ code: "internal", message }) }] };
+    }
+};
+exports.McpPromotedToolsFactory = McpPromotedToolsFactory;
+exports.McpPromotedToolsFactory = McpPromotedToolsFactory = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [config_1.ConfigService,
+        graph_catalog_service_1.GraphCatalogService,
+        search_entities_tool_1.SearchEntitiesTool,
+        read_entity_tool_1.ReadEntityTool,
+        mcp_entity_write_service_1.McpEntityWriteService])
+], McpPromotedToolsFactory);
+//# sourceMappingURL=mcp.promoted.tools.factory.js.map

package/dist/mcp/services/mcp.promoted.tools.factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.promoted.tools.factory.js","sourceRoot":"","sources":["../../../src/mcp/services/mcp.promoted.tools.factory.ts"],"names":[],"mappings":";;;;;;;;;;;;AAwBA,kEAuBC;AA/CD,2CAA4C;AAC5C,2CAA+C;AAE/C,6FAAwF;AACxF,gFAA2E;AAC3E,wFAAmF;AAInF,yEAAmE;AAEnE;;;;;;;;;;;;GAYG;AACH,SAAgB,2BAA2B,CAAC,KAA6C;IACvF,IAAI,IAA6B,CAAC;IAClC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC;QACnB,KAAK,QAAQ;YACX,IAAI,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;YAC1B,MAAM;QACR,KAAK,QAAQ;YACX,IAAI,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;YAC1B,MAAM;QACR,KAAK,SAAS;YACZ,IAAI,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;YAC3B,MAAM;QACR,KAAK,MAAM;YACT,IAAI,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;YAC1C,MAAM;QACR,KAAK,UAAU;YACb,IAAI,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;YAC/C,MAAM;QACR;YACE,IAAI,GAAG,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;YAC1B,MAAM;IACV,CAAC;IACD,OAAO,KAAK,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,EAAE,WAAW,EAAE,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAChF,CAAC;AAED;;;;;;;;;;GAUG;AAEI,IAAM,uBAAuB,GAA7B,MAAM,uBAAuB;IAClC,YACmB,MAAqB,EACrB,OAA4B,EAC5B,UAA8B,EAC9B,QAAwB,EACxB,YAAmC;QAJnC,WAAM,GAAN,MAAM,CAAe;QACrB,YAAO,GAAP,OAAO,CAAqB;QAC5B,eAAU,GAAV,UAAU,CAAoB;QAC9B,aAAQ,GAAR,QAAQ,CAAgB;QACxB,iBAAY,GAAZ,YAAY,CAAuB;IACnD,CAAC;IAEJ;;;;OAIG;IACH,KAAK,CAAC,GAAmB;QACvB,MAAM,gBAAgB,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAqB,KAAK,CAAC,EAAE,gBAAgB,IAAI,EAAE,CAAC;QAC5F,IAAI,CAAC,gBAAgB,CAAC,MAAM;YAAE,OAAO,EAAE,CAAC;QAExC,0EAA0E;QAC1E,0EAA0E;QAC1E,gEAAgE;QAChE,yEAAyE;QACzE,MAAM,QAAQ,GAAqB,EAAE,CAAC;QACtC,MAAM,KAAK,GAAwB,EAAE,CAAC;QAEtC,KAAK,MAAM,IAAI,IAAI,gBAAgB,EAAE,CAAC;YACpC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,IAAI,EAAE,GAAG,CAAC,aAAa,CAAC,CAAC;YACrE,IAAI,CAAC,MAAM;gBAAE,SAAS;YACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,UAAU,EAAE,CAAC,EAAE,CAAC,CAAC;YACxF,KAAK,CAAC,IAAI,CACR,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC,EAC3C,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC,EACxC,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,GAAG,CAAC,EACjC,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,GAAG,CAAC,CAClC,CAAC;QACJ,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAEO,eAAe,CAAC,MAAqB,EAAE,GAAmB,EAAE,QAA0B;QAC5F,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACtF,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAClF,OAAO;YACL,IAAI,EAAE,UAAU,MAAM,CAAC,IAAI,EAAE;YAC7B,WAAW,EAAE,QAAQ,MAAM,CAAC,IAAI,+BAA+B,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE;YACzF,WAAW,EAAE;gBACX,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,OAAO,EAAE;wBACP,WAAW,EAAE,sEAAsE,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,gGAAgG;qBAC/M;oBACD,IAAI,EAAE;wBACJ,WAAW,EAAE,kFAAkF,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;qBAC7H;oBACD,KAAK,EAAE;wBACL,IAAI,EAAE,SAAS;wBACf,WAAW,EAAE,2DAA2D;qBACzE;iBACF;gBACD,oBAAoB,EAAE,KAAK;aAC5B;YACD,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;gBACvB,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAS,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;oBACnG,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;gBACjC,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,OAAO,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;gBAC/B,CAAC;YACH,CAAC;SACF,CAAC;IACJ,CAAC;IAEO,YAAY,CAAC,MAAqB,EAAE,GAAmB,EAAE,QAA0B;QACzF,MAAM,iBAAiB,GAAG,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAClE,OAAO;YACL,IAAI,EAAE,OAAO,MAAM,CAAC,IAAI,EAAE;YAC1B,WAAW,EAAE,aAAa,MAAM,CAAC,IAAI,6DAA6D,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,EAAE;YAC5H,WAAW,EAAE;gBACX,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,iBAAiB,MAAM,CAAC,IAAI,UAAU,EAAE;oBAC3E,OAAO,EAAE;wBACP,IAAI,EAAE,OAAO;wBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;wBACzB,WAAW,EAAE,mEAAmE,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;qBACjH;iBACF;gBACD,QAAQ,EAAE,CAAC,IAAI,CAAC;gBAChB,oBAAoB,EAAE,KAAK;aAC5B;YACD,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;gBACvB,IAAI,CAAC;oBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAS,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;oBACjG,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;gBACjC,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,OAAO,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;gBAC/B,CAAC;YACH,CAAC;SACF,CAAC;IACJ,CAAC;IAEO,eAAe,CAAC,MAAqB,EAAE,GAAmB;QAChE,MAAM,iBAAiB,GAAG,MAAM,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAClE,OAAO;YACL,IAAI,EAAE,UAAU,MAAM,CAAC,IAAI,EAAE;YAC7B,WAAW,EAAE,gBAAgB,MAAM,CAAC,IAAI,WAAW,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,qEAAqE,MAAM,CAAC,IAAI,yBAAyB;YACpL,WAAW,EAAE;gBACX,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,UAAU,EAAE,IAAI,CAAC,qBAAqB,CAAC,MAAM,CAAC;oBAC9C,aAAa,EAAE,IAAI,CAAC,wBAAwB,CAAC,iBAAiB,CAAC;iBAChE;gBACD,QAAQ,EAAE,CAAC,YAAY,CAAC;gBACxB,oBAAoB,EAAE,KAAK;aAC5B;YACD,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;gBACvB,IAAI,CAAC;oBACH,OAAO,MAAM,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAS,EAAE,GAAG,CAAC,CAAC;gBAC3F,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,OAAO,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;gBAC/B,CAAC;YACH,CAAC;SACF,CAAC;IACJ,CAAC;IAEO,eAAe,CAAC,MAAqB,EAAE,GAAmB;QAChE,OAAO;YACL,IAAI,EAAE,UAAU,MAAM,CAAC,IAAI,EAAE;YAC7B,WAAW,EAAE,YAAY,MAAM,CAAC,IAAI,iBAAiB,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,2FAA2F;YACxK,WAAW,EAAE;gBACX,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,WAAW,EAAE,iBAAiB,MAAM,CAAC,IAAI,oBAAoB,EAAE;oBACrF,UAAU,EAAE,IAAI,CAAC,qBAAqB,CAAC,MAAM,CAAC;iBAC/C;gBACD,QAAQ,EAAE,CAAC,IAAI,EAAE,YAAY,CAAC;gBAC9B,oBAAoB,EAAE,KAAK;aAC5B;YACD,QAAQ,EAAE,KAAK;YACf,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE;gBACvB,IAAI,CAAC;oBACH,OAAO,MAAM,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAS,EAAE,GAAG,CAAC,CAAC;gBAC3F,CAAC;gBAAC,OAAO,CAAC,EAAE,CAAC;oBACX,OAAO,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;gBAC/B,CAAC;YACH,CAAC;SACF,CAAC;IACJ,CAAC;IAEO,qBAAqB,CAAC,MAAqB;QACjD,MAAM,UAAU,GAA4B,EAAE,CAAC;QAC/C,KAAK,MAAM,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAClC,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,2BAA2B,CAAC,KAAK,CAAC,CAAC;QAC9D,CAAC;QACD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,UAAU,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAAC;IACrE,CAAC;IAEO,wBAAwB,CAAC,iBAA2B;QAC1D,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,qDAAqD,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,4CAA4C;YAC1I,oBAAoB,EAAE;gBACpB,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE;oBACV,IAAI,EAAE;wBACJ,IAAI,EAAE,OAAO;wBACb,KAAK,EAAE;4BACL,IAAI,EAAE,QAAQ;4BACd,UAAU,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;4BAChE,QAAQ,EAAE,CAAC,MAAM,EAAE,IAAI,CAAC;yBACzB;qBACF;iBACF;gBACD,QAAQ,EAAE,CAAC,MAAM,CAAC;aACnB;SACF,CAAC;IACJ,CAAC;IAEO,WAAW,CAAC,MAAqB;QACvC,OAAO,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,WAAW,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7D,CAAC;IAEO,UAAU,CAAC,MAAe;QAChC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,CAAC;IACvE,CAAC;IAEO,aAAa,CAAC,CAAU;QAC9B,MAAM,OAAO,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,kBAAkB,CAAC;QACpE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;IAC7G,CAAC;CACF,CAAA;AAjMY,0DAAuB;kCAAvB,uBAAuB;IADnC,IAAA,mBAAU,GAAE;qCAGgB,sBAAa;QACZ,2CAAmB;QAChB,yCAAkB;QACpB,iCAAc;QACV,gDAAqB;GAN3C,uBAAuB,CAiMnC"}

package/dist/mcp/services/mcp.server.factory.d.ts

@@ -0,0 +1,24 @@
+import { ConfigService } from "@nestjs/config";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { McpUserContext } from "../interfaces/mcp.tool.interface";
+import { McpToolRegistry } from "./mcp.tool.registry";
+/**
+ * Builds a per-request, stateless MCP protocol server.
+ *
+ * Uses the SDK's low-level `Server` (NOT `McpServer`) so tool input schemas
+ * stay plain JSON Schema objects produced by the tool layer. Each authenticated
+ * request gets its own Server instance bound to that user's context, so
+ * tools/list and tools/call are always RBAC-filtered through McpToolRegistry.
+ */
+export declare class McpServerFactory {
+    private readonly configService;
+    private readonly registry;
+    constructor(configService: ConfigService, registry: McpToolRegistry);
+    /**
+     * Creates a stateless MCP Server for one authenticated request.
+     * Registers tools/list (with `annotations.readOnlyHint` derived from each
+     * tool's `readOnly` flag) and tools/call (dispatched through the registry).
+     */
+    create(ctx: McpUserContext): Server;
+}
+//# sourceMappingURL=mcp.server.factory.d.ts.map

package/dist/mcp/services/mcp.server.factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.server.factory.d.ts","sourceRoot":"","sources":["../../../src/mcp/services/mcp.server.factory.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAGnE,OAAO,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;;;;GAOG;AACH,qBACa,gBAAgB;IAEzB,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBADR,aAAa,EAAE,aAAa,EAC5B,QAAQ,EAAE,eAAe;IAG5C;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,cAAc,GAAG,MAAM;CA2BpC"}

package/dist/mcp/services/mcp.server.factory.js

@@ -0,0 +1,60 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpServerFactory = void 0;
+const common_1 = require("@nestjs/common");
+const config_1 = require("@nestjs/config");
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const mcp_tool_registry_1 = require("./mcp.tool.registry");
+/**
+ * Builds a per-request, stateless MCP protocol server.
+ *
+ * Uses the SDK's low-level `Server` (NOT `McpServer`) so tool input schemas
+ * stay plain JSON Schema objects produced by the tool layer. Each authenticated
+ * request gets its own Server instance bound to that user's context, so
+ * tools/list and tools/call are always RBAC-filtered through McpToolRegistry.
+ */
+let McpServerFactory = class McpServerFactory {
+    constructor(configService, registry) {
+        this.configService = configService;
+        this.registry = registry;
+    }
+    /**
+     * Creates a stateless MCP Server for one authenticated request.
+     * Registers tools/list (with `annotations.readOnlyHint` derived from each
+     * tool's `readOnly` flag) and tools/call (dispatched through the registry).
+     */
+    create(ctx) {
+        const mcp = this.configService.get("mcp");
+        const server = new index_js_1.Server({ name: mcp?.serverName ?? "neural-erp", version: "1.0.0" }, { capabilities: { tools: {} }, instructions: mcp?.instructions });
+        server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+            tools: this.registry.build(ctx).map((tool) => ({
+                name: tool.name,
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+                annotations: { readOnlyHint: tool.readOnly },
+            })),
+        }));
+        server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+            const result = await this.registry.call(request.params.name, (request.params.arguments ?? {}), ctx);
+            return { content: result.content, ...(result.isError !== undefined ? { isError: result.isError } : {}) };
+        });
+        return server;
+    }
+};
+exports.McpServerFactory = McpServerFactory;
+exports.McpServerFactory = McpServerFactory = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [config_1.ConfigService,
+        mcp_tool_registry_1.McpToolRegistry])
+], McpServerFactory);
+//# sourceMappingURL=mcp.server.factory.js.map

package/dist/mcp/services/mcp.server.factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.server.factory.js","sourceRoot":"","sources":["../../../src/mcp/services/mcp.server.factory.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAA4C;AAC5C,2CAA+C;AAC/C,wEAAmE;AACnE,iEAAmH;AAGnH,2DAAsD;AAEtD;;;;;;;GAOG;AAEI,IAAM,gBAAgB,GAAtB,MAAM,gBAAgB;IAC3B,YACmB,aAA4B,EAC5B,QAAyB;QADzB,kBAAa,GAAb,aAAa,CAAe;QAC5B,aAAQ,GAAR,QAAQ,CAAiB;IACzC,CAAC;IAEJ;;;;OAIG;IACH,MAAM,CAAC,GAAmB;QACxB,MAAM,GAAG,GAAG,IAAI,CAAC,aAAa,CAAC,GAAG,CAAqB,KAAK,CAAC,CAAC;QAC9D,MAAM,MAAM,GAAG,IAAI,iBAAM,CACvB,EAAE,IAAI,EAAE,GAAG,EAAE,UAAU,IAAI,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,EAC3D,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,YAAY,EAAE,GAAG,EAAE,YAAY,EAAE,CACjE,CAAC;QAEF,MAAM,CAAC,iBAAiB,CAAC,iCAAsB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;YAC5D,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBAC7C,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,WAAW,EAAE,IAAI,CAAC,WAAW;gBAC7B,WAAW,EAAE,IAAI,CAAC,WAAyD;gBAC3E,WAAW,EAAE,EAAE,YAAY,EAAE,IAAI,CAAC,QAAQ,EAAE;aAC7C,CAAC,CAAC;SACJ,CAAC,CAAC,CAAC;QAEJ,MAAM,CAAC,iBAAiB,CAAC,gCAAqB,EAAE,KAAK,EAAE,OAAO,EAA2B,EAAE;YACzF,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CACrC,OAAO,CAAC,MAAM,CAAC,IAAI,EACnB,CAAC,OAAO,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAA4B,EAC3D,GAAG,CACJ,CAAC;YACF,OAAO,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;QAC3G,CAAC,CAAC,CAAC;QAEH,OAAO,MAAM,CAAC;IAChB,CAAC;CACF,CAAA;AAtCY,4CAAgB;2BAAhB,gBAAgB;IAD5B,IAAA,mBAAU,GAAE;qCAGuB,sBAAa;QAClB,mCAAe;GAHjC,gBAAgB,CAsC5B"}

package/dist/mcp/services/mcp.tool.registry.d.ts

@@ -0,0 +1,21 @@
+import { McpToolContribution, McpToolDefinition, McpToolResult, McpUserContext } from "../interfaces/mcp.tool.interface";
+import { McpGenericToolsService } from "./mcp.generic.tools.service";
+import { McpPromotedToolsFactory } from "./mcp.promoted.tools.factory";
+/**
+ * Composes the MCP tool set for a single authenticated request:
+ * - the generic tools (graph reads, document retrieval, entity writes)
+ * - the config-promoted per-entity tools
+ * - any app-contributed factories registered under the MCP_TOOLS token,
+ *   built per request with the same user context as the built-ins
+ */
+export declare class McpToolRegistry {
+    private readonly generic;
+    private readonly promoted;
+    private readonly contributed?;
+    constructor(generic: McpGenericToolsService, promoted: McpPromotedToolsFactory, contributed?: McpToolContribution[]);
+    /** RBAC-filtered tool list for this user; throws on duplicate tool names. */
+    build(ctx: McpUserContext): McpToolDefinition[];
+    /** Routes a tools/call to the named tool; unknown names return a flat error payload. */
+    call(name: string, input: Record<string, unknown>, ctx: McpUserContext): Promise<McpToolResult>;
+}
+//# sourceMappingURL=mcp.tool.registry.d.ts.map

package/dist/mcp/services/mcp.tool.registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.tool.registry.d.ts","sourceRoot":"","sources":["../../../src/mcp/services/mcp.tool.registry.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,mBAAmB,EACnB,iBAAiB,EACjB,aAAa,EACb,cAAc,EACf,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAEvE;;;;;;GAMG;AACH,qBACa,eAAe;IAExB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACM,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC;gBAF3C,OAAO,EAAE,sBAAsB,EAC/B,QAAQ,EAAE,uBAAuB,EACF,WAAW,CAAC,EAAE,mBAAmB,EAAE;IAGrF,6EAA6E;IAC7E,KAAK,CAAC,GAAG,EAAE,cAAc,GAAG,iBAAiB,EAAE;IAsB/C,wFAAwF;IAClF,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;CAUtG"}