modality-mcp-kit 1.3.0 → 1.3.2

package/dist/FastHonoMcp.js

@@ -24,11 +24,13 @@
  * https://modelcontextprotocol.io/specification/2025-11-25/schema
  */
 import { ModalityFastMCP } from "./util_mcp_tools_converter.js";
+import { createMcpConnectionDemoHandler } from "./util_mcp_connection_demo.js";
 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 defaultMcpDemoPath = "/";
 const mcpSchemaVersion = "2025-11-25";
 // Initialize FastMCP instance for internal use (NO SERVER)
 export class FastHonoMcp extends ModalityFastMCP {
@@ -41,6 +43,20 @@ export class FastHonoMcp extends ModalityFastMCP {
         super();
         this.config = config;
     }
+    initHono(app) {
+        const { name, version, helloWorld, mcpPath = defaultMcpPath, mcpDemoPath = defaultMcpDemoPath, } = this.config;
+        this.mcpPath = mcpPath;
+        const middlewareHandler = this.handler();
+        app.use(mcpPath, middlewareHandler);
+        app.use(`${mcpPath}/*`, middlewareHandler);
+        app.get(mcpDemoPath, createMcpConnectionDemoHandler({
+            serverName: name,
+            serverVersion: version,
+            mcpPath,
+            helloWorld,
+        }));
+        return this;
+    }
     /**
      * Disconnect and cleanup a session
      */
@@ -125,13 +141,6 @@ export class FastHonoMcp extends ModalityFastMCP {
             }
         };
     }
