@absolutejs/mcp 0.0.1 → 0.1.0

package/README.md

@@ -114,14 +114,12 @@ different scope, a stricter `authorize` (role + MFA + a kill switch, re-checked
 live), a rate-limit `beforeCall`, and an audit `onCall`:
 
 ```ts
-app
-  .use(mcpServer({ path: "/mcp" /* member */ }))
-  .use(
-    mcpServer({
-      path: "/mcp/admin",
-      scopesSupported: ["openid", "mcp:admin"] /* stricter */,
-    }),
-  );
+app.use(mcpServer({ path: "/mcp" /* member */ })).use(
+  mcpServer({
+    path: "/mcp/admin",
+    scopesSupported: ["openid", "mcp:admin"] /* stricter */,
+  }),
+);
 ```
 
 Only one endpoint per app should set `serveRootMetadata` (the un-suffixed alias).

package/dist/index.js

@@ -29,6 +29,155 @@ var verifyBearer = async (config) => {
     return { error: "Token has no subject" };
   return { payload, scopes, subject };
 };
+// src/client.ts
+var DEFAULT_TIMEOUT_MS = 30000;
+var DEFAULT_PROTOCOL = "2025-06-18";
+
+class McpClientError extends Error {
+  code;
+  status;
+  constructor(message, options = {}) {
+    super(message);
+    this.name = "McpClientError";
+    this.code = options.code;
+    this.status = options.status;
+  }
+}
+var parseBody = async (response, maxBytes) => {
+  const text = await response.text();
+  if (maxBytes > 0 && text.length > maxBytes) {
+    throw new McpClientError("Response exceeded the size cap", {
+      status: response.status
+    });
+  }
+  const contentType = response.headers.get("content-type") ?? "";
+  if (!contentType.includes("text/event-stream")) {
+    return JSON.parse(text);
+  }
+  const messages = text.split(/\r?\n/).filter((line) => line.startsWith("data:")).map((line) => line.slice("data:".length).trim()).filter((chunk) => chunk.length > 0);
+  for (let index = messages.length - 1;index >= 0; index -= 1) {
+    try {
+      const parsed = JSON.parse(messages[index] ?? "");
+      if (isRecord(parsed) && (("result" in parsed) || ("error" in parsed))) {
+        return parsed;
+      }
+    } catch {}
+  }
+  throw new McpClientError("No JSON-RPC response in the event stream");
+};
+var createMcpClient = (options) => {
+  const doFetch = options.request ?? fetch;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const maxBytes = options.maxResponseBytes ?? 0;
+  let protocolVersion = options.protocolVersion ?? DEFAULT_PROTOCOL;
+  let sessionId = null;
+  let nextId = 1;
+  const rpc = async (method, params) => {
+    const controller = new AbortController;
+    const timer = setTimeout(() => {
+      controller.abort();
+    }, timeoutMs);
+    try {
+      const headers = {
+        accept: "application/json, text/event-stream",
+        "content-type": "application/json",
+        "mcp-protocol-version": protocolVersion,
+        ...options.headers
+      };
+      if (sessionId !== null)
+        headers["mcp-session-id"] = sessionId;
+      const response = await doFetch(options.url, {
+        body: JSON.stringify({
+          id: nextId++,
+          jsonrpc: "2.0",
+          method,
+          ...params === undefined ? {} : { params }
+        }),
+        headers,
+        method: "POST",
+        signal: controller.signal
+      });
+      const captured = response.headers.get("mcp-session-id");
+      if (captured)
+        sessionId = captured;
+      if (response.status === 401) {
+        throw new McpClientError("The MCP server rejected the credentials", {
+          status: 401
+        });
+      }
+      const payload = await parseBody(response, maxBytes);
+      if (!isRecord(payload)) {
+        throw new McpClientError("Malformed JSON-RPC response");
+      }
+      if (isRecord(payload.error)) {
+        const message = typeof payload.error.message === "string" ? payload.error.message : "MCP error";
+        const code = typeof payload.error.code === "number" ? payload.error.code : undefined;
+        throw new McpClientError(message, { code });
+      }
+      return payload.result;
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+  const notify = async (method) => {
+    const headers = {
+      "content-type": "application/json",
+      "mcp-protocol-version": protocolVersion,
+      ...options.headers
+    };
+    if (sessionId !== null)
+      headers["mcp-session-id"] = sessionId;
+    await doFetch(options.url, {
+      body: JSON.stringify({ jsonrpc: "2.0", method }),
+      headers,
+      method: "POST"
+    }).catch(() => {
+      return;
+    });
+  };
+  const initialize = async () => {
+    const result = await rpc("initialize", {
+      capabilities: {},
+      clientInfo: options.clientInfo ?? {
+        name: "@absolutejs/mcp",
+        version: "0"
+      },
+      protocolVersion
+    });
+    if (isRecord(result) && typeof result.protocolVersion === "string") {
+      protocolVersion = result.protocolVersion;
+    }
+    await notify("notifications/initialized");
+    return isRecord(result) ? result : {};
+  };
+  const listTools = async () => {
+    const result = await rpc("tools/list");
+    const tools = isRecord(result) && Array.isArray(result.tools) ? result.tools : [];
+    return tools.filter(isRecord).map((tool) => ({
+      annotations: isRecord(tool.annotations) ? tool.annotations : undefined,
+      description: typeof tool.description === "string" ? tool.description : undefined,
+      inputSchema: isRecord(tool.inputSchema) ? tool.inputSchema : undefined,
+      name: typeof tool.name === "string" ? tool.name : "",
+      outputSchema: isRecord(tool.outputSchema) ? tool.outputSchema : undefined
+    }));
+  };
+  const callTool = async (name, args) => {
+    const result = await rpc("tools/call", { arguments: args ?? {}, name });
+    if (isRecord(result) && Array.isArray(result.content)) {
+      return result;
+    }
+    return { content: [], isError: false };
+  };
+  const listResources = async () => {
+    const result = await rpc("resources/list");
+    return isRecord(result) && Array.isArray(result.resources) ? result.resources : [];
+  };
+  const readResource = async (uri) => rpc("resources/read", { uri });
+  const ping = async () => {
+    await rpc("ping");
+  };
+  return { callTool, initialize, listResources, listTools, ping, readResource };
+};
 // src/jsonrpc.ts
 var JSONRPC_PARSE_ERROR = -32700;
 var JSONRPC_INVALID_REQUEST = -32600;
@@ -69,6 +218,15 @@ var negotiateProtocol = (supported, params) => {
   const requested = isRecord(params) && typeof params.protocolVersion === "string" ? params.protocolVersion : preferred;
   return supported.includes(requested) ? requested : preferred;
 };
+var scopeAllows = (tool, scopes) => tool.scope === undefined || scopes.includes(tool.scope);
+var normalizeResult = (value) => {
+  if (typeof value === "string") {
+    return { content: [{ text: value, type: "text" }], isError: false };
+  }
+  if (Array.isArray(value))
+    return { content: value, isError: false };
+  return { isError: false, ...value };
+};
 var initialize = (config, id, params) => {
   const supported = config.supportedProtocols ?? DEFAULT_PROTOCOLS;
   const capabilities = {
@@ -86,19 +244,20 @@ var initialize = (config, id, params) => {
     serverInfo: config.serverInfo
   });
 };
-var toolsList = async (config, caller, id) => {
+var toolsList = async (config, caller, scopes, id) => {
   const tools = await config.tools({ caller, meta: {} });
   return rpcResult(id, {
-    tools: Object.entries(tools).map(([name, tool]) => ({
+    tools: Object.entries(tools).filter(([, tool]) => scopeAllows(tool, scopes)).map(([name, tool]) => ({
       annotations: tool.annotations,
       description: tool.description,
       inputSchema: tool.inputSchema,
-      name
+      name,
+      ...tool.outputSchema === undefined ? {} : { outputSchema: tool.outputSchema }
     }))
   });
 };
 var errorResult = (id, text) => rpcResult(id, { content: [{ text, type: "text" }], isError: true });
-var toolsCall = async (config, caller, id, params) => {
+var toolsCall = async (config, caller, scopes, id, params) => {
   if (!isRecord(params) || typeof params.name !== "string") {
     return rpcError(id, JSONRPC_INVALID_PARAMS, "tools/call needs a name");
   }
@@ -112,17 +271,15 @@ var toolsCall = async (config, caller, id, params) => {
   }
   const tools = await config.tools({ caller, meta });
   const tool = tools[name];
-  if (!tool)
+  if (!tool || !scopeAllows(tool, scopes)) {
     return rpcError(id, JSONRPC_INVALID_PARAMS, `Unknown tool: ${name}`);
+  }
   let ok = false;
   let response;
   try {
-    const text = await tool.handler(args);
-    ok = true;
-    response = rpcResult(id, {
-      content: [{ text, type: "text" }],
-      isError: false
-    });
+    const result = normalizeResult(await tool.handler(args));
+    ok = result.isError !== true;
+    response = rpcResult(id, result);
   } catch (error) {
     const detail = error instanceof Error ? error.message : "unknown error";
     response = errorResult(id, `Tool failed: ${detail}`);
@@ -187,7 +344,7 @@ var resourcesRead = async (config, caller, id, params) => {
     ]
   });
 };
-var dispatchMcp = async (config, caller, message) => {
+var dispatchMcp = async (config, caller, scopes, message) => {
   if (!isRecord(message) || message.jsonrpc !== "2.0") {
     return rpcError(null, JSONRPC_INVALID_REQUEST, "Not a JSON-RPC 2.0 message");
   }
@@ -201,9 +358,10 @@ var dispatchMcp = async (config, caller, message) => {
   if (method === "ping")
     return rpcResult(id, {});
   if (method === "tools/list")
-    return toolsList(config, caller, id);
-  if (method === "tools/call")
-    return toolsCall(config, caller, id, params);
+    return toolsList(config, caller, scopes, id);
+  if (method === "tools/call") {
+    return toolsCall(config, caller, scopes, id, params);
+  }
   if (method === "prompts/list")
     return promptsList(config, id);
   if (method === "prompts/get")
@@ -222,31 +380,61 @@ var protectedResourceMetadata = (input) => ({
   scopes_supported: input.scopes ?? []
 });
 var metadataPathFor = (path) => `/.well-known/oauth-protected-resource${path}`;
-// src/server.ts
-import { Elysia } from "elysia";
+
+// src/core.ts
 var ROOT_METADATA_PATH = "/.well-known/oauth-protected-resource";
-var mcpServer = (config) => {
+var JSON_HEADERS = {
+  "content-type": "application/json"
+};
+var metadataResponse = (config) => new Response(JSON.stringify(protectedResourceMetadata({
+  issuer: config.issuer,
+  resource: `${config.issuer}${config.path}`,
+  scopes: config.scopesSupported
+})), { headers: JSON_HEADERS });
+var runMcpPost = async (config, request, body) => {
+  const auth = await config.authorize(request);
+  if (!auth.ok) {
+    return unauthorized(`${config.issuer}${metadataPathFor(config.path)}`, auth.reason);
+  }
+  if (body === undefined || body === null) {
+    return rpcError(null, JSONRPC_PARSE_ERROR, "Invalid JSON");
+  }
+  if (Array.isArray(body)) {
+    return rpcError(null, JSONRPC_INVALID_REQUEST, "Batching is not supported");
+  }
+  return dispatchMcp(config, auth.caller, auth.scopes ?? [], body).catch(() => rpcError(null, JSONRPC_INVALID_REQUEST, "Internal error"));
+};
+var handleMcpRequest = async (config, request) => {
+  const { pathname } = new URL(request.url);
   const metadataPath = metadataPathFor(config.path);
-  const metadataUrl = `${config.issuer}${metadataPath}`;
-  const metadata = () => protectedResourceMetadata({
-    issuer: config.issuer,
-    resource: `${config.issuer}${config.path}`,
-    scopes: config.scopesSupported
-  });
-  const base = new Elysia().get(metadataPath, metadata).get(config.path, () => new Response(null, { status: HTTP_METHOD_NOT_ALLOWED })).post(config.path, async ({ body, request }) => {
-    const auth = await config.authorize(request);
-    if (!auth.ok)
-      return unauthorized(metadataUrl, auth.reason);
-    const message = body;
-    if (message === undefined || message === null) {
-      return rpcError(null, JSONRPC_PARSE_ERROR, "Invalid JSON");
+  if (request.method === "GET") {
+    if (pathname === metadataPath)
+      return metadataResponse(config);
+    if (config.serveRootMetadata && pathname === ROOT_METADATA_PATH) {
+      return metadataResponse(config);
     }
-    if (Array.isArray(message)) {
-      return rpcError(null, JSONRPC_INVALID_REQUEST, "Batching is not supported");
+    if (pathname === config.path) {
+      return new Response(null, { status: HTTP_METHOD_NOT_ALLOWED });
     }
-    return dispatchMcp(config, auth.caller, message).catch(() => rpcError(null, JSONRPC_INVALID_REQUEST, "Internal error"));
-  });
-  const app = config.serveRootMetadata ? base.get(ROOT_METADATA_PATH, metadata) : base;
+    return null;
+  }
+  if (request.method === "POST" && pathname === config.path) {
+    const body = await request.json().catch(() => {
+      return;
+    });
+    return runMcpPost(config, request, body);
+  }
+  return null;
+};
+
+// src/handler.ts
+var createMcpHandler = (config) => (request) => handleMcpRequest(config, request);
+// src/server.ts
+import { Elysia } from "elysia";
+var mcpServer = (config) => {
+  const metadataPath = metadataPathFor(config.path);
+  const base = new Elysia().get(metadataPath, () => metadataResponse(config)).get(config.path, () => new Response(null, { status: HTTP_METHOD_NOT_ALLOWED })).post(config.path, ({ body, request }) => runMcpPost(config, request, body));
+  const app = config.serveRootMetadata ? base.get(ROOT_METADATA_PATH, () => metadataResponse(config)) : base;
   return app;
 };
 export {
@@ -254,5 +442,8 @@ export {
   protectedResourceMetadata,
   metadataPathFor,
   mcpServer,
-  dispatchMcp
+  dispatchMcp,
+  createMcpHandler,
+  createMcpClient,
+  McpClientError
 };

package/dist/src/client.d.ts

@@ -0,0 +1,50 @@
+import type { McpToolAnnotations, McpToolResult } from "./types";
+export declare class McpClientError extends Error {
+    readonly code: number | undefined;
+    readonly status: number | undefined;
+    constructor(message: string, options?: {
+        code?: number;
+        status?: number;
+    });
+}
+export type McpClientOptions = {
+    clientInfo?: {
+        name: string;
+        version: string;
+    };
+    /** Sent on every request (e.g. `{ authorization: "Bearer …" }`). */
+    headers?: Record<string, string>;
+    /** Reject responses whose body exceeds this many bytes (0 = no cap). */
+    maxResponseBytes?: number;
+    protocolVersion?: string;
+    /** Inject a custom fetch (tests, proxies). Defaults to global fetch. */
+    request?: typeof fetch;
+    timeoutMs?: number;
+    url: string;
+};
+export type McpRemoteTool = {
+    annotations?: McpToolAnnotations;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    name: string;
+    outputSchema?: Record<string, unknown>;
+};
+export type McpInitializeResult = {
+    capabilities?: Record<string, unknown>;
+    instructions?: string;
+    protocolVersion: string;
+    serverInfo?: {
+        name?: string;
+        title?: string;
+        version?: string;
+    };
+};
+export type McpClient = {
+    callTool: (name: string, args?: unknown) => Promise<McpToolResult>;
+    initialize: () => Promise<McpInitializeResult>;
+    listResources: () => Promise<unknown[]>;
+    listTools: () => Promise<McpRemoteTool[]>;
+    ping: () => Promise<void>;
+    readResource: (uri: string) => Promise<unknown>;
+};
+export declare const createMcpClient: (options: McpClientOptions) => McpClient;

package/dist/src/core.d.ts

@@ -0,0 +1,11 @@
+import type { McpServerConfig } from "./types";
+export declare const ROOT_METADATA_PATH = "/.well-known/oauth-protected-resource";
+export declare const metadataResponse: <Caller>(config: McpServerConfig<Caller>) => Response;
+/** Run one POST: authorize → validate the (already-decoded) body → dispatch.
+ *  The body is passed in because Elysia pre-parses it while a raw handler must
+ *  parse it itself; both funnel through here so the logic lives in one place. */
+export declare const runMcpPost: <Caller>(config: McpServerConfig<Caller>, request: Request, body: unknown) => Promise<Response>;
+/** The full path-aware handler over web-standard Request/Response. Returns a
+ *  Response for any MCP route (POST endpoint, GET 405, discovery metadata) and
+ *  `null` for anything else, so a host can compose it with its own routes. */
+export declare const handleMcpRequest: <Caller>(config: McpServerConfig<Caller>, request: Request) => Promise<Response | null>;

package/dist/src/dispatch.d.ts

@@ -1,4 +1,5 @@
 import type { McpServerConfig } from "./types";
-/** Route one decoded JSON-RPC message to its handler. Notifications (no `id`)
- *  get a bare 202. Unknown methods get JSON-RPC method-not-found. */
-export declare const dispatchMcp: <Caller>(config: McpServerConfig<Caller>, caller: Caller, message: unknown) => Promise<Response>;
+/** Route one decoded JSON-RPC message to its handler. `scopes` are the caller's
+ *  granted scopes (from `authorize`); they gate scope-restricted tools.
+ *  Notifications (no `id`) get a bare 202; unknown methods get method-not-found. */
+export declare const dispatchMcp: <Caller>(config: McpServerConfig<Caller>, caller: Caller, scopes: string[], message: unknown) => Promise<Response>;

package/dist/src/handler.d.ts

@@ -0,0 +1,2 @@
+import type { McpServerConfig } from "./types";
+export declare const createMcpHandler: <Caller>(config: McpServerConfig<Caller>) => (request: Request) => Promise<Response | null>;

package/dist/src/index.d.ts

@@ -1,22 +1,31 @@
 /**
- * `@absolutejs/mcp` — serve a remote Model Context Protocol endpoint
- * (streamable HTTP, stateless) from a tool/prompt/resource registry.
+ * `@absolutejs/mcp` — serve (and consume) a Model Context Protocol endpoint
+ * over streamable HTTP, from a tool/prompt/resource registry.
  *
- * Define the endpoint once with {@link mcpServer} and mount it on your Elysia
- * app. You supply WHICH tools to expose and HOW to authorize a request into a
- * caller ({@link verifyBearer} does the standard OAuth bearer checks against
- * any authorization server); the package owns the JSON-RPC protocol, protocol
+ * **Serve.** Define the endpoint once and mount it: {@link mcpServer} returns an
+ * Elysia plugin, or {@link createMcpHandler} returns a framework-agnostic
+ * `(request) => Response | null` for Bun.serve / Hono / Next.js / Workers. You
+ * supply WHICH tools to expose and HOW to authorize a request into a caller
+ * ({@link verifyBearer} does the standard OAuth bearer checks against any
+ * authorization server); the package owns the JSON-RPC protocol, protocol
  * negotiation, RFC 9728 discovery metadata, and the 401 challenge. Per-call
- * guards (`beforeCall` to gate on credits/rate limits, `onCall` to audit) and a
- * per-call `meta` scratchpad are hooks — the package ships no opinions about
- * billing, storage, or who is allowed in.
+ * guards (`beforeCall`, `onCall`), a per-call `meta` scratchpad, per-tool
+ * `scope` gating, and rich tool results (text/image/structured) are all
+ * built in; the package ships no opinion about billing, storage, or access.
  *
- * The tool shape is structurally compatible with `@absolutejs/ai`'s
- * `AIToolMap`, so an AI tool registry serves over MCP without conversion — but
- * nothing here depends on a model: any typed tool registry works.
+ * **Consume.** {@link createMcpClient} is a streamable-HTTP client for calling
+ * OTHER MCP servers — the half you need to expose a user's own connected tools
+ * to your agent. Safety wrapping around untrusted remote tools (namespacing,
+ * injection defense, approval gating) is the host's job.
+ *
+ * The tool shape is structurally compatible with `@absolutejs/ai`'s `AIToolMap`,
+ * so an AI tool registry serves over MCP without conversion — but nothing here
+ * depends on a model.
  */
 export { verifyBearer, type BearerResult, type BearerVerifier, type VerifiedJwt, type VerifyBearerConfig, } from "./auth";
+export { createMcpClient, McpClientError, type McpClient, type McpClientOptions, type McpInitializeResult, type McpRemoteTool, } from "./client";
 export { dispatchMcp } from "./dispatch";
+export { createMcpHandler } from "./handler";
 export { metadataPathFor, protectedResourceMetadata, type ProtectedResourceMetadata, } from "./metadata";
 export { mcpServer } from "./server";
-export type { McpAuthResult, McpCallGate, McpCallMeta, McpPromptArgument, McpPromptDefinition, McpPrompts, McpResource, McpResources, McpServerConfig, McpServerInfo, McpTool, McpToolAnnotations, McpToolContext, McpToolRegistry, } from "./types";
+export type { McpAudioContent, McpAuthResult, McpCallGate, McpCallMeta, McpContent, McpImageContent, McpPromptArgument, McpPromptDefinition, McpPrompts, McpResource, McpResourceLink, McpResources, McpServerConfig, McpServerInfo, McpTextContent, McpTool, McpToolAnnotations, McpToolContext, McpToolRegistry, McpToolResult, McpToolReturn, } from "./types";

package/dist/src/types.d.ts

@@ -8,13 +8,50 @@ export type McpToolAnnotations = {
     readOnlyHint?: boolean;
     title?: string;
 };
-/** One callable tool. `inputSchema` is a JSON Schema object; `handler` receives
- *  the client's `arguments` and returns text (the tool's `content`). */
+/** Rich tool-result content blocks. A handler may return a bare string (wrapped
+ *  as one text block), an array of these, or a full {@link McpToolResult}. */
+export type McpTextContent = {
+    text: string;
+    type: "text";
+};
+export type McpImageContent = {
+    data: string;
+    mimeType: string;
+    type: "image";
+};
+export type McpAudioContent = {
+    data: string;
+    mimeType: string;
+    type: "audio";
+};
+export type McpResourceLink = {
+    description?: string;
+    mimeType?: string;
+    name?: string;
+    type: "resource_link";
+    uri: string;
+};
+export type McpContent = McpAudioContent | McpImageContent | McpResourceLink | McpTextContent;
+export type McpToolResult = {
+    content: McpContent[];
+    isError?: boolean;
+    /** Structured output validated against the tool's `outputSchema`, if any. */
+    structuredContent?: Record<string, unknown>;
+};
+/** What a tool handler may return. A bare string is the common case. */
+export type McpToolReturn = McpContent[] | McpToolResult | string;
+/** One callable tool. `inputSchema` is a JSON Schema object. */
 export type McpTool = {
     annotations?: McpToolAnnotations;
     description: string;
-    handler: (args: unknown) => Promise<string> | string;
+    handler: (args: unknown) => McpToolReturn | Promise<McpToolReturn>;
     inputSchema: Record<string, unknown>;
+    /** JSON Schema for `structuredContent`, advertised on `tools/list`. */
+    outputSchema?: Record<string, unknown>;
+    /** If set, the tool is only listed and callable when the caller's scopes
+     *  include this. Tools without a scope are always available. Fails closed:
+     *  a scoped tool is hidden when the caller's scopes are unknown. */
+    scope?: string;
 };
 export type McpToolRegistry = Record<string, McpTool>;
 /** A resource the client can list and read (`resources/list` / `resources/read`). */
@@ -38,10 +75,12 @@ export type McpPromptDefinition = {
  *  one `tools/call` request. A tool handler can write to it (e.g. record which
  *  entity it touched) and `onCall` can read it back for the audit row. */
 export type McpCallMeta = Record<string, unknown>;
-/** What `authorize` returns: the resolved caller, or a reason for the 401. */
+/** What `authorize` returns: the resolved caller (plus the caller's scopes, if
+ *  any tools are scope-gated), or a reason for the 401. */
 export type McpAuthResult<Caller> = {
     caller: Caller;
     ok: true;
+    scopes?: string[];
 } | {
     ok: false;
     reason: string;

package/package.json

@@ -37,5 +37,5 @@
     "typecheck": "tsc --noEmit --project tsconfig.json"
   },
   "types": "./dist/src/index.d.ts",
-  "version": "0.0.1"
+  "version": "0.1.0"
 }