@carlonicora/nestjs-neo4jsonapi 1.111.0 → 1.112.0

package/dist/mcp/services/mcp.entity.write.service.js

@@ -0,0 +1,270 @@
+"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.McpEntityWriteService = void 0;
+const common_1 = require("@nestjs/common");
+const node_crypto_1 = require("node:crypto");
+const graph_catalog_service_1 = require("../../agents/graph/services/graph.catalog.service");
+const entity_service_registry_1 = require("../../common/registries/entity.service.registry");
+const rbac_permission_service_1 = require("../../foundations/rbac/services/rbac-permission.service");
+const mcp_errors_1 = require("./mcp.errors");
+const UPDATE_SEMANTICS = "Partial update: only the attributes you provide are changed; omitted attributes and all relationships are left untouched. Use add_relationship/remove_relationship to change relationships.";
+/**
+ * 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.
+ */
+let McpEntityWriteService = class McpEntityWriteService {
+    constructor(registry, catalog, rbac) {
+        this.registry = registry;
+        this.catalog = catalog;
+        this.rbac = rbac;
+    }
+    /**
+     * The four write McpToolDefinitions (all `readOnly: false`) with hand-written
+     * JSON Schemas matching the C4 method params. Consumed by McpGenericToolsService.
+     */
+    buildTools(_ctx) {
+        const typeProperty = {
+            type: "string",
+            description: 'JSON:API entity type (plural, e.g. "orders"). Call describe_entity first for the field list.',
+        };
+        const idProperty = { type: "string", description: "The id of the target record." };
+        return [
+            {
+                name: "create_entity",
+                description: "Create a new record of the given JSON:API entity type. " +
+                    "Call describe_entity first to learn the valid attributes and relationships.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        type: typeProperty,
+                        attributes: {
+                            type: "object",
+                            description: "Attribute values keyed by field name (see describe_entity).",
+                        },
+                        relationships: {
+                            type: "object",
+                            description: "Optional JSON:API relationships keyed by relationship name.",
+                            additionalProperties: {
+                                type: "object",
+                                properties: {
+                                    data: {
+                                        type: "array",
+                                        items: {
+                                            type: "object",
+                                            properties: { type: { type: "string" }, id: { type: "string" } },
+                                            required: ["type", "id"],
+                                        },
+                                    },
+                                },
+                                required: ["data"],
+                            },
+                        },
+                    },
+                    required: ["type", "attributes"],
+                },
+                readOnly: false,
+                execute: (input, ctx) => this.createEntity(input, ctx),
+            },
+            {
+                name: "update_entity",
+                description: `Update an existing record. ${UPDATE_SEMANTICS}`,
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        type: typeProperty,
+                        id: idProperty,
+                        attributes: {
+                            type: "object",
+                            description: `The attribute values to change. ${UPDATE_SEMANTICS}`,
+                        },
+                    },
+                    required: ["type", "id", "attributes"],
+                },
+                readOnly: false,
+                execute: (input, ctx) => this.updateEntity(input, ctx),
+            },
+            {
+                name: "add_relationship",
+                description: "Add one or more related records to a to-many relationship of an existing record. " +
+                    "Call describe_entity first for the relationship names.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        type: typeProperty,
+                        id: idProperty,
+                        relationship: { type: "string", description: "Relationship name on the entity (see describe_entity)." },
+                        relatedType: { type: "string", description: "JSON:API type of the related records." },
+                        relatedIds: { type: "array", items: { type: "string" }, minItems: 1 },
+                    },
+                    required: ["type", "id", "relationship", "relatedType", "relatedIds"],
+                },
+                readOnly: false,
+                execute: (input, ctx) => this.addRelationship(input, ctx),
+            },
+            {
+                name: "remove_relationship",
+                description: "Remove one or more related records from a to-many relationship of an existing record.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        type: typeProperty,
+                        id: idProperty,
+                        relationship: { type: "string", description: "Relationship name on the entity (see describe_entity)." },
+                        relatedType: { type: "string", description: "JSON:API type of the related records." },
+                        relatedIds: { type: "array", items: { type: "string" }, minItems: 1 },
+                    },
+                    required: ["type", "id", "relationship", "relatedType", "relatedIds"],
+                },
+                readOnly: false,
+                execute: (input, ctx) => this.removeRelationship(input, ctx),
+            },
+        ];
+    }
+    /** Create a new entity of the given type. RBAC action: `create`. */
+    async createEntity(params, ctx) {
+        const gate = await this.gate(params.type, "create", ctx);
+        if ("error" in gate)
+            return gate.error;
+        const { entity, service } = gate;
+        const invalid = this.unknownAttributes(entity, params.attributes);
+        if (invalid)
+            return invalid;
+        try {
+            const data = {
+                id: (0, node_crypto_1.randomUUID)(),
+                type: params.type,
+                attributes: params.attributes,
+                ...(params.relationships ? { relationships: params.relationships } : {}),
+            };
+            const result = await service.createFromDTO({ data });
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return (0, mcp_errors_1.mcpError)(e);
+        }
+    }
+    /**
+     * 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.
+     */
+    async updateEntity(params, ctx) {
+        const gate = await this.gate(params.type, "update", ctx);
+        if ("error" in gate)
+            return gate.error;
+        const { entity, service } = gate;
+        const invalid = this.unknownAttributes(entity, params.attributes);
+        if (invalid)
+            return invalid;
+        try {
+            const before = await service.findRecordById({ id: params.id });
+            if (!before)
+                return (0, mcp_errors_1.mcpFlatError)("not_found", `No ${params.type} record with id ${params.id}.`);
+            const data = { id: params.id, type: params.type, attributes: params.attributes };
+            const result = await service.patchFromDTO({ data });
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return (0, mcp_errors_1.mcpError)(e);
+        }
+    }
+    /** Add items to a to-many relationship. RBAC action: `update`. */
+    async addRelationship(params, ctx) {
+        const gate = await this.gate(params.type, "update", ctx);
+        if ("error" in gate)
+            return gate.error;
+        const { service } = gate;
+        try {
+            const data = params.relatedIds.map((id) => ({ type: params.relatedType, id }));
+            const result = await service.addToRelationshipFromDTO({
+                id: params.id,
+                relationship: params.relationship,
+                data,
+            });
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return (0, mcp_errors_1.mcpError)(e);
+        }
+    }
+    /** Remove items from a to-many relationship. RBAC action: `update`. */
+    async removeRelationship(params, ctx) {
+        const gate = await this.gate(params.type, "update", ctx);
+        if ("error" in gate)
+            return gate.error;
+        const { service } = gate;
+        try {
+            const data = params.relatedIds.map((id) => ({ type: params.relatedType, id }));
+            const result = await service.removeFromRelationshipFromDTO({
+                id: params.id,
+                relationship: params.relationship,
+                data,
+            });
+            return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        }
+        catch (e) {
+            return (0, mcp_errors_1.mcpError)(e);
+        }
+    }
+    /**
+     * Shared gate: catalog visibility (unknown_type), RBAC (forbidden), and
+     * service registration (unknown_type).
+     */
+    async gate(type, action, ctx) {
+        const entity = this.catalog.getEntityDetail(type, ctx.userModuleIds);
+        if (!entity) {
+            return {
+                error: (0, mcp_errors_1.mcpFlatError)("unknown_type", `Unknown or inaccessible entity type: ${type}. Call describe_entity first.`),
+            };
+        }
+        if (!(await this.rbac.can({ userId: ctx.userId, moduleId: entity.moduleId, action }))) {
+            return { error: (0, mcp_errors_1.mcpFlatError)("forbidden", `You lack ${action} permission on ${type}.`) };
+        }
+        const service = this.registry.get(type);
+        if (!service) {
+            return { error: (0, mcp_errors_1.mcpFlatError)("unknown_type", `No service registered for ${type}.`) };
+        }
+        return { entity, service };
+    }
+    /**
+     * Rejects attribute keys that are not in the entity's catalog field list.
+     * Catalog fields are a CatalogField[] array — keys are the `name` property.
+     */
+    unknownAttributes(entity, attributes) {
+        const known = new Set(entity.fields.map((f) => f.name));
+        const unknown = Object.keys(attributes).filter((k) => !known.has(k));
+        if (unknown.length) {
+            return (0, mcp_errors_1.mcpFlatError)("validation_failed", `Unknown attributes: ${unknown.join(", ")}. Call describe_entity("${entity.type}") for the field list.`);
+        }
+        return null;
+    }
+};
+exports.McpEntityWriteService = McpEntityWriteService;
+exports.McpEntityWriteService = McpEntityWriteService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [entity_service_registry_1.EntityServiceRegistry,
+        graph_catalog_service_1.GraphCatalogService,
+        rbac_permission_service_1.RbacPermissionService])
+], McpEntityWriteService);
+//# sourceMappingURL=mcp.entity.write.service.js.map

