@rudderjs/mcp 4.0.0 → 5.0.1

package/boost/guidelines.md

@@ -0,0 +1,291 @@
+# @rudderjs/mcp
+
+## Overview
+
+MCP (Model Context Protocol) server framework for RudderJS. Lets the app expose **tools**, **resources**, and **prompts** to AI agents (Claude Code, Cursor, etc.) over either HTTP Streamable transport or local stdio. Tools and resources are plain classes with decorator-driven metadata and Zod input schemas. DI resolves constructor dependencies, OAuth 2.1 protects HTTP endpoints via `@rudderjs/passport`, and an observer registry exposes every tool call / resource read / prompt render for Telescope and other collectors.
+
+## Key Patterns
+
+### Server Definition
+
+Extend `McpServer` and list the tool/resource/prompt **classes** (not instances). Metadata comes from decorators on the class.
+
+```ts
+import { McpServer, Name, Version, Instructions } from '@rudderjs/mcp'
+
+@Name('Weather Server')
+@Version('1.0.0')
+@Instructions('Provide weather information and forecasts.')
+export class WeatherServer extends McpServer {
+  protected tools     = [CurrentWeatherTool]
+  protected resources = [WeatherGuidelinesResource, CityWeatherResource]
+  protected prompts   = [DescribeWeatherPrompt]
+}
+```
+
+### Tools
+
+Declare input via Zod, return via `McpResponse` helpers. Decorator `@Description` drives what the AI sees.
+
+```ts
+import { McpTool, McpResponse, Description } from '@rudderjs/mcp'
+import { z } from 'zod'
+
+@Description('Get current weather for a location.')
+export class CurrentWeatherTool extends McpTool {
+  schema() {
+    return z.object({
+      location: z.string().describe('City name'),
+    })
+  }
+
+  async handle(input: Record<string, unknown>) {
+    const location = input.location as string
+    return McpResponse.text(`Weather in ${location}: sunny, 22°C`)
+  }
+}
+```
+
+**Output schemas** — optional, advertises structured response shape to the client:
+
+```ts
+outputSchema() {
+  return z.object({ temperature: z.number(), conditions: z.string() })
+}
+// handle() must return JSON matching the schema
+async handle() { return McpResponse.json({ temperature: 22, conditions: 'sunny' }) }
+```
+
+### Resources
+
+Two shapes — **static URIs** and **URI templates**:
+
+```ts
+// Static URI
+@Description('Weather usage guidelines')
+export class WeatherGuidelinesResource extends McpResource {
+  uri() { return 'weather://guidelines' }
+  async handle() { return 'Always check conditions before...' }
+}
+
+// URI template — {param} placeholders
+@Description('Weather for a specific city')
+export class CityWeatherResource extends McpResource {
+  uri() { return 'weather://city/{name}' }  // template
+  async handle(params?: Record<string, string>) {
+    return `Weather in ${params?.name}: sunny, 22°C`
+  }
+}
+```
+
+Templates are auto-registered via `ListResourceTemplates`. Params are extracted from the URI and passed to `handle()`.
+
+### Prompts
+
+Like tools, but return message arrays instead of content:
+
+```ts
+import { McpPrompt, Description } from '@rudderjs/mcp'
+
+@Description('Describe weather poetically')
+export class DescribeWeatherPrompt extends McpPrompt {
+  arguments() { return z.object({ location: z.string() }) }
+
+  async handle(args: Record<string, unknown>): Promise<McpPromptMessage[]> {
+    return [{ role: 'user', content: `Describe weather in ${args.location} poetically.` }]
+  }
+}
+```
+
+### Response Helpers
+
+```ts
+McpResponse.text('Plain text output')
+McpResponse.json({ key: 'value' })
+McpResponse.error('Something went wrong')
+```
+
+### Dependency Injection
+
+Constructor params are auto-resolved from the DI container when the class is instantiated by the runtime. Falls back to `new T()` if the container isn't available.
+
+```ts
+@Injectable()
+@Description('Query the database')
+export class DbQueryTool extends McpTool {
+  constructor(private db: DatabaseService) { super() }
+
+  schema() { return z.object({ query: z.string() }) }
+
+  async handle(input: Record<string, unknown>) {
+    const result = await this.db.query(input.query as string)
+    return McpResponse.json(result)
+  }
+}
+```
+
+**Method-level DI** — use `@Handle(TokenA, TokenB, ...)` to request DI-resolved extra parameters beyond the first. This is required under Vite/esbuild because those toolchains drop `design:paramtypes` metadata; explicit tokens are the reliable path.
+
+```ts
+@Handle(GreetingService, Logger)
+async handle(input: Record<string, unknown>, greeter: GreetingService, logger: Logger) {
+  logger.info(greeter.say(input.name as string))
+  return McpResponse.text('ok')
+}
+```
+
+### Registering Servers
+
+```ts
+import { Mcp } from '@rudderjs/mcp'
+import { WeatherServer } from '../app/Mcp/Servers/WeatherServer.js'
+
+// HTTP (Streamable HTTP transport) — served at the given path
+Mcp.web('/mcp/weather', WeatherServer)
+
+// With middleware chain
+Mcp.web('/mcp/weather', WeatherServer).middleware([rateLimitMw, loggingMw])
+
+// Protected by OAuth 2.1 Bearer tokens (requires @rudderjs/passport)
+Mcp.web('/mcp/weather', WeatherServer).oauth2({ scopes: ['mcp:read'] })
+
+// Local stdio (CLI)
+Mcp.local('weather', WeatherServer)
+```
+
+Registration runs once at boot; it's not per-request. Put these calls in a provider's `boot()` method or a dedicated registration module loaded from there.
+
+### OAuth 2.1 Protection
+
+`.oauth2()` on the builder chain does three things: validates the Bearer JWT via `@rudderjs/passport`, enforces required scopes, and registers an RFC 9728 **Protected Resource Metadata** endpoint at `/.well-known/oauth-protected-resource<mcp-path>`. On auth failure, the response carries a `WWW-Authenticate` header pointing the client at that metadata doc — standard MCP client discovery flow.
+
+```ts
+Mcp.web('/mcp/admin', AdminServer).oauth2({
+  scopes: ['admin'],                          // required on the token
+  authorizationServers: ['https://auth.example.com'],  // defaults to app origin
+  scopesSupported: ['admin', 'read', 'write'],         // advertised in metadata
+})
+```
+
+Passport must be installed and configured — see `@rudderjs/passport` guidelines. Without it, the OAuth middleware returns `invalid_token` with the metadata URL.
+
+### Observer Registry (Telescope Integration)
+
+Every tool call, resource read, and prompt render emits a structured event. Packages like Telescope subscribe to collect telemetry; apps can subscribe too for custom logging.
+
+```ts
+import { mcpObservers } from '@rudderjs/mcp/observers'
+
+const unsubscribe = mcpObservers.subscribe((event) => {
+  // event.kind: 'tool.called' | 'tool.failed' | 'resource.read'
+  //           | 'resource.failed' | 'prompt.rendered' | 'prompt.failed'
+  console.log(`[${event.kind}] ${event.serverName}/${event.name} (${event.duration}ms)`)
+})
+```
+
+The registry is a singleton stored on `globalThis` so state survives Vite SSR module re-evaluation. Observer errors are swallowed inside `emit()` — a broken subscriber cannot break an MCP server.
+
+Don't import `@rudderjs/mcp/observers` in normal app code; it's meant for collector packages.
+
+### Config Shape
+
+```ts
+// config/mcp.ts (optional — no required fields today)
+export default {
+  // currently no required configuration; provider reads servers from Mcp.web/Mcp.local
+} satisfies Record<string, unknown>
+
+// bootstrap/providers.ts — provider is auto-discovered after `rudder providers:discover`
+import { McpProvider } from '@rudderjs/mcp'
+export default [..., McpProvider]
+```
+
+### CLI Commands
+
+```bash
+pnpm rudder mcp:start <name>      # start a local server via stdio
+pnpm rudder mcp:list              # list all registered MCP servers (web + local)
+pnpm rudder mcp:inspector <name>  # launch the MCP Inspector UI
+```
+
+### Scaffolders
+
+```bash
+pnpm rudder make:mcp-server   Weather
+pnpm rudder make:mcp-tool     CurrentWeather
+pnpm rudder make:mcp-resource WeatherGuidelines
+pnpm rudder make:mcp-prompt   DescribeWeather
+```
+
+Scaffolders land in `app/Mcp/{Servers,Tools,Resources,Prompts}/`.
+
+### Testing
+
+`McpTestClient` boots an in-process server and exposes a minimal protocol client — no network hop, no stdio spawn.
+
+```ts
+import { McpTestClient } from '@rudderjs/mcp'
+import { WeatherServer } from '../app/Mcp/Servers/WeatherServer.js'
+
+const client = new McpTestClient(WeatherServer)
+
+const result = await client.callTool('current-weather', { location: 'London' })
+
+client.assertToolExists('current-weather')
+client.assertToolCount(1)
+client.assertResourceExists('weather://guidelines')
+client.assertPromptExists('describe-weather')
+
+const tools = await client.listTools()
+const resources = await client.listResources()
+const prompts = await client.listPrompts()
+```
+
+## Common Pitfalls
+
+- **Register classes, not instances** — `protected tools = [MyTool]` (class), never `[new MyTool()]`. The runtime instantiates each class via DI when the server boots.
+- **`Mcp.web()` / `Mcp.local()` only run once** — at boot. Put them in a provider's `boot()` or a route-loaded module; never in request handlers.
+- **OAuth 2.1 needs Passport** — `.oauth2()` requires `@rudderjs/passport` installed and configured. Without it, every request fails `invalid_token`.
+- **Constructor DI works, but method DI under Vite needs `@Handle(...)`** — esbuild drops `design:paramtypes` metadata, so `@Handle()` without tokens silently falls back to empty. Always pass explicit tokens.
+- **Zod v4 introspection differences** — the JSON-schema converter in `zod-to-json-schema.ts` handles both v3 and v4 shapes (`.describe()` location, `typeName`→`type`, `array.type`→`element`, `enum.values`→`entries`). When extending the converter, support both.
+- **URI templates: only `{param}` placeholders** — no regex, no optional segments. Extracted params are always `string`. Validate/coerce inside `handle()`.
+- **Output schema must match `handle()` return** — declaring `outputSchema()` but returning an unrelated shape surfaces a validation error to the client. Keep them in sync.
+- **`McpResponse.error()` vs throwing** — `McpResponse.error(msg)` returns an MCP-protocol-shaped error response; throwing inside `handle()` emits a `tool.failed` observer event and surfaces a generic error to the client. Prefer `McpResponse.error()` for expected failures, throw for programmer errors.
+- **Don't import `/observers` in app code** — that subpath is for Telescope-style collectors, not for general subscription. If you need tool-call logging in an app, prefer AI middleware or route-level observability instead.
+- **Scaffolder registers via `registerMakeSpecs`** — `make:*` commands skip `bootApp()` for speed. Don't add boot-dependent logic to scaffolder stubs.
+- **Provider boot order** — `McpProvider` registers web routes with the router, so the router provider must boot first. Auto-discovery handles this; don't add `McpProvider` manually before `@rudderjs/router` in a custom provider list.
+
+## Key Imports
+
+```ts
+// Server + building blocks
+import { McpServer, McpTool, McpResource, McpPrompt } from '@rudderjs/mcp'
+
+// Response helpers
+import { McpResponse } from '@rudderjs/mcp'
+
+// Decorators
+import { Name, Version, Instructions, Description, Handle } from '@rudderjs/mcp'
+
+// Registration facade
+import { Mcp } from '@rudderjs/mcp'
+import type { McpWebEntry, McpWebBuilder } from '@rudderjs/mcp'
+
+// OAuth 2.1 protection
+import { oauth2McpMiddleware, registerOAuth2Metadata } from '@rudderjs/mcp'
+import type { OAuth2McpOptions } from '@rudderjs/mcp'
+
+// Runtime primitives (rarely needed in app code)
+import { createSdkServer, startStdio, mountHttpTransport } from '@rudderjs/mcp'
+import type { HttpTransportOptions } from '@rudderjs/mcp'
+
+// Provider + testing
+import { McpProvider, McpTestClient } from '@rudderjs/mcp'
+
+// Observer registry — for collectors only, not app code
+import { mcpObservers } from '@rudderjs/mcp/observers'
+import type { McpObserverEvent, McpObserver, McpObserverRegistry } from '@rudderjs/mcp'
+
+// Types
+import type { McpServerMetadata, McpToolResult, McpPromptMessage, InjectToken } from '@rudderjs/mcp'
+```

