@frontmcp/sdk 0.3.1 → 0.4.0

package/README.md

@@ -1,13 +1,18 @@
 <div align="center">
 
-# FrontMCP 🚀
+<picture>
+  <source width="400" media="(prefers-color-scheme: dark)" srcset="docs/assets/logo/frontmcp.dark.svg">
+  <source width="400" media="(prefers-color-scheme: light)" srcset="docs/assets/logo/frontmcp.light.svg">
+  <img width="400" alt="FrontMCP Logo" src="docs/assets/logo/frontmcp.light.svg">
+</picture>
+<hr>
 
-<strong>The TypeScript-first way to build production-grade MCP servers.</strong>
+<strong>The TypeScript way to build MCP servers with decorators, DI, and Streamable HTTP.</strong>
 
 _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)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-339933?logo=node.js&logoColor=white)](https://nodejs.org)
 [![License](https://img.shields.io/github/license/agentfront/frontmcp.svg?v=1)](https://github.com/agentfront/frontmcp/blob/main/LICENSE)
 
 </div>
@@ -15,18 +20,18 @@ _Made with ❤️ for TypeScript developers_
 ---
 
 FrontMCP is a **TypeScript-first framework** for the [Model Context Protocol (MCP)](https://modelcontextprotocol.io).
-You describe servers, apps, tools, resources, and prompts with decorators; FrontMCP handles protocol, transport, DI,
-session/auth, and execution flow.
+You write clean, typed code; FrontMCP handles the protocol, transport, DI, session/auth, and execution flow.
 
 ```ts
 // src/main.ts
+import 'reflect-metadata';
 import { FrontMcp, LogLevel } from '@frontmcp/sdk';
 import HelloApp from './hello.app';
 
 @FrontMcp({
   info: { name: 'Demo 🚀', version: '0.1.0' },
   apps: [HelloApp],
-  http: { port: 3001 },
+  http: { port: 3000 },
   logging: { level: LogLevel.Info },
 })
 export default class Server {}
@@ -41,24 +46,24 @@ export default class Server {}
 - [Why FrontMCP?](#why-frontmcp)
 - [Installation](#installation)
 - [Quickstart](#quickstart)
-  - [Minimal Server & App](#minimal-server--app)
+  - [1) Create Your FrontMCP Server](#1-create-your-frontmcp-server)
+  - [2) Define an App](#2-define-an-app)
+  - [3) Add Your First Tool](#3-add-your-first-tool)
+  - [4) Run It](#4-run-it)
   - [Function and Class Tools](#function-and-class-tools)
   - [Scripts & tsconfig](#scripts--tsconfig)
-  - [MCP Inspector](#mcp-inspector)
+  - [Inspector](#inspector)
 - [Core Concepts](#core-concepts)
   - [Servers](#servers)
   - [Apps](#apps)
   - [Tools](#tools)
   - [Resources](#resources)
   - [Prompts](#prompts)
-  - [Providers](#providers)
-  - [Adapters](#adapters)
-  - [Plugins](#plugins)
+  - [Providers / Adapters / Plugins](#providers--adapters--plugins)
 - [Authentication](#authentication)
   - [Remote OAuth](#remote-oauth)
   - [Local OAuth](#local-oauth)
 - [Sessions & Transport](#sessions--transport)
-- [Logging Transports](#logging-transports)
 - [Deployment](#deployment)
   - [Local Dev](#local-dev)
   - [Production](#production)
@@ -70,73 +75,121 @@ 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
+- **TypeScript-native DX** — decorators, Zod, and strong typing end-to-end
 - **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, …)
+- **Adapters & Plugins** — extend your server without boilerplate
+- **Spec-aligned transport** — Streamable HTTP for modern MCP clients
 
 ---
 
 ## Installation
 
-Choose your package manager:
+**Prereqs:** Node.js ≥ 22, npm ≥ 10. ([Installation - FrontMCP][1])
+
+### Option A — New project (recommended)
+
+```bash
+npx frontmcp create my-app
+```
+
+This scaffolds a FrontMCP project, writes a modern ESM `tsconfig.json` for decorators, adds helpful package scripts, and
+installs required dev deps. ([Installation - FrontMCP][1])
+
+### Option B — Add to an existing project
 
 ```bash
-# npm
-npm install -S frontmcp @frontmcp/sdk zod reflect-metadata
-npm install -D typescript tsx @types/node rimraf @modelcontextprotocol/inspector
+npm i -D frontmcp @types/node@^20
+npx frontmcp init
 ```
 
-> Requires **Node 20+**.
+`init` adds scripts, verifies your `tsconfig.json`, and checks layout. No need to install `@frontmcp/sdk` directly—the
+CLI bundles a compatible SDK for you. ([Installation - FrontMCP][1])
 
 ---
 
 ## Quickstart
 
-### Minimal Server & App
-
-```
-src/
-  main.ts
-  hello.app.ts
-  tools/
-    greet.tool.ts
-```
+If you haven’t installed FrontMCP yet, follow the [installation guide][1] first.
 
-**`src/main.ts`**
+### 1) Create Your FrontMCP Server
 
 ```ts
-import 'reflect-metadata';
+// src/main.ts
 import { FrontMcp, LogLevel } from '@frontmcp/sdk';
 import HelloApp from './hello.app';
 
 @FrontMcp({
   info: { name: 'Hello MCP', version: '0.1.0' },
   apps: [HelloApp],
-  http: { port: Number(process.env.PORT) || 3001 },
-  logging: { level: LogLevel.Info },
+  http: { port: 3000 },
+  logging: { level: LogLevel.INFO },
 })
-export default class Server {}
+export default class HelloServer {}
 ```
 
-**`src/hello.app.ts`**
+### 2) Define an App
 
 ```ts
+// src/hello.app.ts
 import { App } from '@frontmcp/sdk';
 import GreetTool from './tools/greet.tool';
 
 @App({
   id: 'hello',
-  name: 'Hello',
+  name: 'Hello App',
   tools: [GreetTool],
 })
 export default class HelloApp {}
 ```
 
+### 3) Add Your First Tool
+
+```ts
+// src/tools/greet.tool.ts
+import { Tool } from '@frontmcp/sdk';
+import { z } from 'zod';
+
+@Tool({
+  name: 'greet',
+  description: 'Greets a user by name',
+  inputSchema: { name: z.string() },
+})
+export default class GreetTool {
+  async execute({ name }: { name: string }) {
+    return `Hello, ${name}!`;
+  }
+}
+```
+
+### 4) Run It
+
+Add scripts (if you didn't use `frontmcp create`):
+
+```json
+{
+  "scripts": {
+    "dev": "frontmcp dev",
+    "build": "frontmcp build",
+    "start": "node dist/main.js"
+  }
+}
+```
+
+Then:
+
+```bash
+npm run dev
+# Server listening on http://localhost:3000
+```
+
+> **Tip:** FrontMCP speaks **MCP Streamable HTTP**. Connect any MCP-capable client and call `greet` with
+> `{"name": "Ada"}`. ([Quickstart - FrontMCP][2])
+
 ### Function and Class Tools
 
+Tools are typed actions with Zod schemas. Implement them as classes with `@Tool({...})` or inline via `tool()`. Pass
+**Zod fields directly** (no `z.object({...})`). ([Tools - FrontMCP][4])
+
 **Function tool**
 
 ```ts
@@ -146,7 +199,7 @@ import { z } from 'zod';
 export default tool({
   name: 'greet',
   description: 'Greets a user by name',
-  inputSchema: z.object({ name: z.string() }),
+  inputSchema: { name: z.string() }, // shape, not z.object
 })(({ name }) => `Hello, ${name}!`);
 ```
 
@@ -159,10 +212,10 @@ import { z } from 'zod';
 @Tool({
   name: 'add',
   description: 'Add two numbers',
-  inputSchema: z.object({ a: z.number(), b: z.number() }),
+  inputSchema: { a: z.number(), b: z.number() },
 })
 export default class AddTool {
-  execute({ a, b }: { a: number; b: number }) {
+  async execute({ a, b }: { a: number; b: number }) {
     return a + b;
   }
 }
@@ -170,22 +223,37 @@ export default class AddTool {
 
 ### Scripts & tsconfig
 
-**`tsconfig.json`**
+After `create` or `init`, you’ll have:
+
+```json
+{
+  "scripts": {
+    "dev": "frontmcp dev",
+    "build": "frontmcp build",
+    "inspect": "frontmcp inspector",
+    "doctor": "frontmcp doctor"
+  }
+}
+```
+
+These map to dev watch, production build, zero‑setup Inspector launch, and environment checks. ([Installation -
+FrontMCP][1])
+
+**Recommended `tsconfig.json` (ESM + decorators)**
 
 ```json
 {
   "compilerOptions": {
-    "target": "ES2020",
-    "module": "CommonJS",
-    "lib": ["ES2020"],
+    "target": "es2021",
+    "module": "esnext",
+    "lib": ["es2021"],
+    "moduleResolution": "bundler",
     "rootDir": "src",
     "outDir": "dist",
-    "moduleResolution": "Node",
     "strict": true,
     "esModuleInterop": true,
-    "forceConsistentCasingInFileNames": true,
-    "skipLibCheck": true,
     "resolveJsonModule": true,
+    "skipLibCheck": true,
     "experimentalDecorators": true,
     "emitDecoratorMetadata": true,
     "sourceMap": true
@@ -195,7 +263,9 @@ export default class AddTool {
 }
 ```
 
-**`tsconfig.build.json`**
+This mirrors what `init` writes for you. ([Local Dev Server - FrontMCP][3])
+
+**Optional `tsconfig.build.json`**
 
 ```json
 {
@@ -208,79 +278,55 @@ export default class AddTool {
 }
 ```
 
-**`package.json` (scripts)**
-
-```json
-{
-  "scripts": {
-    "dev": "tsx watch src/main.ts",
-    "start:dev": "tsx src/main.ts",
-    "build": "tsc -p tsconfig.build.json",
-    "start": "node dist/main.js",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
-    "clean": "rimraf dist",
-    "inspect:dev": "npx @modelcontextprotocol/inspector tsx src/main.ts",
-    "inspect:dist": "npx @modelcontextprotocol/inspector node dist/main.js"
-  }
-}
-```
-
-> Always import **`reflect-metadata` first** in your entry to enable decorator metadata.
-
-### MCP Inspector
+### Inspector
 
-Debug your server with a browser UI:
+Run a browser UI to exercise tools and messages:
 
 ```bash
-# Dev (runs TS)
-npm run inspect:dev
-# Dist (runs built JS)
-npm run inspect:dist
+npm run inspect
 ```
 
+This launches the MCP Inspector; point it at your local server (e.g., `http://localhost:3000`). ([Local Dev Server -
+FrontMCP][3])
+
 ---
 
 ## Core Concepts
 
 ### Servers
 
-The decorated entry (`@FrontMcp`) defines server **info**, **apps**, **http**, **logging**, **session**, optional **auth
-**, and shared **providers**.
+`@FrontMcp({...})` defines **info**, **apps**, **http**, **logging**, **session**, and optional **auth**. Keep it
+minimal or scale up with providers and plugins. ([The FrontMCP Server - FrontMCP][5])
 
 ### Apps
 
-Use `@App` to group **tools**, **resources**, **prompts**, **providers**, **adapters**, and **plugins**. With
-`splitByApp: true`, each app has its own scope/base path and (optionally) its own auth.
+Use `@App` to group **tools**, **resources**, **prompts**, plus **providers**, **adapters**, and **plugins**. With
+`splitByApp: true`, each app gets its own scope/base path and, if needed, its own auth surface. ([Apps - FrontMCP][6])
 
 ### Tools
 
-Active actions with input/output schemas. Use class tools (`@Tool`) or function tools (`tool({...})(handler)`).
+Typed actions with schemas (class `@Tool` or inline `tool({...})(handler)`). Use the Zod‑field **shape** style for
+`inputSchema`. ([Tools - FrontMCP][4])
 
 ### Resources
 
-Expose read-only data by URI. Define with `@Resource` or `resource(...)` (see docs).
+Readable data by URI or RFC6570 template (see `@Resource` / `@ResourceTemplate`). ([Resources - FrontMCP][7])
 
 ### Prompts
 
-Reusable prompt templates (`@Prompt` / `prompt(...)`) supplying arguments for LLM interactions.
+Reusable templates returning MCP `GetPromptResult`, with typed arguments. ([Prompts - FrontMCP][8])
 
-### Providers
+### Providers / Adapters / Plugins
 
-Dependency-injected singletons for config/DB/Redis/KMS/etc., with scopes: **GLOBAL**, **SESSION**, **REQUEST**.
-
-### Adapters
-
-Generate tools/resources/prompts from external definitions (e.g., **OpenAPI**).
-
-### Plugins
-
-Cross-cutting behavior (caching, tracing, policy). Plugins can contribute providers/adapters/tools/resources/prompts.
+Inject shared services, generate tools from OpenAPI, and add cross‑cutting behavior like caching and hooks. ([Add
+OpenAPI Adapter - FrontMCP][9])
 
 ---
 
 ## Authentication
 
-You can configure auth on the server (multi-app shared) or per app (isolated scopes).
+Configure auth at the **server** (shared) or **per app** (isolated). With `splitByApp: true`, define auth **per app**
+(server‑level `auth` is disallowed). ([Authentication - FrontMCP][10])
 
 ### Remote OAuth
 
@@ -289,26 +335,27 @@ auth: {
   type: 'remote',
   name: 'frontegg',
   baseUrl: 'https://idp.example.com',
-  dcrEnabled ? : boolean,
-  clientId ? : string | ((info: { clientId: string }) => string),
-  mode ? : 'orchestrated' | 'transparent',
-  allowAnonymous ? : boolean,
-  consent ? : boolean,
-  scopes ? : string[],
-  grantTypes ? : ('authorization_code' | 'refresh_token')[],
-  authEndpoint ? : string,
-  tokenEndpoint ? : string,
-  registrationEndpoint ? : string,
-  userInfoEndpoint ? : string,
-  jwks ? : JSONWebKeySet,
-  jwksUri ? : string
+  dcrEnabled?: boolean,
+  clientId?: string | ((info: { clientId: string }) => string),
+  mode?: 'orchestrated' | 'transparent',
+  allowAnonymous?: boolean,
+  consent?: boolean,
+  scopes?: string[],
+  grantTypes?: ('authorization_code' | 'refresh_token')[],
+  authEndpoint?: string,
+  tokenEndpoint?: string,
+  registrationEndpoint?: string,
+  userInfoEndpoint?: string,
+  jwks?: JSONWebKeySet,
+  jwksUri?: string
 }
 ```
 
+See **Authentication → Remote OAuth** for full details and DCR vs non‑DCR. ([Remote OAuth - FrontMCP][11])
+
 ### Local OAuth
 
 ```ts
-{
 auth: {
   type: 'local',
   id: 'local',
@@ -322,7 +369,7 @@ auth: {
 }
 ```
 
-> With `splitByApp: true`, define auth **per `@App`** (server-level `auth` is disallowed).
+Use per‑app when isolating scopes. ([Local OAuth - FrontMCP][12])
 
 ---
 
@@ -330,91 +377,72 @@ auth: {
 
 ```ts
 session: {
-  sessionMode ? : 'stateful' | 'stateless' | ((issuer) =>
-...), // default 'stateless'
-  transportIdMode ? : 'uuid' | 'jwt' | ((issuer) =>
-...),       // default 'uuid'
+  sessionMode?: 'stateful' | 'stateless' | ((issuer) => ...), // default 'stateless'
+  transportIdMode?: 'uuid' | 'jwt' | ((issuer) => ...),       // default 'uuid'
 }
 ```
 
-- **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 (e.g., Redis); supports refresh; best for short‑lived upstream tokens.
+- **Stateless**: embeds session in JWT; simpler but no silent refresh.
+- **Transport IDs**: `uuid` (per node) or `jwt` (signed; distributed setups). ([The FrontMCP Server - FrontMCP][5])
 
 ---
 
-## Logging Transports
-
-Add custom log sinks via `@LogTransport`:
-
-```ts
-import { LogTransport, LogTransportInterface, LogRecord } from '@frontmcp/sdk';
-
-@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 {}
-  }
-}
-```
+## Deployment
 
-Register:
+### Local Dev
 
-```ts
-logging: {
-  level: LogLevel.Info,
-  enableConsole: false,
-  transports : [StructuredJsonTransport],
-}
+```bash
+npm run dev
 ```
 
----
+- Default HTTP port: `3000` unless configured
+- `npm run doctor` checks Node/npm versions, `tsconfig`, and scripts. ([Local Dev Server - FrontMCP][3])
 
-## Deployment
-
-### Local Dev
+### Production
 
 ```bash
-# npm
-npm run dev
-# yarn
-yarn dev
-# pnpm
-pnpm dev
+npm run build
+NODE_ENV=production PORT=8080 npm start
 ```
 
-- HTTP default: `http.port` (e.g., 3001)
-- `http.entryPath` defaults to `''` (set to `/mcp` if you prefer)
+Builds to `dist/` (uses `tsconfig.build.json`). Consider a process manager and reverse proxy; align all `@frontmcp/*`
+versions. ([Production Build - FrontMCP][13])
 
 ---
 
 ## Version Alignment
 
-If versions drift, the runtime may throw a "version mismatch" error at boot. Keep `@frontmcp/*` on the **same version**
-across your workspace.
+If versions drift, the runtime will throw a clear **“version mismatch”** at boot. Keep `@frontmcp/*` versions aligned.
+([Production Build - FrontMCP][13])
 
 ---
 
 ## Contributing
 
-PRs welcome! Please:
-
-- Keep changes focused and tested
-- Run `typecheck`, `build`, and try **MCP Inspector** locally
-- Align `@frontmcp/*` versions in examples
+- PRs welcome! Read the full [CONTRIBUTING.md](./CONTRIBUTING.md) for workflow details, coding standards, and the PR
+  checklist.
+- Keep changes focused, add/adjust Jest specs, and update docs/snippets when behavior changes.
+- Before opening a PR run `yarn nx run-many -t lint,test,build`, `npx frontmcp doctor`, and verify the demo/Inspector
+  flows relevant to your change.
+- Align `@frontmcp/*` versions in examples to avoid runtime version mismatches.
 
 ---
 
 ## License
 
 See [LICENSE](./LICENSE).
+
+[1]: https://docs.agentfront.dev/docs/getting-started/installation 'Installation - FrontMCP'
+[2]: https://docs.agentfront.dev/docs/getting-started/quickstart 'Quickstart - FrontMCP'
+[3]: https://docs.agentfront.dev/docs/deployment/local-dev-server 'Local Dev Server - FrontMCP'
+[4]: https://docs.agentfront.dev/docs/servers/tools 'Tools - FrontMCP'
+[5]: https://docs.agentfront.dev/docs/servers/server 'The FrontMCP Server - FrontMCP'
+[6]: https://docs.agentfront.dev/docs/servers/apps 'Apps - FrontMCP'
+[7]: https://docs.agentfront.dev/docs/servers/resources 'Resources - FrontMCP'
+[8]: https://docs.agentfront.dev/docs/servers/prompts 'Prompts - FrontMCP'
+[9]: https://docs.agentfront.dev/docs/guides/add-openapi-adapter 'Add OpenAPI Adapter - FrontMCP'
+[10]: https://docs.agentfront.dev/docs/servers/authentication/overview 'Authentication - FrontMCP'
+[11]: https://docs.agentfront.dev/docs/servers/authentication/remote 'Remote OAuth - FrontMCP'
+[12]: https://docs.agentfront.dev/docs/servers/authentication/local 'Local OAuth - FrontMCP'
+[13]: https://docs.agentfront.dev/docs/deployment/production-build 'Production Build - FrontMCP'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontmcp/sdk",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "FrontMCP SDK",
   "author": "AgentFront <info@agentfront.dev>",
   "homepage": "https://docs.agentfront.dev",
@@ -33,16 +33,19 @@
       "default": "./src/index.js"
     }
   },
+  "peerDependencies": {
+    "zod": "^3.25.76"
+  },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.21.1",
+    "@modelcontextprotocol/sdk": "^1.22.0",
     "axios": "^1.6.0",
     "ioredis": "^5.8.0",
     "jose": "^6.1.0",
     "openapi-mcp-generator": "^3.2.0",
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.0",
-    "zod-from-json-schema": "^0.5.1",
-    "zod-to-json-schema": "^3.24.6",
+    "json-schema-to-zod-v3": "1.0.0",
+    "zod-to-json-schema": "^3.25.0",
     "tslib": "^2.3.0"
   },
   "devDependencies": {

package/src/__test-utils__/fixtures/hook.fixtures.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Test fixtures for hooks
+ */
+import { HookMetadata } from '../../common/metadata';
+import { Token } from '../../common/interfaces';
+/**
+ * Test token for hook target
+ */
+export declare const TEST_HOOK_TARGET: Token;
+/**
+ * Creates a simple hook metadata object
+ */
+export declare function createHookMetadata(overrides?: Partial<HookMetadata>): HookMetadata;
+/**
+ * Creates a "will" stage hook metadata
+ */
+export declare function createWillHookMetadata(flow?: string, stage?: string): HookMetadata;
+/**
+ * Creates a "did" stage hook metadata
+ */
+export declare function createDidHookMetadata(flow?: string, stage?: string): HookMetadata;
+/**
+ * Creates an "around" stage hook metadata
+ */
+export declare function createAroundHookMetadata(flow?: string, stage?: string): HookMetadata;
+/**
+ * Mock hook class for testing
+ */
+export declare class MockHookClass {
+    onExecute: jest.Mock<Promise<void>, [ctx: any], any>;
+    willExecute: jest.Mock<Promise<void>, [ctx: any], any>;
+    didExecute: jest.Mock<Promise<void>, [ctx: any], any>;
+    aroundExecute: jest.Mock<Promise<any>, [ctx: any, next: () => Promise<any>], any>;
+}
+/**
+ * Creates a mock hook instance for testing
+ */
+export declare function createMockHookInstance(metadata?: Partial<HookMetadata>): {
+    metadata: HookMetadata<keyof ExtendFlows, string, any>;
+    instance: MockHookClass;
+    execute: jest.Mock<Promise<void>, [ctx: any], any>;
+};
+/**
+ * Creates multiple hooks with different priorities
+ */
+export declare function createPriorityHooks(priorities: number[]): HookMetadata[];