@casys/mcp-server 0.11.0 → 0.12.0

package/mod.ts

@@ -71,6 +71,7 @@ export type {
   MCPTool,
   MCPToolMeta,
   McpUiToolMeta,
+  ToolAnnotations,
   QueueMetrics,
   RateLimitContext,
   RateLimitOptions,
@@ -79,6 +80,8 @@ export type {
   SamplingClient,
   SamplingParams,
   SamplingResult,
+  StructuredToolResult,
+  ToolErrorMapper,
   ToolHandler,
 } from "./src/types.js";
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@casys/mcp-server",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Production-ready MCP server framework with concurrency control, auth, and observability",
   "type": "module",
   "main": "mod.ts",

package/src/concurrent-server.ts

@@ -53,6 +53,7 @@ import type {
   QueueMetrics,
   ResourceContent,
   ResourceHandler,
+  StructuredToolResult,
   ToolHandler,
 } from "./types.js";
 import { MCP_APP_MIME_TYPE, MCP_APP_URI_SCHEME } from "./types.js";
@@ -234,6 +235,7 @@ export class ConcurrentMCPServer {
         capabilities: {
           tools: {},
         },
+        instructions: options.instructions,
       },
     );
 
@@ -336,14 +338,7 @@ 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)
@@ -351,43 +346,15 @@ export class ConcurrentMCPServer {
       const toolName = request.params.name;
       const args = request.params.arguments || {};
 
+      let result: unknown;
       try {
-        const result = await this.executeToolCall(toolName, args);
-
-        // 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;
-        }
-
-        // 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;
+        result = await this.executeToolCall(toolName, args);
       } catch (error) {
-        this.log(
-          `Error executing tool ${request.params.name}: ${
-            error instanceof Error ? error.message : String(error)
-          }`,
-        );
-        throw error;
+        return this.handleToolError(error, toolName);
       }
+
+      // Serialization errors are framework bugs, not tool errors — let them propagate
+      return this.buildToolCallResult(toolName, result);
     });
   }
 
@@ -478,6 +445,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).
    *
@@ -859,7 +850,15 @@ 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;
         },
       );
 
@@ -1443,6 +1442,7 @@ export class ConcurrentMCPServer {
                   name: this.options.name,
                   version: this.options.version,
                 },
+                ...(this.options.instructions ? { instructions: this.options.instructions } : {}),
               },
             }),
             {
@@ -1480,29 +1480,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 +1502,34 @@ 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 +1543,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() },
           });
         }
 
@@ -1975,6 +1959,127 @@ 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 +2112,9 @@ 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() */

package/src/security/csp.ts

@@ -13,6 +13,8 @@ export interface CspOptions {
   readonly scriptSources?: readonly string[];
   /** Additional allowed connect sources (e.g. WebSocket endpoints). */
   readonly connectSources?: readonly string[];
+  /** Additional allowed image sources (e.g. tile servers). */
+  readonly imgSources?: readonly string[];
   /** Additional allowed frame ancestors. */
   readonly frameAncestors?: readonly string[];
   /**
@@ -49,7 +51,7 @@ export function buildCspHeader(options: CspOptions = {}): string {
     `default-src 'none'`,
     `script-src ${scriptSrc}`,
     `style-src 'self'${inlineDirective}`,
-    `img-src 'self' data:`,
+    `img-src 'self' data: ${(options.imgSources ?? []).join(" ")}`.trim(),
     `font-src 'self'`,
     `connect-src ${connectSrc}`,
     `frame-ancestors ${frameAncestors}`,

package/src/types.ts

@@ -78,12 +78,29 @@ export interface ConcurrentServerOptions {
   /** Enable sampling support for agentic tools (default: false) */
   enableSampling?: boolean;
 
+  /**
+   * Instructions for the LLM on how to use this server's tools.
+   * Sent in the MCP initialize response. The LLM sees this before any tool call.
+   */
+  instructions?: string;
+
   /** Sampling client implementation (required if enableSampling is true) */
   samplingClient?: SamplingClient;
 
   /** Custom logger function (default: console.error) */
   logger?: (msg: string) => void;
 
+  /**
+   * Custom error handler for tool execution errors.
+   *
+   * When set, errors thrown by tool handlers are passed to this function.
+   * Return a message string to produce `{ content: [{type:"text", text: msg}], isError: true }`
+   * instead of re-throwing. Return null to rethrow as a JSON-RPC error.
+   *
+   * Default: undefined (all errors are re-thrown, existing behaviour).
+   */
+  toolErrorMapper?: ToolErrorMapper;
+
   /**
    * OAuth2/Bearer authentication configuration.
    * When provided, HTTP requests require a valid Bearer token.
@@ -238,6 +255,23 @@ export const MCP_APP_URI_SCHEME = "ui:" as const;
 // MCP Tool Types
 // ============================================
 
+/**
+ * Behavioural hints for model clients (MCP SDK 1.27 ToolAnnotations).
+ * Passed through in tools/list so hosts can adapt their UI accordingly.
+ */
+export interface ToolAnnotations {
+  /** Short human-readable title, may differ from tool name */
+  title?: string;
+  /** If true, tool has no side-effects and is safe to call speculatively */
+  readOnlyHint?: boolean;
+  /** If true, executing may produce irreversible effects */
+  destructiveHint?: boolean;
+  /** If true, repeated calls with same args produce same result */
+  idempotentHint?: boolean;
+  /** If true, tool may interact with entities outside the MCP system */
+  openWorldHint?: boolean;
+}
+
 /**
  * MCP Tool definition (compatible with MCP protocol)
  */
@@ -251,6 +285,15 @@ export interface MCPTool {
   /** JSON Schema for tool input */
   inputSchema: Record<string, unknown>;
 
+  /**
+   * JSON Schema for the tool's structured output (MCP SDK 1.27).
+   * Passed through in tools/list so hosts can validate tool results.
+   */
+  outputSchema?: Record<string, unknown>;
+
+  /** Behavioural hints passed to model clients */
+  annotations?: ToolAnnotations;
+
   /**
    * Tool metadata including UI configuration for MCP Apps
    * @see McpUiToolMeta
@@ -289,6 +332,32 @@ export type ToolHandler = (
   args: Record<string, unknown>,
 ) => Promise<unknown> | unknown;
 
+/**
+ * Structured tool result: separates the LLM text summary (content)
+ * from the machine-readable payload (structuredContent).
+ *
+ * When a ToolHandler returns this shape, the framework produces a
+ * CallToolResult with both `content` and `structuredContent` set,
+ * keeping heavy data out of the LLM context.
+ */
+export interface StructuredToolResult {
+  /** Human-readable summary shown in content[0].text */
+  content: string;
+  /** Structured data conforming to the tool's outputSchema */
+  structuredContent: Record<string, unknown>;
+}
+
+/**
+ * Maps a thrown error to either a business error result (isError: true)
+ * or signals that the error should be re-thrown as a JSON-RPC error.
+ *
+ * @returns A message string to produce `{ isError: true }`, or null to rethrow.
+ */
+export type ToolErrorMapper = (
+  error: unknown,
+  toolName: string,
+) => string | null;
+
 /**
  * Sampling client interface for bidirectional LLM delegation
  * Compatible with the agentic sampling protocol (SEP-1577)