@futdevpro/fdp-agent-memory 0.1.0

package/build/src/_modules/mcp/_services/fam-mcp-adapter.service.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_Mcp_Adapter = void 0;
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+/**
+ * `FAM_Mcp_Adapter` (SP-6.1, BFR-AM-003 workaround) — a hivatalos `@modelcontextprotocol/sdk` köré
+ * épített **vékony adaptor-réteg**. EGY `registerTool` choke-pont + a `tools/list` / `tools/call`
+ * JSON-RPC handler-ek bekötése — semmi domain-logika. Így a bedrock `DyNTS_Mcp_ServerBase` (MP-15)
+ * landolásakor CSAK ez az osztály cserélődik; a 3 core tool + a capability-registry kód változatlan.
+ *
+ * **stdio-konvenció (dsgn-003 §1, dsgn-010 §6):** a stdout a JSON-RPC csatorna — minden log/diag a
+ * stderr-re megy (a hívó App állítja be a `DyFM_Log`-ot stderr-re). Az adaptor maga semmit NEM ír a
+ * stdout-ra a transport-payload-on kívül.
+ *
+ * **Egységes hiba-fordítás (dsgn-008):** a tool-handler dobott `DyFM_Error`-ja (vagy bármilyen hiba)
+ * strukturált `CallToolResult { isError:true, content }`-tá fordul — soha nem néma, soha nem crash-el
+ * a szerver. A handler `FAM_McpToolOutcome.isError` is ide képződik.
+ */
+class FAM_Mcp_Adapter {
+    /** A SDK MCP-szerver (a transport-agnosztikus protocol-réteg). */
+    server;
+    /** A regisztrált tool-definíciók `name` → def map-je (a `tools/call` dispatch-hez). */
+    tools = new Map();
+    constructor(set) {
+        this.server = new index_js_1.Server({ name: set.name, version: set.version }, { capabilities: { tools: {} } });
+        this.installHandlers();
+    }
+    /**
+     * Az EGYETLEN tool-regisztrációs choke-pont (BFR-AM-003). A 3 core tool ezt hívja; a capability-
+     * eszközök NEM (azok a `capabilities` tool-on át, a registry-ből — diszjunkt halmaz). A regisztrált
+     * tool-ok hirdetődnek a `tools/list`-ben.
+     */
+    registerTool(definition) {
+        this.tools.set(definition.name, definition);
+    }
+    /** A hirdetett tool-nevek (a contract/diszjunkció-teszthez). */
+    getAdvertisedToolNames() {
+        return Array.from(this.tools.keys());
+    }
+    /**
+     * A stdio transport csatlakoztatása + a szerver indítása (dsgn-003 §1). A `connect` után a
+     * `tools/list` a regisztrált 3 core tool-t hirdeti. A boot-üzenetek a stderr-en (a hívó App felel).
+     */
+    async startStdio() {
+        const transport = new stdio_js_1.StdioServerTransport();
+        await this.server.connect(transport);
+    }
+    /** A szerver leállítása (graceful close — teszt-/shutdown-úthoz). */
+    async close() {
+        await this.server.close();
+    }
+    // =========================================================================
+    // SDK request-handler bekötés (tools/list + tools/call)
+    // =========================================================================
+    /** A `tools/list` és a `tools/call` JSON-RPC handler bekötése a SDK-szerverre. */
+    installHandlers() {
+        // tools/list — PONTOSAN a regisztrált (advertised) tool-okat hirdeti (dsgn-003 §6.1).
+        this.server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+            tools: Array.from(this.tools.values()).map((definition) => ({
+                name: definition.name,
+                description: definition.description,
+                inputSchema: definition.inputSchema,
+            })),
+        }));
+        // tools/call — a megfelelő core-tool handler futtatása + egységes hiba-fordítás.
+        this.server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+            const toolName = request.params.name;
+            const definition = this.tools.get(toolName);
+            if (!definition) {
+                return this.errorResult(`Ismeretlen tool: '${toolName}'. A hirdetett tool-ok: `
+                    + `${this.getAdvertisedToolNames().join(', ')}.`);
+            }
+            try {
+                const outcome = await definition.handler(request.params.arguments);
+                return this.toCallResult(outcome);
+            }
+            catch (error) {
+                return this.errorResult(this.describeError(error), error);
+            }
+        });
+    }
+    // =========================================================================
+    // CallToolResult fordítás (a transport-payload — text-JSON; dsgn-008 hiba-fordítás)
+    // =========================================================================
+    /** Egy sikeres (vagy strukturált-hiba) handler-outcome → `CallToolResult` (text-JSON content). */
+    toCallResult(outcome) {
+        return {
+            content: [{ type: 'text', text: this.stringify(outcome.data) }],
+            isError: outcome.isError === true,
+        };
+    }
+    /** Egy hiba → `CallToolResult { isError:true }` strukturált hiba-payload-dal (dsgn-008, soha nem néma). */
+    errorResult(message, error) {
+        const errorCode = error instanceof fsm_dynamo_1.DyFM_Error
+            ? fsm_dynamo_1.DyFM_Error.getErrorCode(error)
+            : undefined;
+        const payload = { ok: false, error: { errorCode: errorCode, message: message } };
+        return { content: [{ type: 'text', text: this.stringify(payload) }], isError: true };
+    }
+    /** Egy hiba ember-olvasható üzenete (FAM kanonikus message-prioritás). */
+    describeError(error) {
+        if (error instanceof fsm_dynamo_1.DyFM_Error) {
+            return fsm_dynamo_1.DyFM_Error.getErrorMessage(error) || 'Ismeretlen FAM hiba.';
+        }
+        if (error instanceof Error) {
+            return error.message;
+        }
+        return 'Ismeretlen hiba a tool-végrehajtás során.';
+    }
+    /** JSON-stringify (a transport text-content payload-ja). */
+    stringify(data) {
+        try {
+            return JSON.stringify(data);
+        }
+        catch {
+            return JSON.stringify({ ok: false, error: { message: 'A válasz nem szerializálható JSON-ra.' } });
+        }
+    }
+}
+exports.FAM_Mcp_Adapter = FAM_Mcp_Adapter;