package/dist/mcp/services/mcp.entity.write.service.js.map

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

package/dist/mcp/services/mcp.errors.d.ts

@@ -0,0 +1,24 @@
+import type { McpToolResult } from "../interfaces/mcp.tool.interface";
+/**
+ * MCP tool error codes (C10). Every executor failure is returned to the MCP
+ * client as a FLAT JSON payload `{ code, message, ...meta }` — mirroring the
+ * flat-error convention used by the HTTP layer's HttpExceptionFilter.
+ */
+export type McpErrorCode = "unknown_type" | "forbidden" | "validation_failed" | "not_found" | "internal";
+/**
+ * Maps an unknown thrown value to a flat MCP error result.
+ *
+ * - `HttpException` → status-derived code (404 → not_found, 403 → forbidden,
+ *   400/422 → validation_failed, anything else → internal)
+ * - `ZodError` → validation_failed with per-issue `issues` meta
+ * - other `Error` → internal with the error message
+ *
+ * Never includes stack traces.
+ */
+export declare function mcpError(e: unknown): McpToolResult;
+/**
+ * Builds a flat MCP error result directly from a code + message (+ optional meta).
+ * The payload shape is intentionally flat: `{ code, message, ...meta }`.
+ */
+export declare function mcpFlatError(code: string, message: string, meta?: Record<string, unknown>): McpToolResult;
+//# sourceMappingURL=mcp.errors.d.ts.map

