@lunora/mcp 1.0.0-alpha.81 → 1.0.0-alpha.83

package/dist/index.d.mts

@@ -165,6 +165,73 @@ declare const createLunoraMcpServer: (options: LunoraMcpServerOptions) => Server
  * connected; the process then stays alive serving requests.
  */
 declare const connectStdio: (options: LunoraMcpServerOptions) => Promise<Server>;
+/**
+ * The verified access-token payload better-auth hands a protected handler.
+ *
+ * A JWT payload is an open bag of claims, so this is deliberately an index
+ * signature with the two entries this module reads named. It is structurally
+ * satisfied by `jose`'s `JWTPayload`, which is what better-auth passes.
+ */
+interface McpAccessTokenClaims {
+  readonly [claim: string]: unknown;
+  /** Space-delimited granted scopes (RFC 6749 §3.3). */
+  readonly scope?: unknown;
+  /** Subject — the user the token was issued for. */
+  readonly sub?: string;
+}
+/**
+ * The MCP auth gate: wraps a claims-aware handler into a plain fetch handler.
+ *
+ * Declared structurally here rather than imported from `@better-auth/mcp`,
+ * following the same rule `./paid` follows for `@lunora/x402`: a type import
+ * from a package this one does not depend on puts that package's `.d.ts` into
+ * the build graph, and a consumer that never installs it never builds it
+ * either — so the dts bundler looks for a `dist/` that does not exist and fails
+ * the build. Structural typing costs nothing here because this module never
+ * inspects the gate; it only applies it.
+ *
+ * Both better-auth entry points partially apply to this shape:
+ * `(handler) => requireMcpAuth(auth, handler, opts)` and
+ * `(handler) => createMcpProtectedRequestHandler(options, handler)`.
+ */
+type McpAuthProtect = (handler: (request: Request, claims: McpAccessTokenClaims) => Promise<Response>) => McpFetchHandler;
+/** Server options, or a function deriving them from the request's verified claims. */
+type AuthedMcpServerOptions = ((claims: McpAccessTokenClaims) => LunoraMcpServerOptions | Promise<LunoraMcpServerOptions>) | LunoraMcpServerOptions;
+interface AuthedMcpFetchHandlerOptions {
+  /**
+   * The OAuth gate to mount the MCP server behind. Pass
+   * `(handler) => requireMcpAuth(auth, handler, opts)` from
+   * `@lunora/auth/plugins`.
+   */
+  protect: McpAuthProtect;
+  /**
+   * The Lunora MCP server to serve once a request is authorized — either a
+   * fixed options object, or a function of the verified token claims so tool
+   * exposure can follow the scopes the token actually carries.
+   */
+  server: AuthedMcpServerOptions;
+}
+/**
+ * Parse an access token's `scope` claim into a set.
+ *
+ * RFC 6749 §3.3 makes `scope` a space-delimited string, and better-auth issues
+ * it that way; anything else (absent, or a non-string an extension wrote)
+ * yields an empty set rather than throwing, so a scope check on a malformed
+ * token denies instead of crashing the tool call.
+ */
+declare const mcpTokenScopes: (claims: McpAccessTokenClaims) => ReadonlySet<string>;
+/**
+ * Build an OAuth-protected stateless Streamable-HTTP fetch handler for a Lunora
+ * MCP server.
+ *
+ * Unauthenticated requests never reach the MCP server at all: `protect` answers
+ * them with the RFC 9728 `WWW-Authenticate` challenge that starts the client's
+ * authorization flow. An authorized request builds a fresh proxy server from
+ * `server` (resolved against the verified claims) and serves it through
+ * {@link serveStateless}, exactly as the unprotected `createMcpFetchHandler`
+ * does — the transport behaviour is identical, only the gate is new.
+ */
+declare const createAuthedMcpFetchHandler: (options: AuthedMcpFetchHandlerOptions) => McpFetchHandler;
 /**
  * Build a stateless Streamable-HTTP fetch handler for a Lunora MCP server. Each
  * invocation constructs a fresh proxy server and serves the request through
@@ -318,7 +385,7 @@ interface PaidMcpServer {
  * transient facilitator outage retries on the next call.
  */
 declare const createPaidMcpServer: (config: PaidMcpServerConfig) => PaidMcpServer;
