mcp-expose 1.0.0

package/dist/index.cjs

@@ -0,0 +1,720 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  DEFAULT_FORWARD_HEADERS: () => DEFAULT_FORWARD_HEADERS,
+  LATEST_PROTOCOL_VERSION: () => LATEST_PROTOCOL_VERSION,
+  McpServer: () => McpServer,
+  SUPPORTED_PROTOCOL_VERSIONS: () => SUPPORTED_PROTOCOL_VERSIONS,
+  createFetchDispatcher: () => createFetchDispatcher,
+  createRouteTool: () => createRouteTool,
+  defineTool: () => defineTool,
+  toJsonSchema: () => toJsonSchema,
+  toToolResult: () => toToolResult,
+  toolsFromOpenApi: () => toolsFromOpenApi
+});
+module.exports = __toCommonJS(src_exports);
+
+// 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/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/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/define.ts
+function defineTool(opts) {
+  return {
+    name: opts.name,
+    title: opts.title,
+    description: opts.description,
+    inputSchema: {
+      type: "object",
+      ...toJsonSchema(opts.input) ?? {
+        properties: {}
+      }
+    },
+    annotations: opts.annotations,
+    validate: toValidator(opts.input),
+    async handler(args, ctx) {
+      return toToolResult(await opts.handler(args, ctx));
+    }
+  };
+}
+__name(defineTool, "defineTool");
+function toToolResult(value) {
+  if (value && typeof value === "object" && Array.isArray(value.content)) return value;
+  if (typeof value === "string") return {
+    content: [
+      {
+        type: "text",
+        text: value
+      }
+    ]
+  };
+  const text = JSON.stringify(value ?? null);
+  const result = {
+    content: [
+      {
+        type: "text",
+        text
+      }
+    ]
+  };
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    result.structuredContent = value;
+  }
+  return result;
+}
+__name(toToolResult, "toToolResult");
+function toolsFromOpenApi(doc, dispatch, opts = {}) {
+  const include = opts.include ?? (({ operation }) => !!operation["x-mcp"]);
+  const methods = [
+    "get",
+    "post",
+    "put",
+    "patch",
+    "delete"
+  ];
+  const tools = [];
+  for (const [path, item] of Object.entries(doc.paths ?? {})) {
+    for (const method of methods) {
+      const operation = item[method];
+      if (!operation || !include({
+        method,
+        path,
+        operation
+      })) continue;
+      const extra = typeof operation["x-mcp"] === "object" ? operation["x-mcp"] : {};
+      const query = {
+        type: "object",
+        properties: {},
+        required: []
+      };
+      const params = {
+        type: "object",
+        properties: {}
+      };
+      for (const p of operation.parameters ?? []) {
+        const s = {
+          ...p.schema ?? {
+            type: "string"
+          },
+          ...p.description ? {
+            description: p.description
+          } : {}
+        };
+        if (p.in === "query") {
+          query.properties[p.name] = s;
+          if (p.required) query.required.push(p.name);
+        } else if (p.in === "path") params.properties[p.name] = s;
+      }
+      const body = operation.requestBody?.content?.["application/json"]?.schema;
+      tools.push(createRouteTool({
+        method,
+        path
+      }, {
+        name: operation.operationId,
+        description: operation.description ?? operation.summary,
+        params,
+        query,
+        body,
+        ...extra
+      }, dispatch, opts));
+    }
+  }
+  return tools;
+}
+__name(toolsFromOpenApi, "toolsFromOpenApi");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_FORWARD_HEADERS,
+  LATEST_PROTOCOL_VERSION,
+  McpServer,
+  SUPPORTED_PROTOCOL_VERSIONS,
+  createFetchDispatcher,
+  createRouteTool,
+  defineTool,
+  toJsonSchema,
+  toToolResult,
+  toolsFromOpenApi
+});
+//# sourceMappingURL=index.cjs.map