package/dist/mcp/services/mcp.errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.errors.d.ts","sourceRoot":"","sources":["../../../src/mcp/services/mcp.errors.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAEtE;;;;GAIG;AACH,MAAM,MAAM,YAAY,GAAG,cAAc,GAAG,WAAW,GAAG,mBAAmB,GAAG,WAAW,GAAG,UAAU,CAAC;AAEzG;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,OAAO,GAAG,aAAa,CAuBlD;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,aAAa,CAE7G"}

package/dist/mcp/services/mcp.errors.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mcpError = mcpError;
+exports.mcpFlatError = mcpFlatError;
+const common_1 = require("@nestjs/common");
+const zod_1 = require("zod");
+/**
+ * Maps an unknown thrown value to a flat MCP error result.
+ *
+ * - `HttpException` → status-derived code (404 → not_found, 403 → forbidden,
+ *   400/422 → validation_failed, anything else → internal)
+ * - `ZodError` → validation_failed with per-issue `issues` meta
+ * - other `Error` → internal with the error message
+ *
+ * Never includes stack traces.
+ */
+function mcpError(e) {
+    let code = "internal";
+    let message = "Unexpected error";
+    let meta = {};
+    if (e instanceof common_1.HttpException) {
+        const status = e.getStatus();
+        code =
+            status === 404
+                ? "not_found"
+                : status === 403
+                    ? "forbidden"
+                    : status === 400 || status === 422
+                        ? "validation_failed"
+                        : "internal";
+        message = e.message;
+    }
+    else if (e instanceof zod_1.ZodError) {
+        code = "validation_failed";
+        message = "Input validation failed";
+        meta = { issues: e.issues.map((i) => ({ path: i.path.join("."), message: i.message })) };
+    }
+    else if (e instanceof Error) {
+        message = e.message;
+    }
+    return mcpFlatError(code, message, meta);
+}
+/**
+ * Builds a flat MCP error result directly from a code + message (+ optional meta).
+ * The payload shape is intentionally flat: `{ code, message, ...meta }`.
+ */
+function mcpFlatError(code, message, meta = {}) {
+    return { isError: true, content: [{ type: "text", text: JSON.stringify({ code, message, ...meta }) }] };
+}
+//# sourceMappingURL=mcp.errors.js.map

