@futdevpro/nts-dynamo 1.15.57 → 1.15.60

package/src/_modules/mcp/_models/interfaces/dynts-mcp.interface.ts

@@ -0,0 +1,111 @@
+/**
+ * MCP-réteg shared vokabulár (BFR-AM-003) — a domain-agnosztikus MCP-szerver-base + adaptor közös
+ * típusai. Egy fájlban a szorosan összetartozó tool-/transport-típusok (`*.interface.ts` az
+ * egy-export-per-file konvenció ismert kivétele a tightly-coupled shape-ekre).
+ *
+ * Boundary: a `DyNTS_McpToolDefinition` + a `DyNTS_Mcp_Adapter` egyetlen `registerTool` choke-pontot
+ * ad — a hivatalos `@modelcontextprotocol/sdk` KIZÁRÓLAG az adaptor mögött él, így egy jövőbeli
+ * transport-/SDK-csere NEM-breaking (csak az adaptor cserélődik, a `DyNTS_Mcp_Server_ServiceBase` + a
+ * consumer-tool-ok változatlanok). A consumer a SAJÁT tool-jait regisztrálja (a bedrock NEM definiál
+ * domain-tool-okat — csak a server-base + a transport + a registry).
+ */
+
+/**
+ * Egy JSON-schema fragment (a tool input-schema-jának típusa). Szabad-formájú JSON-objektum (a
+ * draft-07 / MCP tool-schema dialektusa); a `properties`/`required`/`type` mezők gyakoriak, de a
+ * shape nem kényszerített (az MCP-kliens a `tools/list`-ben kapja vissza, ahogy van).
+ */
+export interface DyNTS_Mcp_JsonSchema {
+    /** A JSON-schema gyökér-típusa (a tool input-ja jellemzően `object`). */
+    type: string;
+    /** A property-leírások (kulcs → al-schema). */
+    properties?: { [key: string]: DyNTS_Mcp_JsonSchema };
+    /** Kötelező property-nevek. */
+    required?: string[];
+    /** Array-elem schema (`type: 'array'` esetén). */
+    items?: DyNTS_Mcp_JsonSchema;
+    /** Enum-értékek (string/number/boolean literál-halmaz). */
+    enum?: (string | number | boolean)[];
+    /** Emberi leírás (a tool-választáshoz; az LLM ezt olvassa). */
+    description?: string;
+    /** Default érték (a kliens-hint). */
+    default?: unknown;
+    /** Engedi-e a nem-leírt property-ket (`object` schema-n). */
+    additionalProperties?: boolean;
+    /** Beágyazott `oneOf`/`anyOf` alternatívák. */
+    oneOf?: DyNTS_Mcp_JsonSchema[];
+}
+
+/**
+ * Egy MCP tool-handler kimenete (a transport-agnosztikus core ezt adja; az adaptor MCP-tool-result-tá
+ * fordítja). A `data` a strukturált JSON-payload; az `isError` jelzi a strukturált hibát — a néma
+ * hiba TILOS (a hiba MINDIG `isError:true` payload VAGY dobott exception, amit az adaptor egységesen
+ * `isError`-re fordít).
+ */
+export interface DyNTS_Mcp_ToolOutcome {
+    /** A strukturált eredmény-payload (a tool output-shape JSON-ja). */
+    data: unknown;
+    /** `true`, ha a kimenet strukturált hiba — az adaptor `isError`-re fordítja. */
+    isError?: boolean;
+}
+
+/**
+ * Egy tool-handler aláírása. Az `args` a nyers tool-argumentumok (JSON); a handler a saját
+ * input-shape-jére validál + a `DyNTS_Mcp_ToolOutcome`-ot adja. A hibát NEM nyeli el (strukturált
+ * hiba-payload `isError:true`-val VAGY dobott exception, amit az adaptor egységes MCP-error-ré fordít).
+ */
+export type DyNTS_Mcp_ToolHandler = (args: unknown) => Promise<DyNTS_Mcp_ToolOutcome>;
+
+/**
+ * Egy MCP tool-definíció (a `registerTool` egységes shape-je). A consumer ezt a shape-et használja az
+ * advertised halmazba (`name`+`description`+`inputSchema`+`handler`). A `tools/list` a regisztrált
+ * tool-ok `name`/`description`/`inputSchema`-ját hirdeti.
+ */
+export interface DyNTS_Mcp_ToolDefinition {
+    /** A tool neve (a `tools/list`-ben + a `tools/call` dispatch-kulcsa — UNIK kell legyen). */
+    name: string;
+    /** Agent-barát leírás (mikor melyik tool; az LLM ezt olvassa a tool-választáshoz). */
+    description: string;
+    /** A tool input JSON-schema-ja (a `tools/list` ezt hirdeti). */
+    inputSchema: DyNTS_Mcp_JsonSchema;
+    /** A handler (a transport-agnosztikus core-logika). */
+    handler: DyNTS_Mcp_ToolHandler;
+}
+
+/**
+ * Az MCP-szerver identitása (a SDK `serverInfo`-ja). A `name`/`version` a kliensnek hirdetett.
+ */
+export interface DyNTS_Mcp_ServerInfo {
+    /** A szerver neve (a kliensnek hirdetett `serverInfo.name`). */
+    name: string;
+    /** A szerver verziója (a kliensnek hirdetett `serverInfo.version`). */
+    version: string;
+}
+
+/**
+ * A támogatott transport-fajták. MVP: `stdio` (a JSON-RPC a stdin/stdout-on). A `start({transport})`
+ * ezzel választ — egy jövőbeli transport (pl. `http`/`sse`) NON-breaking módon bővíthető (csak az
+ * adaptor `start`-ja kap új ágat; a server-base + a tool-ok változatlanok).
+ */
+export type DyNTS_Mcp_TransportKind = 'stdio';
+
+/**
+ * A `start()` opciói. A `transport` választja a csatornát (default `stdio`).
+ */
+export interface DyNTS_Mcp_StartOptions {
+    /** A transport-csatorna (default `stdio`). */
+    transport?: DyNTS_Mcp_TransportKind;
+}
+
+/**
+ * Egy MCP `tools/call` strukturált eredménye (a transport-payload shape-je). Az adaptor ezt termeli;
+ * a `content` egy text-JSON blokk, az `isError` a strukturált-hiba jelzés. Ez a SDK
+ * `CallToolResult`-tal wire-kompatibilis al-shape (a SDK-t az adaptor izolálja, ezért itt a saját,
+ * SDK-független shape él).
+ */
+export interface DyNTS_Mcp_CallResult {
+    /** A tartalom-blokkok (MVP: egyetlen `text`-JSON blokk). */
+    content: { type: 'text'; text: string }[];
+    /** `true`, ha a hívás strukturált hibával végződött (no-silent-failure). */
+    isError?: boolean;
+}

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

