@casys/mcp-server 0.12.0 → 0.14.0

package/src/{concurrent-server.ts → mcp-app.ts}

@@ -1,21 +1,23 @@
 /**
- * Concurrent MCP Server Framework
+ * McpApp — Hono-style framework for MCP servers
  *
  * High-performance MCP server with built-in concurrency control,
  * backpressure, and optional sampling support.
  *
  * Wraps the official @modelcontextprotocol/sdk with production-ready
- * concurrency features.
+ * middleware, auth, and observability features.
  *
- * @module lib/server/concurrent-server
+ * @module lib/server/mcp-app
  */
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
+  type CallToolRequest,
   CallToolRequestSchema,
-  ListToolsRequestSchema,
   ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  type ReadResourceRequest,
   ReadResourceRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import { Hono } from "hono";
@@ -45,9 +47,11 @@ import { createScopeMiddleware } from "./auth/scope-middleware.js";
 import { createAuthProviderFromConfig, loadAuthConfig } from "./auth/config.js";
 import type { AuthProvider } from "./auth/provider.js";
 import type {
-  ConcurrentServerOptions,
+  FetchHandler,
   HttpRateLimitContext,
   HttpServerOptions,
+  McpAppOptions,
+  McpAppsClientCapability,
   MCPResource,
   MCPTool,
   QueueMetrics,
@@ -56,8 +60,12 @@ import type {
   StructuredToolResult,
   ToolHandler,
 } from "./types.js";
-import { MCP_APP_MIME_TYPE, MCP_APP_URI_SCHEME } from "./types.js";
-import { resolveViewerDistPath, discoverViewers } from "./ui/viewer-utils.js";
+import {
+  getMcpAppsCapability,
+  MCP_APP_MIME_TYPE,
+  MCP_APP_URI_SCHEME,
+} from "./types.js";
+import { discoverViewers, resolveViewerDistPath } from "./ui/viewer-utils.js";
 import type { DirEntry, DiscoverViewersFS } from "./ui/viewer-utils.js";
 import { buildCspHeader, injectCspMetaTag } from "./security/csp.js";
 import { ServerMetrics } from "./observability/metrics.js";
@@ -157,7 +165,7 @@ async function readBodyWithLimit(
 }
 
 /**
- * ConcurrentMCPServer provides a high-performance MCP server
+ * McpApp provides a high-performance MCP server
  *
  * Features:
  * - Wraps official @modelcontextprotocol/sdk
@@ -169,7 +177,7 @@ async function readBodyWithLimit(
  *
  * @example
  * ```typescript
- * const server = new ConcurrentMCPServer({
+ * const server = new McpApp({
  *   name: "my-server",
  *   version: "1.0.0",
  *   maxConcurrent: 5,
@@ -180,7 +188,7 @@ async function readBodyWithLimit(
  * await server.start();
  * ```
  */
-export class ConcurrentMCPServer {
+export class McpApp {
   private mcpServer: McpServer;
   private requestQueue: RequestQueue;
   private rateLimiter: RateLimiter | null = null;
@@ -188,7 +196,7 @@ export class ConcurrentMCPServer {
   private samplingBridge: SamplingBridge | null = null;
   private tools = new Map<string, ToolWithHandler>();
   private resources = new Map<string, RegisteredResourceInfo>();
-  private options: ConcurrentServerOptions;
+  private options: McpAppOptions;
   private started = false;
   private resourceHandlersInstalled = false;
 
@@ -222,7 +230,7 @@ export class ConcurrentMCPServer {
     windowMs: 60_000,
   });
 
-  constructor(options: ConcurrentServerOptions) {
+  constructor(options: McpAppOptions) {
     this.options = options;
 
     // Create SDK MCP server
@@ -300,26 +308,29 @@ export class ConcurrentMCPServer {
     });
 
     // resources/read — serve resource content by URI
-    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-      const uri = request.params.uri;
-      const info = this.resources.get(uri);
-      if (!info) {
-        throw new Error(`Resource not found: ${uri}`);
-      }
+    server.setRequestHandler(
+      ReadResourceRequestSchema,
+      async (request: ReadResourceRequest) => {
+        const uri = request.params.uri;
+        const info = this.resources.get(uri);
+        if (!info) {
+          throw new Error(`Resource not found: ${uri}`);
+        }
 
-      try {
-        const content = await info.handler(new URL(uri));
-        const finalContent = this.applyResourceCsp(content);
-        return { contents: [finalContent] };
-      } catch (error) {
-        this.log(
-          `[ERROR] Resource handler failed for ${uri}: ${
-            error instanceof Error ? error.message : String(error)
-          }`,
-        );
-        throw error;
-      }
-    });
+        try {
+          const content = await info.handler(new URL(uri));
+          const finalContent = this.applyResourceCsp(content);
+          return { contents: [finalContent] };
+        } catch (error) {
+          this.log(
+            `[ERROR] Resource handler failed for ${uri}: ${
+              error instanceof Error ? error.message : String(error)
+            }`,
+          );
+          throw error;
+        }
+      },
+    );
 
     this.resourceHandlersInstalled = true;
     this.log("Resources capability pre-declared (expectResources: true)");
@@ -342,20 +353,24 @@ export class ConcurrentMCPServer {
     });
 
     // tools/call handler (delegates to middleware pipeline)
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
-      const toolName = request.params.name;
-      const args = request.params.arguments || {};
+    server.setRequestHandler(
+      CallToolRequestSchema,
+      async (request: CallToolRequest) => {
+        const toolName = request.params.name;
+        const args = request.params.arguments || {};
 
-      let result: unknown;
-      try {
-        result = await this.executeToolCall(toolName, args);
-      } catch (error) {
-        return this.handleToolError(error, toolName);
-      }
+        let result: unknown;
+        try {
+          result = await this.executeToolCall(toolName, args);
+        } catch (error) {
+          return this.handleToolError(error, toolName);
+        }
 
-      // Serialization errors are framework bugs, not tool errors — let them propagate
-      return this.buildToolCallResult(toolName, result);
-    });
+        // Serialization errors are framework bugs, not tool errors —
+        // let them propagate
+        return this.buildToolCallResult(toolName, result);
+      },
+    );
   }
 
   /**
@@ -370,7 +385,7 @@ export class ConcurrentMCPServer {
   ): void {
     if (this.started) {
       throw new Error(
-        "[ConcurrentMCPServer] Cannot register tools after server started. " +
+        "[McpApp] Cannot register tools after server started. " +
           "Call registerTools() before start() or startHttp().",
       );
     }
@@ -403,7 +418,7 @@ export class ConcurrentMCPServer {
   registerTool(tool: MCPTool, handler: ToolHandler): void {
     if (this.started) {
       throw new Error(
-        "[ConcurrentMCPServer] Cannot register tools after server started. " +
+        "[McpApp] Cannot register tools after server started. " +
           "Call registerTool() before start() or startHttp().",
       );
     }
@@ -481,7 +496,9 @@ export class ConcurrentMCPServer {
   unregisterTool(toolName: string): boolean {
     const deleted = this.tools.delete(toolName);
     if (deleted) {
-      this.log(`Unregistered tool: ${toolName} (remaining: ${this.tools.size})`);
+      this.log(
+        `Unregistered tool: ${toolName} (remaining: ${this.tools.size})`,
+      );
     }
     return deleted;
   }
@@ -513,7 +530,7 @@ export class ConcurrentMCPServer {
   use(middleware: Middleware): this {
     if (this.started) {
       throw new Error(
-        "[ConcurrentMCPServer] Cannot add middleware after server started. " +
+        "[McpApp] Cannot add middleware after server started. " +
           "Call use() before start() or startHttp().",
       );
     }
@@ -593,7 +610,7 @@ export class ConcurrentMCPServer {
   ): Promise<MiddlewareResult> {
     if (!this.middlewareRunner) {
       throw new Error(
-        "[ConcurrentMCPServer] Pipeline not built. Call start() or startHttp() first.",
+        "[McpApp] Pipeline not built. Call start() or startHttp() first.",
       );
     }
 
@@ -698,7 +715,7 @@ export class ConcurrentMCPServer {
     // Check for duplicate
     if (this.resources.has(resource.uri)) {
       throw new Error(
-        `[ConcurrentMCPServer] Resource already registered: ${resource.uri}`,
+        `[McpApp] Resource already registered: ${resource.uri}`,
       );
     }
 
@@ -760,7 +777,7 @@ export class ConcurrentMCPServer {
 
     if (missingHandlers.length > 0) {
       throw new Error(
-        `[ConcurrentMCPServer] Missing handlers for resources:\n` +
+        `[McpApp] Missing handlers for resources:\n` +
           missingHandlers.map((uri) => `  - ${uri}`).join("\n"),
       );
     }
@@ -775,7 +792,7 @@ export class ConcurrentMCPServer {
 
     if (duplicateUris.length > 0) {
       throw new Error(
-        `[ConcurrentMCPServer] Resources already registered:\n` +
+        `[McpApp] Resources already registered:\n` +
           duplicateUris.map((uri) => `  - ${uri}`).join("\n"),
       );
     }
@@ -786,7 +803,7 @@ export class ConcurrentMCPServer {
       if (!handler) {
         // Should never happen after validation, but defensive check
         throw new Error(
-          `[ConcurrentMCPServer] Handler disappeared for ${resource.uri}`,
+          `[McpApp] Handler disappeared for ${resource.uri}`,
         );
       }
       this.registerResource(resource, handler);
@@ -808,7 +825,9 @@ export class ConcurrentMCPServer {
    */
   registerViewers(config: RegisterViewersConfig): RegisterViewersSummary {
     if (!config.prefix) {
-      throw new Error("[ConcurrentMCPServer] registerViewers: prefix is required");
+      throw new Error(
+        "[McpApp] registerViewers: prefix is required",
+      );
     }
 
     // Resolve viewer list: explicit or auto-discovered
@@ -826,7 +845,11 @@ export class ConcurrentMCPServer {
     const skipped: string[] = [];
 
     for (const viewerName of viewerNames) {
-      const distPath = resolveViewerDistPath(config.moduleUrl, viewerName, config.exists);
+      const distPath = resolveViewerDistPath(
+        config.moduleUrl,
+        viewerName,
+        config.exists,
+      );
 
       if (!distPath) {
         this.log(
@@ -856,7 +879,9 @@ export class ConcurrentMCPServer {
             text: html,
           };
           if (config.csp) {
-            (content as unknown as Record<string, unknown>)._meta = { ui: { csp: config.csp } };
+            (content as unknown as Record<string, unknown>)._meta = {
+              ui: { csp: config.csp },
+            };
           }
           return content;
         },
@@ -866,7 +891,9 @@ export class ConcurrentMCPServer {
     }
 
     if (registered.length > 0) {
-      this.log(`Registered ${registered.length} viewer(s): ${registered.join(", ")}`);
+      this.log(
+        `Registered ${registered.length} viewer(s): ${registered.join(", ")}`,
+      );
     }
 
     return { registered, skipped };
@@ -911,8 +938,8 @@ export class ConcurrentMCPServer {
    */
   private cleanupSessions(): void {
     const now = Date.now();
-    const ttlWithGrace = ConcurrentMCPServer.SESSION_TTL_MS +
-      ConcurrentMCPServer.SESSION_GRACE_PERIOD_MS;
+    const ttlWithGrace = McpApp.SESSION_TTL_MS +
+      McpApp.SESSION_GRACE_PERIOD_MS;
     let cleaned = 0;
     for (const [sessionId, session] of this.sessions) {
       if (now - session.lastActivity > ttlWithGrace) {
@@ -998,7 +1025,7 @@ export class ConcurrentMCPServer {
    *
    * @example
    * ```typescript
-   * const server = new ConcurrentMCPServer({ name: "my-server", version: "1.0.0" });
+   * const server = new McpApp({ name: "my-server", version: "1.0.0" });
    * server.registerTools(tools, handlers);
    * server.registerResource(resource, handler);
    *
@@ -1038,7 +1065,7 @@ export class ConcurrentMCPServer {
     const requireAuth = options.requireAuth ?? false;
     if (requireAuth && !this.authProvider) {
       throw new Error(
-        "[ConcurrentMCPServer] HTTP auth is required (requireAuth=true) but no auth provider is configured.",
+        "[McpApp] HTTP auth is required (requireAuth=true) but no auth provider is configured.",
       );
     }
     if (!this.authProvider && !requireAuth) {
@@ -1411,9 +1438,9 @@ export class ConcurrentMCPServer {
           }
 
           // Guard against session exhaustion
-          if (this.sessions.size >= ConcurrentMCPServer.MAX_SESSIONS) {
+          if (this.sessions.size >= McpApp.MAX_SESSIONS) {
             this.cleanupSessions();
-            if (this.sessions.size >= ConcurrentMCPServer.MAX_SESSIONS) {
+            if (this.sessions.size >= McpApp.MAX_SESSIONS) {
               return c.json({
                 jsonrpc: "2.0",
                 id,
@@ -1442,7 +1469,9 @@ export class ConcurrentMCPServer {
                   name: this.options.name,
                   version: this.options.version,
                 },
-                ...(this.options.instructions ? { instructions: this.options.instructions } : {}),
+                ...(this.options.instructions
+                  ? { instructions: this.options.instructions }
+                  : {}),
               },
             }),
             {
@@ -1513,7 +1542,9 @@ export class ConcurrentMCPServer {
             } catch (rethrown) {
               this.log(
                 `Error executing tool ${toolName}: ${
-                  rethrown instanceof Error ? rethrown.message : String(rethrown)
+                  rethrown instanceof Error
+                    ? rethrown.message
+                    : String(rethrown)
                 }`,
               );
               const errorMessage = rethrown instanceof Error
@@ -1663,6 +1694,37 @@ export class ConcurrentMCPServer {
     // deno-lint-ignore no-explicit-any
     app.post("/", handleMcpPost as any);
 
+    // Embedded mode: skip serve(), surface the Hono fetch handler to the
+    // caller and let them mount it inside their own framework (Fresh, Hono,
+    // Express, etc.). The session cleanup timer + post-init still runs so
+    // SSE clients and sessions are managed identically to the serve() path.
+    if (options.embedded) {
+      if (!options.embeddedHandlerCallback) {
+        throw new Error(
+          "[McpApp] embedded=true requires embeddedHandlerCallback",
+        );
+      }
+      // deno-lint-ignore no-explicit-any
+      options.embeddedHandlerCallback(app.fetch as any);
+      this.started = true;
+      this.sessionCleanupTimer = setInterval(
+        () => this.cleanupSessions(),
+        McpApp.SESSION_CLEANUP_INTERVAL_MS,
+      );
+      unrefTimer(this.sessionCleanupTimer as unknown as number);
+      this.log(
+        `HTTP handler ready (embedded mode — no port bound, max concurrent: ${
+          this.options.maxConcurrent ?? 10
+        })`,
+      );
+      return {
+        shutdown: async () => {
+          await this.stop();
+        },
+        addr: { hostname: "embedded", port: 0 },
+      };
+    }
+
     // Start server
     this.httpServer = serve(
       {
@@ -1683,7 +1745,7 @@ export class ConcurrentMCPServer {
     // Start session cleanup timer (prevents unbounded memory growth)
     this.sessionCleanupTimer = setInterval(
       () => this.cleanupSessions(),
-      ConcurrentMCPServer.SESSION_CLEANUP_INTERVAL_MS,
+      McpApp.SESSION_CLEANUP_INTERVAL_MS,
     );
     // Don't block Deno from exiting because of cleanup timer
     unrefTimer(this.sessionCleanupTimer as unknown as number);
@@ -1714,6 +1776,67 @@ export class ConcurrentMCPServer {
     };
   }
 
+  /**
+   * Build the HTTP middleware stack and return its fetch handler without
+   * binding a port. Use this when you want to mount the MCP HTTP layer
+   * inside another HTTP framework (Fresh, Hono, Express, Cloudflare Workers,
+   * etc.) instead of giving up port ownership to {@link startHttp}.
+   *
+   * The returned handler accepts a Web Standard {@link Request} and returns
+   * a Web Standard {@link Response}. It exposes the same routes as
+   * {@link startHttp}: `POST /mcp`, `GET /mcp` (SSE), `GET /health`,
+   * `GET /metrics`, and `GET /.well-known/oauth-protected-resource`.
+   *
+   * Auth, multi-tenant middleware, scope checks, and rate limiting are all
+   * applied identically. The session cleanup timer and OTel hooks are
+   * started, so the server is fully live after this returns — just without
+   * its own listening socket.
+   *
+   * Multi-tenant SaaS pattern: cache one `McpApp` per tenant
+   * and call `getFetchHandler()` once per server, then dispatch each
+   * inbound request to the right cached handler from your framework's
+   * routing layer.
+   *
+   * @example
+   * ```typescript
+   * // In a Fresh route at routes/mcp/[...path].tsx
+   * const server = new McpApp({ name: "my-mcp", version: "1.0.0" });
+   * server.registerTools(tools, handlers);
+   * const handler = await server.getFetchHandler({
+   *   requireAuth: true,
+   *   auth: { provider: myAuthProvider },
+   * });
+   * // Later, in your route handler:
+   * return await handler(ctx.req);
+   * ```
+   *
+   * @param options - Same as {@link startHttp}, minus `port`/`hostname`/`onListen`.
+   * @returns A Web Standard fetch handler.
+   */
+  async getFetchHandler(
+    options: Omit<HttpServerOptions, "port" | "hostname" | "onListen"> = {},
+  ): Promise<FetchHandler> {
+    let captured: FetchHandler | null = null;
+    await this.startHttp({
+      // port/hostname are unused in embedded mode but the type requires them.
+      // Pass sentinel values that would never bind even if used.
+      port: 0,
+      ...options,
+      embedded: true,
+      embeddedHandlerCallback: (handler) => {
+        captured = handler;
+      },
+    });
+    if (!captured) {
+      // Defensive: startHttp should always invoke the callback synchronously
+      // before returning. If it didn't, something is structurally wrong.
+      throw new Error(
+        "[McpApp] getFetchHandler: embedded callback was not invoked",
+      );
+    }
+    return captured;
+  }
+
   /**
    * Send a JSON-RPC message to all SSE clients in a session
    * Used for server-initiated notifications and requests
@@ -1790,6 +1913,43 @@ export class ConcurrentMCPServer {
     return this.samplingBridge;
   }
 
+  /**
+   * Read the MCP Apps capability advertised by the connected client.
+   *
+   * Returns the capability object (possibly empty `{}`) when the client
+   * advertised support for MCP Apps via its `extensions` capability,
+   * or `undefined` when:
+   * - the client did not send capabilities yet (called before initialize)
+   * - the client did not advertise the MCP Apps extension at all
+   * - the client sent a malformed extension value
+   *
+   * Use this from a tool handler to decide whether to return a UI
+   * resource (`_meta.ui`) or a text-only fallback. Hosts that don't
+   * support MCP Apps will silently drop the `_meta.ui` field, but
+   * checking explicitly lets you serve a richer text response when
+   * the UI path isn't available.
+   *
+   * @returns MCP Apps capability or `undefined` if not supported.
+   *
+   * @example
+   * ```typescript
+   * const cap = app.getClientMcpAppsCapability();
+   * if (cap?.mimeTypes?.includes(MCP_APP_MIME_TYPE)) {
+   *   return {
+   *     content: [{ type: "text", text: summary }],
+   *     _meta: { ui: { resourceUri: "ui://my-app/dashboard" } },
+   *   };
+   * }
+   * return { content: [{ type: "text", text: detailedTextFallback }] };
+   * ```
+   *
+   * @see {@link getMcpAppsCapability} for the standalone reader
+   * @see {@link MCP_APPS_EXTENSION_ID} for the extension key
+   */
+  getClientMcpAppsCapability(): McpAppsClientCapability | undefined {
+    return getMcpAppsCapability(this.mcpServer.server.getClientCapabilities());
+  }
+
   /**
    * Get queue metrics for monitoring
    */
@@ -1948,7 +2108,12 @@ export class ConcurrentMCPServer {
    * without re-wrapping. This supports proxy/gateway patterns.
    */
   // deno-lint-ignore no-explicit-any
-  private isPreformattedResult(result: unknown): result is { content: Array<{ type: string; text: string }>; _meta?: Record<string, unknown> } {
+  private isPreformattedResult(
+    result: unknown,
+  ): result is {
+    content: Array<{ type: string; text: string }>;
+    _meta?: Record<string, unknown>;
+  } {
     if (!result || typeof result !== "object") return false;
     const obj = result as Record<string, unknown>;
     return Array.isArray(obj.content) &&
@@ -2055,7 +2220,9 @@ export class ConcurrentMCPServer {
       } catch (mapperError) {
         this.log(
           `toolErrorMapper threw for tool ${toolName}: ${
-            mapperError instanceof Error ? mapperError.message : String(mapperError)
+            mapperError instanceof Error
+              ? mapperError.message
+              : String(mapperError)
           } (original error: ${
             error instanceof Error ? error.message : String(error)
           })`,
@@ -2114,7 +2281,11 @@ export interface RegisterViewersConfig {
   humanName?: (viewerName: string) => string;
   /** MCP Apps CSP — declares external domains the viewer needs (tiles, APIs, CDNs).
    *  Uses McpUiCsp from @casys/mcp-compose (resourceDomains, connectDomains). */
-  csp?: { resourceDomains?: string[]; connectDomains?: string[]; frameDomains?: string[] };
+  csp?: {
+    resourceDomains?: string[];
+    connectDomains?: string[];
+    frameDomains?: string[];
+  };
 }
 
 /** Summary returned by registerViewers() */

package/src/middleware/mod.ts

@@ -1,5 +1,5 @@
 /**
- * Middleware module for ConcurrentMCPServer.
+ * Middleware module for McpApp.
  *
  * @module lib/server/middleware
  */

package/src/middleware/rate-limit.ts

@@ -1,7 +1,7 @@
 /**
  * Rate limiting middleware.
  *
- * Extracted from ConcurrentMCPServer's inline rate limit logic.
+ * Extracted from McpApp's inline rate limit logic.
  *
  * @module lib/server/middleware/rate-limit
  */

package/src/middleware/types.ts

@@ -1,5 +1,5 @@
 /**
- * Middleware pipeline types for ConcurrentMCPServer.
+ * Middleware pipeline types for McpApp.
  *
  * Provides an onion-model middleware system (similar to Koa/Hono)
  * where each middleware wraps the next, enabling before/after logic.

package/src/observability/metrics.ts

@@ -2,7 +2,7 @@
  * Server Metrics Collector for @casys/mcp-server
  *
  * In-memory counters, histograms, and gauges with Prometheus text format export.
- * Designed to be embedded in ConcurrentMCPServer — no external dependencies.
+ * Designed to be embedded in McpApp — no external dependencies.
  *
  * @module lib/server/observability/metrics
  */