@futdevpro/nts-dynamo 1.15.56 → 1.15.58

package/src/_modules/mcp/_services/dynts-mcp-server.service-base.spec.ts

@@ -0,0 +1,142 @@
+import { DyNTS_Mcp_ServerBase } from './dynts-mcp-server.service-base';
+import {
+    DyNTS_Mcp_CallResult,
+    DyNTS_Mcp_ServerInfo,
+    DyNTS_Mcp_ToolDefinition,
+} from '../_models/interfaces/dynts-mcp.interface';
+
+/**
+ * CONTRACT — `DyNTS_Mcp_ServerBase` tool-registry + dispatch (BFR-AM-003). A transportot NEM nyitjuk
+ * meg (nincs valódi stdio-szerver) — a `build()` + `callTool()` közvetlen dispatch-ét teszteljük,
+ * ami UGYANAZ a logika, mint a SDK `tools/call`-ja:
+ *   - N tool regisztrálása → `getAdvertisedToolNames` PONTOSAN ezeket listázza,
+ *   - `callTool` a megfelelő handler-re dispatch-el (a `name` szerint),
+ *   - ismeretlen tool → strukturált `isError:true` (NEM néma, NEM crash),
+ *   - handler-dobott hiba → `isError:true` fordítás (a payload tartalmazza a message-et),
+ *   - `isError:true` outcome → `isError:true` call-result.
+ */
+describe('DyNTS_Mcp_ServerBase (tool-registry + dispatch, BFR-AM-003)', () => {
+
+    /** A handler-hívások nyoma (melyik tool, milyen args) — a dispatch-helyesség igazolásához. */
+    let calls: { name: string; args: unknown }[];
+
+    /** Egy teszt-tool-definíció gyára (a handler `data`-ba teszi a tool-nevet + az args-ot). */
+    const makeTool = (name: string): DyNTS_Mcp_ToolDefinition => ({
+        name: name,
+        description: `Test tool ${name}.`,
+        inputSchema: { type: 'object', properties: { x: { type: 'string' } } },
+        handler: async (args: unknown) => {
+            calls.push({ name: name, args: args });
+            return { data: { tool: name, echo: args } };
+        },
+    });
+
+    /** A teszt-szerver: 3 tool + egy szándékosan dobó tool. */
+    class TestServer extends DyNTS_Mcp_ServerBase {
+        protected getServerInfo(): DyNTS_Mcp_ServerInfo {
+            return { name: 'test-mcp', version: '0.0.1-spec' };
+        }
+        protected getTools(): DyNTS_Mcp_ToolDefinition[] {
+            return [
+                makeTool('alpha'),
+                makeTool('beta'),
+                {
+                    name: 'boom',
+                    description: 'Always throws.',
+                    inputSchema: { type: 'object' },
+                    handler: async () => {
+                        throw new Error('kaboom from handler');
+                    },
+                },
+                {
+                    name: 'structuredError',
+                    description: 'Returns a structured error outcome.',
+                    inputSchema: { type: 'object' },
+                    handler: async () => ({ data: { reason: 'nope' }, isError: true }),
+                },
+            ];
+        }
+    }
+
+    let server: TestServer;
+
+    beforeEach(() => {
+        calls = [];
+        server = new TestServer();
+    });
+
+    /** A `content[0].text` JSON-payload kiparse-olása (a transport text-JSON shape-je). */
+    const payloadOf = (result: DyNTS_Mcp_CallResult): { [key: string]: unknown } =>
+        JSON.parse(result.content[0].text) as { [key: string]: unknown };
+
+    describe('registry — getTools → advertised', () => {
+        it('a deklarált tool-okat hirdeti build ELŐTT is (determinisztikus)', () => {
+            expect(server.getAdvertisedToolNames().sort())
+                .toEqual(['alpha', 'beta', 'boom', 'structuredError']);
+        });
+
+        it('build() után UGYANAZOK a hirdetett tool-ok (idempotens build)', () => {
+            const adapter1 = server.build();
+            const adapter2 = server.build();
+            expect(adapter1).toBe(adapter2);
+            expect(adapter1.getAdvertisedToolNames().sort())
+                .toEqual(['alpha', 'beta', 'boom', 'structuredError']);
+        });
+    });
+
+    describe('dispatch — callTool a megfelelő handler-re route-ol', () => {
+        it('alpha → az alpha handler fut (a data a tool-nevet + az args-ot adja)', async () => {
+            const result: DyNTS_Mcp_CallResult = await server.callTool({ name: 'alpha', arguments: { x: '1' } });
+            expect(result.isError).toBe(false);
+            expect(calls).toEqual([{ name: 'alpha', args: { x: '1' } }]);
+            expect(payloadOf(result)).toEqual({ tool: 'alpha', echo: { x: '1' } });
+        });
+
+        it('beta → a beta handler fut (a dispatch a `name` szerint választ)', async () => {
+            await server.callTool({ name: 'beta', arguments: { x: '2' } });
+            expect(calls).toEqual([{ name: 'beta', args: { x: '2' } }]);
+        });
+    });
+
+    describe('strukturált hiba (no-silent-failure)', () => {
+        it('ismeretlen tool → isError:true + advertised-lista a message-ben (NEM néma/crash)', async () => {
+            const result: DyNTS_Mcp_CallResult = await server.callTool({ name: 'does_not_exist' });
+            expect(result.isError).toBe(true);
+            const payload = payloadOf(result) as { ok: boolean; error: { message: string } };
+            expect(payload.ok).toBe(false);
+            expect(payload.error.message).toContain('does_not_exist');
+            expect(payload.error.message).toContain('alpha');
+            // egyetlen ismeretlen tool sem futtatott handlert.
+            expect(calls.length).toBe(0);
+        });
+
+        it('handler-dobott hiba → isError:true + a hiba message-e a payload-ban (NEM crash)', async () => {
+            const result: DyNTS_Mcp_CallResult = await server.callTool({ name: 'boom' });
+            expect(result.isError).toBe(true);
+            const payload = payloadOf(result) as { ok: boolean; error: { message: string } };
+            expect(payload.ok).toBe(false);
+            expect(payload.error.message).toContain('kaboom from handler');
+        });
+
+        it('isError:true outcome → isError:true call-result (a strukturált hiba átmegy)', async () => {
+            const result: DyNTS_Mcp_CallResult = await server.callTool({ name: 'structuredError' });
+            expect(result.isError).toBe(true);
+            expect(payloadOf(result)).toEqual({ reason: 'nope' });
+        });
+    });
+
+    describe('start — transport-választás', () => {
+        it('ismeretlen transport → dob (exhaustiveness-guard); stdio nem nyílik a spec-ben', async () => {
+            let thrown: unknown;
+            try {
+                // Szándékosan érvénytelen transport (a típus-szűkítés megkerülésével) — a guard-ágat teszteli,
+                // valódi stdio-szervert NEM indítunk.
+                await server.start({ transport: 'http' as never });
+            } catch (error) {
+                thrown = error;
+            }
+            expect(thrown).toBeDefined();
+            expect((thrown as Error).message).toContain('Unsupported MCP transport');
+        });
+    });
+});

