@frontmcp/sdk 0.2.5 → 0.3.0

package/README.md

@@ -4,7 +4,7 @@
 
 <strong>The TypeScript-first way to build production-grade MCP servers.</strong>
 
-*Made with ❤️ for TypeScript developers*
+_Made with ❤️ for TypeScript developers_
 
 [![NPM - @frontmcp/sdk](https://img.shields.io/npm/v/@frontmcp/sdk.svg?v=2)](https://www.npmjs.com/package/@frontmcp/sdk)
 [![Node](https://img.shields.io/badge/node-%3E%3D20.0.0-339933?logo=node.js&logoColor=white)](https://nodejs.org)
@@ -20,18 +20,17 @@ session/auth, and execution flow.
 
 ```ts
 // src/main.ts
-import {FrontMcp, LogLevel} from '@frontmcp/sdk';
+import { FrontMcp, LogLevel } from '@frontmcp/sdk';
 import HelloApp from './hello.app';
 
 @FrontMcp({
-  info: {name: 'Demo 🚀', version: '0.1.0'},
+  info: { name: 'Demo 🚀', version: '0.1.0' },
   apps: [HelloApp],
-  http: {port: 3001},
-  logging: {level: LogLevel.Info},
+  http: { port: 3001 },
+  logging: { level: LogLevel.Info },
 })
-export default class Server {
-}
-````
+export default class Server {}
+```
 
 ---
 
@@ -42,27 +41,27 @@ export default class Server {
 - [Why FrontMCP?](#why-frontmcp)
 - [Installation](#installation)
 - [Quickstart](#quickstart)
-    - [Minimal Server & App](#minimal-server--app)
-    - [Function and Class Tools](#function-and-class-tools)
-    - [Scripts & tsconfig](#scripts--tsconfig)
-    - [MCP Inspector](#mcp-inspector)
+  - [Minimal Server & App](#minimal-server--app)
+  - [Function and Class Tools](#function-and-class-tools)
+  - [Scripts & tsconfig](#scripts--tsconfig)
+  - [MCP Inspector](#mcp-inspector)
 - [Core Concepts](#core-concepts)
-    - [Servers](#servers)
-    - [Apps](#apps)
-    - [Tools](#tools)
-    - [Resources](#resources)
-    - [Prompts](#prompts)
-    - [Providers](#providers)
-    - [Adapters](#adapters)
-    - [Plugins](#plugins)
+  - [Servers](#servers)
+  - [Apps](#apps)
+  - [Tools](#tools)
+  - [Resources](#resources)
+  - [Prompts](#prompts)
+  - [Providers](#providers)
+  - [Adapters](#adapters)
+  - [Plugins](#plugins)
 - [Authentication](#authentication)
-    - [Remote OAuth](#remote-oauth)
-    - [Local OAuth](#local-oauth)
+  - [Remote OAuth](#remote-oauth)
+  - [Local OAuth](#local-oauth)
 - [Sessions & Transport](#sessions--transport)
 - [Logging Transports](#logging-transports)
 - [Deployment](#deployment)
-    - [Local Dev](#local-dev)
-    - [Production](#production)
+  - [Local Dev](#local-dev)
+  - [Production](#production)
 - [Version Alignment](#version-alignment)
 - [Contributing](#contributing)
 - [License](#license)
@@ -71,12 +70,12 @@ export default class Server {
 
 ## Why FrontMCP?
 
-* **TypeScript-native DX** — decorators, Zod validation, strong typing end-to-end
-* **Spec-aligned transports** — Streamable HTTP (GET/POST), streaming, sessions
-* **Scoped invoker + DI** — secure, composable execution with hooks
-* **Adapters & Plugins** — generate tools from OpenAPI; add cross-cutting behavior
-* **Auth** — remote OAuth (external IdP) or built-in local OAuth
-* **Logging** — pluggable log transports (console, JSONL, HTTP batch, …)
+- **TypeScript-native DX** — decorators, Zod validation, strong typing end-to-end
+- **Spec-aligned transports** — Streamable HTTP (GET/POST), streaming, sessions
+- **Scoped invoker + DI** — secure, composable execution with hooks
+- **Adapters & Plugins** — generate tools from OpenAPI; add cross-cutting behavior
+- **Auth** — remote OAuth (external IdP) or built-in local OAuth
+- **Logging** — pluggable log transports (console, JSONL, HTTP batch, …)
 
 ---
 
@@ -86,16 +85,8 @@ Choose your package manager:
 
 ```bash
 # npm
-npm i -E @frontmcp/sdk @frontmcp/core zod reflect-metadata
-npm i -D typescript tsx @types/node rimraf @modelcontextprotocol/inspector
-
-# yarn
-yarn add -E @frontmcp/sdk @frontmcp/core zod reflect-metadata
-yarn add -D typescript tsx @types/node rimraf @modelcontextprotocol/inspector
-
-# pnpm
-pnpm add -E @frontmcp/sdk @frontmcp/core zod reflect-metadata
-pnpm add -D typescript tsx @types/node rimraf @modelcontextprotocol/inspector
+npm install -S frontmcp @frontmcp/sdk zod reflect-metadata
+npm install -D typescript tsx @types/node rimraf @modelcontextprotocol/inspector
 ```
 
 > Requires **Node 20+**.
@@ -118,28 +109,30 @@ src/
 
 ```ts
 import 'reflect-metadata';
-import {FrontMcp, LogLevel} from '@frontmcp/sdk';
+import { FrontMcp, LogLevel } from '@frontmcp/sdk';
 import HelloApp from './hello.app';
 
 @FrontMcp({
-  info: {name: 'Hello MCP', version: '0.1.0'},
+  info: { name: 'Hello MCP', version: '0.1.0' },
   apps: [HelloApp],
-  http: {port: Number(process.env.PORT) || 3001},
-  logging: {level: LogLevel.Info},
+  http: { port: Number(process.env.PORT) || 3001 },
+  logging: { level: LogLevel.Info },
 })
-export default class Server {
-}
+export default class Server {}
 ```
 
 **`src/hello.app.ts`**
 
 ```ts
-import {App} from '@frontmcp/sdk';
+import { App } from '@frontmcp/sdk';
 import GreetTool from './tools/greet.tool';
 
-@App({id: 'hello', name: 'Hello', tools: [GreetTool]})
-export default class HelloApp {
-}
+@App({
+  id: 'hello',
+  name: 'Hello',
+  tools: [GreetTool],
+})
+export default class HelloApp {}
 ```
 
 ### Function and Class Tools
@@ -147,29 +140,29 @@ export default class HelloApp {
 **Function tool**
 
 ```ts
-import {tool} from '@frontmcp/sdk';
-import {z} from 'zod';
+import { tool } from '@frontmcp/sdk';
+import { z } from 'zod';
 
 export default tool({
   name: 'greet',
   description: 'Greets a user by name',
-  inputSchema: z.object({name: z.string()}),
-})(({name}) => `Hello, ${name}!`);
+  inputSchema: z.object({ name: z.string() }),
+})(({ name }) => `Hello, ${name}!`);
 ```
 
 **Class tool**
 
 ```ts
-import {Tool} from '@frontmcp/sdk';
-import {z} from 'zod';
+import { Tool } from '@frontmcp/sdk';
+import { z } from 'zod';
 
 @Tool({
   name: 'add',
   description: 'Add two numbers',
-  inputSchema: z.object({a: z.number(), b: z.number()}),
+  inputSchema: z.object({ a: z.number(), b: z.number() }),
 })
 export default class AddTool {
-  execute({a, b}: { a: number; b: number }) {
+  execute({ a, b }: { a: number; b: number }) {
     return a + b;
   }
 }
@@ -184,9 +177,7 @@ export default class AddTool {
   "compilerOptions": {
     "target": "ES2020",
     "module": "CommonJS",
-    "lib": [
-      "ES2020"
-    ],
+    "lib": ["ES2020"],
     "rootDir": "src",
     "outDir": "dist",
     "moduleResolution": "Node",
@@ -199,13 +190,8 @@ export default class AddTool {
     "emitDecoratorMetadata": true,
     "sourceMap": true
   },
-  "include": [
-    "src/**/*.ts"
-  ],
-  "exclude": [
-    "**/*.test.ts",
-    "**/__tests__/**"
-  ]
+  "include": ["src/**/*.ts"],
+  "exclude": ["**/*.test.ts", "**/__tests__/**"]
 }
 ```
 
@@ -218,11 +204,7 @@ export default class AddTool {
     "declaration": true,
     "sourceMap": false
   },
-  "exclude": [
-    "**/*.test.ts",
-    "**/__tests__/**",
-    "src/**/*.dev.ts"
-  ]
+  "exclude": ["**/*.test.ts", "**/__tests__/**", "src/**/*.dev.ts"]
 }
 ```
 
@@ -304,7 +286,7 @@ You can configure auth on the server (multi-app shared) or per app (isolated sco
 
 ```ts
 auth: {
-  type: 'remote', 
+  type: 'remote',
   name: 'frontegg',
   baseUrl: 'https://idp.example.com',
   dcrEnabled ? : boolean,
@@ -329,7 +311,7 @@ auth: {
 {
 auth: {
   type: 'local',
-  id: 'local', 
+  id: 'local',
   name: 'Local Auth',
   scopes?: string[],
   grantTypes?: ('authorization_code' | 'refresh_token')[],
@@ -355,9 +337,9 @@ session: {
 }
 ```
 
-* **Stateful**: server-side store for tokens; enables refresh; recommended for short-lived upstream tokens.
-* **Stateless**: tokens embedded in JWT; simpler but no silent refresh.
-* **Transport IDs**: `uuid` (per node) or `jwt` (signed; distributed setups).
+- **Stateful**: server-side store for tokens; enables refresh; recommended for short-lived upstream tokens.
+- **Stateless**: tokens embedded in JWT; simpler but no silent refresh.
+- **Transport IDs**: `uuid` (per node) or `jwt` (signed; distributed setups).
 
 ---
 
@@ -366,21 +348,22 @@ session: {
 Add custom log sinks via `@LogTransport`:
 
 ```ts
-import {LogTransport, LogTransportInterface, LogRecord} from '@frontmcp/sdk';
+import { LogTransport, LogTransportInterface, LogRecord } from '@frontmcp/sdk';
 
-@LogTransport({name: 'StructuredJson', description: 'JSONL to stdout'})
+@LogTransport({ name: 'StructuredJson', description: 'JSONL to stdout' })
 export class StructuredJsonTransport extends LogTransportInterface {
   log(rec: LogRecord): void {
     try {
-      process.stdout.write(JSON.stringify({
-        ts: rec.timestamp.toISOString(),
-        level: rec.levelName,
-        msg: String(rec.message),
-        prefix: rec.prefix || undefined,
-        args: (rec.args || []).map(String),
-      }) + '\n');
-    } catch {
-    }
+      process.stdout.write(
+        JSON.stringify({
+          ts: rec.timestamp.toISOString(),
+          level: rec.levelName,
+          msg: String(rec.message),
+          prefix: rec.prefix || undefined,
+          args: (rec.args || []).map(String),
+        }) + '\n',
+      );
+    } catch {}
   }
 }
 ```
@@ -389,8 +372,8 @@ Register:
 
 ```ts
 logging: {
-  level: LogLevel.Info, 
-  enableConsole: false, 
+  level: LogLevel.Info,
+  enableConsole: false,
   transports : [StructuredJsonTransport],
 }
 ```
@@ -410,15 +393,15 @@ yarn dev
 pnpm dev
 ```
 
-* HTTP default: `http.port` (e.g., 3001)
-* `http.entryPath` defaults to `''` (set to `/mcp` if you prefer)
+- HTTP default: `http.port` (e.g., 3001)
+- `http.entryPath` defaults to `''` (set to `/mcp` if you prefer)
 
 ---
 
 ## Version Alignment
 
-If versions drift, the runtime may throw a "version mismatch" error at boot. Keep `@frontmcp/sdk` and `@frontmcp/core`
-on the **same version** across your workspace.
+If versions drift, the runtime may throw a "version mismatch" error at boot. Keep `@frontmcp/*` on the **same version**
+across your workspace.
 
 ---
 
@@ -426,13 +409,12 @@ on the **same version** across your workspace.
 
 PRs welcome! Please:
 
-* Keep changes focused and tested
-* Run `typecheck`, `build`, and try **MCP Inspector** locally
-* Align `@frontmcp/*` versions in examples
+- Keep changes focused and tested
+- Run `typecheck`, `build`, and try **MCP Inspector** locally
+- Align `@frontmcp/*` versions in examples
 
 ---
 
 ## License
 
 See [LICENSE](./LICENSE).
-

package/package.json

@@ -1,6 +1,28 @@
 {
   "name": "@frontmcp/sdk",
-  "version": "0.2.5",
+  "version": "0.3.0",
+  "description": "FrontMCP SDK",
+  "author": "AgentFront <info@agentfront.dev>",
+  "homepage": "https://docs.agentfront.dev",
+  "license": "Apache-2.0",
+  "keywords": [
+    "mcp",
+    "dependency injection",
+    "sdk",
+    "adapters",
+    "plugins",
+    "agentfront",
+    "frontmcp",
+    "framework",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agentfront/frontmcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/agentfront/frontmcp/issues"
+  },
   "main": "./src/index.js",
   "types": "./src/index.d.ts",
   "exports": {
@@ -12,7 +34,7 @@
     }
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.19.1",
+    "@modelcontextprotocol/sdk": "^1.21.1",
     "axios": "^1.6.0",
     "ioredis": "^5.8.0",
     "jose": "^6.1.0",

package/src/adapter/adapter.instance.d.ts

@@ -0,0 +1,11 @@
+import { AdapterEntry, AdapterRecord, Reference } from '../common';
+import ProviderRegistry from '../provider/provider.registry';
+export declare class AdapterInstance extends AdapterEntry {
+    readonly deps: Set<Reference>;
+    readonly globalProviders: ProviderRegistry;
+    private tools;
+    private resources;
+    private prompts;
+    constructor(record: AdapterRecord, deps: Set<Reference>, globalProviders: ProviderRegistry);
+    protected initialize(): Promise<void>;
+}

package/src/adapter/adapter.instance.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdapterInstance = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("../common");
+const tool_registry_1 = tslib_1.__importDefault(require("../tool/tool.registry"));
+class AdapterInstance extends common_1.AdapterEntry {
+    deps;
+    globalProviders;
+    tools;
+    resources;
+    prompts;
+    constructor(record, deps, globalProviders) {
+        super(record);
+        this.deps = deps;
+        this.globalProviders = globalProviders;
+        this.ready = this.initialize();
+    }
+    async initialize() {
+        const depsTokens = [...this.deps];
+        const depsInstances = await Promise.all(depsTokens.map((t) => this.globalProviders.resolveBootstrapDep(t)));
+        const rec = this.record;
+        let adapter;
+        if (rec.kind === common_1.AdapterKind.CLASS) {
+            const klass = rec.useClass;
+            adapter = new klass(...depsInstances);
+        }
+        else if (rec.kind === common_1.AdapterKind.CLASS_TOKEN) {
+            const klass = rec.provide;
+            adapter = new klass(...depsInstances);
+        }
+        else if (rec.kind === common_1.AdapterKind.FACTORY) {
+            const deps = [...rec.inject()];
+            const args = [];
+            for (const d of deps)
+                args.push(await this.globalProviders.resolveBootstrapDep(d));
+            adapter = rec.useFactory(...args);
+        }
+        else if (rec.kind === common_1.AdapterKind.VALUE) {
+            adapter = rec.useValue;
+        }
+        else {
+            throw Error('Invalid adapter kind');
+        }
+        const result = await adapter.fetch();
+        this.tools = new tool_registry_1.default(this.globalProviders, result.tools ?? [], {
+            kind: 'adapter',
+            id: `${adapter.options.name}`,
+            ref: rec.provide,
+        });
+        // this.resources = new ResourceRegistry(this.globalProviders, result.resources ?? [], {
+        //   kind: 'adapter',
+        //   id: rec.metadata.id ?? rec.metadata.name,
+        //   ref: rec.provide,
+        // });
+        // this.prompts = new PromptRegistry(this.globalProviders, result.prompts ?? [], {
+        //   kind: 'adapter',
+        //   id: rec.metadata.id ?? rec.metadata.name,
+        //   ref: rec.provide,
+        // });
+        await this.tools.ready;
+    }
+}
+exports.AdapterInstance = AdapterInstance;
+//# sourceMappingURL=adapter.instance.js.map

package/src/adapter/adapter.instance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.instance.js","sourceRoot":"","sources":["../../../src/adapter/adapter.instance.ts"],"names":[],"mappings":";;;;AAAA,sCAOmB;AAEnB,kFAAiD;AAIjD,MAAa,eAAgB,SAAQ,qBAAY;IACtC,IAAI,CAAiB;IACrB,eAAe,CAAmB;IAEnC,KAAK,CAAe;IACpB,SAAS,CAAmB;IAC5B,OAAO,CAAiB;IAEhC,YAAY,MAAqB,EAAE,IAAoB,EAAE,eAAiC;QACxF,KAAK,CAAC,MAAM,CAAC,CAAC;QACd,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QAEvC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC;IACjC,CAAC;IAES,KAAK,CAAC,UAAU;QAExB,MAAM,UAAU,GAAG,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;QAClC,MAAM,aAAa,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,eAAe,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5G,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC;QACxB,IAAI,OAAyB,CAAC;QAC9B,IAAI,GAAG,CAAC,IAAI,KAAK,oBAAW,CAAC,KAAK,EAAE,CAAC;YACnC,MAAM,KAAK,GAAG,GAAG,CAAC,QAAe,CAAC;YAClC,OAAO,GAAG,IAAI,KAAK,CAAC,GAAG,aAAa,CAAC,CAAC;QACxC,CAAC;aAAM,IAAI,GAAG,CAAC,IAAI,KAAK,oBAAW,CAAC,WAAW,EAAE,CAAC;YAChD,MAAM,KAAK,GAAG,GAAG,CAAC,OAAc,CAAC;YACjC,OAAO,GAAG,IAAK,KAAmB,CAAC,GAAG,aAAa,CAAC,CAAC;QACvD,CAAC;aAAM,IAAI,GAAG,CAAC,IAAI,KAAK,oBAAW,CAAC,OAAO,EAAE,CAAC;YAC5C,MAAM,IAAI,GAAG,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;YAC/B,MAAM,IAAI,GAAU,EAAE,CAAC;YACvB,KAAK,MAAM,CAAC,IAAI,IAAI;gBAAE,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,CAAC,eAAe,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAAC;YACnF,OAAO,GAAG,GAAG,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC;QACpC,CAAC;aAAM,IAAI,GAAG,CAAC,IAAI,KAAK,oBAAW,CAAC,KAAK,EAAE,CAAC;YAC1C,OAAO,GAAG,GAAG,CAAC,QAAQ,CAAC;QACzB,CAAC;aAAM,CAAC;YACN,MAAM,KAAK,CAAC,sBAAsB,CAAC,CAAC;QACtC,CAAC;QAED,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,EAAE,CAAC;QAErC,IAAI,CAAC,KAAK,GAAG,IAAI,uBAAY,CAAC,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,KAAK,IAAI,EAAE,EAAE;YACtE,IAAI,EAAE,SAAS;YACf,EAAE,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE;YAC7B,GAAG,EAAE,GAAG,CAAC,OAAO;SACjB,CAAC,CAAC;QAEH,wFAAwF;QACxF,qBAAqB;QACrB,8CAA8C;QAC9C,sBAAsB;QACtB,MAAM;QAEN,kFAAkF;QAClF,qBAAqB;QACrB,8CAA8C;QAC9C,sBAAsB;QACtB,MAAM;QAEN,MAAM,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC;IAEzB,CAAC;CACF;AA9DD,0CA8DC","sourcesContent":["import {\n  AdapterEntry,\n  AdapterInterface,\n  AdapterKind,\n  AdapterRecord,\n  Ctor,\n  Reference,\n} from '../common';\nimport ProviderRegistry from '../provider/provider.registry';\nimport ToolRegistry from '../tool/tool.registry';\nimport ResourceRegistry from '../resource/resource.registry';\nimport PromptRegistry from '../prompt/prompt.registry';\n\nexport class AdapterInstance extends AdapterEntry {\n  readonly deps: Set<Reference>;\n  readonly globalProviders: ProviderRegistry;\n\n  private tools: ToolRegistry;\n  private resources: ResourceRegistry;\n  private prompts: PromptRegistry;\n\n  constructor(record: AdapterRecord, deps: Set<Reference>, globalProviders: ProviderRegistry) {\n    super(record);\n    this.deps = deps;\n    this.globalProviders = globalProviders;\n\n    this.ready = this.initialize();\n  }\n\n  protected async initialize() {\n\n    const depsTokens = [...this.deps];\n    const depsInstances = await Promise.all(depsTokens.map((t) => this.globalProviders.resolveBootstrapDep(t)));\n    const rec = this.record;\n    let adapter: AdapterInterface;\n    if (rec.kind === AdapterKind.CLASS) {\n      const klass = rec.useClass as any;\n      adapter = new klass(...depsInstances);\n    } else if (rec.kind === AdapterKind.CLASS_TOKEN) {\n      const klass = rec.provide as any;\n      adapter = new (klass as Ctor<any>)(...depsInstances);\n    } else if (rec.kind === AdapterKind.FACTORY) {\n      const deps = [...rec.inject()];\n      const args: any[] = [];\n      for (const d of deps) args.push(await this.globalProviders.resolveBootstrapDep(d));\n      adapter = rec.useFactory(...args);\n    } else if (rec.kind === AdapterKind.VALUE) {\n      adapter = rec.useValue;\n    } else {\n      throw Error('Invalid adapter kind');\n    }\n\n    const result = await adapter.fetch();\n\n    this.tools = new ToolRegistry(this.globalProviders, result.tools ?? [], {\n      kind: 'adapter',\n      id: `${adapter.options.name}`,\n      ref: rec.provide,\n    });\n\n    // this.resources = new ResourceRegistry(this.globalProviders, result.resources ?? [], {\n    //   kind: 'adapter',\n    //   id: rec.metadata.id ?? rec.metadata.name,\n    //   ref: rec.provide,\n    // });\n\n    // this.prompts = new PromptRegistry(this.globalProviders, result.prompts ?? [], {\n    //   kind: 'adapter',\n    //   id: rec.metadata.id ?? rec.metadata.name,\n    //   ref: rec.provide,\n    // });\n\n    await this.tools.ready;\n\n  }\n}"]}

package/src/adapter/adapter.regsitry.d.ts

@@ -0,0 +1,13 @@
+import 'reflect-metadata';
+import { AdapterEntry, AdapterRecord, AdapterRegistryInterface, AdapterType } from '../common';
+import ProviderRegistry from '../provider/provider.registry';
+import { RegistryAbstract, RegistryBuildMapResult } from '../regsitry';
+import { AdapterInstance } from './adapter.instance';
+export default class AdapterRegistry extends RegistryAbstract<AdapterInstance, AdapterRecord, AdapterType[]> implements AdapterRegistryInterface {
+    constructor(providers: ProviderRegistry, list: AdapterType[]);
+    protected buildMap(list: AdapterType[]): RegistryBuildMapResult<AdapterRecord>;
+    protected buildGraph(): void;
+    /** Instantiate adapters, run fetch/transform, and populate registries. */
+    protected initialize(): Promise<void>;
+    getAdapters(): AdapterEntry[];
+}

package/src/adapter/adapter.regsitry.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+require("reflect-metadata");
+const adapter_utils_1 = require("./adapter.utils");
+const token_utils_1 = require("../utils/token.utils");
+const regsitry_1 = require("../regsitry");
+const adapter_instance_1 = require("./adapter.instance");
+class AdapterRegistry extends regsitry_1.RegistryAbstract {
+    constructor(providers, list) {
+        super('AdapterRegistry', providers, list);
+    }
+    buildMap(list) {
+        const tokens = new Set();
+        const defs = new Map();
+        const graph = new Map();
+        for (const raw of list) {
+            const rec = (0, adapter_utils_1.normalizeAdapter)(raw);
+            const provide = rec.provide;
+            tokens.add(provide);
+            defs.set(provide, rec);
+            graph.set(provide, new Set());
+        }
+        return { tokens, defs, graph };
+    }
+    buildGraph() {
+        for (const token of this.tokens) {
+            const rec = this.defs.get(token);
+            const deps = (0, adapter_utils_1.adapterDiscoveryDeps)(rec);
+            for (const d of deps) {
+                if (!this.providers.get(d)) {
+                    throw new Error(`Adapter ${(0, token_utils_1.tokenName)(token)} depends on ${(0, token_utils_1.tokenName)(d)}, which is not registered.`);
+                }
+                this.graph.get(token).add(d);
+            }
+        }
+    }
+    /** Instantiate adapters, run fetch/transform, and populate registries. */
+    async initialize() {
+        const readyArr = [];
+        for (const token of this.tokens) {
+            const rec = this.defs.get(token);
+            const deps = this.graph.get(token);
+            const instance = new adapter_instance_1.AdapterInstance(rec, deps, this.providers);
+            this.instances.set(token, instance);
+            readyArr.push(instance.ready);
+        }
+        await Promise.all(readyArr);
+    }
+    getAdapters() {
+        return [...this.instances.values()];
+    }
+}
+exports.default = AdapterRegistry;
+//# sourceMappingURL=adapter.regsitry.js.map

package/src/adapter/adapter.regsitry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.regsitry.js","sourceRoot":"","sources":["../../../src/adapter/adapter.regsitry.ts"],"names":[],"mappings":";;AAAA,4BAA0B;AAE1B,mDAAyE;AACzE,sDAAiD;AAEjD,0CAAuE;AACvE,yDAAqD;AAErD,MAAqB,eAAgB,SAAQ,2BAA+D;IAE1G,YACE,SAA2B,EAC3B,IAAmB;QAEnB,KAAK,CAAC,iBAAiB,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;IAC5C,CAAC;IAGkB,QAAQ,CAAC,IAAmB;QAC7C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAS,CAAC;QAChC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAwB,CAAC;QAC7C,MAAM,KAAK,GAAG,IAAI,GAAG,EAAqB,CAAC;QAE3C,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YACvB,MAAM,GAAG,GAAG,IAAA,gCAAgB,EAAC,GAAG,CAAC,CAAC;YAClC,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC;YAC5B,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACpB,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC;YACvB,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;QAChC,CAAC;QAED,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IACjC,CAAC;IAGS,UAAU;QAClB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC;YAClC,MAAM,IAAI,GAAG,IAAA,oCAAoB,EAAC,GAAG,CAAC,CAAC;YAEvC,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;gBACrB,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC3B,MAAM,IAAI,KAAK,CAAC,WAAW,IAAA,uBAAS,EAAC,KAAK,CAAC,eAAe,IAAA,uBAAS,EAAC,CAAC,CAAC,4BAA4B,CAAC,CAAC;gBACtG,CAAC;gBACD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAChC,CAAC;QACH,CAAC;IACH,CAAC;IAED,0EAA0E;IAChE,KAAK,CAAC,UAAU;QAExB,MAAM,QAAQ,GAAoB,EAAE,CAAC;QACrC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;YAChC,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC;YAClC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAE,CAAC;YAEpC,MAAM,QAAQ,GAAG,IAAI,kCAAe,CAAC,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;YAEhE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;YACpC,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QAChC,CAAC;QACD,MAAM,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAE9B,CAAC;IAED,WAAW;QACT,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;IACtC,CAAC;CACF;AA7DD,kCA6DC","sourcesContent":["import 'reflect-metadata';\nimport { AdapterEntry, AdapterRecord, AdapterRegistryInterface, AdapterType, Token } from '../common';\nimport { adapterDiscoveryDeps, normalizeAdapter } from './adapter.utils';\nimport { tokenName } from '../utils/token.utils';\nimport ProviderRegistry from '../provider/provider.registry';\nimport { RegistryAbstract, RegistryBuildMapResult } from '../regsitry';\nimport { AdapterInstance } from './adapter.instance';\n\nexport default class AdapterRegistry extends RegistryAbstract<AdapterInstance, AdapterRecord, AdapterType[]> implements AdapterRegistryInterface {\n\n  constructor(\n    providers: ProviderRegistry,\n    list: AdapterType[],\n  ) {\n    super('AdapterRegistry', providers, list);\n  }\n\n\n  protected override buildMap(list: AdapterType[]): RegistryBuildMapResult<AdapterRecord> {\n    const tokens = new Set<Token>();\n    const defs = new Map<Token, AdapterRecord>();\n    const graph = new Map<Token, Set<Token>>();\n\n    for (const raw of list) {\n      const rec = normalizeAdapter(raw);\n      const provide = rec.provide;\n      tokens.add(provide);\n      defs.set(provide, rec);\n      graph.set(provide, new Set());\n    }\n\n    return { tokens, defs, graph };\n  }\n\n\n  protected buildGraph() {\n    for (const token of this.tokens) {\n      const rec = this.defs.get(token)!;\n      const deps = adapterDiscoveryDeps(rec);\n\n      for (const d of deps) {\n        if (!this.providers.get(d)) {\n          throw new Error(`Adapter ${tokenName(token)} depends on ${tokenName(d)}, which is not registered.`);\n        }\n        this.graph.get(token)!.add(d);\n      }\n    }\n  }\n\n  /** Instantiate adapters, run fetch/transform, and populate registries. */\n  protected async initialize(): Promise<void> {\n\n    const readyArr: Promise<void>[] = [];\n    for (const token of this.tokens) {\n      const rec = this.defs.get(token)!;\n      const deps = this.graph.get(token)!;\n\n      const instance = new AdapterInstance(rec, deps, this.providers);\n\n      this.instances.set(token, instance);\n      readyArr.push(instance.ready);\n    }\n    await Promise.all(readyArr);\n\n  }\n\n  getAdapters(): AdapterEntry[] {\n    return [...this.instances.values()];\n  }\n}\n"]}

package/src/adapter/adapter.utils.d.ts

@@ -0,0 +1,10 @@
+import { Token, AdapterMetadata, AdapterRecord, AdapterType } from '../common';
+export declare function collectAdapterMetadata(cls: AdapterType): AdapterMetadata;
+export declare function normalizeAdapter(item: AdapterType): AdapterRecord;
+/**
+ * For graph/cycle detection. Returns dependency tokens that should be graphed.
+ * - VALUE: no deps
+ * - FACTORY: only includes deps that are registered (others will be resolved)
+ * - CLASS / CLASS_TOKEN: deps come from the class constructor or static with(...)
+ */
+export declare function adapterDiscoveryDeps(rec: AdapterRecord): Token[];

package/src/adapter/adapter.utils.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectAdapterMetadata = collectAdapterMetadata;
+exports.normalizeAdapter = normalizeAdapter;
+exports.adapterDiscoveryDeps = adapterDiscoveryDeps;
+const common_1 = require("../common");
+const metadata_utils_1 = require("../utils/metadata.utils");
+const token_utils_1 = require("../utils/token.utils");
+function collectAdapterMetadata(cls) {
+    return Object.entries(common_1.FrontMcpAdapterTokens).reduce((metadata, [key, token]) => {
+        return Object.assign(metadata, {
+            [key]: (0, metadata_utils_1.getMetadata)(token, cls),
+        });
+    }, {});
+}
+function normalizeAdapter(item) {
+    if ((0, token_utils_1.isClass)(item)) {
+        const metadata = collectAdapterMetadata(item);
+        return { kind: common_1.AdapterKind.CLASS_TOKEN, provide: item, metadata };
+    }
+    if (item && typeof item === 'object') {
+        const { provide, useClass, useValue, useFactory, inject } = item;
+        if (!provide) {
+            const name = item?.name ?? '[object]';
+            throw new Error(`Adapter '${name}' is missing 'provide'.`);
+        }
+        if (useClass) {
+            if (!(0, token_utils_1.isClass)(useClass)) {
+                throw new Error(`'useClass' on adapter '${(0, token_utils_1.tokenName)(provide)}' must be a class.`);
+            }
+            return {
+                kind: common_1.AdapterKind.CLASS,
+                provide,
+                useClass,
+                metadata: item.metadata,
+            };
+        }
+        if (useFactory) {
+            if (typeof useFactory !== 'function') {
+                throw new Error(`'useFactory' on adapter '${(0, token_utils_1.tokenName)(provide)}' must be a function.`);
+            }
+            const inj = typeof inject === 'function' ? inject : () => [];
+            return {
+                kind: common_1.AdapterKind.FACTORY,
+                provide,
+                inject: inj,
+                useFactory,
+                metadata: item.metadata,
+            };
+        }
+        if ('useValue' in item) {
+            const metadata = collectAdapterMetadata(useValue.constructor);
+            return {
+                kind: common_1.AdapterKind.VALUE,
+                provide,
+                useValue,
+                metadata,
+            };
+        }
+    }
+    const name = item?.name ?? String(item);
+    throw new Error(`Invalid adapter '${name}'. Expected a class or a adapter object.`);
+}
+/**
+ * For graph/cycle detection. Returns dependency tokens that should be graphed.
+ * - VALUE: no deps
+ * - FACTORY: only includes deps that are registered (others will be resolved)
+ * - CLASS / CLASS_TOKEN: deps come from the class constructor or static with(...)
+ */
+function adapterDiscoveryDeps(rec) {
+    switch (rec.kind) {
+        case common_1.AdapterKind.VALUE:
+            return [];
+        case common_1.AdapterKind.FACTORY: {
+            return [...rec.inject()];
+        }
+        case common_1.AdapterKind.CLASS:
+            return (0, token_utils_1.depsOfClass)(rec.useClass, 'discovery');
+        case common_1.AdapterKind.CLASS_TOKEN:
+            return (0, token_utils_1.depsOfClass)(rec.provide, 'discovery');
+    }
+}
+//# sourceMappingURL=adapter.utils.js.map

package/src/adapter/adapter.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.utils.js","sourceRoot":"","sources":["../../../src/adapter/adapter.utils.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  Token,\n  AdapterMetadata,\n  FrontMcpAdapterTokens,\n  AdapterRecord,\n  AdapterType,\n  AdapterKind,\n} from '../common';\nimport { getMetadata } from '../utils/metadata.utils';\nimport { depsOfClass, isClass, tokenName } from '../utils/token.utils';\n\nexport function collectAdapterMetadata(cls: AdapterType): AdapterMetadata {\n  return Object.entries(FrontMcpAdapterTokens).reduce((metadata, [key, token]) => {\n    return Object.assign(metadata, {\n      [key]: getMetadata(token, cls),\n    });\n  }, {} as AdapterMetadata);\n}\n\nexport function normalizeAdapter(item: AdapterType): AdapterRecord {\n  if (isClass(item)) {\n    const metadata = collectAdapterMetadata(item);\n    return { kind: AdapterKind.CLASS_TOKEN, provide: item, metadata };\n  }\n  if (item && typeof item === 'object') {\n    const { provide, useClass, useValue, useFactory, inject } = item as any;\n\n    if (!provide) {\n      const name = (item as any)?.name ?? '[object]';\n      throw new Error(`Adapter '${name}' is missing 'provide'.`);\n    }\n\n    if (useClass) {\n      if (!isClass(useClass)) {\n        throw new Error(\n          `'useClass' on adapter '${tokenName(provide)}' must be a class.`,\n        );\n      }\n      return {\n        kind: AdapterKind.CLASS,\n        provide,\n        useClass,\n        metadata: (item as any).metadata,\n      };\n    }\n\n    if (useFactory) {\n      if (typeof useFactory !== 'function') {\n        throw new Error(\n          `'useFactory' on adapter '${tokenName(provide)}' must be a function.`,\n        );\n      }\n      const inj = typeof inject === 'function' ? inject : () => [] as const;\n      return {\n        kind: AdapterKind.FACTORY,\n        provide,\n        inject: inj,\n        useFactory,\n        metadata: (item as any).metadata,\n      };\n    }\n\n    if ('useValue' in item) {\n      const metadata = collectAdapterMetadata(useValue.constructor);\n      return {\n        kind: AdapterKind.VALUE,\n        provide,\n        useValue,\n        metadata,\n      };\n    }\n  }\n\n  const name = (item as any)?.name ?? String(item);\n  throw new Error(\n    `Invalid adapter '${name}'. Expected a class or a adapter object.`,\n  );\n}\n\n\n/**\n * For graph/cycle detection. Returns dependency tokens that should be graphed.\n * - VALUE: no deps\n * - FACTORY: only includes deps that are registered (others will be resolved)\n * - CLASS / CLASS_TOKEN: deps come from the class constructor or static with(...)\n */\nexport function adapterDiscoveryDeps(rec: AdapterRecord): Token[] {\n  switch (rec.kind) {\n    case AdapterKind.VALUE:\n      return [];\n\n    case AdapterKind.FACTORY: {\n      return [...rec.inject()];\n    }\n    case AdapterKind.CLASS:\n      return depsOfClass(rec.useClass, 'discovery');\n\n    case AdapterKind.CLASS_TOKEN:\n      return depsOfClass(rec.provide, 'discovery');\n\n  }\n}\n"]}