@strav/mcp 0.1.0

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@strav/mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Model Context Protocol (MCP) server for the Strav framework",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*.ts"
+  },
+  "strav": {
+    "commands": "src/commands"
+  },
+  "files": [
+    "src/",
+    "stubs/",
+    "package.json",
+    "tsconfig.json"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.25 || ^4.0"
+  },
+  "peerDependencies": {
+    "@strav/kernel": "0.1.0",
+    "@strav/http": "0.1.0",
+    "@strav/cli": "0.1.0"
+  },
+  "scripts": {
+    "test": "bun test tests/",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "commander": "^14.0.3"
+  }
+}

package/src/commands/mcp_commands.ts

@@ -0,0 +1,114 @@
+import type { Command } from 'commander'
+import chalk from 'chalk'
+import { bootstrap, shutdown } from '@stravigor/cli'
+import McpManager from '../mcp_manager.ts'
+
+export function register(program: Command): void {
+  program
+    .command('mcp:serve')
+    .description('Start the MCP server in stdio mode (for Claude Desktop, etc.)')
+    .action(async () => {
+      let db
+      try {
+        const { db: database, config } = await bootstrap()
+        db = database
+
+        new McpManager(config)
+
+        // Load user registration file
+        const registerPath = McpManager.config.register
+        if (registerPath) {
+          await import(`${process.cwd()}/${registerPath}`)
+        }
+
+        const tools = McpManager.registeredTools()
+        const resources = McpManager.registeredResources()
+        const prompts = McpManager.registeredPrompts()
+
+        // Log to stderr (stdout is the MCP protocol channel)
+        console.error(
+          chalk.dim(
+            `MCP server starting (${tools.length} tools, ${resources.length} resources, ${prompts.length} prompts)`
+          )
+        )
+
+        const { serveStdio } = await import('../transports/stdio.ts')
+        await serveStdio()
+
+        console.error(chalk.dim('MCP server closed.'))
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : err}`))
+        process.exit(1)
+      } finally {
+        McpManager.reset()
+        if (db) await shutdown(db)
+      }
+    })
+
+  program
+    .command('mcp:list')
+    .description('List all registered MCP tools, resources, and prompts')
+    .action(async () => {
+      let db
+      try {
+        const { db: database, config } = await bootstrap()
+        db = database
+
+        new McpManager(config)
+
+        // Load user registration file
+        const registerPath = McpManager.config.register
+        if (registerPath) {
+          await import(`${process.cwd()}/${registerPath}`)
+        }
+
+        const tools = McpManager.registeredTools()
+        const resources = McpManager.registeredResources()
+        const prompts = McpManager.registeredPrompts()
+
+        console.log(chalk.bold('\nMCP Server Registry\n'))
+
+        // Tools
+        console.log(chalk.cyan(`Tools (${tools.length}):`))
+        if (tools.length === 0) {
+          console.log(chalk.dim('  (none)'))
+        } else {
+          for (const name of tools) {
+            const reg = McpManager.getToolRegistration(name)!
+            console.log(`  ${chalk.green(name)} ${chalk.dim(reg.description ?? '')}`)
+          }
+        }
+        console.log()
+
+        // Resources
+        console.log(chalk.cyan(`Resources (${resources.length}):`))
+        if (resources.length === 0) {
+          console.log(chalk.dim('  (none)'))
+        } else {
+          for (const uri of resources) {
+            const reg = McpManager.getResourceRegistration(uri)!
+            console.log(`  ${chalk.green(uri)} ${chalk.dim(reg.description ?? '')}`)
+          }
+        }
+        console.log()
+
+        // Prompts
+        console.log(chalk.cyan(`Prompts (${prompts.length}):`))
+        if (prompts.length === 0) {
+          console.log(chalk.dim('  (none)'))
+        } else {
+          for (const name of prompts) {
+            const reg = McpManager.getPromptRegistration(name)!
+            console.log(`  ${chalk.green(name)} ${chalk.dim(reg.description ?? '')}`)
+          }
+        }
+        console.log()
+      } catch (err) {
+        console.error(chalk.red(`Error: ${err instanceof Error ? err.message : err}`))
+        process.exit(1)
+      } finally {
+        McpManager.reset()
+        if (db) await shutdown(db)
+      }
+    })
+}

package/src/errors.ts

@@ -0,0 +1,11 @@
+import { StravError } from '@stravigor/kernel'
+
+/** Base error class for all MCP errors. */
+export class McpError extends StravError {}
+
+/** Thrown when a tool, resource, or prompt with the same name is registered twice. */
+export class DuplicateRegistrationError extends McpError {
+  constructor(type: 'tool' | 'resource' | 'prompt', name: string) {
+    super(`${type} "${name}" is already registered.`)
+  }
+}

package/src/helpers.ts

@@ -0,0 +1,96 @@
+import McpManager from './mcp_manager.ts'
+import type {
+  ZodRawShape,
+  ToolHandler,
+  ToolRegistration,
+  ResourceHandler,
+  ResourceRegistration,
+  PromptHandler,
+  PromptRegistration,
+} from './types.ts'
+
+/**
+ * MCP helper — the primary convenience API.
+ *
+ * @example
+ * import { mcp } from '@stravigor/mcp'
+ * import { z } from 'zod'
+ *
+ * mcp.tool('get-user', {
+ *   description: 'Fetch a user by ID',
+ *   input: { id: z.number() },
+ *   handler: async ({ id }, { app }) => {
+ *     const db = app.resolve(Database)
+ *     const [user] = await db.sql`SELECT * FROM users WHERE id = ${id}`
+ *     return { content: [{ type: 'text', text: JSON.stringify(user) }] }
+ *   }
+ * })
+ */
+export const mcp = {
+  /** Register a tool that AI clients can invoke. */
+  tool<TShape extends ZodRawShape>(
+    name: string,
+    options: {
+      description?: string
+      input?: TShape
+      handler: ToolHandler<TShape>
+    }
+  ): void {
+    McpManager.tool(name, options)
+  },
+
+  /** Register a resource that AI clients can read. */
+  resource(
+    uri: string,
+    options: {
+      name?: string
+      description?: string
+      mimeType?: string
+      handler: ResourceHandler
+    }
+  ): void {
+    McpManager.resource(uri, options)
+  },
+
+  /** Register a prompt template that AI clients can use. */
+  prompt<TShape extends ZodRawShape>(
+    name: string,
+    options: {
+      description?: string
+      args?: TShape
+      handler: PromptHandler<TShape>
+    }
+  ): void {
+    McpManager.prompt(name, options)
+  },
+
+  /** List all registered tool names. */
+  registeredTools(): string[] {
+    return McpManager.registeredTools()
+  },
+
+  /** List all registered resource URIs. */
+  registeredResources(): string[] {
+    return McpManager.registeredResources()
+  },
+
+  /** List all registered prompt names. */
+  registeredPrompts(): string[] {
+    return McpManager.registeredPrompts()
+  },
+
+  /** Get a tool registration by name. */
+  getToolRegistration(name: string): ToolRegistration | undefined {
+    return McpManager.getToolRegistration(name)
+  },
+
+  /** Get a resource registration by URI. */
+  getResourceRegistration(uri: string): ResourceRegistration | undefined {
+    return McpManager.getResourceRegistration(uri)
+  },
+
+  /** Get a prompt registration by name. */
+  getPromptRegistration(name: string): PromptRegistration | undefined {
+    return McpManager.getPromptRegistration(name)
+  },
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+// Manager
+export { default, default as McpManager } from './mcp_manager.ts'
+
+// Provider
+export { default as McpProvider } from './mcp_provider.ts'
+export type { McpProviderOptions } from './mcp_provider.ts'
+
+// Helper
+export { mcp } from './helpers.ts'
+
+// Transports
+export { serveStdio } from './transports/stdio.ts'
+export { mountHttpTransport } from './transports/bun_http_transport.ts'
+export type { WebStandardStreamableHTTPServerTransport } from './transports/bun_http_transport.ts'
+
+// Errors
+export { McpError, DuplicateRegistrationError } from './errors.ts'
+
+// Types
+export type {
+  McpConfig,
+  ZodRawShape,
+  InferShape,
+  ToolHandlerContext,
+  ToolRegistration,
+  ToolHandler,
+  ResourceRegistration,
+  ResourceHandler,
+  PromptRegistration,
+  PromptHandler,
+  // Re-exported SDK result types
+  CallToolResult,
+  GetPromptResult,
+  ReadResourceResult,
+} from './types.ts'

package/src/mcp_manager.ts

@@ -0,0 +1,264 @@
+import { inject, app, Configuration, Emitter, ConfigurationError } from '@stravigor/kernel'
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type {
+  McpConfig,
+  ZodRawShape,
+  ToolRegistration,
+  ToolHandler,
+  ToolHandlerContext,
+  ResourceRegistration,
+  ResourceHandler,
+  PromptRegistration,
+  PromptHandler,
+} from './types.ts'
+import { DuplicateRegistrationError } from './errors.ts'
+
+@inject
+export default class McpManager {
+  private static _config: McpConfig
+  private static _server: McpServer | null = null
+  private static _tools = new Map<string, ToolRegistration>()
+  private static _resources = new Map<string, ResourceRegistration>()
+  private static _prompts = new Map<string, PromptRegistration>()
+
+  constructor(config: Configuration) {
+    McpManager._config = {
+      name: (config.get('mcp.name') ?? config.get('app.name', 'Strav MCP Server')) as string,
+      version: config.get('mcp.version', '1.0.0') as string,
+      register: config.get('mcp.register') as string | undefined,
+      http: {
+        enabled: config.get('mcp.http.enabled', true) as boolean,
+        path: config.get('mcp.http.path', '/mcp') as string,
+      },
+    }
+  }
+
+  // ── Configuration ──────────────────────────────────────────────────
+
+  static get config(): McpConfig {
+    if (!McpManager._config) {
+      throw new ConfigurationError(
+        'McpManager not configured. Resolve it through the container first.'
+      )
+    }
+    return McpManager._config
+  }
+
+  // ── Builder API ────────────────────────────────────────────────────
+
+  /** Register a tool that AI clients can invoke. */
+  static tool<TShape extends ZodRawShape>(
+    name: string,
+    options: {
+      description?: string
+      input?: TShape
+      handler: ToolHandler<TShape>
+    }
+  ): void {
+    if (McpManager._tools.has(name)) {
+      throw new DuplicateRegistrationError('tool', name)
+    }
+
+    McpManager._tools.set(name, {
+      name,
+      description: options.description,
+      input: options.input,
+      handler: options.handler as ToolHandler,
+    })
+
+    Emitter.emit('mcp:tool-registered', { name })
+  }
+
+  /** Register a resource that AI clients can read. */
+  static resource(
+    uri: string,
+    options: {
+      name?: string
+      description?: string
+      mimeType?: string
+      handler: ResourceHandler
+    }
+  ): void {
+    if (McpManager._resources.has(uri)) {
+      throw new DuplicateRegistrationError('resource', uri)
+    }
+
+    McpManager._resources.set(uri, {
+      uri,
+      name: options.name,
+      description: options.description,
+      mimeType: options.mimeType,
+      handler: options.handler,
+    })
+
+    Emitter.emit('mcp:resource-registered', { uri })
+  }
+
+  /** Register a prompt template that AI clients can use. */
+  static prompt<TShape extends ZodRawShape>(
+    name: string,
+    options: {
+      description?: string
+      args?: TShape
+      handler: PromptHandler<TShape>
+    }
+  ): void {
+    if (McpManager._prompts.has(name)) {
+      throw new DuplicateRegistrationError('prompt', name)
+    }
+
+    McpManager._prompts.set(name, {
+      name,
+      description: options.description,
+      args: options.args,
+      handler: options.handler as PromptHandler,
+    })
+
+    Emitter.emit('mcp:prompt-registered', { name })
+  }
+
+  // ── Server ─────────────────────────────────────────────────────────
+
+  /**
+   * Get or create the MCP server instance.
+   *
+   * Lazily creates the server and wires all registered tools, resources,
+   * and prompts. Handlers are wrapped to inject the Application context.
+   */
+  static getServer(): McpServer {
+    if (McpManager._server) return McpManager._server
+
+    const server = new McpServer({
+      name: McpManager.config.name,
+      version: McpManager.config.version,
+    })
+
+    const ctx: ToolHandlerContext = { app }
+
+    // Wire tools — cast at SDK boundary since our handler signature
+    // adds the DI context param that the SDK doesn't know about
+    for (const [name, reg] of McpManager._tools) {
+      const toolCb = async (params: any) => {
+        const result = await reg.handler(params ?? {}, ctx)
+        await Emitter.emit('mcp:tool-called', { name, params })
+        return result
+      }
+
+      if (reg.input) {
+        server.registerTool(
+          name,
+          {
+            description: reg.description,
+            inputSchema: reg.input,
+          },
+          toolCb as any
+        )
+      } else {
+        server.registerTool(
+          name,
+          {
+            description: reg.description,
+          },
+          toolCb as any
+        )
+      }
+    }
+
+    // Wire resources
+    for (const [, reg] of McpManager._resources) {
+      const isTemplate = reg.uri.includes('{')
+      const metadata = {
+        title: reg.name,
+        description: reg.description,
+        mimeType: reg.mimeType,
+      }
+
+      if (isTemplate) {
+        server.registerResource(
+          reg.name ?? reg.uri,
+          new ResourceTemplate(reg.uri, { list: undefined }),
+          metadata,
+          (async (uri: URL, params: Record<string, string>) => {
+            const result = await reg.handler(uri, params, ctx)
+            await Emitter.emit('mcp:resource-read', { uri: uri.href })
+            return result
+          }) as any
+        )
+      } else {
+        server.registerResource(reg.name ?? reg.uri, reg.uri, metadata, (async (uri: URL) => {
+          const result = await reg.handler(uri, {}, ctx)
+          await Emitter.emit('mcp:resource-read', { uri: uri.href })
+          return result
+        }) as any)
+      }
+    }
+
+    // Wire prompts
+    for (const [name, reg] of McpManager._prompts) {
+      const promptCb = async (args: any) => {
+        const result = await reg.handler(args ?? {}, ctx)
+        await Emitter.emit('mcp:prompt-called', { name, args })
+        return result
+      }
+
+      if (reg.args) {
+        server.registerPrompt(
+          name,
+          {
+            description: reg.description,
+            argsSchema: reg.args,
+          },
+          promptCb as any
+        )
+      } else {
+        server.registerPrompt(
+          name,
+          {
+            description: reg.description,
+          },
+          promptCb as any
+        )
+      }
+    }
+
+    McpManager._server = server
+    return server
+  }
+
+  // ── Inspection ─────────────────────────────────────────────────────
+
+  static registeredTools(): string[] {
+    return Array.from(McpManager._tools.keys())
+  }
+
+  static registeredResources(): string[] {
+    return Array.from(McpManager._resources.keys())
+  }
+
+  static registeredPrompts(): string[] {
+    return Array.from(McpManager._prompts.keys())
+  }
+
+  static getToolRegistration(name: string): ToolRegistration | undefined {
+    return McpManager._tools.get(name)
+  }
+
+  static getResourceRegistration(uri: string): ResourceRegistration | undefined {
+    return McpManager._resources.get(uri)
+  }
+
+  static getPromptRegistration(name: string): PromptRegistration | undefined {
+    return McpManager._prompts.get(name)
+  }
+
+  // ── Reset ──────────────────────────────────────────────────────────
+
+  /** Reset all state. Intended for test teardown. */
+  static reset(): void {
+    McpManager._tools.clear()
+    McpManager._resources.clear()
+    McpManager._prompts.clear()
+    McpManager._server = null
+    McpManager._config = undefined as any
+  }
+}

package/src/mcp_provider.ts

@@ -0,0 +1,43 @@
+import { ServiceProvider } from '@stravigor/kernel'
+import type { Application } from '@stravigor/kernel'
+import { Router } from '@stravigor/http'
+import McpManager from './mcp_manager.ts'
+import { mountHttpTransport } from './transports/bun_http_transport.ts'
+
+export interface McpProviderOptions {
+  /** Auto-mount HTTP transport on the router. Default: `true` */
+  mountHttp?: boolean
+}
+
+export default class McpProvider extends ServiceProvider {
+  readonly name = 'mcp'
+  override readonly dependencies = ['config']
+
+  constructor(private options?: McpProviderOptions) {
+    super()
+  }
+
+  override register(app: Application): void {
+    app.singleton(McpManager)
+  }
+
+  override async boot(app: Application): Promise<void> {
+    app.resolve(McpManager)
+
+    // Load user registration file if configured
+    const registerPath = McpManager.config.register
+    if (registerPath) {
+      await import(`${process.cwd()}/${registerPath}`)
+    }
+
+    // Mount HTTP transport on the router
+    if (this.options?.mountHttp !== false && McpManager.config.http.enabled) {
+      const router = app.resolve(Router)
+      mountHttpTransport(router)
+    }
+  }
+
+  override shutdown(): void {
+    McpManager.reset()
+  }
+}

package/src/transports/bun_http_transport.ts

@@ -0,0 +1,42 @@
+import { WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js'
+import type { Router, Context } from '@stravigor/http'
+import { Emitter } from '@stravigor/kernel'
+import McpManager from '../mcp_manager.ts'
+
+export type { WebStandardStreamableHTTPServerTransport }
+
+/**
+ * Mount the MCP server on a Stravigor router via Streamable HTTP.
+ *
+ * Uses the SDK's `WebStandardStreamableHTTPServerTransport` which works
+ * natively with Bun's Web Standard Request/Response API.
+ *
+ * Registers handlers at the configured path (default: `/mcp`) for
+ * POST (requests), GET (SSE), and DELETE (session termination).
+ */
+export function mountHttpTransport(router: Router): WebStandardStreamableHTTPServerTransport {
+  const path = McpManager.config.http.path
+
+  const transport = new WebStandardStreamableHTTPServerTransport({
+    sessionIdGenerator: () => crypto.randomUUID(),
+  })
+
+  const server = McpManager.getServer()
+  server.connect(transport)
+
+  // The SDK transport handles POST/GET/DELETE routing internally
+  // via handleRequest(req: Request): Promise<Response>.
+  const handler = async (ctx: Context) => {
+    const response = await transport.handleRequest(ctx.request)
+    await Emitter.emit('mcp:http-request', { method: ctx.method, path })
+    return response
+  }
+
+  router.post(path, handler)
+  router.get(path, handler)
+  router.delete(path, handler)
+
+  Emitter.emit('mcp:http-mounted', { path })
+
+  return transport
+}

package/src/transports/stdio.ts

@@ -0,0 +1,30 @@
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { Emitter } from '@stravigor/kernel'
+import McpManager from '../mcp_manager.ts'
+
+/**
+ * Start the MCP server in stdio mode.
+ *
+ * Reads JSON-RPC messages from stdin, writes responses to stdout.
+ * Blocks until the AI client disconnects.
+ *
+ * Used by the `mcp:serve` CLI command. Claude Desktop spawns
+ * the process and communicates over stdio.
+ */
+export async function serveStdio(): Promise<void> {
+  const server = McpManager.getServer()
+  const transport = new StdioServerTransport()
+
+  await Emitter.emit('mcp:stdio-starting')
+
+  await server.connect(transport)
+
+  await Emitter.emit('mcp:stdio-connected')
+
+  // Block until the transport closes (AI client disconnects)
+  await new Promise<void>(resolve => {
+    transport.onclose = () => {
+      Emitter.emit('mcp:stdio-closed').then(resolve)
+    }
+  })
+}

package/src/types.ts

@@ -0,0 +1,86 @@
+import type { z } from 'zod'
+import type { Application } from '@stravigor/kernel'
+import type {
+  CallToolResult,
+  GetPromptResult,
+  ReadResourceResult,
+} from '@modelcontextprotocol/sdk/types.js'
+
+// Re-export SDK result types for user convenience
+export type { CallToolResult, GetPromptResult, ReadResourceResult }
+
+// ── Configuration ────────────────────────────────────────────────────
+
+export interface McpConfig {
+  /** Server name shown to AI clients. Defaults to app name. */
+  name: string
+  /** Server version. */
+  version: string
+  /** Path to a file that registers tools/resources/prompts (for CLI). */
+  register?: string
+  /** HTTP transport settings. */
+  http: {
+    /** Whether to enable HTTP transport. */
+    enabled: boolean
+    /** Mount path for the MCP endpoint. */
+    path: string
+  }
+}
+
+// ── Handler Context ──────────────────────────────────────────────────
+
+export interface ToolHandlerContext {
+  /** The Application container — resolve any service via DI. */
+  app: Application
+}
+
+// ── Tool ─────────────────────────────────────────────────────────────
+
+/** Raw Zod shape: `{ id: z.number(), name: z.string() }`. */
+export type ZodRawShape = Record<string, z.ZodTypeAny>
+
+/** Infer the output type from a Zod raw shape. */
+export type InferShape<T extends ZodRawShape> = { [K in keyof T]: z.infer<T[K]> }
+
+export interface ToolRegistration<TShape extends ZodRawShape = ZodRawShape> {
+  name: string
+  description?: string
+  input?: TShape
+  handler: ToolHandler<TShape>
+}
+
+export type ToolHandler<TShape extends ZodRawShape = ZodRawShape> = (
+  params: InferShape<TShape>,
+  ctx: ToolHandlerContext
+) => CallToolResult | Promise<CallToolResult>
+
+// ── Resource ─────────────────────────────────────────────────────────
+
+export interface ResourceRegistration {
+  /** URI or URI template, e.g., `'file:///config'` or `'strav://models/{name}'`. */
+  uri: string
+  name?: string
+  description?: string
+  mimeType?: string
+  handler: ResourceHandler
+}
+
+export type ResourceHandler = (
+  uri: URL,
+  params: Record<string, string>,
+  ctx: ToolHandlerContext
+) => ReadResourceResult | Promise<ReadResourceResult>
+
+// ── Prompt ───────────────────────────────────────────────────────────
+
+export interface PromptRegistration<TShape extends ZodRawShape = ZodRawShape> {
+  name: string
+  description?: string
+  args?: TShape
+  handler: PromptHandler<TShape>
+}
+
+export type PromptHandler<TShape extends ZodRawShape = ZodRawShape> = (
+  args: InferShape<TShape>,
+  ctx: ToolHandlerContext
+) => GetPromptResult | Promise<GetPromptResult>

package/stubs/config/mcp.ts

@@ -0,0 +1,24 @@
+import { env } from '@stravigor/kernel/helpers'
+
+export default {
+  /** Server name shown to AI clients. Defaults to app name if not set. */
+  name: env('MCP_NAME', undefined),
+
+  /** Server version. */
+  version: env('MCP_VERSION', '1.0.0'),
+
+  /**
+   * Path to the file that registers tools, resources, and prompts.
+   * This file is imported automatically by the provider and CLI commands.
+   */
+  register: 'mcp/server.ts',
+
+  /** HTTP transport settings (for hosted deployments). */
+  http: {
+    /** Enable the HTTP transport. Mounts an MCP endpoint on the router. */
+    enabled: env('MCP_HTTP', 'true').bool(),
+
+    /** Mount path for the MCP endpoint. */
+    path: env('MCP_PATH', '/mcp'),
+  },
+}

package/tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "tests"]
+}