mcp-expose 1.0.0 → 1.1.1

package/dist/koa/index.cjs

@@ -116,6 +116,38 @@ function loopbackBaseUrl(req) {
 }
 __name(loopbackBaseUrl, "loopbackBaseUrl");
 
+// src/core/result.ts
+function isToolResult(value) {
+  const content = value?.content;
+  return !!value && typeof value === "object" && Array.isArray(content) && content.length > 0 && content.every((c) => !!c && typeof c === "object" && typeof c.type === "string");
+}
+__name(isToolResult, "isToolResult");
+function toToolResult(value) {
+  if (isToolResult(value)) 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");
+
 // src/core/schema.ts
 function isStandard(s) {
   return typeof s === "object" && s !== null && "~standard" in s;
@@ -336,9 +368,7 @@ function splitArgs(args, mapping) {
 }
 __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 text = truncate(res.body, maxChars);
   const isError = res.status >= 400;
   const result = {
     content: [
@@ -363,6 +393,58 @@ ${text}` : text || `HTTP ${res.status}`
   return result;
 }
 __name(responseToResult, "responseToResult");
+function safeDecode(segment) {
+  try {
+    return decodeURIComponent(segment);
+  } catch {
+    return segment;
+  }
+}
+__name(safeDecode, "safeDecode");
+function truncate(text, maxChars) {
+  return text.length > maxChars ? `${text.slice(0, maxChars)}
+\u2026[truncated ${text.length - maxChars} chars]` : text;
+}
+__name(truncate, "truncate");
+function toRouteToolResponse(res) {
+  let json;
+  if ((res.headers["content-type"] ?? "").includes("json") && res.body) {
+    try {
+      json = JSON.parse(res.body);
+    } catch {
+    }
+  }
+  return {
+    ...res,
+    json,
+    ok: res.status < 400
+  };
+}
+__name(toRouteToolResponse, "toRouteToolResponse");
+function transformedResult(value, res, maxChars) {
+  const explicit = isToolResult(value);
+  const result = toToolResult(value);
+  if (!explicit && !res.ok) {
+    result.isError = true;
+    delete result.structuredContent;
+  }
+  let truncated = false;
+  const content = result.content.map((c) => {
+    if (c.type !== "text" || c.text.length <= maxChars) return c;
+    truncated = true;
+    return {
+      ...c,
+      text: truncate(c.text, maxChars)
+    };
+  });
+  if (!truncated) return result;
+  const { structuredContent: _dropped, ...rest } = result;
+  return {
+    ...rest,
+    content
+  };
+}
+__name(transformedResult, "transformedResult");
 function pickForwardHeaders(ctx, names) {
   const out = {};
   for (const name of names) {
@@ -378,6 +460,7 @@ function createRouteTool(route, opts, dispatch, serverOpts = {}) {
   const { schema, mapping } = buildInputSchema(route, opts);
   const forward = serverOpts.forwardHeaders ?? DEFAULT_FORWARD_HEADERS;
   const maxChars = serverOpts.maxResponseChars ?? 1e5;
+  const transform = opts.transformResponse ?? serverOpts.transformResponse;
   return {
     name,
     title: opts.title,
@@ -387,6 +470,7 @@ function createRouteTool(route, opts, dispatch, serverOpts = {}) {
       ...defaultAnnotations(method),
       ...opts.annotations
     },
+    scopes: opts.scopes,
     validate: toValidator(opts.input),
     async handler(args, ctx) {
       const missing = opts.input ? void 0 : checkRequired(schema, args);
@@ -422,19 +506,167 @@ function createRouteTool(route, opts, dispatch, serverOpts = {}) {
           ]
         };
       }
-      const res = await dispatch({
+      const request = {
         method,
         path,
         query,
         body,
         headers
-      }, ctx);
-      return responseToResult(res, maxChars);
+      };
+      const res = await dispatch(request, ctx);
+      if (!transform) return responseToResult(res, maxChars);
+      const { "content-type": _ct, ...baseHeaders } = headers;
+      const hookCtx = {
+        tool: name,
+        args,
+        request,
+        toolContext: ctx,
+        defaultResult: /* @__PURE__ */ __name(() => responseToResult(res, maxChars), "defaultResult"),
+        async callRoute(r) {
+          if (!r.path.startsWith("/")) {
+            throw new Error(`callRoute: path must start with "/", got ${JSON.stringify(r.path)}`);
+          }
+          const params = r.params ?? {};
+          const missing2 = pathParams(r.path).filter((p) => params[p] === void 0 && !r.path.includes(`:${p}?`));
+          if (missing2.length) throw new Error(`callRoute: missing params for ${r.path}: ${missing2.join(", ")}`);
+          const subPath = interpolatePath(r.path, params);
+          if (subPath.split("/").some((seg) => [
+            ".",
+            ".."
+          ].includes(safeDecode(seg)))) {
+            throw new Error(`callRoute: path must not contain "." or ".." segments: ${JSON.stringify(subPath)}`);
+          }
+          const sub = {
+            method: (r.method ?? "GET").toUpperCase(),
+            path: subPath,
+            query: r.query ?? {},
+            body: r.body,
+            headers: {
+              ...baseHeaders,
+              ...r.headers
+            }
+          };
+          if (sub.body !== void 0) sub.headers["content-type"] = "application/json";
+          return toRouteToolResponse(await dispatch(sub, ctx));
+        }
+      };
+      const response = toRouteToolResponse(res);
+      const value = await transform(response, hookCtx);
+      return value === void 0 ? responseToResult(res, maxChars) : transformedResult(value, response, maxChars);
     }
   };
 }
 __name(createRouteTool, "createRouteTool");
 
+// src/core/oauth.ts
+var PROTECTED_RESOURCE_WELL_KNOWN = "/.well-known/oauth-protected-resource";
+function protectedResourceMetadataPaths(resource) {
+  const pathname = new URL(resource).pathname.replace(/\/+$/, "");
+  return pathname ? [
+    PROTECTED_RESOURCE_WELL_KNOWN + pathname,
+    PROTECTED_RESOURCE_WELL_KNOWN
+  ] : [
+    PROTECTED_RESOURCE_WELL_KNOWN
+  ];
+}
+__name(protectedResourceMetadataPaths, "protectedResourceMetadataPaths");
+function protectedResourceMetadataUrl(resource) {
+  return new URL(protectedResourceMetadataPaths(resource)[0], resource).href;
+}
+__name(protectedResourceMetadataUrl, "protectedResourceMetadataUrl");
+function validateOAuthOptions(o) {
+  let url;
+  try {
+    url = new URL(o.resource);
+  } catch {
+    throw new Error(`mcp-expose: oauth.resource must be an absolute URL, got ${JSON.stringify(o.resource)}`);
+  }
+  if (url.hash) throw new Error("mcp-expose: oauth.resource must not contain a fragment");
+  if (!o.authorizationServers?.length) throw new Error("mcp-expose: oauth.authorizationServers must not be empty");
+  if (typeof o.verifyToken !== "function") throw new Error("mcp-expose: oauth.verifyToken is required");
+}
+__name(validateOAuthOptions, "validateOAuthOptions");
+var quote = /* @__PURE__ */ __name((v) => `"${v.replace(/["\\]/g, "\\$&")}"`, "quote");
+function bearerChallenge(resource, params = {}) {
+  const parts = [];
+  if (params.error) parts.push(`error=${quote(params.error)}`);
+  if (params.errorDescription) parts.push(`error_description=${quote(params.errorDescription)}`);
+  if (params.scope?.length) parts.push(`scope=${quote(params.scope.join(" "))}`);
+  parts.push(`resource_metadata=${quote(protectedResourceMetadataUrl(resource))}`);
+  return `Bearer ${parts.join(", ")}`;
+}
+__name(bearerChallenge, "bearerChallenge");
+function bearerToken(headers) {
+  const m = /^Bearer[ ]+([^\s,]+)\s*$/i.exec(headers.authorization ?? "");
+  return m?.[1];
+}
+__name(bearerToken, "bearerToken");
+async function authenticate(o, headers) {
+  const token = bearerToken(headers);
+  if (!token) {
+    return {
+      ok: false,
+      status: 401,
+      error: "unauthorized",
+      description: "Authorization required",
+      challenge: bearerChallenge(o.resource, {
+        scope: o.requiredScopes
+      })
+    };
+  }
+  let auth;
+  try {
+    auth = await o.verifyToken(token, {
+      resource: o.resource,
+      headers
+    });
+  } catch {
+    auth = void 0;
+  }
+  if (!auth) return deny(o, 401, "invalid_token", "The access token is invalid");
+  if (auth.expiresAt !== void 0 && auth.expiresAt * 1e3 <= Date.now()) {
+    return deny(o, 401, "invalid_token", "The access token has expired");
+  }
+  const missing = missingScopes(auth, o.requiredScopes);
+  if (missing.length) {
+    const scope = [
+      .../* @__PURE__ */ new Set([
+        ...auth.scopes ?? [],
+        ...o.requiredScopes ?? []
+      ])
+    ];
+    return deny(o, 403, "insufficient_scope", `Missing scope: ${missing.join(" ")}`, scope);
+  }
+  return {
+    ok: true,
+    auth: {
+      ...auth,
+      scopes: auth.scopes ?? []
+    }
+  };
+}
+__name(authenticate, "authenticate");
+function deny(o, status, error, description, scope) {
+  return {
+    ok: false,
+    status,
+    error,
+    description,
+    challenge: bearerChallenge(o.resource, {
+      error,
+      errorDescription: description,
+      scope
+    })
+  };
+}
+__name(deny, "deny");
+function missingScopes(auth, required) {
+  if (!required?.length) return [];
+  const granted = new Set(auth?.scopes ?? []);
+  return required.filter((s) => !granted.has(s));
+}
+__name(missingScopes, "missingScopes");
+
 // src/core/server.ts
 var SUPPORTED_PROTOCOL_VERSIONS = [
   "2025-11-25",
@@ -469,6 +701,7 @@ var McpServer = class {
   loaders = [];
   constructor(options) {
     this.options = options;
+    if (options.oauth) validateOAuthOptions(options.oauth);
   }
   /** Register a tool. Throws on duplicate names. */
   addTool(tool) {
@@ -603,6 +836,79 @@ var McpServer = class {
     return (allowed ?? []).includes(origin);
   }
   /**
+  * Paths on which adapters serve the OAuth Protected Resource Metadata
+  * (empty when `oauth` is not configured). They must be public: no auth middleware.
+  */
+  get oauthMetadataPaths() {
+    return this.options.oauth ? protectedResourceMetadataPaths(this.options.oauth.resource) : [];
+  }
+  /** The OAuth Protected Resource Metadata document (RFC 9728). */
+  async protectedResourceMetadata() {
+    const o = this.options.oauth;
+    if (!o) throw new Error("mcp-expose: the oauth option is not configured");
+    await this.load();
+    const scopes = o.scopesSupported ?? [
+      .../* @__PURE__ */ new Set([
+        ...o.requiredScopes ?? [],
+        ...[
+          ...this.tools.values()
+        ].flatMap((t) => t.scopes ?? [])
+      ])
+    ];
+    return {
+      resource: o.resource,
+      authorization_servers: o.authorizationServers,
+      ...scopes.length ? {
+        scopes_supported: scopes
+      } : {},
+      bearer_methods_supported: [
+        "header"
+      ],
+      ...o.resourceName ? {
+        resource_name: o.resourceName
+      } : {},
+      ...o.resourceDocumentation ? {
+        resource_documentation: o.resourceDocumentation
+      } : {},
+      ...o.metadata
+    };
+  }
+  /** HTTP handler for the metadata paths. Public and CORS-enabled so browser-based clients can read it. */
+  async handleMetadataHttp(req) {
+    const cors = {
+      "access-control-allow-origin": "*",
+      "access-control-allow-methods": "GET, OPTIONS"
+    };
+    const method = req.method.toUpperCase();
+    if (!this.options.oauth) return {
+      status: 404,
+      headers: {}
+    };
+    if (method === "OPTIONS") return {
+      status: 204,
+      headers: {
+        ...cors,
+        "access-control-allow-headers": "*"
+      }
+    };
+    if (method !== "GET" && method !== "HEAD") return {
+      status: 405,
+      headers: {
+        allow: "GET, OPTIONS"
+      }
+    };
+    const body = JSON.stringify(await this.protectedResourceMetadata());
+    return {
+      status: 200,
+      headers: {
+        ...cors,
+        "content-type": "application/json",
+        "cache-control": "public, max-age=3600"
+      },
+      body: method === "HEAD" ? void 0 : body
+    };
+  }
+  /**
   * Framework-neutral Streamable HTTP handler. Adapters convert their request
   * into McpHttpRequest, call this, and write the McpHttpResponse back.
   */
@@ -617,6 +923,15 @@ var McpServer = class {
         body: JSON.stringify(fail(null, INVALID_REQUEST, "Origin not allowed"))
       };
     }
+    const oauth = this.options.oauth;
+    if (oauth) {
+      const outcome = await authenticate(oauth, req.headers);
+      if (!outcome.ok) return authError(outcome);
+      ctx = {
+        ...ctx,
+        auth: outcome.auth
+      };
+    }
     if (req.method.toUpperCase() !== "POST") {
       return {
         status: 405,
@@ -637,6 +952,27 @@ var McpServer = class {
         };
       }
     }
+    if (oauth) {
+      await this.load();
+      const calls = Array.isArray(body) ? body : [
+        body
+      ];
+      for (const m of calls) {
+        if (m?.method !== "tools/call") continue;
+        const tool = this.tools.get(m.params?.name);
+        const missing = missingScopes(ctx.auth, tool?.scopes);
+        if (missing.length) {
+          const scope = [
+            .../* @__PURE__ */ new Set([
+              ...ctx.auth?.scopes ?? [],
+              ...oauth.requiredScopes ?? [],
+              ...tool?.scopes ?? []
+            ])
+          ];
+          return authError(deny(oauth, 403, "insufficient_scope", `Tool "${tool.name}" needs scope: ${missing.join(" ")}`, scope));
+        }
+      }
+    }
     const response = await this.handleMessage(body, ctx);
     if (response === null) return {
       status: 202,
@@ -649,6 +985,20 @@ var McpServer = class {
     };
   }
 };
+function authError(o) {
+  return {
+    status: o.status,
+    headers: {
+      "content-type": "application/json",
+      "www-authenticate": o.challenge
+    },
+    body: JSON.stringify({
+      error: o.error,
+      error_description: o.description
+    })
+  };
+}
+__name(authError, "authError");
 
 // src/koa/index.ts
 function mcpTool(options = {}) {
@@ -677,7 +1027,17 @@ function createKoaMcp(options) {
     }
     for (const r of options.routes ?? []) server.addTool(createRouteTool(r, r, dispatch, options));
   });
+  const metadataPaths = server.oauthMetadataPaths;
   const middleware = /* @__PURE__ */ __name(async (ctx, next) => {
+    if (metadataPaths.includes(ctx.path)) {
+      const out2 = await server.handleMetadataHttp({
+        method: ctx.method
+      });
+      ctx.status = out2.status;
+      ctx.set(out2.headers);
+      if (out2.body !== void 0) ctx.body = out2.body;
+      return;
+    }
     if (ctx.path !== path) return next();
     const body = ctx.request.body ?? (ctx.method === "POST" ? await readRawBody(ctx.req) : void 0);
     const toolCtx = {