@casys/mcp-server 0.11.0 → 0.13.0

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
  */

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

@@ -45,9 +45,9 @@ export interface RateLimitContext {
 }
 
 /**
- * Configuration options for ConcurrentMCPServer
+ * Configuration options for McpApp
  */
-export interface ConcurrentServerOptions {
+export interface McpAppOptions {
   /** Server name (shown in MCP protocol) */
   name: string;
 
@@ -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)
@@ -416,8 +485,15 @@ export interface HttpRateLimitOptions {
 /**
  * Options for starting an HTTP server
  */
+// Re-exported from the runtime port so consumers can import the canonical
+// fetch handler type from the same module as HttpServerOptions.
+export type { FetchHandler } from "./runtime/types.js";
+import type { FetchHandler } from "./runtime/types.js";
+
 export interface HttpServerOptions {
-  /** Port to listen on */
+  /**
+   * Port to listen on. Ignored when {@link embedded} is `true`.
+   */
   port: number;
 
   /** Hostname to bind to (default: "0.0.0.0") */
@@ -463,6 +539,27 @@ export interface HttpServerOptions {
    * @param info - Server address info
    */
   onListen?: (info: { hostname: string; port: number }) => void;
+
+  /**
+   * Embedded mode: skip binding a port and instead surface the Hono fetch
+   * handler via the {@link embeddedHandlerCallback} option. Used by
+   * {@link McpApp.getFetchHandler} so consumers (Fresh, Hono,
+   * Express, etc.) can mount the MCP HTTP stack inside their own server
+   * without giving up port ownership.
+   *
+   * When `true`, `port`, `hostname`, and `onListen` are ignored.
+   */
+  embedded?: boolean;
+
+  /**
+   * Receives the Hono fetch handler when running in embedded mode.
+   * Required when {@link embedded} is `true`. Called exactly once,
+   * synchronously, before `startHttp` returns.
+   *
+   * Most consumers should use {@link McpApp.getFetchHandler}
+   * instead of setting this directly.
+   */
+  embeddedHandlerCallback?: (handler: FetchHandler) => void;
 }
 
 /**

package/src/ui/viewer-utils.ts

@@ -8,7 +8,13 @@
  */
 
 /** Directories to skip during auto-discovery */
-const SKIP_DIRS = new Set(["shared", "dist", "node_modules", ".cache", ".vite"]);
+const SKIP_DIRS = new Set([
+  "shared",
+  "dist",
+  "node_modules",
+  ".cache",
+  ".vite",
+]);
 
 /**
  * Convert a file:// URL to a filesystem path.