-export { AGENT_RUN_INPUT_SCHEMA, AGENT_STATUS_TOOL_NAME,
+export { AGENT_RUN_INPUT_SCHEMA, AGENT_STATUS_TOOL_NAME, type AuthedMcpFetchHandlerOptions, type AuthedMcpServerOptions,
 /**
  * `@lunora/mcp` — Model Context Protocol servers for Lunora. This entry exposes
  * a *deployment* to AI agents; the `@lunora/mcp/docs` subpath exposes the
@@ -342,8 +409,14 @@ export { AGENT_RUN_INPUT_SCHEMA, AGENT_STATUS_TOOL_NAME,
  * server remotely over Streamable HTTP with `createMcpFetchHandler` (a
  * Workers-ready `Request` → `Response` handler), or build a server
  * programmatically with `createLunoraMcpServer` and connect any transport.
+ *
+ * A remote endpoint is reachable by anyone who knows its URL, and the tools
+ * carry the deployment's admin bearer — so for a public deployment use
+ * `createAuthedMcpFetchHandler` instead, which mounts the same server behind
+ * better-auth's MCP OAuth gate (`requireMcpAuth` from `@lunora/auth/plugins`)
+ * and can scope tool exposure to the access token's own scopes.
  */
-type CallAgentToolOptions, LOCAL_SERVER_NAME, type LocalDeployment, type LocalDeploymentSource, type LocalMcpServerOptions, type LunoraMcpServerOptions,
+type CallAgentToolOptions, LOCAL_SERVER_NAME, type LocalDeployment, type LocalDeploymentSource, type LocalMcpServerOptions, type LunoraMcpServerOptions, type McpAccessTokenClaims,
 /**
  * `@lunora/mcp` — Model Context Protocol servers for Lunora. This entry exposes
  * a *deployment* to AI agents; the `@lunora/mcp/docs` subpath exposes the
@@ -367,5 +440,11 @@ type CallAgentToolOptions, LOCAL_SERVER_NAME, type LocalDeployment, type LocalDe
  * server remotely over Streamable HTTP with `createMcpFetchHandler` (a
  * Workers-ready `Request` → `Response` handler), or build a server
  * programmatically with `createLunoraMcpServer` and connect any transport.
+ *
+ * A remote endpoint is reachable by anyone who knows its URL, and the tools
+ * carry the deployment's admin bearer — so for a public deployment use
+ * `createAuthedMcpFetchHandler` instead, which mounts the same server behind
+ * better-auth's MCP OAuth gate (`requireMcpAuth` from `@lunora/auth/plugins`)
+ * and can scope tool exposure to the access token's own scopes.
  */
-type McpAgentExposure, type McpFetchHandler, type McpTool, NO_DEPLOYMENT_MESSAGE, OBSERVABILITY_TOOL_DEFINITIONS, type PaidMcpChargeConfig, type PaidMcpServer, type PaidMcpServerConfig, READ_ONLY_TOOL_DEFINITIONS, type RegisterPaidToolOptions, type RegisterToolOptions, type ToolDefinition, type ToolHandler, type ToolInputSchema, type ToolResult, WRITE_TOOL_DEFINITIONS, agentToolDefinitions, callAgentTool, callTool, connectLocalStdio, connectStdio, createLocalMcpServer, createLunoraMcpServer, createMcpFetchHandler, createPaidMcpServer, localTools, parseAgentsEnv, toolDefinitions };
+type McpAgentExposure, type McpAuthProtect, type McpFetchHandler, type McpTool, NO_DEPLOYMENT_MESSAGE, OBSERVABILITY_TOOL_DEFINITIONS, type PaidMcpChargeConfig, type PaidMcpServer, type PaidMcpServerConfig, READ_ONLY_TOOL_DEFINITIONS, type RegisterPaidToolOptions, type RegisterToolOptions, type ToolDefinition, type ToolHandler, type ToolInputSchema, type ToolResult, WRITE_TOOL_DEFINITIONS, agentToolDefinitions, callAgentTool, callTool, connectLocalStdio, connectStdio, createAuthedMcpFetchHandler, createLocalMcpServer, createLunoraMcpServer, createMcpFetchHandler, createPaidMcpServer, localTools, mcpTokenScopes, parseAgentsEnv, toolDefinitions };

package/dist/index.d.ts

@@ -165,6 +165,73 @@ declare const createLunoraMcpServer: (options: LunoraMcpServerOptions) => Server
  * connected; the process then stays alive serving requests.
  */
 declare const connectStdio: (options: LunoraMcpServerOptions) => Promise<Server>;