package/dist/mcp/services/mcp.errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.errors.js","sourceRoot":"","sources":["../../../src/mcp/services/mcp.errors.ts"],"names":[],"mappings":";;AAqBA,4BAuBC;AAMD,oCAEC;AApDD,2CAA+C;AAC/C,6BAA+B;AAU/B;;;;;;;;;GASG;AACH,SAAgB,QAAQ,CAAC,CAAU;IACjC,IAAI,IAAI,GAAiB,UAAU,CAAC;IACpC,IAAI,OAAO,GAAG,kBAAkB,CAAC;IACjC,IAAI,IAAI,GAA4B,EAAE,CAAC;IACvC,IAAI,CAAC,YAAY,sBAAa,EAAE,CAAC;QAC/B,MAAM,MAAM,GAAG,CAAC,CAAC,SAAS,EAAE,CAAC;QAC7B,IAAI;YACF,MAAM,KAAK,GAAG;gBACZ,CAAC,CAAC,WAAW;gBACb,CAAC,CAAC,MAAM,KAAK,GAAG;oBACd,CAAC,CAAC,WAAW;oBACb,CAAC,CAAC,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG;wBAChC,CAAC,CAAC,mBAAmB;wBACrB,CAAC,CAAC,UAAU,CAAC;QACrB,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;IACtB,CAAC;SAAM,IAAI,CAAC,YAAY,cAAQ,EAAE,CAAC;QACjC,IAAI,GAAG,mBAAmB,CAAC;QAC3B,OAAO,GAAG,yBAAyB,CAAC;QACpC,IAAI,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC;IAC3F,CAAC;SAAM,IAAI,CAAC,YAAY,KAAK,EAAE,CAAC;QAC9B,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;IACtB,CAAC;IACD,OAAO,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;AAC3C,CAAC;AAED;;;GAGG;AACH,SAAgB,YAAY,CAAC,IAAY,EAAE,OAAe,EAAE,OAAgC,EAAE;IAC5F,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;AAC1G,CAAC"}

package/dist/mcp/services/mcp.generic.tools.service.d.ts

@@ -0,0 +1,26 @@
+import { DescribeEntityTool } from "../../agents/graph/tools/describe-entity.tool";
+import { ReadEntityTool } from "../../agents/graph/tools/read-entity.tool";
+import { ResolveEntityTool } from "../../agents/graph/tools/resolve-entity.tool";
+import { SearchEntitiesTool } from "../../agents/graph/tools/search-entities.tool";
+import { TraverseTool } from "../../agents/graph/tools/traverse.tool";
+import { SearchDocumentsTool } from "../../agents/operator/tools/search-documents.tool";
+import { McpToolDefinition, McpUserContext } from "../interfaces/mcp.tool.interface";
+import { McpEntityWriteService } from "./mcp.entity.write.service";
+/**
+ * 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.
+ */
+export declare class McpGenericToolsService {
+    private readonly resolveEntityTool;
+    private readonly describeEntityTool;
+    private readonly searchEntitiesTool;
+    private readonly readEntityTool;
+    private readonly traverseTool;
+    private readonly searchDocumentsTool;
+    private readonly writeService;
+    constructor(resolveEntityTool: ResolveEntityTool, describeEntityTool: DescribeEntityTool, searchEntitiesTool: SearchEntitiesTool, readEntityTool: ReadEntityTool, traverseTool: TraverseTool, searchDocumentsTool: SearchDocumentsTool, writeService: McpEntityWriteService);
+    /** Builds the per-request generic tool definitions (read tools + write tools). */
+    build(ctx: McpUserContext): McpToolDefinition[];
+}
+//# sourceMappingURL=mcp.generic.tools.service.d.ts.map

package/dist/mcp/services/mcp.generic.tools.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.generic.tools.service.d.ts","sourceRoot":"","sources":["../../../src/mcp/services/mcp.generic.tools.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAA6B,MAAM,+CAA+C,CAAC;AAC9G,OAAO,EAAE,cAAc,EAAyB,MAAM,2CAA2C,CAAC;AAClG,OAAO,EAAE,iBAAiB,EAA4B,MAAM,8CAA8C,CAAC;AAC3G,OAAO,EAAE,kBAAkB,EAA6B,MAAM,+CAA+C,CAAC;AAE9G,OAAO,EAAE,YAAY,EAAuB,MAAM,wCAAwC,CAAC;AAC3F,OAAO,EAAE,mBAAmB,EAA8B,MAAM,mDAAmD,CAAC;AACpH,OAAO,EAAE,iBAAiB,EAAiB,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAEpG,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAgBnE;;;;GAIG;AACH,qBACa,sBAAsB;IAE/B,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAClC,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,kBAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,cAAc;IAC/B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY;gBANZ,iBAAiB,EAAE,iBAAiB,EACpC,kBAAkB,EAAE,kBAAkB,EACtC,kBAAkB,EAAE,kBAAkB,EACtC,cAAc,EAAE,cAAc,EAC9B,YAAY,EAAE,YAAY,EAC1B,mBAAmB,EAAE,mBAAmB,EACxC,YAAY,EAAE,qBAAqB;IAGtD,kFAAkF;IAClF,KAAK,CAAC,GAAG,EAAE,cAAc,GAAG,iBAAiB,EAAE;CA2EhD"}

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"}