package/src/_modules/mcp/_services/dynts-mcp-server.service-base.ts

@@ -0,0 +1,120 @@
+import { DyFM_Log } from '@futdevpro/fsm-dynamo';
+
+import {
+    DyNTS_Mcp_CallResult,
+    DyNTS_Mcp_ServerInfo,
+    DyNTS_Mcp_StartOptions,
+    DyNTS_Mcp_ToolDefinition,
+} from '../_models/interfaces/dynts-mcp.interface';
+import { DyNTS_Mcp_Adapter } from './dynts-mcp.adapter';
+
+/**
+ * `DyNTS_Mcp_ServerBase` (BFR-AM-003) — a **domain-agnosztikus** MCP-szerver-base. Egy bedrock-réteg
+ * a hivatalos `@modelcontextprotocol/sdk` fölött: a server-base felel a tool-registry-ért, a
+ * `tools/list`/`tools/call` dispatch-ért (az adaptoron át) + a transport-indításért — a SDK KIZÁRÓLAG
+ * a `DyNTS_Mcp_Adapter` mögött él (egy jövőbeli transport-/SDK-csere NON-breaking).
+ *
+ * **Használat (consumer):** a consumer leszármazik (`extends DyNTS_Mcp_ServerBase`) + implementálja a
+ * `getServerInfo()` (név/verzió) és `getTools()` (a SAJÁT tool-jai) abstract metódusokat. A bedrock
+ * SEMMILYEN domain-tool-t NEM definiál — csak a server-base + a transport + a registry. (Pl. a FAM a
+ * `read`/`write`/`capabilities` tool-jait itt regisztrálja, a bedrock-on kívül.)
+ *
+ * ```ts
+ * class My_McpServer extends DyNTS_Mcp_ServerBase {
+ *   protected getServerInfo() { return { name: 'my-app', version: '1.0.0' }; }
+ *   protected getTools() { return [readTool, writeTool]; }
+ * }
+ * await new My_McpServer().start({ transport: 'stdio' });
+ * ```
+ *
+ * **stdio-konvenció:** a stdout a JSON-RPC csatorna — a boot-üzenet + minden log a stderr-re megy (a
+ * hívó App a `DyFM_Log`-ot stdio-módban stderr-re konfigurálja).
+ */
+export abstract class DyNTS_Mcp_ServerBase {
+
+    /** Az MCP-adaptor (a regisztrált tool-ok + a transport mögötti SDK-réteg). Lazy a `build()`-ben. */
+    private adapter: DyNTS_Mcp_Adapter | null = null;
+
+    /**
+     * A szerver identitása (név/verzió) — a consumer adja. A SDK `serverInfo`-jaként hirdetődik.
+     */
+    protected abstract getServerInfo(): DyNTS_Mcp_ServerInfo;
+
+    /**
+     * A consumer SAJÁT tool-definíciói (az advertised halmaz). A `build()` ezeket regisztrálja az
+     * adaptoron át — a `tools/list` PONTOSAN ezeket hirdeti, a `tools/call` ezekre dispatch-el.
+     */
+    protected abstract getTools(): DyNTS_Mcp_ToolDefinition[];
+
+    /**
+     * A szerver felépítése (a consumer-tool-ok regisztrálása az adaptoron). NEM indítja a transportot
+     * — a `start()` teszi. Külön lépés a contract-teszt kedvéért (a szerver felépül + a tool-okat
+     * hirdeti, transport nélkül). Idempotens: ismételt hívás ugyanazt az adaptort adja vissza.
+     */
+    public build(): DyNTS_Mcp_Adapter {
+        if (this.adapter) {
+            return this.adapter;
+        }
+        const adapter: DyNTS_Mcp_Adapter = new DyNTS_Mcp_Adapter(this.getServerInfo());
+        for (const tool of this.getTools()) {
+            adapter.registerTool(tool);
+        }
+        this.adapter = adapter;
+        return adapter;
+    }
+
+    /**
+     * Az MCP-szerver indítása a választott transporton (default `stdio`). Felépíti a szervert (ha még
+     * nem), majd a transportot csatlakoztatja — innentől a `tools/list` a consumer-tool-okat hirdeti,
+     * a `tools/call` route-ol. A boot-üzenet a stderr-en.
+     */
+    public async start(options?: DyNTS_Mcp_StartOptions): Promise<void> {
+        const transport: 'stdio' = options?.transport ?? 'stdio';
+        const adapter: DyNTS_Mcp_Adapter = this.build();
+        const info: DyNTS_Mcp_ServerInfo = this.getServerInfo();
+        DyFM_Log.testInfo(`[DyNTS MCP] ${transport} server starting (${info.name} v${info.version}); `
+            + `advertised tools: ${adapter.getAdvertisedToolNames().join(', ')}`);
+        await this.startTransport(adapter, transport);
+    }
+
+    /**
+     * A felépített tool-nevek (a contract/diszjunkció-teszthez). Build előtt a deklarált `getTools()`
+     * neveit adja (transport nélkül is determinisztikus).
+     */
+    public getAdvertisedToolNames(): string[] {
+        return this.adapter
+            ? this.adapter.getAdvertisedToolNames()
+            : this.getTools().map((tool) => tool.name);
+    }
+
+    /**
+     * Egy tool KÖZVETLEN hívása (a transport megkerülésével) — a contract-teszthez / REST-paritáshoz.
+     * Felépíti a szervert (ha még nem), majd az adaptor egységes dispatch-ét futtatja (ismeretlen
+     * tool → strukturált hiba; handler-hiba → `isError:true`).
+     */
+    public async callTool(set: { name: string; arguments?: unknown }): Promise<DyNTS_Mcp_CallResult> {
+        return this.build().dispatchToolCall(set);
+    }
+
+    /** A szerver leállítása (graceful close — teszt-/shutdown-úthoz). */
+    public async close(): Promise<void> {
+        if (this.adapter) {
+            await this.adapter.close();
+        }
+    }
+
+    /**
+     * A transport-indítás dispatch-e. Külön metódus, hogy egy jövőbeli transport (http/sse) NON-breaking
+     * módon bővíthető legyen (a `start()` + a registry változatlan). MVP: csak `stdio`.
+     */
+    private async startTransport(adapter: DyNTS_Mcp_Adapter, transport: 'stdio'): Promise<void> {
+        switch (transport) {
+            case 'stdio':
+                await adapter.startStdio();
+                return;
+            default:
+                // Exhaustiveness-guard: a `DyNTS_Mcp_TransportKind` bővülésekor itt fordítási hibát kapunk.
+                throw new Error(`Unsupported MCP transport: '${transport as string}'.`);
+        }
+    }
+}