-    initHono(app, path = defaultMcpPath) {
-        this.mcpPath = path;
-        const middlewareHandler = this.handler();
-        app.use(path, middlewareHandler);
-        app.use(`${path}/*`, middlewareHandler);
-        return this;
-    }
 }
 class HonoJSONRPCManager extends JSONRPCManager {
     async sendMessage(message) {

package/dist/index.js

@@ -1,3 +1,4 @@
 export { toJsonSchema } from "xsschema";
 export { setupAITools, ModalityFastMCP } from "./util_mcp_tools_converter";
 export { FastHonoMcp } from "./FastHonoMcp";
+export { mcpProxyHandler, mcpProxyListHandler, mcpProxyCacheHandler, } from "./util_mcp_proxy";

package/dist/types/FastHonoMcp.d.ts

@@ -30,14 +30,18 @@ import { McpSessionManager } from "./McpSessionManager.js";
 export interface FastHonoMcpConfig extends Record<string, unknown> {
     name: string;
     version: string;
+    mcpPath?: string;
+    mcpDemoPath?: string;
+    helloWorld?: string;
 }
 export declare class FastHonoMcp extends ModalityFastMCP {
     logger: ReturnType<typeof getLoggerInstance>;
     config: FastHonoMcpConfig;
     sessions: McpSessionManager;
     private currentSessionId;
-    private mcpPath;
+    mcpPath: string;
     constructor(config: FastHonoMcpConfig);
+    initHono(app: Hono): this;
     /**
      * Disconnect and cleanup a session
      */
@@ -47,5 +51,4 @@ export declare class FastHonoMcp extends ModalityFastMCP {
      */
     private ensureSession;
     handler(): MiddlewareHandler;
-    initHono(app: Hono, path?: string): this;
 }

package/dist/types/index.d.ts

@@ -3,3 +3,4 @@ export { setupAITools, ModalityFastMCP } from "./util_mcp_tools_converter";
 export type { AITools, AITool, FastMCPTool, } from "./schemas/schemas_tool_config";
 export type { FastMCPCompatible, BasePrompt, } from "./util_mcp_tools_converter";
 export { FastHonoMcp } from "./FastHonoMcp";
+export { mcpProxyHandler, mcpProxyListHandler, mcpProxyCacheHandler, type McpProxyConfig, } from "./util_mcp_proxy";

package/dist/types/util_mcp_connection_demo.d.ts

@@ -0,0 +1,31 @@
+/**
+ * MCP Connection Demo Handler
+ *
+ * Provides an interactive demonstration page for MCP connection patterns
+ * with examples showing how to connect various AI tools and development utilities.
+ *
+ * Usage: /mcp-demo - returns MCP connection demo documentation and tool showcase
+ */
+interface MCPConnectionConfig {
+    serverName: string;
+    serverVersion?: string;
+    serverUrl?: string;
+    mcpPath?: string;
+    defaultFormat?: "json" | "markdown" | "html";
+    helloWorld?: string;
+}
+/**
+ * Create MCP connection demo handler with server configuration
+ * @param config - Server name and version for consistency
+ * @returns Hono handler function
+ */
+export declare const createMcpConnectionDemoHandler: (config: MCPConnectionConfig) => (c: any) => Promise<any>;
+/**
+ * Hono handler for MCP connection demo
+ * Returns documentation and tool showcase data
+ * @param c - Hono context
+ * @param config - Optional server configuration
+ * @returns Demo page with connection information
+ */
+export declare const mcpConnectionDemoHandler: (c: any, config?: MCPConnectionConfig) => Promise<any>;
+export {};

package/dist/util_mcp_connection_demo.js

@@ -0,0 +1,496 @@
+/**
+ * MCP Connection Demo Handler
+ *
+ * Provides an interactive demonstration page for MCP connection patterns
+ * with examples showing how to connect various AI tools and development utilities.
+ *
+ * Usage: /mcp-demo - returns MCP connection demo documentation and tool showcase
+ */
+const defaultOutputFormat = "html";
+const connectAIShowcase = (serverName, serverUrl, mcpPath = "/mcp") => ({
+    claudeCode: {
+        name: "Claude Code",
+        description: "Official Claude IDE tool for seamless development workflow",
+        connectionCode: `claude mcp add -s user --transport http ${serverName} ${serverUrl}${mcpPath}`,
+        type: "editor",
+    },
+    githubCli: {
+        name: "GitHub CLI",
+        description: "Command-line tool with MCP support for GitHub operations",
+        connectionCode: `vim ~/.copilot/mcp-config.json
+
+{
+  "mcpServers": {
+    "${serverName}": {
+      "type": "http",
+      "url": "${serverUrl}${mcpPath}",
+      "headers": {},
+      "tools": ["*"]
+    }
+  }
+}`,
+        type: "terminal",
+    },
+    vscode: {
+        name: "VS Code",
+        description: "Popular code editor with MCP extension support",
+        connectionCode: `code --add-mcp '{"name":"${serverName}", "url": "${serverUrl}${mcpPath}", "type": "http"}'`,
+        type: "editor",
+    },
+    mytyAi: {
+        name: "Myty AI",
+        description: "AI assistant platform with comprehensive MCP capabilities",
+        connectionCode: `{
+  "mcpServers": {
+    "${serverName}": {
+      "command": "npx",
+      "args": [
+        "mcp-remote",
+        "${serverUrl}${mcpPath}"
+      ]
+    }
+  }
+}`,
+        type: "platform",
+    },
+});
+// ============================================
+// DEMO CONTENT - MARKDOWN-BASED
+// ============================================
+const generateDemoDocumentation = (serverName, serverUrl, mcpPath = "/mcp", helloWorld) => {
+    const tools = connectAIShowcase(serverName, serverUrl, mcpPath);
+    return `# MCP Connection Guide
+
+${helloWorld ? `## Hello Prompt\n\n${helloWorld}\n` : ""}## How to Connect
+
+1. Copy the connection code for your tool
+2. Add it to your MCP configuration
+3. Establish the session
+
+## Connection Codes
+
+${Object.entries(tools)
+        .map(([, tool]) => `### ${tool.name}
+\`\`\`
+${tool.connectionCode}
+\`\`\``)
+        .join("\n\n")}
+`;
+};
+// ============================================
+// HONO HANDLER
+// ============================================
+/**
+ * Create MCP connection demo handler with server configuration
+ * @param config - Server name and version for consistency
+ * @returns Hono handler function
+ */
+export const createMcpConnectionDemoHandler = (config) => {
+    return async (c) => {
+        return mcpConnectionDemoHandler(c, config);
+    };
+};
+/**
+ * Hono handler for MCP connection demo
+ * Returns documentation and tool showcase data
+ * @param c - Hono context
+ * @param config - Optional server configuration
+ * @returns Demo page with connection information
+ */
+export const mcpConnectionDemoHandler = async (c, config) => {
+    const format = c.req.query("format") || config?.defaultFormat || defaultOutputFormat;
+    const serverName = config?.serverName || "mcp-server";
+    const mcpPath = config?.mcpPath || "/mcp";
+    // Get server URL: from config first, then extract from request
+    let serverUrl = "";
+    if (!config?.serverUrl && c.req.url) {
+        try {
+            const url = new URL(c.req.url);
+            serverUrl = `${url.protocol}//${url.host}`;
+        }
+        catch {
+            // Fallback to default if URL parsing fails
+        }
+    }
+    else if (config?.serverUrl) {
+        serverUrl = config?.serverUrl;
+    }
+    const tools = connectAIShowcase(serverName, serverUrl, mcpPath);
+    const documentation = generateDemoDocumentation(serverName, serverUrl, mcpPath, config?.helloWorld);
+    // Handle different format requests
+    if (format === "markdown" || format === "md") {
+        return new Response(documentation, {
+            status: 200,
+            headers: {
+                "Content-Type": "text/markdown; charset=utf-8",
+                "Cache-Control": "public, max-age=3600",
+                "Access-Control-Allow-Origin": "*",
+            },
+        });
+    }
+    if (format === "html") {
+        const htmlContent = generateHtmlPage(serverUrl, config, tools, mcpPath);
+        return new Response(htmlContent, {
+            status: 200,
+            headers: {
+                "Content-Type": "text/html; charset=utf-8",
+                "Cache-Control": "public, max-age=3600",
+                "Access-Control-Allow-Origin": "*",
+            },
+        });
+    }
+    // Default: JSON format with complete data
+    const demoData = {
+        documentation,
+        tools: Object.entries(tools).map(([key, tool]) => ({
+            id: key,
+            ...tool,
+        })),
+        server: {
+            name: serverName,
+            version: config?.serverVersion || "unknown",
+            url: serverUrl,
+            mcpPath: mcpPath,
+        },
+        metadata: {
+            toolCount: Object.keys(tools).length,
+            lastUpdated: new Date().toISOString(),
+            format: "json",
+            availableFormats: ["json", "markdown", "html"],
+        },
+    };
+    return c.json(demoData, {
+        headers: {
+            "Cache-Control": "public, max-age=3600",
+            "Access-Control-Allow-Origin": "*",
+        },
+    });
+};
+// ============================================
+// HTML GENERATION
+// ============================================
+function escapeHtml(text) {
+    const map = {
+        "&": "&",
+        "<": "&lt;",
+        ">": "&gt;",
+        '"': "&quot;",
+        "'": "&#039;",
+    };
+    return text.replace(/[&<>"']/g, (char) => map[char] || char);
+}
+function escapeForJs(text) {
+    return text.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$/g, "\\$");
+}
+function generateHtmlPage(serverUrl, config, tools, mcpPath = "/mcp") {
+    const toolsToDisplay = tools || connectAIShowcase(config?.serverName || "mcp-server", serverUrl, mcpPath);
+    const toolsHtml = Object.entries(toolsToDisplay)
+        .map(([, tool]) => `
+    <div class="tool-card">
+      <h3>${tool.name}</h3>
+      <p class="tool-type">${tool.type}</p>
+      <p class="tool-description">${tool.description}</p>
+      <div class="connection-section">
+        <label>Connection Code</label>
+        <pre class="code-block"><code>${escapeHtml(tool.connectionCode)}</code></pre>
+        <button class="copy-btn" onclick="copyToClipboard(\`${escapeForJs(tool.connectionCode)}\`)">
+          Copy
+        </button>
+      </div>
+    </div>
+  `)
+        .join("\n");
+    return `
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${config?.serverName || "MCP Connection Demo"}</title>
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
+      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+      min-height: 100vh;
+      padding: 2rem;
+    }
+
+    .container {
+      max-width: 1200px;
+      margin: 0 auto;
+      background: white;
+      border-radius: 12px;
+      box-shadow: 0 20px 60px rgba(0, 0, 0, 0.3);
+      overflow: hidden;
+    }
+
+    header {
+      background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+      color: white;
+      padding: 3rem 2rem;
+      text-align: center;
+    }
+
+    header h1 {
+      font-size: 2.5rem;
+      margin-bottom: 0.5rem;
+    }
+
+    header p {
+      font-size: 1.1rem;
+      opacity: 0.9;
+    }
+
+    .content {
+      padding: 2rem;
+    }
+
+    .intro-section {
+      margin-bottom: 3rem;
+      padding: 2rem;
+      background: #f8f9fa;
+      border-radius: 8px;
+      border-left: 4px solid #667eea;
+    }
+
+    .intro-section h2 {
+      color: #333;
+      margin-bottom: 1rem;
+      font-size: 1.5rem;
+    }
+
+    .intro-section p {
+      color: #666;
+      line-height: 1.6;
+      margin-bottom: 1rem;
+    }
+
+    .tools-section {
+      margin-top: 3rem;
+    }
+
+    .tools-section h2 {
+      color: #333;
+      margin-bottom: 2rem;
+      font-size: 1.5rem;
+      border-bottom: 2px solid #667eea;
+      padding-bottom: 1rem;
+    }
+
+    .tools-grid {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(350px, 1fr));
+      gap: 2rem;
+    }
+
+    .tool-card {
+      border: 1px solid #e0e0e0;
+      border-radius: 8px;
+      padding: 1.5rem;
+      transition: all 0.3s ease;
+      background: white;
+    }
+
+    .tool-card:hover {
+      border-color: #667eea;
+      box-shadow: 0 8px 24px rgba(102, 126, 234, 0.15);
+      transform: translateY(-2px);
+    }
+
+    .tool-card h3 {
+      color: #333;
+      margin-bottom: 0.5rem;
+      font-size: 1.3rem;
+    }
+
+    .tool-type {
+      display: inline-block;
+      background: #667eea;
+      color: white;
+      padding: 0.25rem 0.75rem;
+      border-radius: 20px;
+      font-size: 0.75rem;
+      font-weight: 600;
+      text-transform: uppercase;
+      margin-bottom: 1rem;
+    }
+
+    .tool-description {
+      color: #666;
+      margin-bottom: 1.5rem;
+      line-height: 1.6;
+      font-size: 0.95rem;
+    }
+
+    .connection-section {
+      margin-top: 1rem;
+    }
+
+    .connection-section label {
+      display: block;
+      color: #333;
+      font-weight: 600;
+      margin-bottom: 0.5rem;
+      font-size: 0.9rem;
+    }
+
+    .url-container {
+      display: flex;
+      gap: 0.5rem;
+      align-items: center;
+    }
+
+    code {
+      background: transparent;
+      padding: 0;
+      border: none;
+      color: #333;
+      font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+      font-size: 0.85rem;
+      word-break: break-all;
+    }
+
+    .code-block {
+      background: #f5f5f5;
+      padding: 1rem;
+      border-radius: 4px;
+      font-family: 'Monaco', 'Menlo', 'Ubuntu Mono', monospace;
+      font-size: 0.85rem;
+      color: #333;
+      border: 1px solid #e0e0e0;
+      overflow-x: auto;
+      margin: 0.5rem 0 1rem 0;
+      white-space: pre-wrap;
+      word-wrap: break-word;
+    }
+
+    .copy-btn {
+      background: #667eea;
+      color: white;
+      border: none;
+      padding: 0.5rem 1rem;
+      border-radius: 4px;
+      cursor: pointer;
+      font-weight: 600;
+      font-size: 0.85rem;
+      transition: background 0.2s ease;
+      white-space: nowrap;
+    }
+
+    .copy-btn:hover {
+      background: #764ba2;
+    }
+
+    .copy-btn:active {
+      transform: scale(0.98);
+    }
+
+    footer {
+      background: #f8f9fa;
+      padding: 2rem;
+      text-align: center;
+      color: #666;
+      border-top: 1px solid #e0e0e0;
+      font-size: 0.9rem;
+    }
+
+    @media (max-width: 768px) {
+      header h1 {
+        font-size: 1.8rem;
+      }
+
+      .tools-grid {
+        grid-template-columns: 1fr;
+      }
+
+      .content {
+        padding: 1rem;
+      }
+
+      .url-container {
+        flex-direction: column;
+      }
+
+      .copy-btn {
+        width: 100%;
+      }
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <header>
+      <h1>🌐 ${config?.serverName || "MCP Connection Demo"}</h1>
+      <p>Interactive guide for connecting AI tools and development utilities</p>
+      ${config
+        ? `<p style="font-size: 0.95rem; margin-top: 1rem; opacity: 0.8;">Server: <strong>${config.serverName}</strong> v${config.serverVersion || "unknown"}</p>`
+        : ""}
+    </header>
+
+    <div class="content">
+      ${config?.helloWorld
+        ? `<div class="intro-section">
+        <h2>Hello Prompt</h2>
+        <p>${config.helloWorld}</p>
+      </div>`
+        : `<div class="intro-section">
+        <h2>Welcome to MCP</h2>
+        <p>
+          The Model Context Protocol (MCP) provides a standardized way for AI tools
+          and development utilities to exchange information and capabilities.
+        </p>
+        <p>
+          Below you'll find connection URLs for popular tools. Copy the URL for your
+          tool and add it to your MCP configuration.
+        </p>
+      </div>`}
+
+      <div class="tools-section">
+        <h2>Connect your AI assistant</h2>
+        <div class="tools-grid">
+          ${toolsHtml}
+        </div>
+      </div>
+    </div>
+
+    <footer>
+      <p>${config?.serverName || "MCP Connection Demo"} &copy; 2026 | Last updated: ${new Date().toLocaleDateString()}</p>
+      ${config
+        ? `<p>Server: <strong>${config.serverName}</strong> | URL: <code>${serverUrl}</code></p>`
+        : ""}
+    </footer>
+  </div>
+
+  <script>
+    function copyToClipboard(text) {
+      navigator.clipboard.writeText(text).then(() => {
+        const btn = event.target;
+        const originalText = btn.textContent;
+        btn.textContent = '✓ Copied!';
+        setTimeout(() => {
+          btn.textContent = originalText;
+        }, 2000);
+      }).catch(err => {
+        console.error('Failed to copy:', err);
+        alert('Failed to copy to clipboard');
+      });
+    }
+
+    // Log page load performance
+    window.addEventListener('load', () => {
+      const perfData = performance.getEntriesByType('navigation')[0];
+      if (perfData) {
+        console.log('Page Load Time:', perfData.loadEventEnd - perfData.fetchStart, 'ms');
+      }
+    });
+  </script>
+</body>
+</html>
+  `.trim();
+}

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.3.0",
+  "version": "1.3.2",
   "name": "modality-mcp-kit",
   "repository": {
     "type": "git",
@@ -23,7 +23,7 @@
   "license": "ISC",
   "peerDependencies": {
     "zod": "^4.3.5",
-    "hono": "*"
+    "hono": "^4.11.3"
   },
   "dependencies": {
     "@valibot/to-json-schema": "^1.5.0",