mcp-expose 1.0.0

package/dist/koa/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/koa/index.ts","../../src/core/dispatch.ts","../../src/core/marker.ts","../../src/core/node.ts","../../src/core/schema.ts","../../src/core/route-tool.ts","../../src/core/server.ts"],"sourcesContent":["import type { IncomingMessage } from 'node:http';\nimport { createFetchDispatcher } from '../core/dispatch.js';\nimport { mark, markerOf } from '../core/marker.js';\nimport { loopbackBaseUrl, normalizeHeaders, readRawBody } from '../core/node.js';\nimport { createRouteTool } from '../core/route-tool.js';\nimport { McpServer } from '../core/server.js';\nimport type { McpServerOptions, McpToolDefinition, RouteToolOptions, ToolContext } from '../core/types.js';\n\ninterface KoaContext {\n  method: string;\n  path: string;\n  ip: string;\n  req: IncomingMessage;\n  request: { body?: unknown };\n  status: number;\n  body: unknown;\n  set(headers: Record<string, string>): void;\n}\ntype KoaMiddleware = (ctx: KoaContext, next: () => Promise<unknown>) => Promise<unknown>;\n\n/**\n * Mark a @koa/router route as an MCP tool:\n *\n *   router.get('/users/:id', mcpTool({ description: 'Get a user' }), auth, getUser)\n */\nexport function mcpTool(options: RouteToolOptions = {}): KoaMiddleware {\n  return mark<KoaMiddleware>((_ctx, next) => next(), options);\n}\n\ninterface RouterLike {\n  stack: { path: string | RegExp; methods: string[]; stack: unknown[] }[];\n}\n\nexport interface KoaMcpOptions extends McpServerOptions {\n  /** Path of the MCP endpoint. @default '/mcp' */\n  path?: string;\n  /** @koa/router instances to scan for `mcpTool()` routes. */\n  routers?: RouterLike[];\n  /** Base URL for internal calls. Defaults to loopback on the incoming port. */\n  baseUrl?: string;\n  /** Routes to expose without touching the route definitions. */\n  routes?: (RouteToolOptions & { method: string; path: string })[];\n  tools?: McpToolDefinition[];\n}\n\n/** Returns `{ server, middleware }`. Mount the middleware with `app.use()`. */\nexport function createKoaMcp(options: KoaMcpOptions): { server: McpServer; middleware: KoaMiddleware } {\n  const path = options.path ?? '/mcp';\n  const server = new McpServer(options);\n  const dispatch = createFetchDispatcher({\n    baseUrl: options.baseUrl ?? ((ctx) => loopbackBaseUrl(ctx.raw as IncomingMessage)),\n  });\n\n  for (const t of options.tools ?? []) server.addTool(t);\n  server.onLoad(() => {\n    for (const router of options.routers ?? []) {\n      for (const layer of router.stack) {\n        const marker = layer.stack.map(markerOf).find(Boolean);\n        if (!marker || typeof layer.path !== 'string') continue;\n        for (const method of layer.methods.filter((m) => m !== 'HEAD')) {\n          server.addTool(createRouteTool({ method, path: layer.path }, marker, dispatch, options));\n        }\n      }\n    }\n    for (const r of options.routes ?? []) server.addTool(createRouteTool(r, r, dispatch, options));\n  });\n\n  const middleware: KoaMiddleware = async (ctx, next) => {\n    if (ctx.path !== path) return next();\n    const body = ctx.request.body ?? (ctx.method === 'POST' ? await readRawBody(ctx.req) : undefined);\n    const toolCtx: ToolContext = { headers: normalizeHeaders(ctx.req.headers), clientIp: ctx.ip, raw: ctx.req };\n    const out = await server.handleHttp({ method: ctx.method, headers: toolCtx.headers, body }, toolCtx);\n    ctx.status = out.status;\n    ctx.set(out.headers);\n    if (out.body !== undefined) ctx.body = out.body;\n  };\n  return { server, middleware };\n}\n\n/** Shortcut: `app.use(koaMcp({ name, routers: [router] }))`. */\nexport function koaMcp(options: KoaMcpOptions): KoaMiddleware {\n  return createKoaMcp(options).middleware;\n}\n\n/**\n * Add the MCP endpoint to a Koa app and return the server:\n *\n *   mountMcp(app, { name: 'shop-api', routers: [router] })\n *   app.use(router.routes())\n *\n * Call it before mounting your routers, like any Koa middleware.\n */\nexport function mountMcp(app: { use(middleware: KoaMiddleware): unknown }, options: KoaMcpOptions): McpServer {\n  const { server, middleware } = createKoaMcp(options);\n  app.use(middleware);\n  return server;\n}\n\n// ---------------------------------------------------------------------------\n// Koa 1 (generator middleware, koa-router 5)\n// ---------------------------------------------------------------------------\n\ntype LegacyMiddleware = (this: KoaContext, next: unknown) => Generator<unknown, void, unknown>;\n\n/** Koa 1 variant of `mcpTool()` (a generator middleware for koa-router 5). */\nexport function mcpToolLegacy(options: RouteToolOptions = {}): LegacyMiddleware {\n  return mark<LegacyMiddleware>(function* (next) {\n    yield next;\n  }, options);\n}\n\n/** Koa 1 variant of `koaMcp()`: `app.use(koaMcpLegacy({ name, routers: [router] }))`. */\nexport function koaMcpLegacy(options: KoaMcpOptions): LegacyMiddleware {\n  const { middleware } = createKoaMcp(options);\n  return function* (next) {\n    let passThrough = false;\n    // Koa 1 runs on co, which can yield promises.\n    yield middleware(this, async () => {\n      passThrough = true;\n    });\n    if (passThrough) yield next;\n  };\n}\n","import type { Dispatcher, RouteRequest, ToolContext } from './types.js';\n\nexport function buildUrl(base: string, req: Pick<RouteRequest, 'path' | 'query'>): string {\n  const url = new URL(base.replace(/\\/+$/, '') + req.path);\n  for (const [k, v] of Object.entries(req.query)) {\n    for (const item of Array.isArray(v) ? v : [v]) url.searchParams.append(k, item);\n  }\n  return url.toString();\n}\n\nexport interface FetchDispatcherOptions {\n  /**\n   * Base URL of the API, e.g. `http://127.0.0.1:3000` or `https://api.example.com/v1`.\n   * A function lets adapters resolve it per call (e.g. from the local port).\n   */\n  baseUrl: string | ((ctx: ToolContext) => string);\n  /** Custom fetch implementation. Defaults to the global `fetch`. */\n  fetch?: typeof fetch;\n  /** Per-request timeout in ms. @default 30_000 */\n  timeoutMs?: number;\n}\n\n/**\n * Dispatches tool calls as real HTTP requests. Used for loopback calls into the\n * host app (Express, Koa, NestJS) and for standalone gateways in front of any API.\n */\nexport function createFetchDispatcher(opts: FetchDispatcherOptions): Dispatcher {\n  const doFetch = opts.fetch ?? fetch;\n  return async (req, ctx) => {\n    const base = typeof opts.baseUrl === 'function' ? opts.baseUrl(ctx) : opts.baseUrl;\n    const res = await doFetch(buildUrl(base, req), {\n      method: req.method,\n      headers: req.headers,\n      body:\n        req.body === undefined || req.method === 'GET' || req.method === 'HEAD' ? undefined : JSON.stringify(req.body),\n      signal: AbortSignal.timeout(opts.timeoutMs ?? 30_000),\n    });\n    const headers: Record<string, string> = {};\n    res.headers.forEach((v, k) => (headers[k] = v));\n    return { status: res.status, headers, body: await res.text() };\n  };\n}\n","import type { RouteToolOptions } from './types.js';\n\n/** Symbol under which marker middleware carries its tool options. */\nexport const MCP_TOOL = Symbol.for('mcp-expose.tool');\n\nexport type Marked<T> = T & { [MCP_TOOL]: RouteToolOptions };\n\nexport function markerOf(fn: unknown): RouteToolOptions | undefined {\n  return typeof fn === 'function' ? (fn as Partial<Marked<object>>)[MCP_TOOL] : undefined;\n}\n\nexport function mark<T extends object>(fn: T, opts: RouteToolOptions): Marked<T> {\n  Object.defineProperty(fn, MCP_TOOL, { value: opts, enumerable: false });\n  return fn as Marked<T>;\n}\n","import type { IncomingMessage, ServerResponse } from 'node:http';\nimport type { McpHttpResponse } from './server.js';\n\n/** Flatten Node's IncomingHttpHeaders into lower-cased single strings. */\nexport function normalizeHeaders(headers: Record<string, string | string[] | undefined>): Record<string, string> {\n  const out: Record<string, string> = {};\n  for (const [k, v] of Object.entries(headers)) {\n    if (v === undefined) continue;\n    out[k.toLowerCase()] = Array.isArray(v) ? v.join(', ') : String(v);\n  }\n  return out;\n}\n\n/** Read and return the raw body of a Node request (for frameworks without a JSON body parser). */\nexport function readRawBody(req: IncomingMessage, limit = 4 * 1024 * 1024): Promise<string> {\n  return new Promise((resolve, reject) => {\n    let size = 0;\n    const chunks: Buffer[] = [];\n    req.on('data', (c: Buffer) => {\n      size += c.length;\n      if (size > limit) {\n        reject(new Error('Request body too large'));\n        req.destroy();\n      } else chunks.push(c);\n    });\n    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));\n    req.on('error', reject);\n  });\n}\n\n/** Base URL that reaches the same server the MCP request arrived on. */\nexport function loopbackBaseUrl(req: IncomingMessage): string {\n  const socket = req.socket as IncomingMessage['socket'] & {\n    encrypted?: boolean;\n    server?: { address(): { address: string } | string | null };\n  };\n  const port = socket.localPort;\n  const encrypted = socket.encrypted;\n  // Prefer the address the server is bound to: when it listens on all\n  // interfaces this yields 127.0.0.1, so internal calls come from loopback\n  // (which `trust proxy: 'loopback'` style settings rely on).\n  const bound = socket.server?.address();\n  let host = (typeof bound === 'object' && bound?.address) || socket.localAddress || '127.0.0.1';\n  if (host.startsWith('::ffff:')) host = host.slice(7);\n  if (host === '::' || host === '0.0.0.0') host = '127.0.0.1';\n  if (host.includes(':')) host = `[${host}]`;\n  return `${encrypted ? 'https' : 'http'}://${host}:${port}`;\n}\n\nexport function writeNodeResponse(res: ServerResponse, out: McpHttpResponse): void {\n  res.statusCode = out.status;\n  for (const [k, v] of Object.entries(out.headers)) res.setHeader(k, v);\n  res.end(out.body);\n}\n","import type { JsonSchema, McpToolDefinition, SchemaLike } from './types.js';\n\ninterface StandardSchemaV1 {\n  '~standard': {\n    validate?: (value: unknown) => unknown;\n    jsonSchema?: { input?: (opts: { target: string }) => unknown };\n  };\n}\n\nfunction isStandard(s: unknown): s is StandardSchemaV1 {\n  return typeof s === 'object' && s !== null && '~standard' in s;\n}\n\n/** Convert any supported schema flavour into a plain JSON Schema object. */\nexport function toJsonSchema(schema: SchemaLike | undefined): JsonSchema | undefined {\n  if (schema === undefined || schema === null) return undefined;\n  let out: unknown;\n  if (isStandard(schema) && typeof schema['~standard'].jsonSchema?.input === 'function') {\n    out = schema['~standard'].jsonSchema.input({ target: 'draft-2020-12' });\n  } else if (typeof (schema as { toJSONSchema?: unknown }).toJSONSchema === 'function') {\n    out = (schema as { toJSONSchema(): unknown }).toJSONSchema();\n  } else if (isStandard(schema)) {\n    throw new Error(\n      'mcp-expose: this schema library does not support JSON Schema export. Pass a plain JSON Schema instead.',\n    );\n  } else {\n    out = schema;\n  }\n  const { $schema: _ignored, ...rest } = out as JsonSchema;\n  return rest;\n}\n\n/** Build a validator from a Standard Schema, if the input is one. */\nexport function toValidator(schema: SchemaLike | undefined): McpToolDefinition['validate'] {\n  if (!isStandard(schema) || typeof schema['~standard'].validate !== 'function') return undefined;\n  const validate = schema['~standard'].validate;\n  return async (value) => {\n    const result = (await validate(value)) as {\n      value?: unknown;\n      issues?: { message: string; path?: (PropertyKey | { key: PropertyKey })[] }[];\n    };\n    if (!result.issues) return { ok: true, value: result.value };\n    const message = result.issues\n      .map((i) => {\n        const path = (i.path ?? []).map((p) => (typeof p === 'object' ? String(p.key) : String(p))).join('.');\n        return path ? `${path}: ${i.message}` : i.message;\n      })\n      .join('; ');\n    return { ok: false, message };\n  };\n}\n\n/** Very small structural check used when no Standard Schema validator exists. */\nexport function checkRequired(schema: JsonSchema, args: Record<string, unknown>): string | undefined {\n  const missing = (schema.required ?? []).filter((k) => args[k] === undefined);\n  return missing.length ? `Missing required argument(s): ${missing.join(', ')}` : undefined;\n}\n","import { checkRequired, toJsonSchema, toValidator } from './schema.js';\nimport type {\n  Dispatcher,\n  JsonSchema,\n  McpServerOptions,\n  McpToolDefinition,\n  RouteResponse,\n  RouteSpec,\n  RouteToolOptions,\n  ToolAnnotations,\n  ToolContext,\n  ToolResult,\n} from './types.js';\n\nexport const DEFAULT_FORWARD_HEADERS = ['authorization', 'cookie', 'x-api-key', 'accept-language'];\nconst BODY_METHODS = new Set(['POST', 'PUT', 'PATCH']);\nconst PARAM_RE = /:([A-Za-z0-9_]+)\\??|\\{([A-Za-z0-9_]+)\\}/g;\n\n/** Names of the path parameters in a route path (`/a/:id/{slug}` -> ['id', 'slug']). */\nexport function pathParams(path: string): string[] {\n  return [...path.matchAll(PARAM_RE)].map((m) => (m[1] ?? m[2]) as string);\n}\n\n/**\n * Encode one path-parameter value. Rejects empty, `.` and `..` values: after URL\n * normalisation they would change which route is called (e.g. `/orders/../admin`),\n * letting an agent reach routes that were never exposed as tools.\n */\nfunction encodeSegment(name: string, value: unknown): string {\n  const raw = String(value);\n  if (raw === '' || raw === '.' || raw === '..') {\n    throw new Error(`Invalid value for path parameter \"${name}\": ${JSON.stringify(raw)}`);\n  }\n  return encodeURIComponent(raw);\n}\n\n/** Replace path placeholders with URL-encoded values. Missing optional params drop their segment. */\nexport function interpolatePath(path: string, values: Record<string, unknown>): string {\n  return path\n    .replace(/\\/:([A-Za-z0-9_]+)\\?/g, (_, k: string) =>\n      values[k] === undefined ? '' : `/${encodeSegment(k, values[k])}`,\n    )\n    .replace(PARAM_RE, (_, a?: string, b?: string) => {\n      const k = (a ?? b) as string;\n      return encodeSegment(k, values[k]);\n    });\n}\n\n/** Join path segments, normalising slashes. */\nexport function joinPaths(...parts: (string | undefined)[]): string {\n  const joined = parts\n    .filter((p): p is string => !!p && p !== '/')\n    .map((p) => p.replace(/^\\/+|\\/+$/g, ''))\n    .filter(Boolean)\n    .join('/');\n  return `/${joined}`;\n}\n\n/** `GET /users/:id/orders` -> `get_users_by_id_orders` */\nexport function toolNameFromRoute(method: string, path: string): string {\n  const segments = path\n    .split('/')\n    .filter(Boolean)\n    .map((s) => {\n      const m = /^(?::([A-Za-z0-9_]+)\\??|\\{([A-Za-z0-9_]+)\\})$/.exec(s);\n      return m ? `by_${m[1] ?? m[2]}` : s;\n    });\n  return sanitizeToolName([method.toLowerCase(), ...segments].join('_'));\n}\n\nexport function sanitizeToolName(name: string): string {\n  return name\n    .replace(/[^A-Za-z0-9_-]+/g, '_')\n    .replace(/_+/g, '_')\n    .replace(/^_|_$/g, '')\n    .slice(0, 64);\n}\n\nfunction defaultAnnotations(method: string): ToolAnnotations {\n  switch (method) {\n    case 'GET':\n    case 'HEAD':\n      return { readOnlyHint: true, openWorldHint: false };\n    case 'DELETE':\n      return { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false };\n    case 'PUT':\n      return { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };\n    default:\n      return { readOnlyHint: false, destructiveHint: false, openWorldHint: false };\n  }\n}\n\ninterface ArgMapping {\n  params: string[];\n  query: Set<string>;\n  body: Set<string>;\n  /** Body schema is not an object: the whole body is passed under the `body` key. */\n  wholeBody: boolean;\n  bodyMethod: boolean;\n}\n\n/**\n * Build the flat input schema an agent sees, and remember which argument goes\n * to the path, query string or body when the tool is called.\n */\nexport function buildInputSchema(\n  route: RouteSpec,\n  opts: RouteToolOptions,\n): { schema: JsonSchema; mapping: ArgMapping } {\n  const method = route.method.toUpperCase();\n  const params = pathParams(route.path);\n  const mapping: ArgMapping = {\n    params,\n    query: new Set(),\n    body: new Set(),\n    wholeBody: false,\n    bodyMethod: BODY_METHODS.has(method),\n  };\n\n  if (opts.input) {\n    const schema = toJsonSchema(opts.input) as JsonSchema;\n    return { schema: { type: 'object', ...schema }, mapping };\n  }\n\n  const properties: Record<string, JsonSchema> = {};\n  const required = new Set<string>();\n\n  const paramSchema = toJsonSchema(opts.params);\n  for (const p of params) {\n    properties[p] = paramSchema?.properties?.[p] ?? { type: 'string', description: `Path parameter \"${p}\"` };\n    if (!route.path.includes(`:${p}?`)) required.add(p);\n  }\n\n  const querySchema = toJsonSchema(opts.query);\n  for (const [k, v] of Object.entries(querySchema?.properties ?? {})) {\n    properties[k] = v;\n    mapping.query.add(k);\n  }\n  for (const k of querySchema?.required ?? []) required.add(k);\n\n  const bodySchema = toJsonSchema(opts.body);\n  if (bodySchema) {\n    if (bodySchema.properties && (bodySchema.type === undefined || bodySchema.type === 'object')) {\n      for (const [k, v] of Object.entries(bodySchema.properties)) {\n        properties[k] = v;\n        mapping.body.add(k);\n      }\n      for (const k of bodySchema.required ?? []) required.add(k);\n    } else {\n      properties.body = bodySchema;\n      required.add('body');\n      mapping.wholeBody = true;\n    }\n  }\n\n  const schema: JsonSchema = { type: 'object', properties };\n  if (required.size) schema.required = [...required];\n  return { schema, mapping };\n}\n\nfunction splitArgs(args: Record<string, unknown>, mapping: ArgMapping) {\n  const pathValues: Record<string, unknown> = {};\n  const query: Record<string, string | string[]> = {};\n  let body: Record<string, unknown> | unknown | undefined;\n\n  for (const [k, v] of Object.entries(args)) {\n    if (v === undefined) continue;\n    if (mapping.params.includes(k)) {\n      pathValues[k] = v;\n    } else if (mapping.wholeBody && k === 'body') {\n      body = v;\n    } else if (mapping.query.has(k) || (!mapping.body.has(k) && !mapping.bodyMethod)) {\n      query[k] = Array.isArray(v) ? v.map(String) : typeof v === 'object' && v !== null ? JSON.stringify(v) : String(v);\n    } else {\n      body = { ...((body as Record<string, unknown>) ?? {}), [k]: v };\n    }\n  }\n  if (body === undefined && mapping.bodyMethod) body = {};\n  return { pathValues, query, body };\n}\n\nexport function responseToResult(res: RouteResponse, maxChars: number): ToolResult {\n  let text = res.body;\n  if (text.length > maxChars) text = `${text.slice(0, maxChars)}\\n…[truncated ${text.length - maxChars} chars]`;\n  const isError = res.status >= 400;\n  const result: ToolResult = {\n    content: [{ type: 'text', text: isError ? `HTTP ${res.status}\\n${text}` : text || `HTTP ${res.status}` }],\n  };\n  if (isError) {\n    result.isError = true;\n    return result;\n  }\n  if ((res.headers['content-type'] ?? '').includes('json') && text === res.body) {\n    try {\n      const parsed = JSON.parse(res.body);\n      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) result.structuredContent = parsed;\n    } catch {\n      /* not JSON after all */\n    }\n  }\n  return result;\n}\n\nexport function pickForwardHeaders(ctx: ToolContext, names: string[]): Record<string, string> {\n  const out: Record<string, string> = {};\n  for (const name of names) {\n    const v = ctx.headers[name.toLowerCase()];\n    if (v !== undefined) out[name.toLowerCase()] = v;\n  }\n  return out;\n}\n\n/**\n * Turn an HTTP route + options into an MCP tool whose handler calls the route\n * through `dispatch`, so auth guards, validation and rate limits all still apply.\n */\nexport function createRouteTool(\n  route: RouteSpec,\n  opts: RouteToolOptions,\n  dispatch: Dispatcher,\n  serverOpts: Pick<McpServerOptions, 'forwardHeaders' | 'maxResponseChars'> = {},\n): McpToolDefinition {\n  const method = route.method.toUpperCase();\n  const name = sanitizeToolName(opts.name ?? toolNameFromRoute(method, route.path));\n  const { schema, mapping } = buildInputSchema(route, opts);\n  const forward = serverOpts.forwardHeaders ?? DEFAULT_FORWARD_HEADERS;\n  const maxChars = serverOpts.maxResponseChars ?? 100_000;\n\n  return {\n    name,\n    title: opts.title,\n    description: opts.description ?? `${method} ${route.path}`,\n    inputSchema: schema,\n    annotations: { ...defaultAnnotations(method), ...opts.annotations },\n    validate: toValidator(opts.input),\n    async handler(args, ctx) {\n      const missing = opts.input ? undefined : checkRequired(schema, args);\n      if (missing) return { isError: true, content: [{ type: 'text', text: missing }] };\n\n      const { pathValues, query, body } = splitArgs(args, mapping);\n      const headers: Record<string, string> = {\n        accept: 'application/json',\n        ...pickForwardHeaders(ctx, forward),\n        ...opts.headers,\n        'x-mcp-tool': name,\n      };\n      if (ctx.clientIp) headers['x-forwarded-for'] = ctx.clientIp;\n      if (body !== undefined) headers['content-type'] = 'application/json';\n\n      let path: string;\n      try {\n        path = interpolatePath(route.path, pathValues);\n      } catch (err) {\n        return { isError: true, content: [{ type: 'text', text: (err as Error).message }] };\n      }\n      const res = await dispatch({ method, path, query, body, headers }, ctx);\n      return responseToResult(res, maxChars);\n    },\n  };\n}\n","import type { McpServerOptions, McpToolDefinition, ToolContext, ToolResult } from './types.js';\n\nexport const SUPPORTED_PROTOCOL_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];\nexport const LATEST_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[0] as string;\n\ntype JsonRpcId = string | number | null;\ninterface JsonRpcRequest {\n  jsonrpc: '2.0';\n  id?: JsonRpcId;\n  method: string;\n  params?: Record<string, unknown>;\n}\nexport interface JsonRpcResponse {\n  jsonrpc: '2.0';\n  id: JsonRpcId;\n  result?: unknown;\n  error?: { code: number; message: string; data?: unknown };\n}\n\nconst PARSE_ERROR = -32700;\nconst INVALID_REQUEST = -32600;\nconst METHOD_NOT_FOUND = -32601;\nconst INVALID_PARAMS = -32602;\n\nconst ok = (id: JsonRpcId, result: unknown): JsonRpcResponse => ({ jsonrpc: '2.0', id, result });\nconst fail = (id: JsonRpcId, code: number, message: string): JsonRpcResponse => ({\n  jsonrpc: '2.0',\n  id,\n  error: { code, message },\n});\n\n/** Minimal HTTP request/response shapes, so each adapter can bridge its own framework. */\nexport interface McpHttpRequest {\n  method: string;\n  headers: Record<string, string>;\n  /** Parsed JSON body, or the raw string. */\n  body: unknown;\n}\nexport interface McpHttpResponse {\n  status: number;\n  headers: Record<string, string>;\n  body?: string;\n}\n\n/**\n * A stateless MCP server speaking the Streamable HTTP transport (JSON responses).\n * Holds the tool registry and answers JSON-RPC messages.\n */\nexport class McpServer {\n  private readonly tools = new Map<string, McpToolDefinition>();\n  private loaders: (() => void | Promise<void>)[] = [];\n\n  constructor(readonly options: McpServerOptions) {}\n\n  /** Register a tool. Throws on duplicate names. */\n  addTool(tool: McpToolDefinition): this {\n    if (this.tools.has(tool.name)) {\n      throw new Error(`mcp-expose: duplicate tool name \"${tool.name}\". Set an explicit \\`name\\`.`);\n    }\n    this.tools.set(tool.name, tool);\n    return this;\n  }\n\n  /** Register a function that adds tools lazily, right before the first MCP request is served. */\n  onLoad(loader: () => void | Promise<void>): this {\n    this.loaders.push(loader);\n    return this;\n  }\n\n  async listTools(): Promise<McpToolDefinition[]> {\n    await this.load();\n    return [...this.tools.values()];\n  }\n\n  private async load() {\n    if (!this.loaders.length) return;\n    const loaders = this.loaders;\n    this.loaders = [];\n    for (const l of loaders) await l();\n  }\n\n  /** Handle one JSON-RPC message (or a batch). Returns null when no response is due. */\n  async handleMessage(message: unknown, ctx: ToolContext): Promise<JsonRpcResponse | JsonRpcResponse[] | null> {\n    if (Array.isArray(message)) {\n      const results = (await Promise.all(message.map((m) => this.handleOne(m, ctx)))).filter(\n        (r): r is JsonRpcResponse => r !== null,\n      );\n      return results.length ? results : null;\n    }\n    return this.handleOne(message, ctx);\n  }\n\n  private async handleOne(message: unknown, ctx: ToolContext): Promise<JsonRpcResponse | null> {\n    const msg = message as Partial<JsonRpcRequest>;\n    if (!msg || typeof msg !== 'object' || msg.jsonrpc !== '2.0') {\n      return fail(null, INVALID_REQUEST, 'Invalid JSON-RPC message');\n    }\n    // Responses from the client or notifications: acknowledge, no reply.\n    if (typeof msg.method !== 'string' || msg.id === undefined) return null;\n    const id = msg.id;\n    const params = msg.params ?? {};\n\n    await this.load();\n    switch (msg.method) {\n      case 'initialize': {\n        const requested = params.protocolVersion as string | undefined;\n        const protocolVersion =\n          requested && SUPPORTED_PROTOCOL_VERSIONS.includes(requested) ? requested : LATEST_PROTOCOL_VERSION;\n        return ok(id, {\n          protocolVersion,\n          capabilities: { tools: { listChanged: false } },\n          serverInfo: { name: this.options.name, version: this.options.version ?? '1.0.0' },\n          ...(this.options.instructions ? { instructions: this.options.instructions } : {}),\n        });\n      }\n      case 'ping':\n        return ok(id, {});\n      case 'tools/list':\n        return ok(id, {\n          tools: [...this.tools.values()].map((t) => ({\n            name: t.name,\n            ...(t.title ? { title: t.title } : {}),\n            description: t.description,\n            inputSchema: t.inputSchema,\n            ...(t.annotations ? { annotations: t.annotations } : {}),\n          })),\n        });\n      case 'tools/call': {\n        const tool = this.tools.get(params.name as string);\n        if (!tool) return fail(id, INVALID_PARAMS, `Unknown tool: ${String(params.name)}`);\n        return ok(id, await this.callTool(tool, (params.arguments ?? {}) as Record<string, unknown>, ctx));\n      }\n      case 'resources/list':\n        return ok(id, { resources: [] });\n      case 'prompts/list':\n        return ok(id, { prompts: [] });\n      default:\n        return fail(id, METHOD_NOT_FOUND, `Method not found: ${msg.method}`);\n    }\n  }\n\n  private async callTool(\n    tool: McpToolDefinition,\n    args: Record<string, unknown>,\n    ctx: ToolContext,\n  ): Promise<ToolResult> {\n    try {\n      if (tool.validate) {\n        const v = await tool.validate(args);\n        if (!v.ok) return { isError: true, content: [{ type: 'text', text: `Invalid arguments: ${v.message}` }] };\n        args = v.value as Record<string, unknown>;\n      }\n      return await tool.handler(args, ctx);\n    } catch (err) {\n      // Tool failures are reported in-band so the model can react to them.\n      return { isError: true, content: [{ type: 'text', text: `Tool error: ${(err as Error).message}` }] };\n    }\n  }\n\n  /** Check the Origin header (DNS rebinding protection). */\n  isOriginAllowed(origin: string | undefined): boolean {\n    if (!origin) return true;\n    const allowed = this.options.allowedOrigins;\n    if (allowed === '*') return true;\n    return (allowed ?? []).includes(origin);\n  }\n\n  /**\n   * Framework-neutral Streamable HTTP handler. Adapters convert their request\n   * into McpHttpRequest, call this, and write the McpHttpResponse back.\n   */\n  async handleHttp(req: McpHttpRequest, ctx: ToolContext): Promise<McpHttpResponse> {\n    const json = { 'content-type': 'application/json' };\n    if (!this.isOriginAllowed(req.headers.origin)) {\n      return { status: 403, headers: json, body: JSON.stringify(fail(null, INVALID_REQUEST, 'Origin not allowed')) };\n    }\n    if (req.method.toUpperCase() !== 'POST') {\n      // Stateless server: no standalone SSE stream and no sessions to delete.\n      return { status: 405, headers: { allow: 'POST' } };\n    }\n    let body = req.body;\n    if (typeof body === 'string' || body instanceof Uint8Array) {\n      try {\n        body = JSON.parse(typeof body === 'string' ? body : new TextDecoder().decode(body));\n      } catch {\n        return { status: 400, headers: json, body: JSON.stringify(fail(null, PARSE_ERROR, 'Parse error')) };\n      }\n    }\n    const response = await this.handleMessage(body, ctx);\n    if (response === null) return { status: 202, headers: {} };\n    return { status: 200, headers: json, body: JSON.stringify(response) };\n  }\n}\n"],"mappings":"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","names":["buildUrl","base","req","url","URL","replace","path","k","v","Object","entries","query","item","Array","isArray","searchParams","append","toString","createFetchDispatcher","opts","doFetch","fetch","ctx","baseUrl","res","method","headers","body","undefined","JSON","stringify","signal","AbortSignal","timeout","timeoutMs","forEach","status","text","MCP_TOOL","Symbol","for","markerOf","fn","undefined","mark","opts","Object","defineProperty","value","enumerable","normalizeHeaders","headers","out","k","v","Object","entries","undefined","toLowerCase","Array","isArray","join","String","readRawBody","req","limit","Promise","resolve","reject","size","chunks","on","c","length","Error","destroy","push","Buffer","concat","toString","loopbackBaseUrl","socket","port","localPort","encrypted","bound","server","address","host","localAddress","startsWith","slice","includes","isStandard","s","toJsonSchema","schema","undefined","out","jsonSchema","input","target","toJSONSchema","Error","$schema","_ignored","rest","toValidator","validate","value","result","issues","ok","message","map","i","path","p","String","key","join","checkRequired","args","missing","required","filter","k","length","DEFAULT_FORWARD_HEADERS","BODY_METHODS","Set","PARAM_RE","pathParams","path","matchAll","map","m","encodeSegment","name","value","raw","String","Error","JSON","stringify","encodeURIComponent","interpolatePath","values","replace","_","k","undefined","a","b","toolNameFromRoute","method","path","segments","split","filter","Boolean","map","s","m","exec","sanitizeToolName","toLowerCase","join","name","replace","slice","defaultAnnotations","readOnlyHint","openWorldHint","destructiveHint","idempotentHint","buildInputSchema","route","opts","toUpperCase","params","pathParams","mapping","query","Set","body","wholeBody","bodyMethod","BODY_METHODS","has","input","schema","toJsonSchema","type","properties","required","paramSchema","p","description","includes","add","querySchema","k","v","Object","entries","bodySchema","undefined","size","splitArgs","args","pathValues","Array","isArray","String","JSON","stringify","responseToResult","res","maxChars","text","length","isError","status","result","content","headers","parsed","parse","structuredContent","pickForwardHeaders","ctx","names","out","createRouteTool","dispatch","serverOpts","forward","forwardHeaders","DEFAULT_FORWARD_HEADERS","maxResponseChars","title","inputSchema","annotations","validate","toValidator","handler","missing","checkRequired","accept","clientIp","interpolatePath","err","message","SUPPORTED_PROTOCOL_VERSIONS","LATEST_PROTOCOL_VERSION","PARSE_ERROR","INVALID_REQUEST","METHOD_NOT_FOUND","INVALID_PARAMS","ok","id","result","jsonrpc","fail","code","message","error","McpServer","tools","Map","loaders","options","addTool","tool","has","name","Error","set","onLoad","loader","push","listTools","load","values","length","l","handleMessage","ctx","Array","isArray","results","Promise","all","map","m","handleOne","filter","r","msg","method","undefined","params","requested","protocolVersion","includes","capabilities","listChanged","serverInfo","version","instructions","t","title","description","inputSchema","annotations","get","String","callTool","arguments","resources","prompts","args","validate","v","isError","content","type","text","value","handler","err","isOriginAllowed","origin","allowed","allowedOrigins","handleHttp","req","json","headers","status","body","JSON","stringify","toUpperCase","allow","Uint8Array","parse","TextDecoder","decode","response","mcpTool","options","mark","_ctx","next","createKoaMcp","path","server","McpServer","dispatch","createFetchDispatcher","baseUrl","ctx","loopbackBaseUrl","raw","t","tools","addTool","onLoad","router","routers","layer","stack","marker","map","markerOf","find","Boolean","method","methods","filter","m","createRouteTool","r","routes","middleware","body","request","readRawBody","req","undefined","toolCtx","headers","normalizeHeaders","clientIp","ip","out","handleHttp","status","set","koaMcp","mountMcp","app","use","mcpToolLegacy","koaMcpLegacy","passThrough"]}

