@futdevpro/nts-dynamo 1.15.58 → 1.15.64

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

@@ -1,12 +1,12 @@
-import { DyNTS_Mcp_ServerBase } from './dynts-mcp-server.service-base';
+import { DyNTS_Mcp_Server_ServiceBase } from './dynts-mcp-server.service-base';
 import {
-    DyNTS_Mcp_CallResult,
-    DyNTS_Mcp_ServerInfo,
-    DyNTS_Mcp_ToolDefinition,
+  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
+ * CONTRACT — `DyNTS_Mcp_Server_ServiceBase` 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,
@@ -15,128 +15,137 @@ import {
  *   - 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 } };
+describe('| DyNTS_Mcp_Server_ServiceBase (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_Server_ServiceBase {
+    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' ]);
     });
 
-    /** 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 }),
-                },
-            ];
-        }
-    }
+    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' ]);
+    });
+  });
 
-    let server: TestServer;
+  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' } });
 
-    beforeEach(() => {
-        calls = [];
-        server = new TestServer();
+      expect(result.isError).toBe(false);
+      expect(calls).toEqual([{ name: 'alpha', args: { x: '1' } }]);
+      expect(payloadOf(result)).toEqual({ tool: 'alpha', echo: { x: '1' } });
     });
 
-    /** 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 };
+    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' });
 
-    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']);
-        });
+      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);
     });
 
-    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' } }]);
-        });
+    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');
     });
 
-    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' });
-        });
+    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;
 
-    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');
-        });
+      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

@@ -1,26 +1,26 @@
 import { DyFM_Log } from '@futdevpro/fsm-dynamo';
 
 import {
-    DyNTS_Mcp_CallResult,
-    DyNTS_Mcp_ServerInfo,
-    DyNTS_Mcp_StartOptions,
-    DyNTS_Mcp_ToolDefinition,
+  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
+ * `DyNTS_Mcp_Server_ServiceBase` (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
+ * **Használat (consumer):** a consumer leszármazik (`extends DyNTS_Mcp_Server_ServiceBase`) + 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 {
+ * class My_McpServer extends DyNTS_Mcp_Server_ServiceBase {
  *   protected getServerInfo() { return { name: 'my-app', version: '1.0.0' }; }
  *   protected getTools() { return [readTool, writeTool]; }
  * }
@@ -30,10 +30,10 @@ import { DyNTS_Mcp_Adapter } from './dynts-mcp.adapter';
  * **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 {
+export abstract class DyNTS_Mcp_Server_ServiceBase {
 
-    /** 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;
+  /** 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.
@@ -52,15 +52,17 @@ export abstract class DyNTS_Mcp_ServerBase {
      * 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;
+      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;
     }
 
     /**
@@ -69,12 +71,13 @@ export abstract class DyNTS_Mcp_ServerBase {
      * 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}); `
+      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);
+      await this.startTransport(adapter, transport);
     }
 
     /**
@@ -82,9 +85,9 @@ export abstract class DyNTS_Mcp_ServerBase {
      * neveit adja (transport nélkül is determinisztikus).
      */
     public getAdvertisedToolNames(): string[] {
-        return this.adapter
-            ? this.adapter.getAdvertisedToolNames()
-            : this.getTools().map((tool) => tool.name);
+      return this.adapter
+        ? this.adapter.getAdvertisedToolNames()
+        : this.getTools().map((tool) => tool.name);
     }
 
     /**
@@ -93,14 +96,14 @@ export abstract class DyNTS_Mcp_ServerBase {
      * 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);
+      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();
-        }
+      if (this.adapter) {
+        await this.adapter.close();
+      }
     }
 
     /**
@@ -108,13 +111,15 @@ export abstract class DyNTS_Mcp_ServerBase {
      * 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}'.`);
-        }
+      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}'.`);
+      }
     }
 }