mcp-expose 1.0.0

package/dist/koa/index.js

@@ -0,0 +1,709 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/core/dispatch.ts
+function buildUrl(base, req) {
+  const url = new URL(base.replace(/\/+$/, "") + req.path);
+  for (const [k, v] of Object.entries(req.query)) {
+    for (const item of Array.isArray(v) ? v : [
+      v
+    ]) url.searchParams.append(k, item);
+  }
+  return url.toString();
+}
+__name(buildUrl, "buildUrl");
+function createFetchDispatcher(opts) {
+  const doFetch = opts.fetch ?? fetch;
+  return async (req, ctx) => {
+    const base = typeof opts.baseUrl === "function" ? opts.baseUrl(ctx) : opts.baseUrl;
+    const res = await doFetch(buildUrl(base, req), {
+      method: req.method,
+      headers: req.headers,
+      body: req.body === void 0 || req.method === "GET" || req.method === "HEAD" ? void 0 : JSON.stringify(req.body),
+      signal: AbortSignal.timeout(opts.timeoutMs ?? 3e4)
+    });
+    const headers = {};
+    res.headers.forEach((v, k) => headers[k] = v);
+    return {
+      status: res.status,
+      headers,
+      body: await res.text()
+    };
+  };
+}
+__name(createFetchDispatcher, "createFetchDispatcher");
+
+// src/core/marker.ts
+var MCP_TOOL = /* @__PURE__ */ Symbol.for("mcp-expose.tool");
+function markerOf(fn) {
+  return typeof fn === "function" ? fn[MCP_TOOL] : void 0;
+}
+__name(markerOf, "markerOf");
+function mark(fn, opts) {
+  Object.defineProperty(fn, MCP_TOOL, {
+    value: opts,
+    enumerable: false
+  });
+  return fn;
+}
+__name(mark, "mark");
+
+// src/core/node.ts
+function normalizeHeaders(headers) {
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) {
+    if (v === void 0) continue;
+    out[k.toLowerCase()] = Array.isArray(v) ? v.join(", ") : String(v);
+  }
+  return out;
+}
+__name(normalizeHeaders, "normalizeHeaders");
+function readRawBody(req, limit = 4 * 1024 * 1024) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    req.on("data", (c) => {
+      size += c.length;
+      if (size > limit) {
+        reject(new Error("Request body too large"));
+        req.destroy();
+      } else chunks.push(c);
+    });
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+}
+__name(readRawBody, "readRawBody");
+function loopbackBaseUrl(req) {
+  const socket = req.socket;
+  const port = socket.localPort;
+  const encrypted = socket.encrypted;
+  const bound = socket.server?.address();
+  let host = typeof bound === "object" && bound?.address || socket.localAddress || "127.0.0.1";
+  if (host.startsWith("::ffff:")) host = host.slice(7);
+  if (host === "::" || host === "0.0.0.0") host = "127.0.0.1";
+  if (host.includes(":")) host = `[${host}]`;
+  return `${encrypted ? "https" : "http"}://${host}:${port}`;
+}
+__name(loopbackBaseUrl, "loopbackBaseUrl");
+
+// src/core/schema.ts
+function isStandard(s) {
+  return typeof s === "object" && s !== null && "~standard" in s;
+}
+__name(isStandard, "isStandard");
+function toJsonSchema(schema) {
+  if (schema === void 0 || schema === null) return void 0;
+  let out;
+  if (isStandard(schema) && typeof schema["~standard"].jsonSchema?.input === "function") {
+    out = schema["~standard"].jsonSchema.input({
+      target: "draft-2020-12"
+    });
+  } else if (typeof schema.toJSONSchema === "function") {
+    out = schema.toJSONSchema();
+  } else if (isStandard(schema)) {
+    throw new Error("mcp-expose: this schema library does not support JSON Schema export. Pass a plain JSON Schema instead.");
+  } else {
+    out = schema;
+  }
+  const { $schema: _ignored, ...rest } = out;
+  return rest;
+}
+__name(toJsonSchema, "toJsonSchema");
+function toValidator(schema) {
+  if (!isStandard(schema) || typeof schema["~standard"].validate !== "function") return void 0;
+  const validate = schema["~standard"].validate;
+  return async (value) => {
+    const result = await validate(value);
+    if (!result.issues) return {
+      ok: true,
+      value: result.value
+    };
+    const message = result.issues.map((i) => {
+      const path = (i.path ?? []).map((p) => typeof p === "object" ? String(p.key) : String(p)).join(".");
+      return path ? `${path}: ${i.message}` : i.message;
+    }).join("; ");
+    return {
+      ok: false,
+      message
+    };
+  };
+}
+__name(toValidator, "toValidator");
+function checkRequired(schema, args) {
+  const missing = (schema.required ?? []).filter((k) => args[k] === void 0);
+  return missing.length ? `Missing required argument(s): ${missing.join(", ")}` : void 0;
+}
+__name(checkRequired, "checkRequired");
+
+// src/core/route-tool.ts
+var DEFAULT_FORWARD_HEADERS = [
+  "authorization",
+  "cookie",
+  "x-api-key",
+  "accept-language"
+];
+var BODY_METHODS = /* @__PURE__ */ new Set([
+  "POST",
+  "PUT",
+  "PATCH"
+]);
+var PARAM_RE = /:([A-Za-z0-9_]+)\??|\{([A-Za-z0-9_]+)\}/g;
+function pathParams(path) {
+  return [
+    ...path.matchAll(PARAM_RE)
+  ].map((m) => m[1] ?? m[2]);
+}
+__name(pathParams, "pathParams");
+function encodeSegment(name, value) {
+  const raw = String(value);
+  if (raw === "" || raw === "." || raw === "..") {
+    throw new Error(`Invalid value for path parameter "${name}": ${JSON.stringify(raw)}`);
+  }
+  return encodeURIComponent(raw);
+}
+__name(encodeSegment, "encodeSegment");
+function interpolatePath(path, values) {
+  return path.replace(/\/:([A-Za-z0-9_]+)\?/g, (_, k) => values[k] === void 0 ? "" : `/${encodeSegment(k, values[k])}`).replace(PARAM_RE, (_, a, b) => {
+    const k = a ?? b;
+    return encodeSegment(k, values[k]);
+  });
+}
+__name(interpolatePath, "interpolatePath");
+function toolNameFromRoute(method, path) {
+  const segments = path.split("/").filter(Boolean).map((s) => {
+    const m = /^(?::([A-Za-z0-9_]+)\??|\{([A-Za-z0-9_]+)\})$/.exec(s);
+    return m ? `by_${m[1] ?? m[2]}` : s;
+  });
+  return sanitizeToolName([
+    method.toLowerCase(),
+    ...segments
+  ].join("_"));
+}
+__name(toolNameFromRoute, "toolNameFromRoute");
+function sanitizeToolName(name) {
+  return name.replace(/[^A-Za-z0-9_-]+/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "").slice(0, 64);
+}
+__name(sanitizeToolName, "sanitizeToolName");
+function defaultAnnotations(method) {
+  switch (method) {
+    case "GET":
+    case "HEAD":
+      return {
+        readOnlyHint: true,
+        openWorldHint: false
+      };
+    case "DELETE":
+      return {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      };
+    case "PUT":
+      return {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false
+      };
+    default:
+      return {
+        readOnlyHint: false,
+        destructiveHint: false,
+        openWorldHint: false
+      };
+  }
+}
+__name(defaultAnnotations, "defaultAnnotations");
+function buildInputSchema(route, opts) {
+  const method = route.method.toUpperCase();
+  const params = pathParams(route.path);
+  const mapping = {
+    params,
+    query: /* @__PURE__ */ new Set(),
+    body: /* @__PURE__ */ new Set(),
+    wholeBody: false,
+    bodyMethod: BODY_METHODS.has(method)
+  };
+  if (opts.input) {
+    const schema2 = toJsonSchema(opts.input);
+    return {
+      schema: {
+        type: "object",
+        ...schema2
+      },
+      mapping
+    };
+  }
+  const properties = {};
+  const required = /* @__PURE__ */ new Set();
+  const paramSchema = toJsonSchema(opts.params);
+  for (const p of params) {
+    properties[p] = paramSchema?.properties?.[p] ?? {
+      type: "string",
+      description: `Path parameter "${p}"`
+    };
+    if (!route.path.includes(`:${p}?`)) required.add(p);
+  }
+  const querySchema = toJsonSchema(opts.query);
+  for (const [k, v] of Object.entries(querySchema?.properties ?? {})) {
+    properties[k] = v;
+    mapping.query.add(k);
+  }
+  for (const k of querySchema?.required ?? []) required.add(k);
+  const bodySchema = toJsonSchema(opts.body);
+  if (bodySchema) {
+    if (bodySchema.properties && (bodySchema.type === void 0 || bodySchema.type === "object")) {
+      for (const [k, v] of Object.entries(bodySchema.properties)) {
+        properties[k] = v;
+        mapping.body.add(k);
+      }
+      for (const k of bodySchema.required ?? []) required.add(k);
+    } else {
+      properties.body = bodySchema;
+      required.add("body");
+      mapping.wholeBody = true;
+    }
+  }
+  const schema = {
+    type: "object",
+    properties
+  };
+  if (required.size) schema.required = [
+    ...required
+  ];
+  return {
+    schema,
+    mapping
+  };
+}
+__name(buildInputSchema, "buildInputSchema");
+function splitArgs(args, mapping) {
+  const pathValues = {};
+  const query = {};
+  let body;
+  for (const [k, v] of Object.entries(args)) {
+    if (v === void 0) continue;
+    if (mapping.params.includes(k)) {
+      pathValues[k] = v;
+    } else if (mapping.wholeBody && k === "body") {
+      body = v;
+    } else if (mapping.query.has(k) || !mapping.body.has(k) && !mapping.bodyMethod) {
+      query[k] = Array.isArray(v) ? v.map(String) : typeof v === "object" && v !== null ? JSON.stringify(v) : String(v);
+    } else {
+      body = {
+        ...body ?? {},
+        [k]: v
+      };
+    }
+  }
+  if (body === void 0 && mapping.bodyMethod) body = {};
+  return {
+    pathValues,
+    query,
+    body
+  };
+}
+__name(splitArgs, "splitArgs");
+function responseToResult(res, maxChars) {
+  let text = res.body;
+  if (text.length > maxChars) text = `${text.slice(0, maxChars)}
+\u2026[truncated ${text.length - maxChars} chars]`;
+  const isError = res.status >= 400;
+  const result = {
+    content: [
+      {
+        type: "text",
+        text: isError ? `HTTP ${res.status}
+${text}` : text || `HTTP ${res.status}`
+      }
+    ]
+  };
+  if (isError) {
+    result.isError = true;
+    return result;
+  }
+  if ((res.headers["content-type"] ?? "").includes("json") && text === res.body) {
+    try {
+      const parsed = JSON.parse(res.body);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) result.structuredContent = parsed;
+    } catch {
+    }
+  }
+  return result;
+}
+__name(responseToResult, "responseToResult");
+function pickForwardHeaders(ctx, names) {
+  const out = {};
+  for (const name of names) {
+    const v = ctx.headers[name.toLowerCase()];
+    if (v !== void 0) out[name.toLowerCase()] = v;
+  }
+  return out;
+}
+__name(pickForwardHeaders, "pickForwardHeaders");
+function createRouteTool(route, opts, dispatch, serverOpts = {}) {
+  const method = route.method.toUpperCase();
+  const name = sanitizeToolName(opts.name ?? toolNameFromRoute(method, route.path));
+  const { schema, mapping } = buildInputSchema(route, opts);
+  const forward = serverOpts.forwardHeaders ?? DEFAULT_FORWARD_HEADERS;
+  const maxChars = serverOpts.maxResponseChars ?? 1e5;
+  return {
+    name,
+    title: opts.title,
+    description: opts.description ?? `${method} ${route.path}`,
+    inputSchema: schema,
+    annotations: {
+      ...defaultAnnotations(method),
+      ...opts.annotations
+    },
+    validate: toValidator(opts.input),
+    async handler(args, ctx) {
+      const missing = opts.input ? void 0 : checkRequired(schema, args);
+      if (missing) return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: missing
+          }
+        ]
+      };
+      const { pathValues, query, body } = splitArgs(args, mapping);
+      const headers = {
+        accept: "application/json",
+        ...pickForwardHeaders(ctx, forward),
+        ...opts.headers,
+        "x-mcp-tool": name
+      };
+      if (ctx.clientIp) headers["x-forwarded-for"] = ctx.clientIp;
+      if (body !== void 0) headers["content-type"] = "application/json";
+      let path;
+      try {
+        path = interpolatePath(route.path, pathValues);
+      } catch (err) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: err.message
+            }
+          ]
+        };
+      }
+      const res = await dispatch({
+        method,
+        path,
+        query,
+        body,
+        headers
+      }, ctx);
+      return responseToResult(res, maxChars);
+    }
+  };
+}
+__name(createRouteTool, "createRouteTool");
+
+// src/core/server.ts
+var SUPPORTED_PROTOCOL_VERSIONS = [
+  "2025-11-25",
+  "2025-06-18",
+  "2025-03-26",
+  "2024-11-05"
+];
+var LATEST_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[0];
+var PARSE_ERROR = -32700;
+var INVALID_REQUEST = -32600;
+var METHOD_NOT_FOUND = -32601;
+var INVALID_PARAMS = -32602;
+var ok = /* @__PURE__ */ __name((id, result) => ({
+  jsonrpc: "2.0",
+  id,
+  result
+}), "ok");
+var fail = /* @__PURE__ */ __name((id, code, message) => ({
+  jsonrpc: "2.0",
+  id,
+  error: {
+    code,
+    message
+  }
+}), "fail");
+var McpServer = class {
+  static {
+    __name(this, "McpServer");
+  }
+  options;
+  tools = /* @__PURE__ */ new Map();
+  loaders = [];
+  constructor(options) {
+    this.options = options;
+  }
+  /** Register a tool. Throws on duplicate names. */
+  addTool(tool) {
+    if (this.tools.has(tool.name)) {
+      throw new Error(`mcp-expose: duplicate tool name "${tool.name}". Set an explicit \`name\`.`);
+    }
+    this.tools.set(tool.name, tool);
+    return this;
+  }
+  /** Register a function that adds tools lazily, right before the first MCP request is served. */
+  onLoad(loader) {
+    this.loaders.push(loader);
+    return this;
+  }
+  async listTools() {
+    await this.load();
+    return [
+      ...this.tools.values()
+    ];
+  }
+  async load() {
+    if (!this.loaders.length) return;
+    const loaders = this.loaders;
+    this.loaders = [];
+    for (const l of loaders) await l();
+  }
+  /** Handle one JSON-RPC message (or a batch). Returns null when no response is due. */
+  async handleMessage(message, ctx) {
+    if (Array.isArray(message)) {
+      const results = (await Promise.all(message.map((m) => this.handleOne(m, ctx)))).filter((r) => r !== null);
+      return results.length ? results : null;
+    }
+    return this.handleOne(message, ctx);
+  }
+  async handleOne(message, ctx) {
+    const msg = message;
+    if (!msg || typeof msg !== "object" || msg.jsonrpc !== "2.0") {
+      return fail(null, INVALID_REQUEST, "Invalid JSON-RPC message");
+    }
+    if (typeof msg.method !== "string" || msg.id === void 0) return null;
+    const id = msg.id;
+    const params = msg.params ?? {};
+    await this.load();
+    switch (msg.method) {
+      case "initialize": {
+        const requested = params.protocolVersion;
+        const protocolVersion = requested && SUPPORTED_PROTOCOL_VERSIONS.includes(requested) ? requested : LATEST_PROTOCOL_VERSION;
+        return ok(id, {
+          protocolVersion,
+          capabilities: {
+            tools: {
+              listChanged: false
+            }
+          },
+          serverInfo: {
+            name: this.options.name,
+            version: this.options.version ?? "1.0.0"
+          },
+          ...this.options.instructions ? {
+            instructions: this.options.instructions
+          } : {}
+        });
+      }
+      case "ping":
+        return ok(id, {});
+      case "tools/list":
+        return ok(id, {
+          tools: [
+            ...this.tools.values()
+          ].map((t) => ({
+            name: t.name,
+            ...t.title ? {
+              title: t.title
+            } : {},
+            description: t.description,
+            inputSchema: t.inputSchema,
+            ...t.annotations ? {
+              annotations: t.annotations
+            } : {}
+          }))
+        });
+      case "tools/call": {
+        const tool = this.tools.get(params.name);
+        if (!tool) return fail(id, INVALID_PARAMS, `Unknown tool: ${String(params.name)}`);
+        return ok(id, await this.callTool(tool, params.arguments ?? {}, ctx));
+      }
+      case "resources/list":
+        return ok(id, {
+          resources: []
+        });
+      case "prompts/list":
+        return ok(id, {
+          prompts: []
+        });
+      default:
+        return fail(id, METHOD_NOT_FOUND, `Method not found: ${msg.method}`);
+    }
+  }
+  async callTool(tool, args, ctx) {
+    try {
+      if (tool.validate) {
+        const v = await tool.validate(args);
+        if (!v.ok) return {
+          isError: true,
+          content: [
+            {
+              type: "text",
+              text: `Invalid arguments: ${v.message}`
+            }
+          ]
+        };
+        args = v.value;
+      }
+      return await tool.handler(args, ctx);
+    } catch (err) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: `Tool error: ${err.message}`
+          }
+        ]
+      };
+    }
+  }
+  /** Check the Origin header (DNS rebinding protection). */
+  isOriginAllowed(origin) {
+    if (!origin) return true;
+    const allowed = this.options.allowedOrigins;
+    if (allowed === "*") return true;
+    return (allowed ?? []).includes(origin);
+  }
+  /**
+  * Framework-neutral Streamable HTTP handler. Adapters convert their request
+  * into McpHttpRequest, call this, and write the McpHttpResponse back.
+  */
+  async handleHttp(req, ctx) {
+    const json = {
+      "content-type": "application/json"
+    };
+    if (!this.isOriginAllowed(req.headers.origin)) {
+      return {
+        status: 403,
+        headers: json,
+        body: JSON.stringify(fail(null, INVALID_REQUEST, "Origin not allowed"))
+      };
+    }
+    if (req.method.toUpperCase() !== "POST") {
+      return {
+        status: 405,
+        headers: {
+          allow: "POST"
+        }
+      };
+    }
+    let body = req.body;
+    if (typeof body === "string" || body instanceof Uint8Array) {
+      try {
+        body = JSON.parse(typeof body === "string" ? body : new TextDecoder().decode(body));
+      } catch {
+        return {
+          status: 400,
+          headers: json,
+          body: JSON.stringify(fail(null, PARSE_ERROR, "Parse error"))
+        };
+      }
+    }
+    const response = await this.handleMessage(body, ctx);
+    if (response === null) return {
+      status: 202,
+      headers: {}
+    };
+    return {
+      status: 200,
+      headers: json,
+      body: JSON.stringify(response)
+    };
+  }
+};
+
+// src/koa/index.ts
+function mcpTool(options = {}) {
+  return mark((_ctx, next) => next(), options);
+}
+__name(mcpTool, "mcpTool");
+function createKoaMcp(options) {
+  const path = options.path ?? "/mcp";
+  const server = new McpServer(options);
+  const dispatch = createFetchDispatcher({
+    baseUrl: options.baseUrl ?? ((ctx) => loopbackBaseUrl(ctx.raw))
+  });
+  for (const t of options.tools ?? []) server.addTool(t);
+  server.onLoad(() => {
+    for (const router of options.routers ?? []) {
+      for (const layer of router.stack) {
+        const marker = layer.stack.map(markerOf).find(Boolean);
+        if (!marker || typeof layer.path !== "string") continue;
+        for (const method of layer.methods.filter((m) => m !== "HEAD")) {
+          server.addTool(createRouteTool({
+            method,
+            path: layer.path
+          }, marker, dispatch, options));
+        }
+      }
+    }
+    for (const r of options.routes ?? []) server.addTool(createRouteTool(r, r, dispatch, options));
+  });
+  const middleware = /* @__PURE__ */ __name(async (ctx, next) => {
+    if (ctx.path !== path) return next();
+    const body = ctx.request.body ?? (ctx.method === "POST" ? await readRawBody(ctx.req) : void 0);
+    const toolCtx = {
+      headers: normalizeHeaders(ctx.req.headers),
+      clientIp: ctx.ip,
+      raw: ctx.req
+    };
+    const out = await server.handleHttp({
+      method: ctx.method,
+      headers: toolCtx.headers,
+      body
+    }, toolCtx);
+    ctx.status = out.status;
+    ctx.set(out.headers);
+    if (out.body !== void 0) ctx.body = out.body;
+  }, "middleware");
+  return {
+    server,
+    middleware
+  };
+}
+__name(createKoaMcp, "createKoaMcp");
+function koaMcp(options) {
+  return createKoaMcp(options).middleware;
+}
+__name(koaMcp, "koaMcp");
+function mountMcp(app, options) {
+  const { server, middleware } = createKoaMcp(options);
+  app.use(middleware);
+  return server;
+}
+__name(mountMcp, "mountMcp");
+function mcpToolLegacy(options = {}) {
+  return mark(function* (next) {
+    yield next;
+  }, options);
+}
+__name(mcpToolLegacy, "mcpToolLegacy");
+function koaMcpLegacy(options) {
+  const { middleware } = createKoaMcp(options);
+  return function* (next) {
+    let passThrough = false;
+    yield middleware(this, async () => {
+      passThrough = true;
+    });
+    if (passThrough) yield next;
+  };
+}
+__name(koaMcpLegacy, "koaMcpLegacy");
+export {
+  createKoaMcp,
+  koaMcp,
+  koaMcpLegacy,
+  mcpTool,
+  mcpToolLegacy,
+  mountMcp
+};
+//# sourceMappingURL=index.js.map