package/src/_modules/mcp/_services/dynts-mcp.adapter.ts

@@ -0,0 +1,157 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, CallToolResult, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+import { DyFM_Error } from '@futdevpro/fsm-dynamo';
+
+import {
+    DyNTS_Mcp_CallResult,
+    DyNTS_Mcp_ServerInfo,
+    DyNTS_Mcp_ToolDefinition,
+    DyNTS_Mcp_ToolOutcome,
+} from '../_models/interfaces/dynts-mcp.interface';
+
+/**
+ * `DyNTS_Mcp_Adapter` (BFR-AM-003) — a hivatalos `@modelcontextprotocol/sdk` köré épített **vékony
+ * adaptor-réteg**. EZ az EGYETLEN hely a `/mcp` submodule-ban, ahol a SDK-típusok megjelennek — a
+ * `DyNTS_Mcp_ServerBase` + a consumer tool-jai SDK-mentesek, így egy jövőbeli transport-/SDK-csere
+ * NON-breaking (csak ez az osztály cserélődik).
+ *
+ * Felelősség (3 dolog, semmi domain-logika):
+ *   1. EGY `registerTool` choke-pont (a tool-name → def map),
+ *   2. a `tools/list` + `tools/call` JSON-RPC handler bekötése a SDK-szerverre,
+ *   3. egységes hiba-fordítás: a tool-handler dobott hibája (vagy `isError:true` outcome-ja)
+ *      strukturált `CallToolResult { isError:true }`-tá fordul — SOHA nem néma, SOHA nem crash.
+ *
+ * **stdio-konvenció:** a stdout a JSON-RPC csatorna — az adaptor maga SEMMIT nem ír a stdout-ra a
+ * transport-payload-on kívül (minden log/diag a hívó App felelőssége, stderr-re).
+ */
+export class DyNTS_Mcp_Adapter {
+
+    /** A SDK MCP-szerver (a transport-agnosztikus protocol-réteg). */
+    private readonly server: Server;
+
+    /** A regisztrált tool-definíciók `name` → def map-je (a `tools/call` dispatch-hez). */
+    private readonly tools: Map<string, DyNTS_Mcp_ToolDefinition> =
+        new Map<string, DyNTS_Mcp_ToolDefinition>();
+
+    constructor(set: DyNTS_Mcp_ServerInfo) {
+        this.server = new Server(
+            { name: set.name, version: set.version },
+            { capabilities: { tools: {} } },
+        );
+        this.installHandlers();
+    }
+
+    /**
+     * Az EGYETLEN tool-regisztrációs choke-pont. A regisztrált tool-ok hirdetődnek a `tools/list`-ben
+     * és dispatch-elhetők a `tools/call`-on. Az azonos nevű ismételt regisztráció felülír (last-wins).
+     */
+    public registerTool(definition: DyNTS_Mcp_ToolDefinition): void {
+        this.tools.set(definition.name, definition);
+    }
+
+    /** A hirdetett (regisztrált) tool-nevek (a contract/diszjunkció-teszthez). */
+    public getAdvertisedToolNames(): string[] {
+        return Array.from(this.tools.keys());
+    }
+
+    /**
+     * A stdio transport csatlakoztatása + a szerver indítása. A `connect` után a `tools/list` a
+     * regisztrált tool-okat hirdeti. A boot-üzenetek a stderr-en (a hívó App felel).
+     */
+    public async startStdio(): Promise<void> {
+        const transport: StdioServerTransport = new StdioServerTransport();
+        await this.server.connect(transport);
+    }
+
+    /** A szerver leállítása (graceful close — teszt-/shutdown-úthoz). */
+    public async close(): Promise<void> {
+        await this.server.close();
+    }
+
+    /**
+     * Egy tool-hívás KÖZVETLEN dispatch-elése (a transport-megkerülésével) — a contract/registry-teszt
+     * ezt hívja a stdio-szerver indítása nélkül. Ugyanaz a logika fut, mint a SDK `tools/call`-on:
+     * ismeretlen tool → strukturált hiba; handler-hiba → `isError:true` fordítás.
+     */
+    public async dispatchToolCall(set: { name: string; arguments?: unknown }): Promise<DyNTS_Mcp_CallResult> {
+        const definition: DyNTS_Mcp_ToolDefinition | undefined = this.tools.get(set.name);
+        if (!definition) {
+            return this.errorResult(`Unknown tool: '${set.name}'. Advertised tools: `
+                + `${this.getAdvertisedToolNames().join(', ')}.`);
+        }
+        try {
+            const outcome: DyNTS_Mcp_ToolOutcome = await definition.handler(set.arguments);
+            return this.toCallResult(outcome);
+        } catch (error) {
+            return this.errorResult(this.describeError(error), error);
+        }
+    }
+
+    // =========================================================================
+    // 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. */
+    private installHandlers(): void {
+        // tools/list — PONTOSAN a regisztrált (advertised) tool-okat hirdeti.
+        this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
+            tools: Array.from(this.tools.values()).map((definition) => ({
+                name: definition.name,
+                description: definition.description,
+                inputSchema: definition.inputSchema,
+            })),
+        }));
+
+        // tools/call — a megfelelő handler futtatása + egységes hiba-fordítás (a közös dispatch-en át).
+        // A `DyNTS_Mcp_CallResult` a SDK `CallToolResult` egy al-shape-je (text-content + isError) — a
+        // SDK-cast KIZÁRÓLAG itt, az adaptor-boundary-n él (a SDK izolálva marad).
+        this.server.setRequestHandler(CallToolRequestSchema, async (request): Promise<CallToolResult> =>
+            (await this.dispatchToolCall({
+                name: request.params.name,
+                arguments: request.params.arguments,
+            })) as CallToolResult);
+    }
+
+    // =========================================================================
+    // CallToolResult fordítás (a transport-payload — text-JSON; egységes hiba-fordítás)
+    // =========================================================================
+
+    /** Egy sikeres (vagy strukturált-hiba) handler-outcome → `CallToolResult` (text-JSON content). */
+    private toCallResult(outcome: DyNTS_Mcp_ToolOutcome): DyNTS_Mcp_CallResult {
+        return {
+            content: [{ type: 'text', text: this.stringify(outcome.data) }],
+            isError: outcome.isError === true,
+        };
+    }
+
+    /** Egy hiba → `CallToolResult { isError:true }` strukturált hiba-payload-dal (soha nem néma). */
+    private errorResult(message: string, error?: unknown): DyNTS_Mcp_CallResult {
+        const errorCode: string | undefined = error instanceof DyFM_Error
+            ? DyFM_Error.getErrorCode(error)
+            : undefined;
+        const payload: object = { ok: false, error: { errorCode: errorCode, message: message } };
+        return { content: [{ type: 'text', text: this.stringify(payload) }], isError: true };
+    }
+
+    /** Egy hiba ember-olvasható üzenete (DyFM_Error → message; Error → message; egyéb → fallback). */
+    private describeError(error: unknown): string {
+        if (error instanceof DyFM_Error) {
+            return DyFM_Error.getErrorMessage(error) || 'Unknown DyFM error.';
+        }
+        if (error instanceof Error) {
+            return error.message;
+        }
+        return 'Unknown error during tool execution.';
+    }
+
+    /** JSON-stringify (a transport text-content payload-ja); szerializálás-hiba → strukturált hiba. */
+    private stringify(data: unknown): string {
+        try {
+            return JSON.stringify(data);
+        } catch {
+            return JSON.stringify({ ok: false, error: { message: 'The response is not JSON-serializable.' } });
+        }
+    }
+}

package/src/_modules/mcp/index.ts

@@ -0,0 +1,13 @@
+
+
+// MCP MODULE (BFR-AM-003) — domain-agnosztikus Model Context Protocol szerver-base + transport +
+// tool-registry, a hivatalos `@modelcontextprotocol/sdk` köré izolált adaptorral. A consumer
+// leszármazik a `DyNTS_Mcp_ServerBase`-ből + a SAJÁT tool-jait regisztrálja (a bedrock NEM definiál
+// domain-tool-t). A SDK KIZÁRÓLAG a `DyNTS_Mcp_Adapter` mögött él (transport-csere NON-breaking).
+
+// INTERFACES
+export * from './_models/interfaces/dynts-mcp.interface';
+
+// SERVICES
+export * from './_services/dynts-mcp.adapter';
+export * from './_services/dynts-mcp-server.service-base';