@casys/mcp-server 0.11.0 → 0.13.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,18 +47,20 @@ 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,
   MCPResource,
   MCPTool,
   QueueMetrics,
   ResourceContent,
   ResourceHandler,
+  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 { 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";
@@ -156,7 +160,7 @@ async function readBodyWithLimit(
 }
 
 /**
- * ConcurrentMCPServer provides a high-performance MCP server
+ * McpApp provides a high-performance MCP server
  *
  * Features:
  * - Wraps official @modelcontextprotocol/sdk
@@ -168,7 +172,7 @@ async function readBodyWithLimit(
  *
  * @example
  * ```typescript
- * const server = new ConcurrentMCPServer({
+ * const server = new McpApp({
  *   name: "my-server",
  *   version: "1.0.0",
  *   maxConcurrent: 5,
@@ -179,7 +183,7 @@ async function readBodyWithLimit(
  * await server.start();
  * ```
  */
-export class ConcurrentMCPServer {
+export class McpApp {
   private mcpServer: McpServer;
   private requestQueue: RequestQueue;
   private rateLimiter: RateLimiter | null = null;
@@ -187,7 +191,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;
 
@@ -221,7 +225,7 @@ export class ConcurrentMCPServer {
     windowMs: 60_000,
   });
 
-  constructor(options: ConcurrentServerOptions) {
+  constructor(options: McpAppOptions) {
     this.options = options;
 
     // Create SDK MCP server
@@ -234,6 +238,7 @@ export class ConcurrentMCPServer {
         capabilities: {
           tools: {},
         },
+        instructions: options.instructions,
       },
     );
 
@@ -298,26 +303,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)");
@@ -336,59 +344,28 @@ export class ConcurrentMCPServer {
 
     // tools/list handler
     server.setRequestHandler(ListToolsRequestSchema, () => {
-      return {
-        tools: Array.from(this.tools.values()).map((t) => ({
-          name: t.name,
-          description: t.description,
-          inputSchema: t.inputSchema,
-          _meta: t._meta, // Always include, even if undefined (MCP Apps discovery)
-        })),
-      };
+      return { tools: this.buildToolListing() };
     });
 
     // tools/call handler (delegates to middleware pipeline)
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
-      const toolName = request.params.name;
-      const args = request.params.arguments || {};
-
-      try {
-        const result = await this.executeToolCall(toolName, args);
+    server.setRequestHandler(
+      CallToolRequestSchema,
+      async (request: CallToolRequest) => {
+        const toolName = request.params.name;
+        const args = request.params.arguments || {};
 
-        // If handler returns a pre-formatted MCP result (has content array),
-        // pass it through without re-wrapping. This supports proxy/gateway
-        // patterns where the handler builds the complete response.
-        if (this.isPreformattedResult(result)) {
-          return result;
+        let result: unknown;
+        try {
+          result = await this.executeToolCall(toolName, args);
+        } catch (error) {
+          return this.handleToolError(error, toolName);
         }
 
-        // Format response according to MCP protocol
-        const tool = this.tools.get(toolName);
-        const response: {
-          content: Array<{ type: "text"; text: string }>;
-          _meta?: Record<string, unknown>;
-        } = {
-          content: [
-            {
-              type: "text",
-              text: typeof result === "string"
-                ? result
-                : JSON.stringify(result, null, 2),
-            },
-          ],
-        };
-        if (tool?._meta) {
-          response._meta = tool._meta as Record<string, unknown>;
-        }
-        return response;
-      } catch (error) {
-        this.log(
-          `Error executing tool ${request.params.name}: ${
-            error instanceof Error ? error.message : String(error)
-          }`,
-        );
-        throw error;
-      }
-    });
+        // Serialization errors are framework bugs, not tool errors —
+        // let them propagate
+        return this.buildToolCallResult(toolName, result);
+      },
+    );
   }
 
   /**
@@ -403,7 +380,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().",
       );
     }
@@ -436,7 +413,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().",
       );
     }
@@ -478,6 +455,30 @@ export class ConcurrentMCPServer {
     this.log(`Live-registered tool: ${tool.name} (total: ${this.tools.size})`);
   }
 
+  /**
+   * Register a tool that is only visible to the MCP App (UI layer),
+   * not to the model via tools/list.
+   *
+   * Equivalent to registerTool() with _meta.ui.visibility: ["app"].
+   * The tool is still callable via tools/call if the caller knows its name.
+   *
+   * @param tool - Tool definition
+   * @param handler - Tool handler function
+   */
+  registerAppOnlyTool(tool: MCPTool, handler: ToolHandler): void {
+    const merged: MCPTool = {
+      ...tool,
+      _meta: {
+        ...tool._meta,
+        ui: {
+          ...tool._meta?.ui,
+          visibility: ["app"],
+        },
+      } as MCPTool["_meta"],
+    };
+    this.registerTool(merged, handler);
+  }
+
   /**
    * Unregister a tool (removes it from tools/list and tools/call).
    *
@@ -490,7 +491,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;
   }
@@ -522,7 +525,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().",
       );
     }
@@ -602,7 +605,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.",
       );
     }
 
@@ -707,7 +710,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}`,
       );
     }
 
@@ -769,7 +772,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"),
       );
     }
@@ -784,7 +787,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"),
       );
     }
@@ -795,7 +798,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);
@@ -817,7 +820,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
@@ -835,7 +840,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(
@@ -859,7 +868,17 @@ export class ConcurrentMCPServer {
         },
         async () => {
           const html = await Promise.resolve(readFile(currentDistPath));
-          return { uri: resourceUri, mimeType: MCP_APP_MIME_TYPE, text: html };
+          const content: import("./types.js").ResourceContent = {
+            uri: resourceUri,
+            mimeType: MCP_APP_MIME_TYPE,
+            text: html,
+          };
+          if (config.csp) {
+            (content as unknown as Record<string, unknown>)._meta = {
+              ui: { csp: config.csp },
+            };
+          }
+          return content;
         },
       );
 
@@ -867,7 +886,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 };
@@ -912,8 +933,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) {
@@ -999,7 +1020,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);
    *
@@ -1039,7 +1060,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) {
@@ -1412,9 +1433,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,
@@ -1443,6 +1464,9 @@ export class ConcurrentMCPServer {
                   name: this.options.name,
                   version: this.options.version,
                 },
+                ...(this.options.instructions
+                  ? { instructions: this.options.instructions }
+                  : {}),
               },
             }),
             {
@@ -1480,29 +1504,10 @@ export class ConcurrentMCPServer {
               c.req.raw,
               reqSessionId,
             );
-
-            // Pre-formatted result: pass through as-is
-            if (this.isPreformattedResult(result)) {
-              return c.json({
-                jsonrpc: "2.0",
-                id,
-                result,
-              });
-            }
-
-            const tool = this.tools.get(toolName);
             return c.json({
               jsonrpc: "2.0",
               id,
-              result: {
-                content: [{
-                  type: "text",
-                  text: typeof result === "string"
-                    ? result
-                    : JSON.stringify(result, null, 2),
-                }],
-                ...(tool?._meta && { _meta: tool._meta }),
-              },
+              result: this.buildToolCallResult(toolName, result),
             });
           } catch (error) {
             // Handle AuthError with proper HTTP status codes
@@ -1521,24 +1526,36 @@ export class ConcurrentMCPServer {
               }
             }
 
-            this.log(
-              `Error executing tool ${toolName}: ${
-                error instanceof Error ? error.message : String(error)
-              }`,
-            );
-            const errorMessage = error instanceof Error
-              ? error.message
-              : "Tool execution failed";
-            const errorCode = errorMessage.startsWith("Unknown tool")
-              ? -32602
-              : errorMessage.startsWith("Rate limit")
-              ? -32000
-              : -32603;
-            return c.json({
-              jsonrpc: "2.0",
-              id,
-              error: { code: errorCode, message: errorMessage },
-            });
+            // Delegate to centralized error handler
+            try {
+              const isErrorResult = this.handleToolError(error, toolName);
+              return c.json({
+                jsonrpc: "2.0",
+                id,
+                result: isErrorResult,
+              });
+            } catch (rethrown) {
+              this.log(
+                `Error executing tool ${toolName}: ${
+                  rethrown instanceof Error
+                    ? rethrown.message
+                    : String(rethrown)
+                }`,
+              );
+              const errorMessage = rethrown instanceof Error
+                ? rethrown.message
+                : "Tool execution failed";
+              const errorCode = errorMessage.startsWith("Unknown tool")
+                ? -32602
+                : errorMessage.startsWith("Rate limit")
+                ? -32000
+                : -32603;
+              return c.json({
+                jsonrpc: "2.0",
+                id,
+                error: { code: errorCode, message: errorMessage },
+              });
+            }
           }
         }
 
@@ -1552,14 +1569,7 @@ export class ConcurrentMCPServer {
           return c.json({
             jsonrpc: "2.0",
             id,
-            result: {
-              tools: Array.from(this.tools.values()).map((t) => ({
-                name: t.name,
-                description: t.description,
-                inputSchema: t.inputSchema,
-                _meta: t._meta,
-              })),
-            },
+            result: { tools: this.buildToolListing() },
           });
         }
 
@@ -1679,6 +1689,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(
       {
@@ -1699,7 +1740,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);
@@ -1730,6 +1771,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
@@ -1964,7 +2066,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) &&
@@ -1975,6 +2082,129 @@ export class ConcurrentMCPServer {
       "text" in obj.content[0];
   }
 
+  /**
+   * Build the tools/list response, filtering out app-only tools
+   * and passing through outputSchema/annotations when defined.
+   */
+  private buildToolListing(): Array<Record<string, unknown>> {
+    return Array.from(this.tools.values())
+      .filter((t) => {
+        const vis = t._meta?.ui?.visibility;
+        if (vis !== undefined && !vis.includes("model")) return false;
+        return true;
+      })
+      .map((t) => {
+        const entry: Record<string, unknown> = {
+          name: t.name,
+          description: t.description,
+          inputSchema: t.inputSchema,
+          _meta: t._meta,
+        };
+        if (t.outputSchema !== undefined) entry.outputSchema = t.outputSchema;
+        if (t.annotations !== undefined) entry.annotations = t.annotations;
+        return entry;
+      });
+  }
+
+  /**
+   * Check if a handler result is a StructuredToolResult
+   * (has content as string + structuredContent as object).
+   */
+  private isStructuredToolResult(
+    result: unknown,
+  ): result is StructuredToolResult {
+    if (!result || typeof result !== "object") return false;
+    const obj = result as Record<string, unknown>;
+    return (
+      typeof obj.content === "string" &&
+      obj.structuredContent !== null &&
+      obj.structuredContent !== undefined &&
+      typeof obj.structuredContent === "object" &&
+      !Array.isArray(obj.structuredContent)
+    );
+  }
+
+  /**
+   * Build a CallToolResult from the handler's return value.
+   * Priority: preformatted > structuredToolResult > plain value.
+   */
+  private buildToolCallResult(
+    toolName: string,
+    result: unknown,
+  ): Record<string, unknown> {
+    // Proxy/gateway pattern — pass through as-is
+    if (this.isPreformattedResult(result)) {
+      return result as Record<string, unknown>;
+    }
+
+    const tool = this.tools.get(toolName);
+
+    // StructuredToolResult: separate content (for LLM) and structuredContent (for viewer)
+    if (this.isStructuredToolResult(result)) {
+      const r: Record<string, unknown> = {
+        content: [{ type: "text", text: result.content }],
+        structuredContent: result.structuredContent,
+      };
+      if (tool?._meta) r._meta = tool._meta;
+      return r;
+    }
+
+    // Plain value: JSON-stringify into content[0].text
+    const r: Record<string, unknown> = {
+      content: [{
+        type: "text",
+        text: typeof result === "string"
+          ? result
+          : JSON.stringify(result, null, 2),
+      }],
+    };
+    if (tool?._meta) r._meta = tool._meta;
+    return r;
+  }
+
+  /**
+   * Handle a tool execution error using the configured toolErrorMapper.
+   * Returns an isError result if the mapper handles it, otherwise rethrows.
+   */
+  private handleToolError(
+    error: unknown,
+    toolName: string,
+  ): Record<string, unknown> {
+    const mapper = this.options.toolErrorMapper;
+    if (mapper) {
+      let msg: string | null;
+      try {
+        msg = mapper(error, toolName);
+      } catch (mapperError) {
+        this.log(
+          `toolErrorMapper threw for tool ${toolName}: ${
+            mapperError instanceof Error
+              ? mapperError.message
+              : String(mapperError)
+          } (original error: ${
+            error instanceof Error ? error.message : String(error)
+          })`,
+        );
+        // Fall through to rethrow original error
+        msg = null;
+      }
+      if (msg !== null) {
+        this.log(`Tool ${toolName} returned business error: ${msg}`);
+        return {
+          content: [{ type: "text", text: msg }],
+          isError: true,
+        };
+      }
+    }
+    // No mapper or mapper returned null → rethrow
+    this.log(
+      `Error executing tool ${toolName}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+    throw error;
+  }
+
   /**
    * Log message using custom logger or stderr
    */
@@ -2007,6 +2237,13 @@ export interface RegisterViewersConfig {
   } & DiscoverViewersFS;
   /** Custom function to generate human-readable names. Default: kebab-to-Title. */
   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[];
+  };
 }
 
 /** Summary returned by registerViewers() */