@@ -0,0 +1,151 @@
+import { DyNTS_Mcp_Server_ServiceBase } 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_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,
+ *   - `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_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' ]);
+    });
+
+    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,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;
+      }
+      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,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.' } });
+    }
+  }
+}

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_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';

package/src/_modules/scoped-config/_enums/dynts-scoped-config-level.enum.ts

@@ -0,0 +1,22 @@
+
+/**
+ * `DyNTS_ScopedConfig_Level` — a DB-backed scoped config feloldási-szintjei (BFR-AM-004).
+ *
+ * A precedencia: **scope (leaf→root) > table > global > builtin-default**. Egy `DyNTS_ScopedConfig`
+ * dokumentum mindig pontosan EGY szinten él; a `level` + `tableScope` + `scopeId` hármas adja a
+ * feloldási-kulcsot (a `key`-vel együtt a logikai unique-constraint).
+ *
+ * **Domain-agnosztikus:** a konkrét table-/scope-nevek a fogyasztó dolga; a bedrock csak a generikus
+ * precedencia-engine + a tárolás szintjeit definiálja (a katalógus/kulcsok NEM ide tartoznak).
+ */
+export enum DyNTS_ScopedConfig_Level {
+
+  /** Rendszer-szintű default (a legalacsonyabb precedencia a builtin felett). */
+  global = 'global',
+
+  /** Egy adott logikai tár/táblázat szintje (`tableScope` kötelező). */
+  table = 'table',
+
+  /** A legspecifikusabb szint: egy konkrét scope-entitás (`tableScope` + `scopeId` kötelező). */
+  scope = 'scope',
+}

package/src/_modules/scoped-config/_models/data-models/dynts-scoped-config.data-model.ts

@@ -0,0 +1,82 @@
+
+import { DyFM_DataModel_Params, DyFM_Metadata, DyFM_Object } from '@futdevpro/fsm-dynamo';
+
+import { DyNTS_ScopedConfig_Level } from '../../_enums/dynts-scoped-config-level.enum';
+
+/**
+ * `DyNTS_ScopedConfig` entitás (BFR-AM-004) — egy dokumentum = **egy setting-érték egy adott szinten**.
+ * A `level` + `tableScope` + `scopeId` hármas adja a feloldási-kulcsot (a `key`-vel együtt a logikai
+ * unique-constraint); a precedencia: **scope (leaf→root) > table > global > builtin-default**.
+ *
+ * `extends DyFM_Metadata`: az identitás/metadata (`_id`, `__created`, `__lastModified`, `_deleted`)
+ * az ősből jön; a `_deleted` soft-delete marker (Date), amit a `DyNTS_ArchiveDataService` kezel — ez
+ * a felülírás-history alapja (egy `set` a régi aktív rekordot archiválja, az újat aktívan írja).
+ *
+ * **Domain-agnosztikus:** a `key` `string`, a `value` `unknown` (Mongoose `Mixed`, séma-szinten
+ * `type:'object'`). A bedrock NEM validál séma-szinten — a típushelyesség / katalógus a FOGYASZTÓ
+ * dolga. A `value` írása **`$set`-tel atomikus** (Mongoose Mixed silent-drop ellen — lásd
+ * `DyNTS_ScopedConfig_DataService.setValue`).
+ */
+export class DyNTS_ScopedConfig extends DyFM_Metadata {
+
+  // --- a feloldási kulcs ---
+
+  /** A feloldási-szint (`global`|`table`|`scope`). */
+  level?: DyNTS_ScopedConfig_Level;
+
+  /** `level='table'|'scope'` esetén kötelező: melyik logikai tár. */
+  tableScope?: string;
+
+  /** `level='scope'` esetén kötelező: a scope-entitás logikai azonosítója. */
+  scopeId?: string;
+
+  // --- a setting maga ---
+
+  /** A config-kulcs (a fogyasztó katalógusából; string-ként perzistált). */
+  key?: string;
+
+  /** A setting-érték; típusa a fogyasztó katalógusa szerint. Mongoose `Mixed`. */
+  value?: unknown;
+
+  // --- audit ---
+
+  /** Ki/mi állította be (audit). */
+  setBy?: string;
+
+  /** Beállítás-részlet (pl. preset-név, CLI-user). */
+  setByDetail?: string;
+
+  /** Opcionális indoklás. */
+  note?: string;
+
+  constructor(set?: Partial<DyNTS_ScopedConfig>) {
+    super(set);
+
+    if (set) {
+      DyFM_Object.cleanAssign(this, set);
+    }
+  }
+}
+
+/**
+ * MongoDB data-params a `dynts_scoped_config` collection-höz (BFR-AM-004). `addArchive: true` → a
+ * felülírt (régi) értékek soft-delete-elve megőrződnek (audit-trail / history).
+ *
+ * A `value` `type:'object'` (Mongoose `Mixed`) — a séma NEM validál; a típushelyesség a fogyasztó
+ * katalógusának + set-kori validációjának dolga.
+ */
+export const DyNTS_scopedConfig_dataParams: DyFM_DataModel_Params<DyNTS_ScopedConfig> =
+  new DyFM_DataModel_Params<DyNTS_ScopedConfig>({
+    dataName: 'dynts_scoped_config',
+    addArchive: true,
+    properties: {
+      level: { type: 'string', index: true, required: true },
+      tableScope: { type: 'string', index: true },
+      scopeId: { type: 'string', index: true },
+      key: { type: 'string', index: true, required: true },
+      value: { type: 'object' },
+      setBy: { type: 'string', index: true },
+      setByDetail: { type: 'string' },
+      note: { type: 'string' },
+    },
+  });