package/dist/koa/index.d.cts

@@ -0,0 +1,68 @@
+import { IncomingMessage } from 'node:http';
+import { M as McpServerOptions, R as RouteToolOptions, a as McpToolDefinition, b as McpServer } from '../server-fzkb-wJo.cjs';
+
+interface KoaContext {
+    method: string;
+    path: string;
+    ip: string;
+    req: IncomingMessage;
+    request: {
+        body?: unknown;
+    };
+    status: number;
+    body: unknown;
+    set(headers: Record<string, string>): void;
+}
+type KoaMiddleware = (ctx: KoaContext, next: () => Promise<unknown>) => Promise<unknown>;
+/**
+ * Mark a @koa/router route as an MCP tool:
+ *
+ *   router.get('/users/:id', mcpTool({ description: 'Get a user' }), auth, getUser)
+ */
+declare function mcpTool(options?: RouteToolOptions): KoaMiddleware;
+interface RouterLike {
+    stack: {
+        path: string | RegExp;
+        methods: string[];
+        stack: unknown[];
+    }[];
+}
+interface KoaMcpOptions extends McpServerOptions {
+    /** Path of the MCP endpoint. @default '/mcp' */
+    path?: string;
+    /** @koa/router instances to scan for `mcpTool()` routes. */
+    routers?: RouterLike[];
+    /** Base URL for internal calls. Defaults to loopback on the incoming port. */
+    baseUrl?: string;
+    /** Routes to expose without touching the route definitions. */
+    routes?: (RouteToolOptions & {
+        method: string;
+        path: string;
+    })[];
+    tools?: McpToolDefinition[];
+}
+/** Returns `{ server, middleware }`. Mount the middleware with `app.use()`. */
+declare function createKoaMcp(options: KoaMcpOptions): {
+    server: McpServer;
+    middleware: KoaMiddleware;
+};
+/** Shortcut: `app.use(koaMcp({ name, routers: [router] }))`. */
+declare function koaMcp(options: KoaMcpOptions): KoaMiddleware;
+/**
+ * Add the MCP endpoint to a Koa app and return the server:
+ *
+ *   mountMcp(app, { name: 'shop-api', routers: [router] })
+ *   app.use(router.routes())
+ *
+ * Call it before mounting your routers, like any Koa middleware.
+ */
+declare function mountMcp(app: {
+    use(middleware: KoaMiddleware): unknown;
+}, options: KoaMcpOptions): McpServer;
+type LegacyMiddleware = (this: KoaContext, next: unknown) => Generator<unknown, void, unknown>;
+/** Koa 1 variant of `mcpTool()` (a generator middleware for koa-router 5). */
+declare function mcpToolLegacy(options?: RouteToolOptions): LegacyMiddleware;
+/** Koa 1 variant of `koaMcp()`: `app.use(koaMcpLegacy({ name, routers: [router] }))`. */
+declare function koaMcpLegacy(options: KoaMcpOptions): LegacyMiddleware;
+
+export { type KoaMcpOptions, createKoaMcp, koaMcp, koaMcpLegacy, mcpTool, mcpToolLegacy, mountMcp };