package/build/src/_modules/mcp/_services/fam-mcp-server.service.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_McpServer_Service = void 0;
+const fsm_dynamo_1 = require("@futdevpro/fsm-dynamo");
+const fam_core_tools_const_1 = require("../_collections/fam-core-tools.const");
+const fam_capability_registry_service_1 = require("./fam-capability-registry.service");
+const fam_mcp_adapter_service_1 = require("./fam-mcp-adapter.service");
+/**
+ * `FAM_McpServer_Service` (SP-6.1, dsgn-003 §1/§5/§6) — az MCP-szerver orchestrátora. Singleton.
+ * Felelősség: a `FAM_Mcp_Adapter`-be regisztrálja a **PONTOSAN 3** advertised core-tool-t
+ * (`read`/`write`/`capabilities`), példányosítja a capability-registry-t (a discoverable speciális
+ * eszközök single-source-a — diszjunkt halmaz, dsgn-003 §6.6), és a stdio transporton elindítja a
+ * szervert (`start`).
+ *
+ * **Diszjunkció-garancia (dsgn-003 §6.1/§6.6):** az adaptor `registerTool`-ja CSAK a 3 core-tool-t
+ * kapja meg — a capability-eszközök SOHA nem kerülnek a SDK advertised tool-listájába (azok kizárólag
+ * a `capabilities` tool-on át, a registry-ből elérhetők).
+ *
+ * **stdio-konvenció (dsgn-003 §1):** a stdout a JSON-RPC csatorna — a boot-üzenetek + minden log a
+ * stderr-re mennek (a `DyFM_Log` az App-ban stderr-re konfigurált stdio-módban).
+ */
+class FAM_McpServer_Service {
+    static _instance;
+    /** Az MCP-adaptor (a 3 core tool + a stdio transport mögötti SDK-réteg; BFR-AM-003). */
+    adapter = null;
+    static getInstance() {
+        if (!FAM_McpServer_Service._instance) {
+            FAM_McpServer_Service._instance = new FAM_McpServer_Service();
+        }
+        return FAM_McpServer_Service._instance;
+    }
+    /**
+     * A szerver felépítése (a 3 advertised core-tool + a capability-registry példányosítása). NEM
+     * indítja a transportot — a `start()` teszi. Külön lépés a contract-teszt kedvéért (require-time
+     * smoke: a szerver felépül + 3 tool-t hirdet, transport nélkül).
+     */
+    build(set) {
+        const adapter = new fam_mcp_adapter_service_1.FAM_Mcp_Adapter({ name: set.name, version: set.version });
+        // A PONTOSAN 3 advertised core-tool regisztrálása (a single-source `FAM_CORE_TOOLS`-ból).
+        for (const tool of fam_core_tools_const_1.FAM_CORE_TOOLS) {
+            adapter.registerTool(tool);
+        }
+        // A capability-registry példányosítása (a discoverable speciális eszközök katalógusa) — ezek
+        // NEM advertised tool-ok, csak a `capabilities` tool-on át elérhetők (diszjunkció).
+        fam_capability_registry_service_1.FAM_CapabilityRegistry.getInstance();
+        this.adapter = adapter;
+        return adapter;
+    }
+    /**
+     * A stdio MCP-szerver indítása (dsgn-003 §1). Felépíti a szervert (ha még nem), majd a stdio
+     * transportot csatlakoztatja — innentől a `tools/list` a 3 core tool-t hirdeti, a `tools/call`
+     * route-ol. A boot-üzenet a stderr-en.
+     */
+    async start(set) {
+        const adapter = this.adapter ?? this.build(set);
+        fsm_dynamo_1.DyFM_Log.testInfo(`[FAM MCP] stdio szerver indul (${set.name} v${set.version}); hirdetett tool-ok: `
+            + `${adapter.getAdvertisedToolNames().join(', ')}`);
+        await adapter.startStdio();
+    }
+    /** A hirdetett tool-nevek (a contract/diszjunkció-teszthez). */
+    getAdvertisedToolNames() {
+        return this.adapter ? this.adapter.getAdvertisedToolNames() : [];
+    }
+    /** A discoverable capability-nevek (a diszjunkció-teszthez: ezek SOHA nem advertised). */
+    getCapabilityNames() {
+        return fam_capability_registry_service_1.FAM_CapabilityRegistry.getInstance().names();
+    }
+}
+exports.FAM_McpServer_Service = FAM_McpServer_Service;