+/**
+ * The verified access-token payload better-auth hands a protected handler.
+ *
+ * A JWT payload is an open bag of claims, so this is deliberately an index
+ * signature with the two entries this module reads named. It is structurally
+ * satisfied by `jose`'s `JWTPayload`, which is what better-auth passes.
+ */
+interface McpAccessTokenClaims {
+  readonly [claim: string]: unknown;
+  /** Space-delimited granted scopes (RFC 6749 §3.3). */
+  readonly scope?: unknown;
+  /** Subject — the user the token was issued for. */
+  readonly sub?: string;
+}
+/**
+ * The MCP auth gate: wraps a claims-aware handler into a plain fetch handler.
+ *
+ * Declared structurally here rather than imported from `@better-auth/mcp`,
+ * following the same rule `./paid` follows for `@lunora/x402`: a type import
+ * from a package this one does not depend on puts that package's `.d.ts` into
+ * the build graph, and a consumer that never installs it never builds it
+ * either — so the dts bundler looks for a `dist/` that does not exist and fails
+ * the build. Structural typing costs nothing here because this module never
+ * inspects the gate; it only applies it.
+ *
+ * Both better-auth entry points partially apply to this shape:
+ * `(handler) => requireMcpAuth(auth, handler, opts)` and
+ * `(handler) => createMcpProtectedRequestHandler(options, handler)`.
+ */
+type McpAuthProtect = (handler: (request: Request, claims: McpAccessTokenClaims) => Promise<Response>) => McpFetchHandler;
+/** Server options, or a function deriving them from the request's verified claims. */
+type AuthedMcpServerOptions = ((claims: McpAccessTokenClaims) => LunoraMcpServerOptions | Promise<LunoraMcpServerOptions>) | LunoraMcpServerOptions;
+interface AuthedMcpFetchHandlerOptions {
+  /**
+   * The OAuth gate to mount the MCP server behind. Pass
+   * `(handler) => requireMcpAuth(auth, handler, opts)` from
+   * `@lunora/auth/plugins`.
+   */
+  protect: McpAuthProtect;
+  /**
+   * The Lunora MCP server to serve once a request is authorized — either a
+   * fixed options object, or a function of the verified token claims so tool
+   * exposure can follow the scopes the token actually carries.
+   */
+  server: AuthedMcpServerOptions;
+}
+/**
+ * Parse an access token's `scope` claim into a set.
+ *
+ * RFC 6749 §3.3 makes `scope` a space-delimited string, and better-auth issues
+ * it that way; anything else (absent, or a non-string an extension wrote)
+ * yields an empty set rather than throwing, so a scope check on a malformed
+ * token denies instead of crashing the tool call.
+ */
+declare const mcpTokenScopes: (claims: McpAccessTokenClaims) => ReadonlySet<string>;
+/**
+ * Build an OAuth-protected stateless Streamable-HTTP fetch handler for a Lunora
+ * MCP server.
+ *
+ * Unauthenticated requests never reach the MCP server at all: `protect` answers
+ * them with the RFC 9728 `WWW-Authenticate` challenge that starts the client's
+ * authorization flow. An authorized request builds a fresh proxy server from
+ * `server` (resolved against the verified claims) and serves it through
+ * {@link serveStateless}, exactly as the unprotected `createMcpFetchHandler`
+ * does — the transport behaviour is identical, only the gate is new.
+ */
+declare const createAuthedMcpFetchHandler: (options: AuthedMcpFetchHandlerOptions) => McpFetchHandler;
 /**
  * Build a stateless Streamable-HTTP fetch handler for a Lunora MCP server. Each
  * invocation constructs a fresh proxy server and serves the request through
@@ -318,7 +385,7 @@ interface PaidMcpServer {
  * transient facilitator outage retries on the next call.
  */
 declare const createPaidMcpServer: (config: PaidMcpServerConfig) => PaidMcpServer;