package/dist/koa/index.d.ts

@@ -0,0 +1,68 @@
+import { IncomingMessage } from 'node:http';
+import { M as McpServerOptions, R as RouteToolOptions, a as McpToolDefinition, b as McpServer } from '../server-fzkb-wJo.js';
+
+interface KoaContext {
+    method: string;
+    path: string;
+    ip: string;
+    req: IncomingMessage;
+    request: {
+        body?: unknown;
+    };
+    status: number;
+    body: unknown;
+    set(headers: Record<string, string>): void;
+}
+type KoaMiddleware = (ctx: KoaContext, next: () => Promise<unknown>) => Promise<unknown>;
+/**
+ * Mark a @koa/router route as an MCP tool:
+ *
+ *   router.get('/users/:id', mcpTool({ description: 'Get a user' }), auth, getUser)
+ */
+declare function mcpTool(options?: RouteToolOptions): KoaMiddleware;
+interface RouterLike {
+    stack: {
+        path: string | RegExp;
+        methods: string[];
+        stack: unknown[];
+    }[];
+}
+interface KoaMcpOptions extends McpServerOptions {
+    /** Path of the MCP endpoint. @default '/mcp' */
+    path?: string;
+    /** @koa/router instances to scan for `mcpTool()` routes. */
+    routers?: RouterLike[];
+    /** Base URL for internal calls. Defaults to loopback on the incoming port. */
+    baseUrl?: string;
+    /** Routes to expose without touching the route definitions. */
+    routes?: (RouteToolOptions & {
+        method: string;
+        path: string;
+    })[];
+    tools?: McpToolDefinition[];
+}
+/** Returns `{ server, middleware }`. Mount the middleware with `app.use()`. */
+declare function createKoaMcp(options: KoaMcpOptions): {
+    server: McpServer;
+    middleware: KoaMiddleware;
+};
+/** Shortcut: `app.use(koaMcp({ name, routers: [router] }))`. */
+declare function koaMcp(options: KoaMcpOptions): KoaMiddleware;
+/**
+ * Add the MCP endpoint to a Koa app and return the server:
+ *
+ *   mountMcp(app, { name: 'shop-api', routers: [router] })
+ *   app.use(router.routes())
+ *
+ * Call it before mounting your routers, like any Koa middleware.
+ */
+declare function mountMcp(app: {
+    use(middleware: KoaMiddleware): unknown;
+}, options: KoaMcpOptions): McpServer;
+type LegacyMiddleware = (this: KoaContext, next: unknown) => Generator<unknown, void, unknown>;
+/** Koa 1 variant of `mcpTool()` (a generator middleware for koa-router 5). */
+declare function mcpToolLegacy(options?: RouteToolOptions): LegacyMiddleware;
+/** Koa 1 variant of `koaMcp()`: `app.use(koaMcpLegacy({ name, routers: [router] }))`. */
+declare function koaMcpLegacy(options: KoaMcpOptions): LegacyMiddleware;
+
+export { type KoaMcpOptions, createKoaMcp, koaMcp, koaMcpLegacy, mcpTool, mcpToolLegacy, mountMcp };