modality-mcp-kit 1.1.3 → 1.2.0

package/dist/FastHonoMcp.js

@@ -27,7 +27,9 @@ import { ModalityFastMCP } from "modality-mcp-kit";
 import { JSONRPCManager, getLoggerInstance, } from "modality-kit";
 import { sseNotification, sseError, SSE_HEADERS, createSSEStream, } from "./sse-wrapper.js";
 import { McpSessionManager } from "./McpSessionManager.js";
+import { handleToolCall } from "./handlers/tools-call-handler.js";
 const defaultMcpPath = "/mcp";
+const mcpSchemaVersion = "2025-11-25";
 // Initialize FastMCP instance for internal use (NO SERVER)
 export class FastHonoMcp extends ModalityFastMCP {
     logger;
@@ -114,7 +116,7 @@ export class FastHonoMcp extends ModalityFastMCP {
                         writer.send(result);
                     }, headers);
                 }
-                return c.json({ error: `${url.pathname} endpoint not implemented` }, 501);
+                return c.json({ error: `Use ${this.mcpPath} for MCP requests` }, 400);
             }
             catch (error) {
                 this.logger.error(`FastHonoMcp (${url.pathname}) Middleware Error`, error);
@@ -154,7 +156,7 @@ function createJsonRpcManager(middleware) {
             }
             // Return valid InitializeResult
             return {
-                protocolVersion: "2025-11-25",
+                protocolVersion: mcpSchemaVersion,
                 capabilities: {
                     tools: { listChanged: true },
                     ...(mcpPrompts.length > 0 && { prompts: { listChanged: true } }),
@@ -183,20 +185,7 @@ function createJsonRpcManager(middleware) {
     });
     jsonrpc.registerMethod("tools/call", {
         async handler(params) {
-            const { ERROR_METHOD_NOT_FOUND } = await import("modality-kit");
-            const { name, arguments: args } = params;
-            const tool = mcpTools.find((t) => t.name === name);
-            if (!tool) {
-                throw new ERROR_METHOD_NOT_FOUND(`Tool not found: ${name}`);
-            }
-            return {
-                content: [
-                    {
-                        text: await tool.execute(args),
-                        type: "text",
-                    },
-                ],
-            };
+            return handleToolCall(params, mcpTools);
         },
     });
     jsonrpc.registerMethod("prompts/list", {

package/dist/handlers/tools-call-handler.js

@@ -0,0 +1,41 @@
+/**
+ * Tools/Call Handler
+ *
+ * Independent MCP JSON-RPC handler for tools/call method
+ * Manages tool lookup, execution, result normalization, and error handling
+ *
+ * Features:
+ * - Type-safe tool lookup with proper error handling
+ * - Rich result support (multiple content types, structured data, errors)
+ * - Exception-to-isError conversion
+ * - Backward compatible with string-returning tools
+ */
+import { normalizeToolResult, normalizeToolError, } from "../utils/normalize-tool-result.js";
+/**
+ * Handles the tools/call JSON-RPC method
+ *
+ * @param params - Tool call parameters (name and arguments)
+ * @param mcpTools - List of available tools
+ * @returns CallToolResult with content, optional structured data, and error flag
+ * @throws ERROR_METHOD_NOT_FOUND if tool not found (converted to isError in caller)
+ */
+export async function handleToolCall(params, mcpTools) {
+    const { ERROR_METHOD_NOT_FOUND } = await import("modality-kit");
+    const { name, arguments: args } = params;
+    // Find the requested tool
+    const tool = mcpTools.find((t) => t.name === name);
+    if (!tool) {
+        throw new ERROR_METHOD_NOT_FOUND(`Tool not found: ${name}`);
+    }
+    try {
+        // Execute the tool with provided arguments
+        const result = await tool.execute(args || {});
+        // Normalize result to CallToolResult format
+        return normalizeToolResult(result);
+    }
+    catch (error) {
+        // Convert exceptions to isError response
+        // This ensures errors don't break the protocol, following MCP spec guidance
+        return normalizeToolError(error);
+    }
+}

package/dist/types/handlers/tools-call-handler.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Tools/Call Handler
+ *
+ * Independent MCP JSON-RPC handler for tools/call method
+ * Manages tool lookup, execution, result normalization, and error handling
+ *
+ * Features:
+ * - Type-safe tool lookup with proper error handling
+ * - Rich result support (multiple content types, structured data, errors)
+ * - Exception-to-isError conversion
+ * - Backward compatible with string-returning tools
+ */
+import type { CallToolResult } from "@modelcontextprotocol/sdk/spec.types.js";
+import type { FastMCPTool } from "../schemas/schemas_tool_config.js";
+/**
+ * Parameters for tools/call JSON-RPC method
+ */
+export interface ToolCallParams {
+    name: string;
+    arguments?: Record<string, unknown>;
+}
+/**
+ * Handles the tools/call JSON-RPC method
+ *
+ * @param params - Tool call parameters (name and arguments)
+ * @param mcpTools - List of available tools
+ * @returns CallToolResult with content, optional structured data, and error flag
+ * @throws ERROR_METHOD_NOT_FOUND if tool not found (converted to isError in caller)
+ */
+export declare function handleToolCall(params: ToolCallParams, mcpTools: FastMCPTool<any, any>[]): Promise<CallToolResult>;

package/dist/types/mcp-result-types.js

@@ -0,0 +1,259 @@
+/**
+ * MCP Tool Result Types and Validators
+ *
+ * Provides type definitions and validation utilities for MCP CallToolResult
+ * schema compliance. Supports multiple content types, structured data,
+ * error handling, and metadata.
+ */
+/**
+ * Type guards for result type detection
+ */
+export function isString(value) {
+    return typeof value === "string";
+}
+/**
+ * Check if value looks like it's intended to be a CallToolResult
+ * (has content array field, regardless of validity)
+ */
+export function looksLikeCallToolResult(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const obj = value;
+    // If it has a content array field, it's intended to be CallToolResult
+    return Array.isArray(obj.content);
+}
+export function isCallToolResult(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const obj = value;
+    return (Array.isArray(obj.content) &&
+        obj.content.length > 0 &&
+        (typeof obj.isError === "undefined" || typeof obj.isError === "boolean") &&
+        (typeof obj.structuredContent === "undefined" ||
+            typeof obj.structuredContent === "object"));
+}
+export function isPlainObject(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        !isCallToolResult(value));
+}
+export function isErrorResult(value) {
+    return isCallToolResult(value) && value.isError === true;
+}
+export function isNullOrUndefined(value) {
+    return value === null || value === undefined;
+}
+/**
+ * Type-safe ContentBlock validators
+ */
+export function isTextContent(block) {
+    if (typeof block !== "object" || block === null)
+        return false;
+    const obj = block;
+    return obj.type === "text" && typeof obj.text === "string";
+}
+export function isImageContent(block) {
+    if (typeof block !== "object" || block === null)
+        return false;
+    const obj = block;
+    return (obj.type === "image" &&
+        typeof obj.data === "string" &&
+        typeof obj.mimeType === "string");
+}
+export function isAudioContent(block) {
+    if (typeof block !== "object" || block === null)
+        return false;
+    const obj = block;
+    return (obj.type === "audio" &&
+        typeof obj.data === "string" &&
+        typeof obj.mimeType === "string");
+}
+export function isResourceLink(block) {
+    if (typeof block !== "object" || block === null)
+        return false;
+    const obj = block;
+    return obj.type === "resource_link";
+}
+export function isEmbeddedResource(block) {
+    if (typeof block !== "object" || block === null)
+        return false;
+    const obj = block;
+    return obj.type === "resource" && typeof obj.resource === "object";
+}
+export function isContentBlock(block) {
+    return (isTextContent(block) ||
+        isImageContent(block) ||
+        isAudioContent(block) ||
+        isResourceLink(block) ||
+        isEmbeddedResource(block));
+}
+/**
+ * Validates a single ContentBlock against MCP schema
+ */
+export function validateContentBlock(block) {
+    const errors = [];
+    if (typeof block !== "object" || block === null) {
+        return {
+            valid: false,
+            errors: [{ field: "block", message: "Content block must be an object" }],
+        };
+    }
+    const obj = block;
+    const type = obj.type;
+    // Validate type field exists
+    if (typeof type !== "string") {
+        return {
+            valid: false,
+            errors: [{ field: "type", message: "type field is required and must be a string" }],
+        };
+    }
+    // Validate based on type
+    switch (type) {
+        case "text": {
+            if (typeof obj.text !== "string") {
+                errors.push({
+                    field: "text",
+                    message: "text field is required and must be a string",
+                });
+            }
+            break;
+        }
+        case "image": {
+            if (typeof obj.data !== "string") {
+                errors.push({
+                    field: "data",
+                    message: "data field is required and must be a base64 string",
+                });
+            }
+            if (typeof obj.mimeType !== "string") {
+                errors.push({
+                    field: "mimeType",
+                    message: "mimeType field is required for image content",
+                });
+            }
+            break;
+        }
+        case "audio": {
+            if (typeof obj.data !== "string") {
+                errors.push({
+                    field: "data",
+                    message: "data field is required and must be a base64 string",
+                });
+            }
+            if (typeof obj.mimeType !== "string") {
+                errors.push({
+                    field: "mimeType",
+                    message: "mimeType field is required for audio content",
+                });
+            }
+            break;
+        }
+        case "resource_link":
+        case "resource": {
+            // More lenient validation for resource types
+            break;
+        }
+        default: {
+            errors.push({
+                field: "type",
+                message: `Invalid content type: ${type}. Must be one of: text, image, audio, resource_link, resource`,
+            });
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Validates a complete CallToolResult against MCP schema
+ */
+export function validateCallToolResult(result) {
+    const errors = [];
+    if (typeof result !== "object" || result === null) {
+        return {
+            valid: false,
+            errors: [
+                {
+                    field: "result",
+                    message: "CallToolResult must be an object",
+                },
+            ],
+        };
+    }
+    const obj = result;
+    // Validate content array
+    if (!Array.isArray(obj.content)) {
+        errors.push({
+            field: "content",
+            message: "content field is required and must be an array",
+        });
+    }
+    else if (obj.content.length === 0) {
+        errors.push({
+            field: "content",
+            message: "content array cannot be empty",
+        });
+    }
+    else {
+        // Validate each content block
+        obj.content.forEach((block, index) => {
+            const blockValidation = validateContentBlock(block);
+            if (!blockValidation.valid) {
+                blockValidation.errors.forEach((err) => {
+                    errors.push({
+                        field: `content[${index}].${err.field}`,
+                        message: err.message,
+                    });
+                });
+            }
+        });
+    }
+    // Validate optional fields
+    if (typeof obj.isError !== "undefined" &&
+        typeof obj.isError !== "boolean") {
+        errors.push({
+            field: "isError",
+            message: "isError field must be a boolean if provided",
+        });
+    }
+    if (typeof obj.structuredContent !== "undefined" &&
+        (typeof obj.structuredContent !== "object" ||
+            obj.structuredContent === null ||
+            Array.isArray(obj.structuredContent))) {
+        errors.push({
+            field: "structuredContent",
+            message: "structuredContent field must be an object if provided",
+        });
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Creates a TextContent block
+ */
+export function createTextContent(text, annotations, _meta) {
+    const content = {
+        type: "text",
+        text,
+    };
+    if (annotations)
+        content.annotations = annotations;
+    if (_meta)
+        content._meta = _meta;
+    return content;
+}
+/**
+ * Creates a minimal valid CallToolResult with text content
+ */
+export function createSimpleResult(text, isError = false) {
+    return {
+        content: [createTextContent(text)],
+        ...(isError && { isError: true }),
+    };
+}

package/dist/types/types/mcp-result-types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * MCP Tool Result Types and Validators
+ *
+ * Provides type definitions and validation utilities for MCP CallToolResult
+ * schema compliance. Supports multiple content types, structured data,
+ * error handling, and metadata.
+ */
+import type { CallToolResult, ContentBlock, TextContent, ImageContent, AudioContent, ResourceLink, EmbeddedResource } from "@modelcontextprotocol/sdk/spec.types.js";
+/**
+ * Union type for tool execution results
+ * Tools can return:
+ * - string: Simple text result (backward compatible)
+ * - CallToolResult: Full MCP result with content, structured data, errors, metadata
+ * - object: Plain object that will be converted to structuredContent
+ */
+export type ToolExecuteResult = string | CallToolResult | Record<string, unknown> | null | undefined;
+/**
+ * Type guards for result type detection
+ */
+export declare function isString(value: unknown): value is string;
+/**
+ * Check if value looks like it's intended to be a CallToolResult
+ * (has content array field, regardless of validity)
+ */
+export declare function looksLikeCallToolResult(value: unknown): boolean;
+export declare function isCallToolResult(value: unknown): value is CallToolResult;
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+export declare function isErrorResult(value: unknown): value is CallToolResult & {
+    isError: true;
+};
+export declare function isNullOrUndefined(value: unknown): value is null | undefined;
+/**
+ * Type-safe ContentBlock validators
+ */
+export declare function isTextContent(block: unknown): block is TextContent;
+export declare function isImageContent(block: unknown): block is ImageContent;
+export declare function isAudioContent(block: unknown): block is AudioContent;
+export declare function isResourceLink(block: unknown): block is ResourceLink;
+export declare function isEmbeddedResource(block: unknown): block is EmbeddedResource;
+export declare function isContentBlock(block: unknown): block is ContentBlock;
+/**
+ * Validation result type
+ */
+export interface ValidationError {
+    field: string;
+    message: string;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+/**
+ * Validates a single ContentBlock against MCP schema
+ */
+export declare function validateContentBlock(block: unknown): ValidationResult;
+/**
+ * Validates a complete CallToolResult against MCP schema
+ */
+export declare function validateCallToolResult(result: unknown): ValidationResult;
+/**
+ * Creates a TextContent block
+ */
+export declare function createTextContent(text: string, annotations?: any, _meta?: any): TextContent;
+/**
+ * Creates a minimal valid CallToolResult with text content
+ */
+export declare function createSimpleResult(text: string, isError?: boolean): CallToolResult;

package/dist/types/utils/normalize-tool-result.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Tool Result Normalizer
+ *
+ * Converts various tool execution result types into valid MCP CallToolResult
+ * format. Implements smart detection with strict validation and backward
+ * compatibility for string-returning tools.
+ *
+ * Supported Input Types:
+ * - string: Wrapped as TextContent
+ * - CallToolResult: Validated and returned as-is
+ * - Plain object: Converted to structuredContent with text summary
+ * - null/undefined: Returns empty content array
+ * - Error: Returns error CallToolResult
+ */
+import type { CallToolResult } from "@modelcontextprotocol/sdk/spec.types.js";
+import { type ToolExecuteResult } from "../types/mcp-result-types.js";
+/**
+ * Normalizes a tool execution result into a valid CallToolResult
+ *
+ * @param result - The result from tool.execute()
+ * @returns Valid CallToolResult with appropriate content and metadata
+ * @throws Error if result validation fails (strict mode)
+ */
+export declare function normalizeToolResult(result: ToolExecuteResult): CallToolResult;
+/**
+ * Normalizes a tool execution result with error handling
+ *
+ * Returns error in CallToolResult format instead of throwing
+ * Useful for handlers that want to catch and format errors
+ *
+ * @param result - The result from tool.execute()
+ * @returns Valid CallToolResult (never throws)
+ */
+export declare function normalizeToolResultSafe(result: ToolExecuteResult): CallToolResult;
+/**
+ * Normalizes an error into a CallToolResult with isError flag
+ *
+ * @param error - The error to normalize
+ * @returns CallToolResult with isError: true
+ */
+export declare function normalizeToolError(error: unknown): CallToolResult;

package/dist/utils/normalize-tool-result.js

@@ -0,0 +1,120 @@
+/**
+ * Tool Result Normalizer
+ *
+ * Converts various tool execution result types into valid MCP CallToolResult
+ * format. Implements smart detection with strict validation and backward
+ * compatibility for string-returning tools.
+ *
+ * Supported Input Types:
+ * - string: Wrapped as TextContent
+ * - CallToolResult: Validated and returned as-is
+ * - Plain object: Converted to structuredContent with text summary
+ * - null/undefined: Returns empty content array
+ * - Error: Returns error CallToolResult
+ */
+import { isString, looksLikeCallToolResult, isPlainObject, isNullOrUndefined, validateCallToolResult, createTextContent, createSimpleResult, } from "../types/mcp-result-types.js";
+/**
+ * Generates a human-readable JSON summary of an object
+ * Limits depth and size for reasonable output
+ */
+function generateJsonSummary(obj) {
+    try {
+        // Limit JSON string length to 2000 chars
+        const json = JSON.stringify(obj, null, 2);
+        if (json.length > 2000) {
+            return json.substring(0, 2000) + "\n... (truncated)";
+        }
+        return json;
+    }
+    catch {
+        // If JSON serialization fails, try string representation
+        try {
+            const str = String(obj);
+            return str.length > 500 ? str.substring(0, 500) + "..." : str;
+        }
+        catch {
+            return "[Unable to serialize object]";
+        }
+    }
+}
+/**
+ * Normalizes a tool execution result into a valid CallToolResult
+ *
+ * @param result - The result from tool.execute()
+ * @returns Valid CallToolResult with appropriate content and metadata
+ * @throws Error if result validation fails (strict mode)
+ */
+export function normalizeToolResult(result) {
+    // Handle string results (backward compatibility)
+    if (isString(result)) {
+        return createSimpleResult(result);
+    }
+    // Handle null/undefined
+    if (isNullOrUndefined(result)) {
+        return {
+            content: [],
+        };
+    }
+    // Check if it looks like CallToolResult (has content array)
+    // If so, validate strictly regardless of other fields
+    if (looksLikeCallToolResult(result)) {
+        const validation = validateCallToolResult(result);
+        if (!validation.valid) {
+            const errorMessages = validation.errors
+                .map((e) => `${e.field}: ${e.message}`)
+                .join("; ");
+            throw new Error(`Invalid CallToolResult: ${errorMessages}`);
+        }
+        return result;
+    }
+    // Handle plain objects - convert to structuredContent with summary
+    if (isPlainObject(result)) {
+        const summary = generateJsonSummary(result);
+        return {
+            content: [createTextContent(`Result:\n\`\`\`json\n${summary}\n\`\`\``)],
+            structuredContent: result,
+        };
+    }
+    // Shouldn't reach here, but handle unexpected types
+    return createSimpleResult(`[Unexpected result type: ${typeof result}]`);
+}
+/**
+ * Normalizes a tool execution result with error handling
+ *
+ * Returns error in CallToolResult format instead of throwing
+ * Useful for handlers that want to catch and format errors
+ *
+ * @param result - The result from tool.execute()
+ * @returns Valid CallToolResult (never throws)
+ */
+export function normalizeToolResultSafe(result) {
+    try {
+        return normalizeToolResult(result);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return createSimpleResult(message, true);
+    }
+}
+/**
+ * Normalizes an error into a CallToolResult with isError flag
+ *
+ * @param error - The error to normalize
+ * @returns CallToolResult with isError: true
+ */
+export function normalizeToolError(error) {
+    let message;
+    if (error instanceof Error) {
+        message = error.message;
+    }
+    else if (typeof error === "string") {
+        message = error;
+    }
+    else if (typeof error === "object" && error !== null) {
+        message = JSON.stringify(error);
+    }
+    else {
+        message = String(error);
+    }
+    return createSimpleResult(message, true);
+}

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.1.3",
+  "version": "1.2.0",
   "name": "modality-mcp-kit",
   "repository": {
     "type": "git",