-export { AGENT_RUN_INPUT_SCHEMA, AGENT_STATUS_TOOL_NAME,
+export { AGENT_RUN_INPUT_SCHEMA, AGENT_STATUS_TOOL_NAME, type AuthedMcpFetchHandlerOptions, type AuthedMcpServerOptions,
 /**
  * `@lunora/mcp` — Model Context Protocol servers for Lunora. This entry exposes
  * a *deployment* to AI agents; the `@lunora/mcp/docs` subpath exposes the
@@ -342,8 +409,14 @@ export { AGENT_RUN_INPUT_SCHEMA, AGENT_STATUS_TOOL_NAME,
  * server remotely over Streamable HTTP with `createMcpFetchHandler` (a
  * Workers-ready `Request` → `Response` handler), or build a server
  * programmatically with `createLunoraMcpServer` and connect any transport.
+ *
+ * A remote endpoint is reachable by anyone who knows its URL, and the tools
+ * carry the deployment's admin bearer — so for a public deployment use
+ * `createAuthedMcpFetchHandler` instead, which mounts the same server behind
+ * better-auth's MCP OAuth gate (`requireMcpAuth` from `@lunora/auth/plugins`)
+ * and can scope tool exposure to the access token's own scopes.
  */
-type CallAgentToolOptions, LOCAL_SERVER_NAME, type LocalDeployment, type LocalDeploymentSource, type LocalMcpServerOptions, type LunoraMcpServerOptions,
+type CallAgentToolOptions, LOCAL_SERVER_NAME, type LocalDeployment, type LocalDeploymentSource, type LocalMcpServerOptions, type LunoraMcpServerOptions, type McpAccessTokenClaims,
 /**
  * `@lunora/mcp` — Model Context Protocol servers for Lunora. This entry exposes
  * a *deployment* to AI agents; the `@lunora/mcp/docs` subpath exposes the
@@ -367,5 +440,11 @@ type CallAgentToolOptions, LOCAL_SERVER_NAME, type LocalDeployment, type LocalDe
  * server remotely over Streamable HTTP with `createMcpFetchHandler` (a
  * Workers-ready `Request` → `Response` handler), or build a server
  * programmatically with `createLunoraMcpServer` and connect any transport.
+ *
+ * A remote endpoint is reachable by anyone who knows its URL, and the tools
+ * carry the deployment's admin bearer — so for a public deployment use
+ * `createAuthedMcpFetchHandler` instead, which mounts the same server behind
+ * better-auth's MCP OAuth gate (`requireMcpAuth` from `@lunora/auth/plugins`)
+ * and can scope tool exposure to the access token's own scopes.
  */
-type McpAgentExposure, type McpFetchHandler, type McpTool, NO_DEPLOYMENT_MESSAGE, OBSERVABILITY_TOOL_DEFINITIONS, type PaidMcpChargeConfig, type PaidMcpServer, type PaidMcpServerConfig, READ_ONLY_TOOL_DEFINITIONS, type RegisterPaidToolOptions, type RegisterToolOptions, type ToolDefinition, type ToolHandler, type ToolInputSchema, type ToolResult, WRITE_TOOL_DEFINITIONS, agentToolDefinitions, callAgentTool, callTool, connectLocalStdio, connectStdio, createLocalMcpServer, createLunoraMcpServer, createMcpFetchHandler, createPaidMcpServer, localTools, parseAgentsEnv, toolDefinitions };
+type McpAgentExposure, type McpAuthProtect, type McpFetchHandler, type McpTool, NO_DEPLOYMENT_MESSAGE, OBSERVABILITY_TOOL_DEFINITIONS, type PaidMcpChargeConfig, type PaidMcpServer, type PaidMcpServerConfig, READ_ONLY_TOOL_DEFINITIONS, type RegisterPaidToolOptions, type RegisterToolOptions, type ToolDefinition, type ToolHandler, type ToolInputSchema, type ToolResult, WRITE_TOOL_DEFINITIONS, agentToolDefinitions, callAgentTool, callTool, connectLocalStdio, connectStdio, createAuthedMcpFetchHandler, createLocalMcpServer, createLunoraMcpServer, createMcpFetchHandler, createPaidMcpServer, localTools, mcpTokenScopes, parseAgentsEnv, toolDefinitions };

package/dist/index.mjs

