@absolutejs/mcp 0.0.1

package/LICENSE

@@ -0,0 +1,89 @@
+# Business Source License 1.1
+
+**Licensor:** Alex Kahn
+
+**Licensed Work:** @absolutejs/mcp (https://github.com/absolutejs/mcp)
+
+**Change Date:** July 10, 2030
+
+**Change License:** Apache License, Version 2.0
+
+---
+
+## Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, permitting limited production use.
+
+### Additional Use Grant
+
+You may use the Licensed Work in production, provided your use does not include
+any of the following:
+
+1. **Offering a Competing Service.** You may not offer the Licensed Work, or
+   any derivative or substantial portion of it, to third parties as a hosted or
+   managed Model Context Protocol (MCP) gateway, registry, proxy, or
+   server-hosting service (including, but not limited to, services like
+   Smithery, Composio, or mcp.run). This includes any product whose primary
+   value to its users is the functionality the Licensed Work provides.
+
+2. **Resale or Redistribution as a Standalone Product.** You may not sell,
+   license, or distribute the Licensed Work, or any derivative or fork of it,
+   as a standalone commercial product.
+
+3. **Removal of Attribution.** Any derivative work, fork, or redistribution of
+   the Licensed Work must prominently credit AbsoluteJS and include a link to
+   the original project repository (https://github.com/absolutejs/mcp).
+
+For clarity, the following uses are expressly permitted:
+
+- Using the Licensed Work to build and operate your own applications, websites,
+  internal tools, or SaaS products (whether commercial or non-commercial), so
+  long as the Licensed Work itself is not the primary product you are selling.
+- Using the Licensed Work as a dependency in commercial software you build and
+  sell, as long as the software is not itself a competing managed service of
+  the kind described in clause 1.
+- Providing consulting, development, or professional services to clients using
+  the Licensed Work.
+- Forking and modifying the Licensed Work for your own internal use, provided
+  attribution is maintained.
+
+### Change Date and Change License
+
+On the Change Date specified above, or on such other date as the Licensor may
+specify by written notice, the Licensed Work will be made available under the
+Change License (Apache License, Version 2.0). Until the Change Date, the terms
+of this Business Source License 1.1 apply.
+
+### Trademark
+
+This license does not grant you any rights to use the "AbsoluteJS" or
+"@absolutejs" name, logo, or any related trademarks. Forks and derivative works
+must not be named or branded in a manner that suggests endorsement by or
+affiliation with AbsoluteJS or the Licensor.
+
+### Notices
+
+You must not remove or obscure any licensing, copyright, or other notices
+included in the Licensed Work.
+
+### No Warranty
+
+THE LICENSED WORK IS PROVIDED "AS IS". THE LICENSOR HEREBY DISCLAIMS ALL
+WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR
+IN CONNECTION WITH THE LICENSED WORK OR THE USE OR OTHER DEALINGS IN THE
+LICENSED WORK.
+
+---
+
+## Contact
+
+For commercial licensing inquiries or additional permissions, contact:
+
+- **Alex Kahn**
+- alexkahndev@gmail.com
+- alexkahndev.github.io

package/README.md

@@ -0,0 +1,132 @@
+# @absolutejs/mcp
+
+Serve a remote [Model Context Protocol](https://modelcontextprotocol.io) endpoint
+— streamable HTTP, stateless — from a tool/prompt/resource registry. You supply
+**which** tools to expose and **how** to authorize a request into a caller; the
+package owns the JSON-RPC protocol, protocol-version negotiation, RFC 9728
+discovery metadata, and the `401` challenge that lets a client find your
+authorization server.
+
+Nothing here depends on a model. The tool shape is structurally compatible with
+[`@absolutejs/ai`](https://github.com/absolutejs/ai)'s `AIToolMap`, so an AI tool
+registry serves over MCP without conversion — but any typed tool registry works.
+
+```
+bun add @absolutejs/mcp
+```
+
+Peer dependency: `elysia`.
+
+## Define an endpoint
+
+```ts
+import { Elysia } from "elysia";
+import { mcpServer, verifyBearer } from "@absolutejs/mcp";
+import { verifyJwt } from "@absolutejs/auth"; // or any JWT verifier
+
+type Caller = { userId: string };
+
+const server = new Elysia().use(
+  mcpServer<Caller>({
+    path: "/mcp",
+    issuer: "https://your.app",
+    serverInfo: { name: "your-app", title: "Your App", version: "1.0.0" },
+    instructions: "What the model should know about this server.",
+    scopesSupported: ["openid", "mcp"],
+    serveRootMetadata: true,
+
+    // You decide who is allowed in. verifyBearer does the standard OAuth
+    // access-token checks; add your own (billing, role, MFA) on top.
+    authorize: async (request) => {
+      const token = await verifyBearer({
+        request,
+        issuer: "https://your.app",
+        requiredScope: "mcp",
+        verify: (jwt) => verifyJwt(jwt, publicJwk),
+      });
+      if ("error" in token) return { ok: false, reason: token.error };
+      return { ok: true, caller: { userId: token.subject } };
+    },
+
+    // Called once per request; build the tools for this caller.
+    tools: ({ caller }) => buildToolsFor(caller.userId),
+  }),
+);
+```
+
+That is a complete member endpoint. `GET /mcp` returns `405`, `POST /mcp` speaks
+JSON-RPC, and `GET /.well-known/oauth-protected-resource[/mcp]` serves the
+discovery metadata.
+
+## Guards, prompts, resources
+
+Everything beyond tools is a hook — the package ships no opinion about billing,
+storage, or auditing.
+
+```ts
+mcpServer<Caller>({
+  // ...as above
+
+  // Refuse a single call before it runs (credits, rate limit). The message
+  // comes back as an isError tool result the model can relay — not a crash.
+  beforeCall: async ({ caller }) =>
+    (await outOfCredits(caller))
+      ? { block: "Out of credits this cycle." }
+      : undefined,
+
+  // Audit every call. `meta` carries whatever the tool handler wrote.
+  onCall: ({ caller, name, ok, meta }) =>
+    recordCall({ caller, name, ok, touched: meta.touched }),
+
+  // Server-side prompts: recipes the client shows in its picker.
+  prompts: {
+    definitions: {
+      daily_briefing: { title: "Daily briefing", description: "..." },
+    },
+    get: async ({ name, args, caller }) => buildPromptText(name, args, caller),
+  },
+
+  // Readable resources.
+  resources: {
+    list: ({ caller }) => listResources(caller),
+    read: ({ caller, uri }) => readResource(caller, uri), // string | null
+  },
+});
+```
+
+### The `meta` scratchpad
+
+Each `tools/call` gets a fresh `meta` object shared between `tools`,
+`beforeCall`, and `onCall`. A tool handler can record what it touched, and your
+audit hook can read it back:
+
+```ts
+tools: ({ caller, meta }) =>
+  buildAdminTools(caller, (memberId) => { meta.touched = memberId; }),
+onCall: ({ meta, name, ok }) =>
+  ledger.write({ tool: name, ok, member: meta.touched }),
+```
+
+## A second, stricter endpoint
+
+`mcpServer` is per-endpoint, so an admin console is the same call with a
+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 */,
+    }),
+  );
+```
+
+Only one endpoint per app should set `serveRootMetadata` (the un-suffixed alias).
+
+## License
+
+Business Source License 1.1 — see [LICENSE](./LICENSE). Converts to Apache 2.0
+on the Change Date.

package/dist/index.js

@@ -0,0 +1,258 @@
+// @bun
+// src/guards.ts
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+
+// src/auth.ts
+var MS_PER_SECOND = 1000;
+var verifyBearer = async (config) => {
+  const { issuer, request, verify, requiredScope } = config;
+  const header = request.headers.get("authorization");
+  if (!header?.startsWith("Bearer "))
+    return { error: "Missing bearer token" };
+  const verified = await verify(header.slice("Bearer ".length));
+  if (!verified || !isRecord(verified.payload))
+    return { error: "Invalid token" };
+  const { payload } = verified;
+  if (payload.token_use !== "access")
+    return { error: "Not an access token" };
+  if (payload.iss !== issuer)
+    return { error: "Wrong issuer" };
+  const expires = typeof payload.exp === "number" ? payload.exp : 0;
+  if (expires * MS_PER_SECOND <= Date.now())
+    return { error: "Token expired" };
+  const scopes = typeof payload.scope === "string" ? payload.scope.split(" ") : [];
+  if (requiredScope !== undefined && !scopes.includes(requiredScope)) {
+    return { error: `Token lacks the ${requiredScope} scope` };
+  }
+  const subject = typeof payload.sub === "string" ? payload.sub : "";
+  if (!subject)
+    return { error: "Token has no subject" };
+  return { payload, scopes, subject };
+};
+// src/jsonrpc.ts
+var JSONRPC_PARSE_ERROR = -32700;
+var JSONRPC_INVALID_REQUEST = -32600;
+var JSONRPC_METHOD_NOT_FOUND = -32601;
+var JSONRPC_INVALID_PARAMS = -32602;
+var JSONRPC_INTERNAL_ERROR = -32603;
+var HTTP_ACCEPTED = 202;
+var HTTP_UNAUTHORIZED = 401;
+var HTTP_METHOD_NOT_ALLOWED = 405;
+var jsonHeaders = {
+  "content-type": "application/json"
+};
+var rpcResult = (id, result) => new Response(JSON.stringify({ id, jsonrpc: "2.0", result }), {
+  headers: jsonHeaders
+});
+var rpcError = (id, code, message) => new Response(JSON.stringify({ error: { code, message }, id, jsonrpc: "2.0" }), {
+  headers: jsonHeaders
+});
+var notificationAck = () => new Response(null, { status: HTTP_ACCEPTED });
+var unauthorized = (metadataUrl, detail) => new Response(JSON.stringify({
+  error: { code: JSONRPC_INVALID_REQUEST, message: detail },
+  id: null,
+  jsonrpc: "2.0"
+}), {
+  headers: {
+    ...jsonHeaders,
+    "www-authenticate": `Bearer resource_metadata="${metadataUrl}"`
+  },
+  status: HTTP_UNAUTHORIZED
+});
+
+// src/dispatch.ts
+var DEFAULT_PROTOCOLS = ["2025-06-18", "2025-03-26", "2024-11-05"];
+var DEFAULT_RESOURCE_MIME = "text/markdown";
+var idOf = (message) => typeof message.id === "string" || typeof message.id === "number" ? message.id : null;
+var negotiateProtocol = (supported, params) => {
+  const preferred = supported[0] ?? DEFAULT_PROTOCOLS[0] ?? "";
+  const requested = isRecord(params) && typeof params.protocolVersion === "string" ? params.protocolVersion : preferred;
+  return supported.includes(requested) ? requested : preferred;
+};
+var initialize = (config, id, params) => {
+  const supported = config.supportedProtocols ?? DEFAULT_PROTOCOLS;
+  const capabilities = {
+    tools: { listChanged: false }
+  };
+  if (config.prompts)
+    capabilities.prompts = { listChanged: false };
+  if (config.resources) {
+    capabilities.resources = { listChanged: false, subscribe: false };
+  }
+  return rpcResult(id, {
+    capabilities,
+    ...config.instructions === undefined ? {} : { instructions: config.instructions },
+    protocolVersion: negotiateProtocol(supported, params),
+    serverInfo: config.serverInfo
+  });
+};
+var toolsList = async (config, caller, id) => {
+  const tools = await config.tools({ caller, meta: {} });
+  return rpcResult(id, {
+    tools: Object.entries(tools).map(([name, tool]) => ({
+      annotations: tool.annotations,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      name
+    }))
+  });
+};
+var errorResult = (id, text) => rpcResult(id, { content: [{ text, type: "text" }], isError: true });
+var toolsCall = async (config, caller, id, params) => {
+  if (!isRecord(params) || typeof params.name !== "string") {
+    return rpcError(id, JSONRPC_INVALID_PARAMS, "tools/call needs a name");
+  }
+  const name = params.name;
+  const args = params.arguments ?? {};
+  const meta = {};
+  if (config.beforeCall) {
+    const gate = await config.beforeCall({ args, caller, meta, name });
+    if (gate)
+      return errorResult(id, gate.block);
+  }
+  const tools = await config.tools({ caller, meta });
+  const tool = tools[name];
+  if (!tool)
+    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
+    });
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : "unknown error";
+    response = errorResult(id, `Tool failed: ${detail}`);
+  }
+  if (config.onCall)
+    await config.onCall({ args, caller, meta, name, ok });
+  return response;
+};
+var promptsList = (config, id) => {
+  const definitions = config.prompts?.definitions ?? {};
+  return rpcResult(id, {
+    prompts: Object.entries(definitions).map(([name, def]) => ({
+      arguments: def.arguments ?? [],
+      description: def.description,
+      name,
+      title: def.title
+    }))
+  });
+};
+var promptsGet = async (config, caller, id, params) => {
+  const prompts = config.prompts;
+  if (!prompts)
+    return rpcError(id, JSONRPC_METHOD_NOT_FOUND, "No prompts");
+  if (!isRecord(params) || typeof params.name !== "string") {
+    return rpcError(id, JSONRPC_INVALID_PARAMS, "prompts/get needs a name");
+  }
+  const def = prompts.definitions[params.name];
+  if (!def) {
+    return rpcError(id, JSONRPC_INVALID_PARAMS, `Unknown prompt: ${params.name}`);
+  }
+  const args = isRecord(params.arguments) ? params.arguments : {};
+  const text = await prompts.get({ args, caller, name: params.name });
+  if (text === null) {
+    return rpcError(id, JSONRPC_INTERNAL_ERROR, "Prompt failed to build");
+  }
+  return rpcResult(id, {
+    description: def.description,
+    messages: [{ content: { text, type: "text" }, role: "user" }]
+  });
+};
+var resourcesList = async (config, caller, id) => {
+  const resources = config.resources;
+  if (!resources)
+    return rpcResult(id, { resources: [] });
+  return rpcResult(id, { resources: await resources.list({ caller }) });
+};
+var resourcesRead = async (config, caller, id, params) => {
+  const resources = config.resources;
+  if (!resources)
+    return rpcError(id, JSONRPC_METHOD_NOT_FOUND, "No resources");
+  if (!isRecord(params) || typeof params.uri !== "string") {
+    return rpcError(id, JSONRPC_INVALID_PARAMS, "resources/read needs a uri");
+  }
+  const uri = params.uri;
+  const text = await resources.read({ caller, uri });
+  if (text === null) {
+    return rpcError(id, JSONRPC_INVALID_PARAMS, `Unknown resource: ${uri}`);
+  }
+  return rpcResult(id, {
+    contents: [
+      { mimeType: resources.mimeType ?? DEFAULT_RESOURCE_MIME, text, uri }
+    ]
+  });
+};
+var dispatchMcp = async (config, caller, message) => {
+  if (!isRecord(message) || message.jsonrpc !== "2.0") {
+    return rpcError(null, JSONRPC_INVALID_REQUEST, "Not a JSON-RPC 2.0 message");
+  }
+  if (!("id" in message))
+    return notificationAck();
+  const id = idOf(message);
+  const method = typeof message.method === "string" ? message.method : "";
+  const { params } = message;
+  if (method === "initialize")
+    return initialize(config, id, params);
+  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);
+  if (method === "prompts/list")
+    return promptsList(config, id);
+  if (method === "prompts/get")
+    return promptsGet(config, caller, id, params);
+  if (method === "resources/list")
+    return resourcesList(config, caller, id);
+  if (method === "resources/read") {
+    return resourcesRead(config, caller, id, params);
+  }
+  return rpcError(id, JSONRPC_METHOD_NOT_FOUND, `Unknown method: ${method}`);
+};
+// src/metadata.ts
+var protectedResourceMetadata = (input) => ({
+  authorization_servers: [input.issuer],
+  resource: input.resource,
+  scopes_supported: input.scopes ?? []
+});
+var metadataPathFor = (path) => `/.well-known/oauth-protected-resource${path}`;
+// src/server.ts
+import { Elysia } from "elysia";
+var ROOT_METADATA_PATH = "/.well-known/oauth-protected-resource";
+var mcpServer = (config) => {
+  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 (Array.isArray(message)) {
+      return rpcError(null, JSONRPC_INVALID_REQUEST, "Batching is not supported");
+    }
+    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 app;
+};
+export {
+  verifyBearer,
+  protectedResourceMetadata,
+  metadataPathFor,
+  mcpServer,
+  dispatchMcp
+};

package/dist/src/auth.d.ts

@@ -0,0 +1,26 @@
+/** The decoded JWT, as returned by your `verify`. Only `payload` is read. */
+export type VerifiedJwt = {
+    header?: unknown;
+    payload: unknown;
+};
+export type BearerVerifier = (token: string) => Promise<VerifiedJwt | undefined> | VerifiedJwt | undefined;
+export type VerifyBearerConfig = {
+    issuer: string;
+    request: Request;
+    /** Verify the JWT signature and decode it (e.g. `@absolutejs/auth`'s
+     *  `verifyJwt`). Return undefined on an invalid signature. */
+    verify: BearerVerifier;
+    requiredScope?: string;
+};
+export type BearerResult = {
+    error: string;
+} | {
+    payload: Record<string, unknown>;
+    scopes: string[];
+    subject: string;
+};
+/** Verify the `Authorization: Bearer` token: signature (via your `verify`),
+ *  `token_use: access`, issuer, expiry, the required scope, and a subject.
+ *  Returns the decoded payload + parsed scopes + subject, or a reason string.
+ *  The reason is safe to surface in the 401 (never why the signature failed). */
+export declare const verifyBearer: (config: VerifyBearerConfig) => Promise<BearerResult>;

package/dist/src/dispatch.d.ts

@@ -0,0 +1,4 @@
+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>;

package/dist/src/guards.d.ts

@@ -0,0 +1 @@
+export declare const isRecord: (value: unknown) => value is Record<string, unknown>;

package/dist/src/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@absolutejs/mcp` — serve a remote Model Context Protocol endpoint
+ * (streamable HTTP, stateless) 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
+ * 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.
+ *
+ * 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.
+ */
+export { verifyBearer, type BearerResult, type BearerVerifier, type VerifiedJwt, type VerifyBearerConfig, } from "./auth";
+export { dispatchMcp } from "./dispatch";
+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";

package/dist/src/jsonrpc.d.ts

@@ -0,0 +1,15 @@
+export declare const JSONRPC_PARSE_ERROR = -32700;
+export declare const JSONRPC_INVALID_REQUEST = -32600;
+export declare const JSONRPC_METHOD_NOT_FOUND = -32601;
+export declare const JSONRPC_INVALID_PARAMS = -32602;
+export declare const JSONRPC_INTERNAL_ERROR = -32603;
+export declare const HTTP_ACCEPTED = 202;
+export declare const HTTP_UNAUTHORIZED = 401;
+export declare const HTTP_METHOD_NOT_ALLOWED = 405;
+export type JsonRpcId = string | number | null;
+export declare const rpcResult: (id: JsonRpcId, result: unknown) => Response;
+export declare const rpcError: (id: JsonRpcId, code: number, message: string) => Response;
+export declare const notificationAck: () => Response;
+/** 401 with the RFC 9728 `WWW-Authenticate` challenge pointing at the
+ *  protected-resource metadata, so the client can discover the auth server. */
+export declare const unauthorized: (metadataUrl: string, detail: string) => Response;

package/dist/src/metadata.d.ts

@@ -0,0 +1,13 @@
+export type ProtectedResourceMetadata = {
+    authorization_servers: string[];
+    resource: string;
+    scopes_supported: string[];
+};
+export declare const protectedResourceMetadata: (input: {
+    issuer: string;
+    resource: string;
+    scopes?: string[];
+}) => ProtectedResourceMetadata;
+/** The metadata document URL for an endpoint path, per RFC 9728 §3: the path is
+ *  inserted after the well-known segment. `/mcp` → `/.well-known/oauth-protected-resource/mcp`. */
+export declare const metadataPathFor: (path: string) => string;

package/dist/src/server.d.ts

@@ -0,0 +1,11 @@
+import { Elysia } from "elysia";
+import type { McpServerConfig } from "./types";
+/** Build the MCP endpoint as an Elysia plugin. Mount it with `.use(...)`.
+ *
+ *  Serves:
+ *   - `POST <path>`   — the JSON-RPC endpoint (stateless streamable HTTP)
+ *   - `GET  <path>`   — 405 (no server-initiated stream to subscribe to)
+ *   - `GET  /.well-known/oauth-protected-resource<path>` — RFC 9728 metadata
+ *   - `GET  /.well-known/oauth-protected-resource` — the same, if
+ *     `serveRootMetadata` is set (only one endpoint per app should). */
+export declare const mcpServer: <Caller>(config: McpServerConfig<Caller>) => Elysia;

package/dist/src/types.d.ts

@@ -0,0 +1,123 @@
+/** MCP behaviour hints, passed straight through to the client on `tools/list`.
+ *  Structurally identical to `@absolutejs/ai`'s `AIToolAnnotations`, so a tool
+ *  map from that package satisfies this without conversion. All optional. */
+export type McpToolAnnotations = {
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+    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`). */
+export type McpTool = {
+    annotations?: McpToolAnnotations;
+    description: string;
+    handler: (args: unknown) => Promise<string> | string;
+    inputSchema: Record<string, unknown>;
+};
+export type McpToolRegistry = Record<string, McpTool>;
+/** A resource the client can list and read (`resources/list` / `resources/read`). */
+export type McpResource = {
+    description?: string;
+    mimeType?: string;
+    name: string;
+    uri: string;
+};
+export type McpPromptArgument = {
+    description: string;
+    name: string;
+    required?: boolean;
+};
+export type McpPromptDefinition = {
+    arguments?: McpPromptArgument[];
+    description: string;
+    title: string;
+};
+/** Per-call scratchpad shared between `tools`, `beforeCall`, and `onCall` for
+ *  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. */
+export type McpAuthResult<Caller> = {
+    caller: Caller;
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Returned by `beforeCall` to refuse a tool call without running it — the
+ *  message becomes an `isError` tool result (a paused/rate-limited notice the
+ *  model can relay), not a transport error. */
+export type McpCallGate = {
+    block: string;
+};
+export type McpToolContext<Caller> = {
+    caller: Caller;
+    meta: McpCallMeta;
+};
+export type McpPrompts<Caller> = {
+    definitions: Record<string, McpPromptDefinition>;
+    get: (ctx: {
+        args: Record<string, unknown>;
+        caller: Caller;
+        name: string;
+    }) => Promise<string | null> | string | null;
+};
+export type McpResources<Caller> = {
+    /** Defaults to "text/markdown". */
+    mimeType?: string;
+    list: (ctx: {
+        caller: Caller;
+    }) => Promise<McpResource[]> | McpResource[];
+    read: (ctx: {
+        caller: Caller;
+        uri: string;
+    }) => Promise<string | null> | string | null;
+};
+export type McpServerInfo = {
+    name: string;
+    title?: string;
+    version: string;
+};
+export type McpServerConfig<Caller> = {
+    /** Resolve the request into a caller, or a reason for the 401. The package
+     *  emits the 401 + RFC 9728 `WWW-Authenticate` challenge; you decide who is
+     *  allowed in. See {@link verifyBearer} for the standard token checks. */
+    authorize: (request: Request) => Promise<McpAuthResult<Caller>>;
+    /** Refuse a single `tools/call` before it runs (credits exhausted, rate
+     *  limited). Return `{ block }` to short-circuit; return nothing to proceed. */
+    beforeCall?: (ctx: {
+        args: unknown;
+        caller: Caller;
+        meta: McpCallMeta;
+        name: string;
+    }) => Promise<McpCallGate | void> | McpCallGate | void;
+    instructions?: string;
+    /** The token issuer — used for discovery metadata and the challenge URL. */
+    issuer: string;
+    /** Fired after every `tools/call` for auditing. `meta` carries anything the
+     *  tool handler wrote during the call. */
+    onCall?: (record: {
+        args: unknown;
+        caller: Caller;
+        meta: McpCallMeta;
+        name: string;
+        ok: boolean;
+    }) => Promise<void> | void;
+    /** The endpoint path, e.g. "/mcp" or "/mcp/admin". */
+    path: string;
+    prompts?: McpPrompts<Caller>;
+    resources?: McpResources<Caller>;
+    /** Advertised in the protected-resource metadata. */
+    scopesSupported?: string[];
+    /** Also serve the un-suffixed `/.well-known/oauth-protected-resource` alias
+     *  (some clients probe the root). Only one endpoint per app may set this. */
+    serveRootMetadata?: boolean;
+    serverInfo: McpServerInfo;
+    /** Protocol versions this endpoint accepts; the first is the preferred one.
+     *  Defaults to the versions this package knows. */
+    supportedProtocols?: string[];
+    /** Build the tool registry for this caller. Called once per request. */
+    tools: (ctx: McpToolContext<Caller>) => McpToolRegistry | Promise<McpToolRegistry>;
+};

package/package.json

@@ -0,0 +1,41 @@
+{
+  "author": "Alex Kahn",
+  "description": "Serve a remote Model Context Protocol endpoint (streamable HTTP, stateless) from a tool/prompt/resource registry — OAuth bearer auth, RFC 9728 discovery, and per-call guards are yours to wire, the JSON-RPC protocol is done correctly by construction.",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "elysia": "^1.1.0",
+    "prettier": "3.5.3",
+    "typescript": "5.8.3"
+  },
+  "peerDependencies": {
+    "elysia": ">=1.1.0"
+  },
+  "license": "BUSL-1.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "name": "@absolutejs/mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/absolutejs/mcp.git"
+  },
+  "homepage": "https://github.com/absolutejs/mcp",
+  "bugs": {
+    "url": "https://github.com/absolutejs/mcp/issues"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts --outdir dist --target=bun --external elysia && tsc --emitDeclarationOnly --project tsconfig.json",
+    "format": "prettier --write \"./**/*.{ts,json,md}\"",
+    "release": "bun run format && bun run test && bun run build && bun publish",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit --project tsconfig.json"
+  },
+  "types": "./dist/src/index.d.ts",
+  "version": "0.0.1"
+}