package/build/src/_modules/mcp/_services/fam-read-tool.service.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FAM_ReadTool_Service = void 0;
+const fam_table_type_enum_1 = require("../../../_enums/fam-table.type-enum");
+const error_codes_const_1 = require("../../../_collections/error-codes.const");
+const fam_error_factory_util_1 = require("../../../_collections/fam-error-factory.util");
+const retrieval_1 = require("../../retrieval");
+/**
+ * `FAM_ReadTool_Service` (SP-6.2, dsgn-003 §2) — a `read` core-tool **transport-agnosztikus**
+ * handler-je. Singleton. EGY belépési pont (`handle`), amit MIND az MCP-tool (stdio), MIND a REST
+ * `POST /read` hív — így a két felület garantáltan paritásban van (dsgn-003 §6.5, SP-6.5 paritás-teszt).
+ *
+ * A handler **NEM implementál keresési logikát** — validál + a MP-5 `FAM_Retrieval_ControlService`-re
+ * route-ol, és a kimenetet a dsgn-003 §2.2 wire-shape-re map-eli (a retrieval-engine `FAM_RetrievalResult`-ja
+ * MÁR a §2.2 shape — `hits`/`score`/`weight`/`denseResults`/`totalRelevant`/`truncated`/`suggestions`/
+ * `uncertaintyNotes`). Az `includeContent` default `true` (single-pass, azonnal tartalom).
+ *
+ * **Validáció (dsgn-003 §2.1):** legalább 1 query; query-nként legalább 1 tábla; a `reference` tár
+ * TILTOTT a `tables`-ben (helper, nem kereshető) → `FAM-VAL-READ-001` (strukturált hiba, nem néma).
+ */
+class FAM_ReadTool_Service {
+    static _instance;
+    /** Default issuer (a validációs hibák issuer-éhez; dsgn-008). */
+    issuer = 'FAM_ReadTool_Service';
+    static getInstance() {
+        if (!FAM_ReadTool_Service._instance) {
+            FAM_ReadTool_Service._instance = new FAM_ReadTool_Service();
+        }
+        return FAM_ReadTool_Service._instance;
+    }
+    /**
+     * A `read` core-handler (dsgn-003 §2). Validál → a MP-5 retrieval-pipeline-ra route-ol → a
+     * §2.2 output-ot adja (`results[]`). A validációs hiba **dobott** `DyFM_Error` (`FAM-VAL-READ-001`),
+     * amit az MCP-adaptor / a REST-réteg egységesen strukturált hibává fordít (dsgn-008).
+     */
+    async handle(input) {
+        this.validate(input);
+        const request = this.toRetrievalRequest(input);
+        return retrieval_1.FAM_Retrieval_ControlService.getInstance().read(request);
+    }
+    /**
+     * A `read` input validációja (dsgn-003 §2.1). Üres `queries` / üres `tables` / `reference` a
+     * `tables`-ben → `FAM-VAL-READ-001` (deskriptív, level=user). A `reference` helper-tár SOHA nem
+     * kereshető közvetlenül (dsgn-002/dsgn-005 §1).
+     */
+    validate(input) {
+        if (!input || !Array.isArray(input.queries) || !input.queries.length) {
+            throw fam_error_factory_util_1.FAM_Error_Util.create({
+                errorCode: error_codes_const_1.FAM_ERROR_CODES.valReadEmptyOrReference,
+                message: 'A `read` legalább egy query-t igényel (`queries[]`). Adj meg legalább egy '
+                    + '{ tables, query } blokkot.',
+                issuer: this.issuer,
+                context: { operation: 'read-validate' },
+            });
+        }
+        for (const query of input.queries) {
+            if (!query || !Array.isArray(query.tables) || !query.tables.length || !query.query) {
+                throw fam_error_factory_util_1.FAM_Error_Util.create({
+                    errorCode: error_codes_const_1.FAM_ERROR_CODES.valReadEmptyOrReference,
+                    message: 'Minden `read` query-nek legalább 1 `tables` elemet és egy nem-üres `query` '
+                        + 'phrase-t kell tartalmaznia.',
+                    issuer: this.issuer,
+                    context: { operation: 'read-validate' },
+                });
+            }
+            if (query.tables.includes(fam_table_type_enum_1.FAM_Table.reference)) {
+                throw fam_error_factory_util_1.FAM_Error_Util.create({
+                    errorCode: error_codes_const_1.FAM_ERROR_CODES.valReadEmptyOrReference,
+                    message: "A `reference` tár helper (alias/fogalom-feloldás), NEM kereshető közvetlenül — "
+                        + 'automatikusan közreműködik a scope/reference-feloldásban. Válassz fő tárat '
+                        + '(rules/documents/codebase/knowledge/coding_patterns/memory).',
+                    issuer: this.issuer,
+                    context: { operation: 'read-validate', table: fam_table_type_enum_1.FAM_Table.reference },
+                });
+            }
+        }
+    }
+    /** A `read` tool-input → a MP-5 retrieval-engine `FAM_RetrievalRequest`-je (1:1 mező-map). */
+    toRetrievalRequest(input) {
+        return {
+            queries: input.queries.map((query) => this.toRetrievalQuery(query)),
+            includeContent: input.includeContent,
+            globalScopeFilter: input.globalScopeFilter,
+        };
+    }
+    /** Egy `read` query → `FAM_RetrievalQuery` (a retrieval-engine bemenete). */
+    toRetrievalQuery(query) {
+        return {
+            tables: query.tables,
+            query: query.query,
+            topK: query.topK,
+            minScore: query.minScore,
+            scopeFilter: query.scopeFilter,
+            tagFilter: query.tagFilter,
+            kindFilter: query.kindFilter,
+        };
+    }
+}
+exports.FAM_ReadTool_Service = FAM_ReadTool_Service;