@@ -1 +1 @@
-import{AGENT_RUN_INPUT_SCHEMA as r,AGENT_STATUS_TOOL_NAME as t,agentToolDefinitions as T,callAgentTool as c,parseAgentsEnv as E}from"./packem_shared/AGENT_RUN_INPUT_SCHEMA-DRSY74ed.mjs";import{createToolServer as O}from"./packem_shared/createToolServer-BtGuPyMU.mjs";import{createMcpFetchHandler as _}from"./packem_shared/createMcpFetchHandler-TKDnZTGs.mjs";import{LOCAL_SERVER_NAME as N,NO_DEPLOYMENT_MESSAGE as n,connectLocalStdio as p,createLocalMcpServer as I,localTools as A}from"./packem_shared/LOCAL_SERVER_NAME-CisKTqzv.mjs";import{createPaidMcpServer as f}from"./packem_shared/createPaidMcpServer-CQO-59WV.mjs";import{connectStdio as m,createLunoraMcpServer as s}from"./packem_shared/connectStdio-BCeI0Wqu.mjs";import{READ_ONLY_TOOL_DEFINITIONS as M,WRITE_TOOL_DEFINITIONS as D,callTool as v,toolDefinitions as R}from"./packem_shared/READ_ONLY_TOOL_DEFINITIONS-DGexf3Tn.mjs";import{O as F}from"./packem_shared/observability-tools-Ce0YK58T.mjs";import{serveStateless as G}from"./packem_shared/serveStateless-Db7J3pAO.mjs";export{r as AGENT_RUN_INPUT_SCHEMA,t as AGENT_STATUS_TOOL_NAME,N as LOCAL_SERVER_NAME,n as NO_DEPLOYMENT_MESSAGE,F as OBSERVABILITY_TOOL_DEFINITIONS,M as READ_ONLY_TOOL_DEFINITIONS,D as WRITE_TOOL_DEFINITIONS,T as agentToolDefinitions,c as callAgentTool,v as callTool,p as connectLocalStdio,m as connectStdio,I as createLocalMcpServer,s as createLunoraMcpServer,_ as createMcpFetchHandler,f as createPaidMcpServer,O as createToolServer,A as localTools,E as parseAgentsEnv,G as serveStateless,R as toolDefinitions};
+import{AGENT_RUN_INPUT_SCHEMA as r,AGENT_STATUS_TOOL_NAME as t,agentToolDefinitions as c,callAgentTool as T,parseAgentsEnv as a}from"./packem_shared/AGENT_RUN_INPUT_SCHEMA-DRSY74ed.mjs";import{createAuthedMcpFetchHandler as E,mcpTokenScopes as S}from"./packem_shared/createAuthedMcpFetchHandler-BUoCjrxu.mjs";import{createToolServer as O}from"./packem_shared/createToolServer-BtGuPyMU.mjs";import{createMcpFetchHandler as n}from"./packem_shared/createMcpFetchHandler-TKDnZTGs.mjs";import{LOCAL_SERVER_NAME as A,NO_DEPLOYMENT_MESSAGE as I,connectLocalStdio as f,createLocalMcpServer as L,localTools as m}from"./packem_shared/LOCAL_SERVER_NAME-CisKTqzv.mjs";import{createPaidMcpServer as x}from"./packem_shared/createPaidMcpServer-CQO-59WV.mjs";import{connectStdio as i,createLunoraMcpServer as D}from"./packem_shared/connectStdio-BCeI0Wqu.mjs";import{READ_ONLY_TOOL_DEFINITIONS as v,WRITE_TOOL_DEFINITIONS as R,callTool as F,toolDefinitions as g}from"./packem_shared/READ_ONLY_TOOL_DEFINITIONS-DGexf3Tn.mjs";import{O as G}from"./packem_shared/observability-tools-Ce0YK58T.mjs";import{serveStateless as P}from"./packem_shared/serveStateless-Db7J3pAO.mjs";export{r as AGENT_RUN_INPUT_SCHEMA,t as AGENT_STATUS_TOOL_NAME,A as LOCAL_SERVER_NAME,I as NO_DEPLOYMENT_MESSAGE,G as OBSERVABILITY_TOOL_DEFINITIONS,v as READ_ONLY_TOOL_DEFINITIONS,R as WRITE_TOOL_DEFINITIONS,c as agentToolDefinitions,T as callAgentTool,F as callTool,f as connectLocalStdio,i as connectStdio,E as createAuthedMcpFetchHandler,L as createLocalMcpServer,D as createLunoraMcpServer,n as createMcpFetchHandler,x as createPaidMcpServer,O as createToolServer,m as localTools,S as mcpTokenScopes,a as parseAgentsEnv,P as serveStateless,g as toolDefinitions};

package/dist/packem_shared/createAuthedMcpFetchHandler-BUoCjrxu.mjs

@@ -0,0 +1 @@
+import{serveStateless as n}from"./serveStateless-Db7J3pAO.mjs";import{createLunoraMcpServer as o}from"./connectStdio-BCeI0Wqu.mjs";const a=e=>typeof e.scope!="string"?new Set:new Set(e.scope.split(" ").filter(r=>r!=="")),f=e=>e.protect(async(r,t)=>{const c=typeof e.server=="function"?await e.server(t):e.server;return await n(o(c),r)});export{f as createAuthedMcpFetchHandler,a as mcpTokenScopes};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lunora/mcp",
-  "version": "1.0.0-alpha.81",
+  "version": "1.0.0-alpha.83",
   "description": "Model Context Protocol server exposing a Lunora deployment to AI agents",
   "keywords": [
     "ai-agents",
@@ -53,9 +53,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@lunora/client": "1.0.0-alpha.56",
+    "@lunora/client": "1.0.0-alpha.57",
     "@lunora/errors": "1.0.0-alpha.22",
-    "@lunora/shard-engine": "1.0.0-alpha.34",
+    "@lunora/shard-engine": "1.0.0-alpha.35",
     "@modelcontextprotocol/sdk": "^1.30.0"
   },
   "peerDependencies": {