@rudderjs/mcp 5.0.0 → 5.1.0

package/README.md

@@ -85,6 +85,38 @@ Don't take a `send` callback parameter — the generator pattern matches
 `@rudderjs/ai` and lets the runtime choose where progress lands (HTTP SSE,
 in-process collector, etc.).
 
+### Tool annotations (behavior hints)
+
+Tools may carry MCP-spec hints that clients (Claude Desktop, Cursor, etc.) use to decide whether to auto-approve a call, batch it, or sandbox it. Apply them as class decorators:
+
+```ts
+import { McpTool, IsReadOnly, IsDestructive, IsIdempotent, IsOpenWorld } from '@rudderjs/mcp'
+
+@IsReadOnly()
+@IsIdempotent()
+class GetUserTool extends McpTool { /* ... */ }
+
+@IsDestructive()
+@IsOpenWorld()
+class DeleteFileTool extends McpTool { /* ... */ }
+```
+
+These surface as `annotations` on `tools/list` per the MCP spec. The hints are advisory — clients still apply their own policy. Both `true` and `false` are meaningful (vs. omitted), so the decorators accept an explicit value: `@IsReadOnly()` (= true), `@IsReadOnly(false)`, or no decorator (= omitted).
+
+### Conditional registration (`shouldRegister`)
+
+Hide a tool, resource, or prompt from listings based on static state — feature flags, env mode, build-time config:
+
+```ts
+class ExperimentalTool extends McpTool {
+  schema() { return z.object({}) }
+  async handle() { return McpResponse.text('experimental') }
+  shouldRegister() { return process.env.FEATURE_EXPERIMENTAL === 'true' }
+}
+```
+
+Returning `false` hides the primitive from `tools/list` AND causes `tools/call` to return "Unknown tool" — preventing bypass via direct call. The same hook is available on `McpResource` and `McpPrompt`. Async hooks are supported.
+
 ### Server-initiated notifications
 
 Push events to all connected clients via `McpServer` instance methods. The
@@ -119,6 +151,24 @@ export class WeatherGuidelinesResource extends McpResource {
 }
 ```
 
+### Resource annotations
+
+Resources accept three protocol-level annotations: `@Audience`, `@Priority`, and `@LastModified`. These help clients rank and surface resources in their UI:
+
+```ts
+import { McpResource, Audience, Priority, LastModified } from '@rudderjs/mcp'
+
+@Audience('user')                            // 'user' | 'assistant' | both
+@Priority(0.9)                                // 0..1 importance score
+@LastModified('2026-05-09T00:00:00Z')         // ISO 8601 string or Date
+export class ReleaseNotesResource extends McpResource {
+  uri() { return 'file://release-notes' }
+  async handle() { return await readReleaseNotes() }
+}
+```
+
+Resources also accept the same `shouldRegister()` hook as tools.
+
 ## Prompts
 
 ```ts

package/boost/guidelines.md

@@ -0,0 +1,316 @@
+# @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' }) }
+```
+
+**Behavior annotations (MCP spec hints).** Apply as class decorators — clients use these to decide auto-approval / sandboxing / batching:
+
+```ts
+import { IsReadOnly, IsDestructive, IsIdempotent, IsOpenWorld } from '@rudderjs/mcp'
+
+@IsReadOnly() @IsIdempotent()  class GetUserTool extends McpTool { /* ... */ }
+@IsDestructive() @IsOpenWorld() class DeleteFileTool extends McpTool { /* ... */ }
+```
+
+Both `true` and `false` are meaningful (vs. omitted). `@IsReadOnly()` = true; `@IsReadOnly(false)` = explicit false.
+
+**Conditional registration.** Hide a tool/resource/prompt for static gating (env flags, feature toggles) — `shouldRegister(): boolean | Promise<boolean>`. Returning false hides from `tools/list` AND blocks `tools/call` (no bypass).
+
+### 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()`.
+
+**Resource annotations (MCP spec).** Three class decorators — `@Audience('user' | 'assistant')`, `@Priority(0..1)`, `@LastModified(string | Date)`. They surface in `resources/list`/`resources/templates/list` to help clients rank.
+
+```ts
+@Audience('user') @Priority(0.9) @LastModified(new Date())
+class ReleaseNotesResource extends McpResource { /* ... */ }
+```
+
+Resources also accept the same `shouldRegister()` hook as tools.
+
+### 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'
+// MCP-spec annotations
+import { IsReadOnly, IsDestructive, IsIdempotent, IsOpenWorld } from '@rudderjs/mcp'  // tools
+import { Audience, Priority, LastModified } from '@rudderjs/mcp'                       // resources
+
+// 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/dist/McpPrompt.d.ts

@@ -15,5 +15,12 @@ export declare abstract class McpPrompt {
      * from the DI container when the method is decorated with `@Handle()`.
      */
     abstract handle(args: Record<string, unknown>, ...deps: unknown[]): Promise<McpPromptMessage[]>;
+    /**
+     * Optional hook controlling whether this prompt is exposed to clients.
+     *
+     * Returning `false` hides the prompt from `prompts/list` AND causes
+     * `prompts/get` to throw "Unknown prompt" — preventing bypass.
+     */
+    shouldRegister?(): boolean | Promise<boolean>;
 }
 //# sourceMappingURL=McpPrompt.d.ts.map

package/dist/McpPrompt.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"McpPrompt.d.ts","sourceRoot":"","sources":["../src/McpPrompt.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;IAC1B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,8BAAsB,SAAS;IAC7B,kBAAkB;IAClB,IAAI,IAAI,MAAM;IAId,kBAAkB;IAClB,WAAW,IAAI,MAAM;IAIrB,kDAAkD;IAClD,SAAS,CAAC,IAAI,aAAa;IAE3B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;CAChG"}
+{"version":3,"file":"McpPrompt.d.ts","sourceRoot":"","sources":["../src/McpPrompt.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,WAAW,CAAA;IAC1B,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,8BAAsB,SAAS;IAC7B,kBAAkB;IAClB,IAAI,IAAI,MAAM;IAId,kBAAkB;IAClB,WAAW,IAAI,MAAM;IAIrB,kDAAkD;IAClD,SAAS,CAAC,IAAI,aAAa;IAE3B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAE/F;;;;;OAKG;IACH,cAAc,CAAC,IAAI,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;CAC9C"}

package/dist/McpPrompt.js.map

@@ -1 +1 @@
-{"version":3,"file":"McpPrompt.js","sourceRoot":"","sources":["../src/McpPrompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAQhD,MAAM,OAAgB,SAAS;IAC7B,kBAAkB;IAClB,IAAI;QACF,OAAO,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAA;IAClE,CAAC;IAED,kBAAkB;IAClB,WAAW;QACT,OAAO,cAAc,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAA;IAC/C,CAAC;CAUF"}
+{"version":3,"file":"McpPrompt.js","sourceRoot":"","sources":["../src/McpPrompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAQhD,MAAM,OAAgB,SAAS;IAC7B,kBAAkB;IAClB,IAAI;QACF,OAAO,WAAW,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAA;IAClE,CAAC;IAED,kBAAkB;IAClB,WAAW;QACT,OAAO,cAAc,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,EAAE,CAAA;IAC/C,CAAC;CAkBF"}