@futdevpro/nts-dynamo 1.15.98 → 1.15.100

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

@@ -1,125 +1,125 @@
-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_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_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_Server_ServiceBase {
- *   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_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;
-
-    /**
-     * 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;
-      }
+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_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_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_Server_ServiceBase {
+ *   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_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;
+
+    /**
+     * 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);
-      }
+
+      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();
+
+      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':
+
+      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}'.`);
-      }
-    }
-}
+
+        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

@@ -1,168 +1,168 @@
-// A `@modelcontextprotocol/sdk` ESM-only csomag; a deep subpath-importjai (server/index, server/stdio,
-// types) KÖTELEZŐEN `.js`-suffixet igényelnek (az SDK `exports`-map így oldja fel) — ezért a `no-js-import`
-// szabály ITT indokoltan kikapcsolva (C2, FAM-REV bedrock-fix). Suffix-strip → resolve-hiba.
-/* eslint-disable @futdevpro/dynamo/no-js-import */
-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';
-/* eslint-enable @futdevpro/dynamo/no-js-import */
-
-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_Server_ServiceBase` + 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.' } });
-    }
-  }
-}
+// A `@modelcontextprotocol/sdk` ESM-only csomag; a deep subpath-importjai (server/index, server/stdio,
+// types) KÖTELEZŐEN `.js`-suffixet igényelnek (az SDK `exports`-map így oldja fel) — ezért a `no-js-import`
+// szabály ITT indokoltan kikapcsolva (C2, FAM-REV bedrock-fix). Suffix-strip → resolve-hiba.
+/* eslint-disable @futdevpro/dynamo/no-js-import */
+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';
+/* eslint-enable @futdevpro/dynamo/no-js-import */
+
+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_Server_ServiceBase` + 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

@@ -1,13 +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_Server_ServiceBase`-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';
+
+
+// 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_Server_ServiceBase`-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';