package/boost/skills/mcp-servers/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: mcp-servers
+description: Building MCP servers with tools, resources, prompts, decorators, and HTTP/stdio transports in RudderJS
+---
+
+# MCP Servers
+
+## When to use this skill
+
+Load this skill when you need to build a Model Context Protocol (MCP) server to expose tools, resources, and prompts to AI coding assistants and other MCP clients.
+
+## Key concepts
+
+- **McpServer**: Base class that declares which tools, resources, and prompts to register. Extend it and set `protected tools`, `resources`, and `prompts` arrays.
+- **McpTool**: Base class for tools. Implement `schema()` (Zod) and `handle()`. Name auto-derived from class name (PascalCase -> kebab-case, minus "Tool" suffix).
+- **McpResource**: Base class for resources. Implement `uri()` and `handle()`. Supports URI templates with `{param}` placeholders.
+- **McpPrompt**: Base class for prompts. Implement `handle()` and optionally `arguments()` for a Zod schema.
+- **Decorators**: `@Name`, `@Version`, `@Instructions`, `@Description` set metadata via reflect-metadata.
+- **McpResponse**: Helper for building tool results (`McpResponse.text()`, `.json()`, `.error()`).
+- **Transports**: stdio (local CLI) via `startStdio()`, HTTP/SSE (web) via `mountHttpTransport()`.
+- **DI support**: Tool/resource/prompt classes are resolved via the framework's DI container when available, falling back to plain `new T()`.
+- **McpTestClient**: In-memory test client for unit testing servers without transport overhead.
+
+## Step-by-step
+
+### 1. Create a tool
+
+```ts
+// app/Mcp/Tools/WeatherTool.ts
+import { McpTool, McpResponse, Description } from '@rudderjs/mcp'
+import { z } from 'zod'
+
+@Description('Get current weather for a city')
+export class WeatherTool extends McpTool {
+  // Name auto-derived: "WeatherTool" -> "weather"
+  // Override with: name() { return 'get-weather' }
+
+  schema() {
+    return z.object({
+      city: z.string().describe('City name'),
+      units: z.enum(['celsius', 'fahrenheit']).default('celsius'),
+    })
+  }
+
+  // Optional: advertise the output structure
+  outputSchema() {
+    return z.object({
+      temperature: z.number(),
+      conditions: z.string(),
+    })
+  }
+
+  async handle(input: Record<string, unknown>) {
+    const { city, units } = input as { city: string; units: string }
+    const data = await fetchWeather(city, units)
+    return McpResponse.json({ temperature: data.temp, conditions: data.conditions })
+  }
+}
+```
+
+### 2. Create a resource
+
+```ts
+// app/Mcp/Resources/SchemaResource.ts
+import { McpResource, Description } from '@rudderjs/mcp'
+
+@Description('Returns the database schema')
+export class SchemaResource extends McpResource {
+  uri() { return 'db://schema' }
+  mimeType() { return 'text/plain' }
+
+  async handle() {
+    const schema = await readFile('prisma/schema.prisma', 'utf-8')
+    return schema
+  }
+}
+```
+
+### 3. Create a resource with URI template
+
+```ts
+// app/Mcp/Resources/TableResource.ts
+import { McpResource, Description } from '@rudderjs/mcp'
+
+@Description('Read rows from a database table')
+export class TableResource extends McpResource {
+  uri() { return 'db://tables/{tableName}' }  // {param} makes it a template
+  mimeType() { return 'application/json' }
+
+  async handle(params?: Record<string, string>) {
+    const tableName = params?.tableName ?? 'unknown'
+    const rows = await db.query(`SELECT * FROM ${tableName} LIMIT 100`)
+    return JSON.stringify(rows, null, 2)
+  }
+}
+```
+
+### 4. Create a prompt
+
+```ts
+// app/Mcp/Prompts/ReviewPrompt.ts
+import { McpPrompt, Description } from '@rudderjs/mcp'
+import type { McpPromptMessage } from '@rudderjs/mcp'
+import { z } from 'zod'
+
+@Description('Generate a code review prompt for a file')
+export class ReviewPrompt extends McpPrompt {
+  // Name auto-derived: "ReviewPrompt" -> "review"
+
+  arguments() {
+    return z.object({
+      file: z.string().describe('Path to the file to review'),
+      focus: z.string().optional().describe('Area to focus on'),
+    })
+  }
+
+  async handle(args: Record<string, unknown>): Promise<McpPromptMessage[]> {
+    const { file, focus } = args as { file: string; focus?: string }
+    const content = await readFile(file, 'utf-8')
+
+    return [
+      {
+        role: 'user',
+        content: `Please review this code${focus ? ` with focus on ${focus}` : ''}:\n\n${content}`,
+      },
+    ]
+  }
+}
+```
+
+### 5. Assemble the server
+
+```ts
+// app/Mcp/AppMcpServer.ts
+import { McpServer, Name, Version, Instructions } from '@rudderjs/mcp'
+import { WeatherTool } from './Tools/WeatherTool.js'
+import { SchemaResource } from './Resources/SchemaResource.js'
+import { TableResource } from './Resources/TableResource.js'
+import { ReviewPrompt } from './Prompts/ReviewPrompt.js'
+
+@Name('my-app-mcp')
+@Version('1.0.0')
+@Instructions('An MCP server for my application. Use the weather tool to check conditions.')
+export class AppMcpServer extends McpServer {
+  protected tools = [WeatherTool]
+  protected resources = [SchemaResource, TableResource]
+  protected prompts = [ReviewPrompt]
+}
+```
+
+### 6. Register for stdio transport (local CLI)
+
+```ts
+// routes/console.ts or bootstrap
+import { Mcp } from '@rudderjs/mcp'
+import { AppMcpServer } from '../app/Mcp/AppMcpServer.js'
+
+Mcp.local('app', AppMcpServer)
+
+// Run via: pnpm rudder mcp:start app
+```
+
+### 7. Register for HTTP transport (web endpoint)
+
+```ts
+// routes/console.ts or a provider's boot()
+import { Mcp } from '@rudderjs/mcp'
+import { AppMcpServer } from '../app/Mcp/AppMcpServer.js'
+
+Mcp.web('/mcp', AppMcpServer)
+
+// Optionally add middleware:
+Mcp.web('/mcp', AppMcpServer).middleware([rateLimitMiddleware])
+
+// The endpoint handles:
+// POST /mcp — JSON-RPC messages
+// GET  /mcp — SSE stream for server-initiated notifications
+// DELETE /mcp — session termination
+```
+
+### 8. Register the MCP service provider
+
+```ts
+// bootstrap/providers.ts
+import { mcp } from '@rudderjs/mcp'
+
+export default [
+  ...(await defaultProviders()),
+  mcp(),  // registers Mcp facade + boots web/local servers + CLI commands
+]
+```
+
+### 9. McpResponse helpers
+
+```ts
+import { McpResponse } from '@rudderjs/mcp'
+
+// Text response
+return McpResponse.text('The weather is sunny')
+
+// JSON response (pretty-printed)
+return McpResponse.json({ temp: 72, conditions: 'sunny' })
+
+// Error response
+return McpResponse.error('City not found')
+
+// Raw response (for images etc.)
+return {
+  content: [
+    { type: 'text', text: 'Here is the chart:' },
+    { type: 'image', data: base64Data, mimeType: 'image/png' },
+  ],
+}
+```
+
+### 10. Testing with McpTestClient
+
+```ts
+import { McpTestClient } from '@rudderjs/mcp'
+import { AppMcpServer } from './AppMcpServer.js'
+
+const client = new McpTestClient(AppMcpServer)
+
+// List tools
+const tools = await client.listTools()
+// [{ name: 'weather', description: 'Get current weather...' }]
+
+// Call a tool
+const result = await client.callTool('weather', { city: 'Paris', units: 'celsius' })
+
+// Read a resource
+const schema = await client.readResource('db://schema')
+
+// Get a prompt
+const messages = await client.getPrompt('review', { file: 'src/index.ts' })
+
+// Assertions
+client.assertToolExists('weather')
+client.assertToolCount(1)
+client.assertResourceExists('db://schema')
+client.assertResourceCount(2)
+client.assertPromptExists('review')
+client.assertPromptCount(1)
+```
+
+### 11. DI-injected tools
+
+```ts
+import { McpTool, McpResponse, Description } from '@rudderjs/mcp'
+import { injectable, inject } from 'tsyringe'
+import { z } from 'zod'
+
+@injectable()
+@Description('Search the knowledge base')
+export class SearchTool extends McpTool {
+  constructor(@inject('search.service') private search: SearchService) {
+    super()
+  }
+
+  schema() {
+    return z.object({ query: z.string() })
+  }
+
+  async handle(input: Record<string, unknown>) {
+    const results = await this.search.query(input.query as string)
+    return McpResponse.json(results)
+  }
+}
+// When the RudderJS DI container is available, tools are resolved via
+// container.make(ToolClass), auto-injecting constructor dependencies.
+```
+
+## Examples
+
+See `packages/mcp/src/index.test.ts` for test examples and `packages/mcp/src/runtime.ts` for the full transport implementation.
+
+## Common pitfalls
+
+- **Name derivation**: `WeatherTool` -> `weather`, `GetUserInfoTool` -> `get-user-info`. The class name is converted to kebab-case with the `Tool` suffix removed. Override `name()` if the auto-derived name isn't what you want.
+- **Schema must be z.object()**: Both `schema()` and `arguments()` must return `z.object(...)`, not a bare `z.string()` or other type.
+- **@modelcontextprotocol/sdk peer dep**: The MCP SDK (`@modelcontextprotocol/sdk`) is a peer dependency. Install it alongside `@rudderjs/mcp`.
+- **HTTP transport requires @rudderjs/router**: `mountHttpTransport()` dynamically imports `@rudderjs/router` to register the endpoint. Stdio transport has no such requirement.
+- **URI template matching**: Template resources use `{param}` syntax (e.g. `db://tables/{name}`). The extracted params are passed to `handle(params)`.
+- **Error handling**: If `handle()` throws, the runtime catches it and returns `McpResponse.error(err.message)` automatically. You don't need try/catch in every tool.
+- **mcp:list command**: Run `pnpm rudder mcp:list` to see all registered MCP servers (web and local).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rudderjs/mcp",
-  "version": "4.0.0",
+  "version": "5.0.1",
   "description": "MCP (Model Context Protocol) server framework for RudderJS",
   "rudderjs": {
     "provider": "McpProvider",
@@ -14,7 +14,8 @@
   },
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "boost"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -48,11 +49,11 @@
     "@modelcontextprotocol/sdk": "^1.13.0",
     "reflect-metadata": "^0.2.0",
     "zod": "^3.23.0",
-    "@rudderjs/core": "^1.0.0"
+    "@rudderjs/core": "^1.1.3"
   },
   "peerDependencies": {
-    "@rudderjs/router": "^1.0.0",
-    "@rudderjs/console": "^0.0.4"
+    "@rudderjs/router": "^1.2.0",
+    "@rudderjs/console": "^1.0.1"
   },
   "peerDependenciesMeta": {
     "@rudderjs/router": {
@@ -65,8 +66,8 @@
   "devDependencies": {
     "@types/node": "^20.0.0",
     "typescript": "^5.4.0",
-    "@rudderjs/console": "^0.0.4",
-    "@rudderjs/router": "^1.0.0"
+    "@rudderjs/router": "^1.2.0",
+    "@rudderjs/console": "^1.0.1"
   },
   "author": "Suleiman Shahbari",
   "scripts": {