mcpbox 0.2.1 → 0.3.1

package/README.md

@@ -5,12 +5,13 @@
   </picture>
 </p>
 
-**MCPBox** is a lightweight gateway that exposes local stdio-based MCP (Model Context Protocol) servers via Streamable HTTP, enabling Claude and other AI agents to connect from anywhere.
+**MCPBox** is a lightweight gateway that exposes local stdio-based [MCP](https://modelcontextprotocol.io) servers via Streamable HTTP, enabling Claude and other AI agents to connect from anywhere.
 
-- Runs multiple MCP stdio servers behind a single HTTP endpoint
-- Exposes Tools, Resources & Prompts
+- Runs multiple servers behind a single HTTP endpoint
+- Supports Tools, Resources & Prompts
 - Namespaces with `servername__` prefix to avoid collisions
-- OAuth or API key authentication
+- Per-server tool filtering to limit AI access and reduce context usage
+- OAuth 2.1, API key, or no auth
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="assets/diagram-dark.excalidraw.png">
@@ -27,28 +28,22 @@ Create `mcpbox.json`:
     "memory": {
       "command": "npx",
       "args": ["-y", "@modelcontextprotocol/server-memory"]
+    },
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
     }
   }
 }
 ```
 
-Run with:
-
-**npx**
+Run:
 
 ```bash
 npx mcpbox
 ```
-*MCP server commands (e.g., `uvx`, `docker`) must be available where the box runs.*
-
-**Docker**
-
-```bash
-docker run -v ./mcpbox.json:/config/config.json -p 8080:8080 ghcr.io/kandobyte/mcpbox
-```
-*The Docker image includes Node.js and Python, supporting MCP servers launched via `npx` and `uvx`.*
 
-The box starts on http://localhost:8080. Connect an agent by adding this to your MCP client config:
+Add to your MCP client config:
 
 ```json
 {
@@ -61,103 +56,6 @@ The box starts on http://localhost:8080. Connect an agent by adding this to your
 }
 ```
 
-For remote access with authentication, see [Deployment](#deployment) and [Connect Your AI](#connect-your-ai).
-
-## Configuration
-
-See [`mcpbox.example.jsonc`](mcpbox.example.jsonc) for all options. All string values support `${VAR_NAME}` environment variable substitution.
-
-**[Authentication](docs/authentication.md)** — none (default), API key, or OAuth.
-
-## Deployment
-
-To expose MCPBox remotely, put it behind a TLS-terminating reverse proxy.
-
-Before deploying with OAuth:
-- [ ] Use sqlite storage for persistence across restarts
-- [ ] Set issuer to your public URL
-- [ ] Use bcrypt hashes for local passwords
-
-> [!NOTE]
-> MCPBox is single-instance only — don't run multiple instances behind a load balancer.
-
-### Quick remote access
-
-Use [cloudflared](https://github.com/cloudflare/cloudflared) to expose a local instance (no account required):
-
-```bash
-cloudflared tunnel --url http://localhost:8080
-```
-
-Then update your config with the generated public URL:
-
-```json
-{
-  "auth": {
-    "type": "oauth",
-    "issuer": "https://<tunnel-id>.trycloudflare.com",
-    "identityProviders": [
-      { "type": "local", "users": [{ "username": "admin", "password": "${MCPBOX_PASSWORD}" }] }
-    ],
-    "dynamicRegistration": true
-  },
-  "storage": {
-    "type": "sqlite",
-    "path": "/data/mcpbox.db"
-  },
-  "mcpServers": { ... }
-}
-```
-
-Run with a persistent data volume:
-
-```bash
-docker run -v ./mcpbox.json:/config/config.json -v ./data:/data -p 8080:8080 ghcr.io/kandobyte/mcpbox
-```
-
-## Connect Your AI
-
-### Claude Web & Mobile
+## Documentation
 
-Settings → Connectors → Add Custom Connector → enter your URL → Connect
-
-Requires `dynamicRegistration: true` in your config.
-
-### Claude Code
-
-```bash
-claude mcp add --transport http mcpbox https://your-mcpbox-url.com
-```
-
-Requires `dynamicRegistration: true` in your config.
-
-### Other MCP clients
-
-**With dynamic registration (OAuth)** — just provide the URL:
-
-```json
-{
-  "mcpServers": {
-    "mcpbox": {
-      "type": "http",
-      "url": "https://your-mcpbox-url.com"
-    }
-  }
-}
-```
-
-**With API key:**
-
-```json
-{
-  "mcpServers": {
-    "mcpbox": {
-      "type": "http",
-      "url": "https://your-mcpbox-url.com",
-      "headers": {
-        "Authorization": "Bearer YOUR_API_KEY"
-      }
-    }
-  }
-}
-```
+See the [documentation](https://kandobyte.github.io/mcpbox/quick-start) for configuration, authentication, deployment, and connecting clients.

package/dist/config/loader.js

@@ -2,7 +2,13 @@ import { existsSync, readFileSync } from "node:fs";
 import { RawConfigSchema, } from "./schema.js";
 function substituteEnvVars(obj) {
     if (typeof obj === "string") {
-        return obj.replace(/\$\{(\w+)\}/g, (_, name) => process.env[name] ?? "");
+        return obj.replace(/\$\{(\w+)\}/g, (match, name) => {
+            const value = process.env[name];
+            if (value === undefined) {
+                throw new Error(`Environment variable ${name} is not set (referenced as ${match})`);
+            }
+            return value;
+        });
     }
     if (Array.isArray(obj)) {
         return obj.map(substituteEnvVars);
@@ -25,6 +31,8 @@ function parseMcpServers(mcpServers) {
             args: entry.args,
             env: entry.env,
             tools: entry.tools,
+            resources: entry.resources,
+            prompts: entry.prompts,
         });
     }
     return mcps;

package/dist/config/schema.d.ts

@@ -8,6 +8,8 @@ export declare const McpServerEntrySchema: z.ZodObject<{
     args: z.ZodOptional<z.ZodArray<z.ZodString>>;
     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    resources: z.ZodOptional<z.ZodBoolean>;
+    prompts: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
 /**
  * OAuth user credentials
@@ -204,6 +206,8 @@ export declare const RawConfigSchema: z.ZodObject<{
         args: z.ZodOptional<z.ZodArray<z.ZodString>>;
         env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        resources: z.ZodOptional<z.ZodBoolean>;
+        prompts: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strict>>>;
 }, z.core.$strict>;
 /**
@@ -216,6 +220,8 @@ export declare const McpConfigSchema: z.ZodObject<{
     args: z.ZodOptional<z.ZodArray<z.ZodString>>;
     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    resources: z.ZodOptional<z.ZodBoolean>;
+    prompts: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 /**
  * Processed config (after loader adds defaults and resolves mcpServers)
@@ -282,6 +288,8 @@ export declare const ConfigSchema: z.ZodObject<{
         args: z.ZodOptional<z.ZodArray<z.ZodString>>;
         env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         tools: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        resources: z.ZodOptional<z.ZodBoolean>;
+        prompts: z.ZodOptional<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 export type McpServerEntry = z.infer<typeof McpServerEntrySchema>;

package/dist/config/schema.js

@@ -17,6 +17,8 @@ export const McpServerEntrySchema = z
     args: z.array(z.string()).optional(),
     env: z.record(z.string(), z.string()).optional(),
     tools: z.array(z.string()).optional(),
+    resources: z.boolean().optional(),
+    prompts: z.boolean().optional(),
 })
     .strict();
 /**
@@ -129,6 +131,14 @@ export const AuthConfigSchema = z.discriminatedUnion("type", [
         return oauth.identityProviders && oauth.identityProviders.length > 0;
     }, {
         message: "dynamic registration requires identity providers to be configured for user login",
+    })
+        .refine((oauth) => {
+        if (!oauth.clients)
+            return true;
+        const ids = oauth.clients.map((c) => c.clientId);
+        return new Set(ids).size === ids.length;
+    }, {
+        message: "Duplicate client IDs are not allowed",
     }),
 ]);
 /**
@@ -193,6 +203,8 @@ export const McpConfigSchema = z.object({
     args: z.array(z.string()).optional(),
     env: z.record(z.string(), z.string()).optional(),
     tools: z.array(z.string()).optional(),
+    resources: z.boolean().optional(),
+    prompts: z.boolean().optional(),
 });
 /**
  * Processed config (after loader adds defaults and resolves mcpServers)

package/dist/mcp/handler.d.ts

@@ -0,0 +1,22 @@
+import { ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import type { Context } from "hono";
+import type { McpManager } from "./manager.js";
+export declare function createMcpHandler(mcpManager: McpManager): (c: Context) => Promise<(Response & import("hono").TypedResponse<{
+    jsonrpc: "2.0";
+    id: string | number;
+    error: {
+        code: number;
+        message: string;
+    };
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">) | (Response & import("hono").TypedResponse<{
+    jsonrpc: "2.0";
+    id: string | number;
+    result: import("hono/utils/types").JSONValue;
+}, import("hono/utils/http-status").ContentfulStatusCode, "json">) | (Response & import("hono").TypedResponse<{
+    jsonrpc: string;
+    error: {
+        code: ErrorCode;
+        message: string;
+    };
+    id: null;
+}, 400, "json">) | (Response & import("hono").TypedResponse<null, 202, "body">)>;

package/dist/mcp/handler.js

@@ -0,0 +1,148 @@
+import { CallToolRequestSchema, CompleteRequestSchema, ErrorCode, GetPromptRequestSchema, InitializeRequestSchema, isJSONRPCNotification, JSONRPCRequestSchema, ListPromptsRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, PingRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { logger } from "../logger.js";
+import { NAME, VERSION } from "../version.js";
+function jsonrpcResult(id, result) {
+    return { jsonrpc: "2.0", id, result };
+}
+function jsonrpcError(id, code, message) {
+    return { jsonrpc: "2.0", id, error: { code, message } };
+}
+export function createMcpHandler(mcpManager) {
+    return async (c) => {
+        let body;
+        try {
+            body = await c.req.json();
+        }
+        catch (e) {
+            logger.warn({ error: e instanceof Error ? e.message : String(e) }, "MCP parse error");
+            return c.json({
+                jsonrpc: "2.0",
+                error: { code: ErrorCode.ParseError, message: "Parse error" },
+                id: null,
+            }, 400);
+        }
+        if (isJSONRPCNotification(body)) {
+            const method = body.method;
+            logger.debug({ method }, "MCP notification");
+            return c.body(null, 202);
+        }
+        const envelope = JSONRPCRequestSchema.safeParse(body);
+        if (!envelope.success) {
+            return c.json({
+                jsonrpc: "2.0",
+                error: {
+                    code: ErrorCode.InvalidRequest,
+                    message: "Invalid request",
+                },
+                id: null,
+            }, 400);
+        }
+        const request = envelope.data;
+        logger.debug({ method: request.method, id: request.id }, "MCP request");
+        return handleRequest(c, request, mcpManager);
+    };
+}
+async function handleRequest(c, request, mcpManager) {
+    const { id, method } = request;
+    if (method === "initialize") {
+        const parsed = InitializeRequestSchema.safeParse(request);
+        if (!parsed.success) {
+            return c.json(jsonrpcError(id, ErrorCode.InvalidParams, "Invalid params"));
+        }
+        const result = {
+            protocolVersion: "2025-11-25",
+            capabilities: {
+                tools: { listChanged: true },
+                resources: { listChanged: true },
+                prompts: { listChanged: true },
+                completions: {},
+            },
+            serverInfo: {
+                name: NAME,
+                version: VERSION,
+            },
+        };
+        return c.json(jsonrpcResult(id, result));
+    }
+    if (method === "ping") {
+        const parsed = PingRequestSchema.safeParse(request);
+        if (!parsed.success) {
+            return c.json(jsonrpcError(id, ErrorCode.InvalidParams, "Invalid params"));
+        }
+        return c.json(jsonrpcResult(id, {}));
+    }
+    if (method === "tools/list") {
+        const parsed = ListToolsRequestSchema.safeParse(request);
+        if (!parsed.success) {
+            return c.json(jsonrpcError(id, ErrorCode.InvalidParams, "Invalid params"));
+        }
+        return c.json(jsonrpcResult(id, { tools: mcpManager.listTools() }));
+    }
+    if (method === "tools/call") {
+        const parsed = CallToolRequestSchema.safeParse(request);
+        if (!parsed.success) {
+            return c.json(jsonrpcError(id, ErrorCode.InvalidParams, "Invalid params"));
+        }
+        try {
+            const result = await mcpManager.callTool(parsed.data.params);
+            return c.json(jsonrpcResult(id, result));
+        }
+        catch (error) {
+            return c.json(jsonrpcError(id, ErrorCode.InternalError, error instanceof Error ? error.message : "Internal error"));
+        }
+    }
+    if (method === "resources/list") {
+        const parsed = ListResourcesRequestSchema.safeParse(request);
+        if (!parsed.success) {
+            return c.json(jsonrpcError(id, ErrorCode.InvalidParams, "Invalid params"));
+        }
+        return c.json(jsonrpcResult(id, { resources: mcpManager.listResources() }));
+    }
+    if (method === "resources/read") {
+        const parsed = ReadResourceRequestSchema.safeParse(request);
+        if (!parsed.success) {
+            return c.json(jsonrpcError(id, ErrorCode.InvalidParams, "Invalid params"));
+        }
+        try {
+            const result = await mcpManager.readResource(parsed.data.params);
+            return c.json(jsonrpcResult(id, result));
+        }
+        catch (error) {
+            return c.json(jsonrpcError(id, ErrorCode.InternalError, error instanceof Error ? error.message : "Internal error"));
+        }
+    }
+    if (method === "prompts/list") {
+        const parsed = ListPromptsRequestSchema.safeParse(request);
+        if (!parsed.success) {
+            return c.json(jsonrpcError(id, ErrorCode.InvalidParams, "Invalid params"));
+        }
+        return c.json(jsonrpcResult(id, { prompts: mcpManager.listPrompts() }));
+    }
+    if (method === "prompts/get") {
+        const parsed = GetPromptRequestSchema.safeParse(request);
+        if (!parsed.success) {
+            return c.json(jsonrpcError(id, ErrorCode.InvalidParams, "Invalid params"));
+        }
+        try {
+            const result = await mcpManager.getPrompt(parsed.data.params);
+            return c.json(jsonrpcResult(id, result));
+        }
+        catch (error) {
+            return c.json(jsonrpcError(id, ErrorCode.InternalError, error instanceof Error ? error.message : "Internal error"));
+        }
+    }
+    if (method === "completion/complete") {
+        const parsed = CompleteRequestSchema.safeParse(request);
+        if (!parsed.success) {
+            return c.json(jsonrpcError(id, ErrorCode.InvalidParams, "Invalid params"));
+        }
+        try {
+            const result = await mcpManager.complete(parsed.data.params);
+            return c.json(jsonrpcResult(id, result));
+        }
+        catch (error) {
+            return c.json(jsonrpcError(id, ErrorCode.InternalError, error instanceof Error ? error.message : "Internal error"));
+        }
+    }
+    return c.json(jsonrpcError(id, ErrorCode.MethodNotFound, `Method not found: ${method}`));
+}

package/dist/mcp/manager.d.ts

@@ -1,6 +1,6 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import type { CallToolResult, CompleteResult, GetPromptResult, Prompt, ReadResourceResult, Resource, Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { CallToolRequestParams, CallToolResult, CompleteRequestParams, CompleteResult, GetPromptRequestParams, GetPromptResult, Prompt, ReadResourceRequestParams, ReadResourceResult, Resource, Tool } from "@modelcontextprotocol/sdk/types.js";
 import type { LogConfig, McpConfig } from "../config/types.js";
 export interface ManagedMcp {
     name: string;
@@ -33,16 +33,9 @@ export declare class McpManager {
             prompts: number;
         }>;
     }>;
-    callTool(toolName: string, args: Record<string, unknown>): Promise<CallToolResult>;
-    readResource(resourceUri: string): Promise<ReadResourceResult>;
-    getPrompt(promptName: string, args?: Record<string, string>): Promise<GetPromptResult>;
-    complete(ref: {
-        type: string;
-        name?: string;
-        uri?: string;
-    }, argument: {
-        name: string;
-        value: string;
-    }): Promise<CompleteResult>;
+    callTool(params: CallToolRequestParams): Promise<CallToolResult>;
+    readResource(params: ReadResourceRequestParams): Promise<ReadResourceResult>;
+    getPrompt(params: GetPromptRequestParams): Promise<GetPromptResult>;
+    complete(params: CompleteRequestParams): Promise<CompleteResult>;
     private resolveCompletionRef;
 }

package/dist/mcp/manager.js

@@ -106,37 +106,47 @@ export class McpManager {
         }
         // Get resources from this MCP (namespace them if multiple servers)
         let resources = [];
-        try {
-            const { resources: rawResources } = await client.listResources();
-            resources = this.useNamespacing
-                ? rawResources.map((resource) => ({
-                    ...resource,
-                    uri: namespaceName(config.name, resource.uri),
-                }))
-                : rawResources;
-            for (const resource of resources) {
-                this.resourceToMcp.set(resource.uri, config.name);
+        if (config.resources !== false) {
+            try {
+                const { resources: rawResources } = await client.listResources();
+                resources = this.useNamespacing
+                    ? rawResources.map((resource) => ({
+                        ...resource,
+                        uri: namespaceName(config.name, resource.uri),
+                    }))
+                    : rawResources;
+                for (const resource of resources) {
+                    this.resourceToMcp.set(resource.uri, config.name);
+                }
+            }
+            catch {
+                logger.debug({ mcp: config.name }, "Server doesn't support resources");
             }
         }
-        catch {
-            logger.debug({ mcp: config.name }, "Server doesn't support resources");
+        else {
+            logger.debug({ mcp: config.name }, "Resources disabled by config");
         }
         // Get prompts from this MCP (namespace them if multiple servers)
         let prompts = [];
-        try {
-            const { prompts: rawPrompts } = await client.listPrompts();
-            prompts = this.useNamespacing
-                ? rawPrompts.map((prompt) => ({
-                    ...prompt,
-                    name: namespaceName(config.name, prompt.name),
-                }))
-                : rawPrompts;
-            for (const prompt of prompts) {
-                this.promptToMcp.set(prompt.name, config.name);
+        if (config.prompts !== false) {
+            try {
+                const { prompts: rawPrompts } = await client.listPrompts();
+                prompts = this.useNamespacing
+                    ? rawPrompts.map((prompt) => ({
+                        ...prompt,
+                        name: namespaceName(config.name, prompt.name),
+                    }))
+                    : rawPrompts;
+                for (const prompt of prompts) {
+                    this.promptToMcp.set(prompt.name, config.name);
+                }
+            }
+            catch {
+                logger.debug({ mcp: config.name }, "Server doesn't support prompts");
             }
         }
-        catch {
-            logger.debug({ mcp: config.name }, "Server doesn't support prompts");
+        else {
+            logger.debug({ mcp: config.name }, "Prompts disabled by config");
         }
         this.mcps.set(config.name, {
             name: config.name,
@@ -217,91 +227,94 @@ export class McpManager {
         }
         return { servers };
     }
-    async callTool(toolName, args) {
-        const mcpName = this.toolToMcp.get(toolName);
+    async callTool(params) {
+        const mcpName = this.toolToMcp.get(params.name);
         if (!mcpName) {
-            logger.warn(`Unknown tool called: ${toolName}`);
-            throw new Error(`Unknown tool: ${toolName}`);
+            logger.warn(`Unknown tool called: ${params.name}`);
+            throw new Error(`Unknown tool: ${params.name}`);
         }
         const mcp = this.mcps.get(mcpName);
         if (!mcp) {
-            logger.error({ mcpName }, `MCP not found for tool: ${toolName}`);
+            logger.error({ mcpName }, `MCP not found for tool: ${params.name}`);
             throw new Error(`MCP not found: ${mcpName}`);
         }
         // Strip namespace prefix to get original tool name
         const originalName = this.useNamespacing
-            ? stripNamespace(mcpName, toolName)
-            : toolName;
-        logger.info({ args }, `Tool call: ${toolName}`);
+            ? stripNamespace(mcpName, params.name)
+            : params.name;
+        logger.info({ arguments: params.arguments }, `Tool call: ${params.name}`);
         const startTime = Date.now();
         const result = await mcp.client.callTool({
             name: originalName,
-            arguments: args,
+            arguments: params.arguments,
         });
         const duration = Date.now() - startTime;
         logger.info({
             duration: `${duration}ms`,
             isError: result.isError ?? false,
-        }, `Tool result: ${toolName}`);
+        }, `Tool result: ${params.name}`);
         return result;
     }
-    async readResource(resourceUri) {
-        const mcpName = this.resourceToMcp.get(resourceUri);
+    async readResource(params) {
+        const mcpName = this.resourceToMcp.get(params.uri);
         if (!mcpName) {
-            logger.warn(`Unknown resource: ${resourceUri}`);
-            throw new Error(`Unknown resource: ${resourceUri}`);
+            logger.warn(`Unknown resource: ${params.uri}`);
+            throw new Error(`Unknown resource: ${params.uri}`);
         }
         const mcp = this.mcps.get(mcpName);
         if (!mcp) {
-            logger.error({ mcpName }, `MCP not found for resource: ${resourceUri}`);
+            logger.error({ mcpName }, `MCP not found for resource: ${params.uri}`);
             throw new Error(`MCP not found: ${mcpName}`);
         }
         // Strip namespace prefix to get original URI
         const originalUri = this.useNamespacing
-            ? stripNamespace(mcpName, resourceUri)
-            : resourceUri;
-        logger.info(`Resource read: ${resourceUri}`);
+            ? stripNamespace(mcpName, params.uri)
+            : params.uri;
+        logger.info(`Resource read: ${params.uri}`);
         const startTime = Date.now();
         const result = await mcp.client.readResource({ uri: originalUri });
         const duration = Date.now() - startTime;
-        logger.info({ duration: `${duration}ms` }, `Resource result: ${resourceUri}`);
+        logger.info({ duration: `${duration}ms` }, `Resource result: ${params.uri}`);
         return result;
     }
-    async getPrompt(promptName, args) {
-        const mcpName = this.promptToMcp.get(promptName);
+    async getPrompt(params) {
+        const mcpName = this.promptToMcp.get(params.name);
         if (!mcpName) {
-            logger.warn(`Unknown prompt: ${promptName}`);
-            throw new Error(`Unknown prompt: ${promptName}`);
+            logger.warn(`Unknown prompt: ${params.name}`);
+            throw new Error(`Unknown prompt: ${params.name}`);
         }
         const mcp = this.mcps.get(mcpName);
         if (!mcp) {
-            logger.error({ mcpName }, `MCP not found for prompt: ${promptName}`);
+            logger.error({ mcpName }, `MCP not found for prompt: ${params.name}`);
             throw new Error(`MCP not found: ${mcpName}`);
         }
         // Strip namespace prefix to get original name
         const originalName = this.useNamespacing
-            ? stripNamespace(mcpName, promptName)
-            : promptName;
-        logger.info({ args }, `Prompt get: ${promptName}`);
+            ? stripNamespace(mcpName, params.name)
+            : params.name;
+        logger.info({ arguments: params.arguments }, `Prompt get: ${params.name}`);
         const startTime = Date.now();
         const result = await mcp.client.getPrompt({
             name: originalName,
-            arguments: args,
+            arguments: params.arguments,
         });
         const duration = Date.now() - startTime;
-        logger.info({ duration: `${duration}ms` }, `Prompt result: ${promptName}`);
+        logger.info({ duration: `${duration}ms` }, `Prompt result: ${params.name}`);
         return result;
     }
-    async complete(ref, argument) {
-        const { mcpName, originalRef } = this.resolveCompletionRef(ref);
+    async complete(params) {
+        const { mcpName, originalRef } = this.resolveCompletionRef(params.ref);
         const mcp = this.mcps.get(mcpName);
         if (!mcp) {
             logger.error({ mcpName }, "MCP not found for completion");
             throw new Error(`MCP not found: ${mcpName}`);
         }
-        logger.info({ ref, argument }, "Completion request");
+        logger.info({ ref: params.ref, argument: params.argument }, "Completion request");
         const startTime = Date.now();
-        const result = await mcp.client.complete({ ref: originalRef, argument });
+        const result = await mcp.client.complete({
+            ref: originalRef,
+            argument: params.argument,
+        });
         const duration = Date.now() - startTime;
         logger.info({ duration: `${duration}ms` }, "Completion result");
         return result;

package/dist/server.js

@@ -7,7 +7,7 @@ import { OAuthServer } from "./auth/oauth.js";
 import { GitHubIdentityProvider } from "./auth/providers/github.js";
 import { LocalIdentityProvider } from "./auth/providers/local.js";
 import { logger } from "./logger.js";
-import { handleCompletionComplete, handleInitialize, handleInitialized, handleMethodNotFound, handlePing, handlePromptsGet, handlePromptsList, handleResourcesList, handleResourcesRead, handleToolsCall, handleToolsList, } from "./mcp/handlers.js";
+import { createMcpHandler } from "./mcp/handler.js";
 import { McpManager } from "./mcp/manager.js";
 import { MemoryStore } from "./storage/memory.js";
 import { SqliteStore } from "./storage/sqlite.js";
@@ -150,67 +150,15 @@ export async function createServer(config) {
         }
         return next();
     });
-    // MCP handler
-    const handleMcp = async (c) => {
-        let message;
-        try {
-            message = await c.req.json();
-        }
-        catch (e) {
-            logger.warn({ error: e instanceof Error ? e.message : String(e) }, "MCP parse error");
-            return c.json({
-                jsonrpc: "2.0",
-                error: { code: -32700, message: "Parse error" },
-                id: null,
-            }, 400);
-        }
-        const method = "method" in message ? message.method : undefined;
-        const id = "id" in message ? message.id : undefined;
-        logger.debug({ method, id }, "MCP request");
-        if (method === "initialize") {
-            return handleInitialize(c, message);
-        }
-        if (method === "notifications/initialized") {
-            return handleInitialized(c);
-        }
-        if (method === "tools/list") {
-            return handleToolsList(c, message, mcpManager);
-        }
-        if (method === "tools/call") {
-            const params = message.params;
-            return handleToolsCall(c, message, mcpManager, params);
-        }
-        if (method === "resources/list") {
-            return handleResourcesList(c, message, mcpManager);
-        }
-        if (method === "resources/read") {
-            const params = message.params;
-            return handleResourcesRead(c, message, mcpManager, params);
-        }
-        if (method === "prompts/list") {
-            return handlePromptsList(c, message, mcpManager);
-        }
-        if (method === "prompts/get") {
-            const params = message.params;
-            return handlePromptsGet(c, message, mcpManager, params);
-        }
-        if (method === "ping") {
-            return handlePing(c, message);
-        }
-        if (method === "completion/complete") {
-            const params = message.params;
-            return handleCompletionComplete(c, message, mcpManager, params);
-        }
-        return handleMethodNotFound(c, message, method ?? "unknown");
-    };
     // Status endpoint (protected)
     protectedRoutes.get("/status", async (c) => {
         const health = await mcpManager.checkHealth();
         return c.json({ servers: health.servers });
     });
     // MCP endpoints (protected)
-    protectedRoutes.post("/", handleMcp);
-    protectedRoutes.post("/mcp", handleMcp);
+    const mcp = createMcpHandler(mcpManager);
+    protectedRoutes.post("/", mcp);
+    protectedRoutes.post("/mcp", mcp);
     // Mount protected routes
     app.route("/", protectedRoutes);
     // 404 for other routes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpbox",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "A lightweight gateway that exposes local stdio-based MCP servers via Streamable HTTP",
   "main": "dist/index.js",
   "bin": {
@@ -18,7 +18,10 @@
     "test:conformance:oauth": "node --disable-warning=ExperimentalWarning --import tsx --test --test-concurrency=1 'test/conformance-oauth/**/*.test.ts'",
     "test:coverage": "node --experimental-test-coverage --disable-warning=ExperimentalWarning --import tsx --test --test-concurrency=1 'test/unit/**/*.test.ts' 'test/integration/**/*.test.ts' 'test/conformance-oauth/**/*.test.ts'",
     "format": "biome check --write .",
-    "check": "biome check ."
+    "check": "biome check .",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "keywords": [
     "mcp",
@@ -51,7 +54,7 @@
   "dependencies": {
     "@hono/node-server": "^1.19.9",
     "@modelcontextprotocol/sdk": "^1.25.3",
-    "bcryptjs": "^2.4.3",
+    "bcryptjs": "^3.0.0",
     "hono": "^4.11.7",
     "pino": "^10.3.0",
     "pino-pretty": "^13.1.3",
@@ -59,9 +62,9 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.14",
-    "@types/bcryptjs": "^2.4.6",
     "@types/node": "^25.1.0",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitepress": "^1.6.4"
   }
 }

package/dist/mcp/handlers.d.ts

@@ -1,433 +0,0 @@
-import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
-import type { Context } from "hono";
-import type { McpManager } from "./manager.js";
-export declare function handleInitialize(c: Context, message: JSONRPCMessage): Response & import("hono").TypedResponse<{
-    jsonrpc: string;
-    id: string | number | undefined;
-    result: {
-        protocolVersion: string;
-        capabilities: {
-            tools: {
-                listChanged: true;
-            };
-            resources: {
-                listChanged: true;
-            };
-            prompts: {
-                listChanged: true;
-            };
-            completions: {};
-        };
-        serverInfo: {
-            name: string;
-            version: string;
-        };
-    };
-}, import("hono/utils/http-status").ContentfulStatusCode, "json">;
-export declare function handleInitialized(c: Context): Response & import("hono").TypedResponse<null, 202, "body">;
-export declare function handleToolsList(c: Context, message: JSONRPCMessage, mcpManager: McpManager): Response & import("hono").TypedResponse<{
-    jsonrpc: string;
-    id: string | number | undefined;
-    result: {
-        tools: {
-            inputSchema: {
-                [x: string]: import("hono/utils/types").JSONValue;
-                type: "object";
-                properties?: {
-                    [x: string]: never;
-                } | undefined;
-                required?: string[] | undefined;
-            };
-            name: string;
-            description?: string | undefined;
-            outputSchema?: {
-                [x: string]: import("hono/utils/types").JSONValue;
-                type: "object";
-                properties?: {
-                    [x: string]: never;
-                } | undefined;
-                required?: string[] | undefined;
-            } | undefined;
-            annotations?: {
-                title?: string | undefined;
-                readOnlyHint?: boolean | undefined;
-                destructiveHint?: boolean | undefined;
-                idempotentHint?: boolean | undefined;
-                openWorldHint?: boolean | undefined;
-            } | undefined;
-            execution?: {
-                taskSupport?: "optional" | "required" | "forbidden" | undefined;
-            } | undefined;
-            _meta?: {
-                [x: string]: import("hono/utils/types").JSONValue;
-            } | undefined;
-            icons?: {
-                src: string;
-                mimeType?: string | undefined;
-                sizes?: string[] | undefined;
-                theme?: "light" | "dark" | undefined;
-            }[] | undefined;
-            title?: string | undefined;
-        }[];
-    };
-}, import("hono/utils/http-status").ContentfulStatusCode, "json">;
-export declare function handleToolsCall(c: Context, message: JSONRPCMessage, mcpManager: McpManager, params: {
-    name: string;
-    arguments?: Record<string, unknown>;
-}): Promise<(Response & import("hono").TypedResponse<{
-    jsonrpc: string;
-    id: string | number | undefined;
-    result: {
-        [x: string]: import("hono/utils/types").JSONValue;
-        content: ({
-            type: "text";
-            text: string;
-            annotations?: {
-                audience?: ("user" | "assistant")[] | undefined;
-                priority?: number | undefined;
-                lastModified?: string | undefined;
-            } | undefined;
-            _meta?: {
-                [x: string]: import("hono/utils/types").JSONValue;
-            } | undefined;
-        } | {
-            type: "image";
-            data: string;
-            mimeType: string;
-            annotations?: {
-                audience?: ("user" | "assistant")[] | undefined;
-                priority?: number | undefined;
-                lastModified?: string | undefined;
-            } | undefined;
-            _meta?: {
-                [x: string]: import("hono/utils/types").JSONValue;
-            } | undefined;
-        } | {
-            type: "audio";
-            data: string;
-            mimeType: string;
-            annotations?: {
-                audience?: ("user" | "assistant")[] | undefined;
-                priority?: number | undefined;
-                lastModified?: string | undefined;
-            } | undefined;
-            _meta?: {
-                [x: string]: import("hono/utils/types").JSONValue;
-            } | undefined;
-        } | {
-            uri: string;
-            name: string;
-            type: "resource_link";
-            description?: string | undefined;
-            mimeType?: string | undefined;
-            annotations?: {
-                audience?: ("user" | "assistant")[] | undefined;
-                priority?: number | undefined;
-                lastModified?: string | undefined;
-            } | undefined;
-            _meta?: {
-                [x: string]: import("hono/utils/types").JSONValue;
-            } | undefined;
-            icons?: {
-                src: string;
-                mimeType?: string | undefined;
-                sizes?: string[] | undefined;
-                theme?: "light" | "dark" | undefined;
-            }[] | undefined;
-            title?: string | undefined;
-        } | {
-            type: "resource";
-            resource: {
-                uri: string;
-                text: string;
-                mimeType?: string | undefined;
-                _meta?: {
-                    [x: string]: import("hono/utils/types").JSONValue;
-                } | undefined;
-            } | {
-                uri: string;
-                blob: string;
-                mimeType?: string | undefined;
-                _meta?: {
-                    [x: string]: import("hono/utils/types").JSONValue;
-                } | undefined;
-            };
-            annotations?: {
-                audience?: ("user" | "assistant")[] | undefined;
-                priority?: number | undefined;
-                lastModified?: string | undefined;
-            } | undefined;
-            _meta?: {
-                [x: string]: import("hono/utils/types").JSONValue;
-            } | undefined;
-        })[];
-        _meta?: {
-            [x: string]: import("hono/utils/types").JSONValue;
-            progressToken?: string | number | undefined;
-            "io.modelcontextprotocol/related-task"?: {
-                taskId: string;
-            } | undefined;
-        } | undefined;
-        structuredContent?: {
-            [x: string]: import("hono/utils/types").JSONValue;
-        } | undefined;
-        isError?: boolean | undefined;
-    };
-}, import("hono/utils/http-status").ContentfulStatusCode, "json">) | (Response & import("hono").TypedResponse<{
-    jsonrpc: string;
-    id: string | number | undefined;
-    error: {
-        code: number;
-        message: string;
-    };
-}, import("hono/utils/http-status").ContentfulStatusCode, "json">)>;
-export declare function handlePing(c: Context, message: JSONRPCMessage): Response & import("hono").TypedResponse<{
-    jsonrpc: string;
-    id: string | number | undefined;
-    result: {};
-}, import("hono/utils/http-status").ContentfulStatusCode, "json">;
-export declare function handleResourcesList(c: Context, message: JSONRPCMessage, mcpManager: McpManager): Response & import("hono").TypedResponse<{
-    jsonrpc: string;
-    id: string | number | undefined;
-    result: {
-        resources: {
-            uri: string;
-            name: string;
-            description?: string | undefined;
-            mimeType?: string | undefined;
-            annotations?: {
-                audience?: ("user" | "assistant")[] | undefined;
-                priority?: number | undefined;
-                lastModified?: string | undefined;
-            } | undefined;
-            _meta?: {
-                [x: string]: import("hono/utils/types").JSONValue;
-            } | undefined;
-            icons?: {
-                src: string;
-                mimeType?: string | undefined;
-                sizes?: string[] | undefined;
-                theme?: "light" | "dark" | undefined;
-            }[] | undefined;
-            title?: string | undefined;
-        }[];
-    };
-}, import("hono/utils/http-status").ContentfulStatusCode, "json">;
-export declare function handleResourcesRead(c: Context, message: JSONRPCMessage, mcpManager: McpManager, params: {
-    uri: string;
-}): Promise<(Response & import("hono").TypedResponse<{
-    jsonrpc: string;
-    id: string | number | undefined;
-    result: {
-        [x: string]: import("hono/utils/types").JSONValue;
-        contents: ({
-            uri: string;
-            text: string;
-            mimeType?: string | undefined;
-            _meta?: {
-                [x: string]: import("hono/utils/types").JSONValue;
-            } | undefined;
-        } | {
-            uri: string;
-            blob: string;
-            mimeType?: string | undefined;
-            _meta?: {
-                [x: string]: import("hono/utils/types").JSONValue;
-            } | undefined;
-        })[];
-        _meta?: {
-            [x: string]: import("hono/utils/types").JSONValue;
-            progressToken?: string | number | undefined;
-            "io.modelcontextprotocol/related-task"?: {
-                taskId: string;
-            } | undefined;
-        } | undefined;
-    };
-}, import("hono/utils/http-status").ContentfulStatusCode, "json">) | (Response & import("hono").TypedResponse<{
-    jsonrpc: string;
-    id: string | number | undefined;
-    error: {
-        code: number;
-        message: string;
-    };
-}, import("hono/utils/http-status").ContentfulStatusCode, "json">)>;
-export declare function handlePromptsList(c: Context, message: JSONRPCMessage, mcpManager: McpManager): Response & import("hono").TypedResponse<{
-    jsonrpc: string;
-    id: string | number | undefined;
-    result: {
-        prompts: {
-            name: string;
-            description?: string | undefined;
-            arguments?: {
-                name: string;
-                description?: string | undefined;
-                required?: boolean | undefined;
-            }[] | undefined;
-            _meta?: {
-                [x: string]: import("hono/utils/types").JSONValue;
-            } | undefined;
-            icons?: {
-                src: string;
-                mimeType?: string | undefined;
-                sizes?: string[] | undefined;
-                theme?: "light" | "dark" | undefined;
-            }[] | undefined;
-            title?: string | undefined;
-        }[];
-    };
-}, import("hono/utils/http-status").ContentfulStatusCode, "json">;
-export declare function handlePromptsGet(c: Context, message: JSONRPCMessage, mcpManager: McpManager, params: {
-    name: string;
-    arguments?: Record<string, string>;
-}): Promise<(Response & import("hono").TypedResponse<{
-    jsonrpc: string;
-    id: string | number | undefined;
-    result: {
-        [x: string]: import("hono/utils/types").JSONValue;
-        messages: {
-            role: "user" | "assistant";
-            content: {
-                type: "text";
-                text: string;
-                annotations?: {
-                    audience?: ("user" | "assistant")[] | undefined;
-                    priority?: number | undefined;
-                    lastModified?: string | undefined;
-                } | undefined;
-                _meta?: {
-                    [x: string]: import("hono/utils/types").JSONValue;
-                } | undefined;
-            } | {
-                type: "image";
-                data: string;
-                mimeType: string;
-                annotations?: {
-                    audience?: ("user" | "assistant")[] | undefined;
-                    priority?: number | undefined;
-                    lastModified?: string | undefined;
-                } | undefined;
-                _meta?: {
-                    [x: string]: import("hono/utils/types").JSONValue;
-                } | undefined;
-            } | {
-                type: "audio";
-                data: string;
-                mimeType: string;
-                annotations?: {
-                    audience?: ("user" | "assistant")[] | undefined;
-                    priority?: number | undefined;
-                    lastModified?: string | undefined;
-                } | undefined;
-                _meta?: {
-                    [x: string]: import("hono/utils/types").JSONValue;
-                } | undefined;
-            } | {
-                uri: string;
-                name: string;
-                type: "resource_link";
-                description?: string | undefined;
-                mimeType?: string | undefined;
-                annotations?: {
-                    audience?: ("user" | "assistant")[] | undefined;
-                    priority?: number | undefined;
-                    lastModified?: string | undefined;
-                } | undefined;
-                _meta?: {
-                    [x: string]: import("hono/utils/types").JSONValue;
-                } | undefined;
-                icons?: {
-                    src: string;
-                    mimeType?: string | undefined;
-                    sizes?: string[] | undefined;
-                    theme?: "light" | "dark" | undefined;
-                }[] | undefined;
-                title?: string | undefined;
-            } | {
-                type: "resource";
-                resource: {
-                    uri: string;
-                    text: string;
-                    mimeType?: string | undefined;
-                    _meta?: {
-                        [x: string]: import("hono/utils/types").JSONValue;
-                    } | undefined;
-                } | {
-                    uri: string;
-                    blob: string;
-                    mimeType?: string | undefined;
-                    _meta?: {
-                        [x: string]: import("hono/utils/types").JSONValue;
-                    } | undefined;
-                };
-                annotations?: {
-                    audience?: ("user" | "assistant")[] | undefined;
-                    priority?: number | undefined;
-                    lastModified?: string | undefined;
-                } | undefined;
-                _meta?: {
-                    [x: string]: import("hono/utils/types").JSONValue;
-                } | undefined;
-            };
-        }[];
-        _meta?: {
-            [x: string]: import("hono/utils/types").JSONValue;
-            progressToken?: string | number | undefined;
-            "io.modelcontextprotocol/related-task"?: {
-                taskId: string;
-            } | undefined;
-        } | undefined;
-        description?: string | undefined;
-    };
-}, import("hono/utils/http-status").ContentfulStatusCode, "json">) | (Response & import("hono").TypedResponse<{
-    jsonrpc: string;
-    id: string | number | undefined;
-    error: {
-        code: number;
-        message: string;
-    };
-}, import("hono/utils/http-status").ContentfulStatusCode, "json">)>;
-export declare function handleCompletionComplete(c: Context, message: JSONRPCMessage, mcpManager: McpManager, params: {
-    ref: {
-        type: string;
-        name?: string;
-        uri?: string;
-    };
-    argument: {
-        name: string;
-        value: string;
-    };
-}): Promise<(Response & import("hono").TypedResponse<{
-    jsonrpc: string;
-    id: string | number | undefined;
-    result: {
-        [x: string]: import("hono/utils/types").JSONValue;
-        completion: {
-            [x: string]: import("hono/utils/types").JSONValue;
-            values: string[];
-            total?: number | undefined;
-            hasMore?: boolean | undefined;
-        };
-        _meta?: {
-            [x: string]: import("hono/utils/types").JSONValue;
-            progressToken?: string | number | undefined;
-            "io.modelcontextprotocol/related-task"?: {
-                taskId: string;
-            } | undefined;
-        } | undefined;
-    };
-}, import("hono/utils/http-status").ContentfulStatusCode, "json">) | (Response & import("hono").TypedResponse<{
-    jsonrpc: string;
-    id: string | number | undefined;
-    error: {
-        code: number;
-        message: string;
-    };
-}, import("hono/utils/http-status").ContentfulStatusCode, "json">)>;
-export declare function handleMethodNotFound(c: Context, message: JSONRPCMessage, method: string): Response & import("hono").TypedResponse<{
-    jsonrpc: string;
-    id: string | number | null;
-    error: {
-        code: number;
-        message: string;
-    };
-}, import("hono/utils/http-status").ContentfulStatusCode, "json">;

package/dist/mcp/handlers.js

@@ -1,144 +0,0 @@
-import { NAME, VERSION } from "../version.js";
-function getMessageId(message) {
-    return "id" in message ? message.id : undefined;
-}
-export function handleInitialize(c, message) {
-    return c.json({
-        jsonrpc: "2.0",
-        id: getMessageId(message),
-        result: {
-            protocolVersion: "2025-11-25",
-            capabilities: {
-                tools: { listChanged: true },
-                resources: { listChanged: true },
-                prompts: { listChanged: true },
-                completions: {},
-            },
-            serverInfo: {
-                name: NAME,
-                version: VERSION,
-            },
-        },
-    });
-}
-export function handleInitialized(c) {
-    return c.body(null, 202);
-}
-export function handleToolsList(c, message, mcpManager) {
-    const tools = mcpManager.listTools();
-    return c.json({
-        jsonrpc: "2.0",
-        id: getMessageId(message),
-        result: { tools },
-    });
-}
-export async function handleToolsCall(c, message, mcpManager, params) {
-    try {
-        const result = await mcpManager.callTool(params.name, params.arguments ?? {});
-        return c.json({
-            jsonrpc: "2.0",
-            id: getMessageId(message),
-            result,
-        });
-    }
-    catch (error) {
-        return c.json({
-            jsonrpc: "2.0",
-            id: getMessageId(message),
-            error: {
-                code: -32603,
-                message: error instanceof Error ? error.message : "Internal error",
-            },
-        });
-    }
-}
-export function handlePing(c, message) {
-    return c.json({
-        jsonrpc: "2.0",
-        id: getMessageId(message),
-        result: {},
-    });
-}
-export function handleResourcesList(c, message, mcpManager) {
-    const resources = mcpManager.listResources();
-    return c.json({
-        jsonrpc: "2.0",
-        id: getMessageId(message),
-        result: { resources },
-    });
-}
-export async function handleResourcesRead(c, message, mcpManager, params) {
-    try {
-        const result = await mcpManager.readResource(params.uri);
-        return c.json({
-            jsonrpc: "2.0",
-            id: getMessageId(message),
-            result,
-        });
-    }
-    catch (error) {
-        return c.json({
-            jsonrpc: "2.0",
-            id: getMessageId(message),
-            error: {
-                code: -32603,
-                message: error instanceof Error ? error.message : "Internal error",
-            },
-        });
-    }
-}
-export function handlePromptsList(c, message, mcpManager) {
-    const prompts = mcpManager.listPrompts();
-    return c.json({
-        jsonrpc: "2.0",
-        id: getMessageId(message),
-        result: { prompts },
-    });
-}
-export async function handlePromptsGet(c, message, mcpManager, params) {
-    try {
-        const result = await mcpManager.getPrompt(params.name, params.arguments);
-        return c.json({
-            jsonrpc: "2.0",
-            id: getMessageId(message),
-            result,
-        });
-    }
-    catch (error) {
-        return c.json({
-            jsonrpc: "2.0",
-            id: getMessageId(message),
-            error: {
-                code: -32603,
-                message: error instanceof Error ? error.message : "Internal error",
-            },
-        });
-    }
-}
-export async function handleCompletionComplete(c, message, mcpManager, params) {
-    try {
-        const result = await mcpManager.complete(params.ref, params.argument);
-        return c.json({
-            jsonrpc: "2.0",
-            id: getMessageId(message),
-            result,
-        });
-    }
-    catch (error) {
-        return c.json({
-            jsonrpc: "2.0",
-            id: getMessageId(message),
-            error: {
-                code: -32603,
-                message: error instanceof Error ? error.message : "Internal error",
-            },
-        });
-    }
-}
-export function handleMethodNotFound(c, message, method) {
-    return c.json({
-        jsonrpc: "2.0",
-        id: getMessageId(message) ?? null,
-        error: { code: -32601, message: `Method not found: ${method}` },
-    });
-}