mcpbox 0.2.2 → 0.3.2

package/README.md

@@ -3,6 +3,8 @@
     <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
     <img src="assets/logo.svg" width="128" alt="MCPBox">
   </picture>
+  <br>
+  <a href="https://www.npmjs.com/package/mcpbox"><img src="https://img.shields.io/npm/v/mcpbox?style=flat-square" alt="npm version"></a>
 </p>
 
 **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.
@@ -11,7 +13,7 @@
 - Supports Tools, Resources & Prompts
 - Namespaces with `servername__` prefix to avoid collisions
 - Per-server tool filtering to limit AI access and reduce context usage
-- OAuth or API key authentication
+- OAuth 2.1, API key, or no auth
 
 <picture>
   <source media="(prefers-color-scheme: dark)" srcset="assets/diagram-dark.excalidraw.png">
@@ -28,137 +30,33 @@ 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
 {
   "mcpServers": {
     "mcpbox": {
-      "type": "http",
       "url": "http://localhost:8080"
     }
   }
 }
 ```
 
-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
+## Documentation
 
-### Claude Web & Mobile
-
-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/auth/oauth.d.ts

@@ -2,7 +2,7 @@ import type { Context } from "hono";
 import type { OAuthClient } from "../config/types.js";
 import type { StateStore } from "../storage/types.js";
 import type { IdentityProvider } from "./providers/identity-provider.js";
-export interface OAuthConfig {
+interface OAuthConfig {
     issuer: string;
     providers: IdentityProvider[];
     clients?: OAuthClient[];
@@ -35,3 +35,4 @@ export declare class OAuthServer {
     };
     sendUnauthorized(c: Context, error?: string): Response;
 }
+export {};

package/dist/auth/oauth.js

@@ -406,7 +406,10 @@ export class OAuthServer {
               box-sizing: border-box;
             }
             body {
-              font-family: system-ui, -apple-system, sans-serif;
+              font-family:
+                system-ui,
+                -apple-system,
+                sans-serif;
               background: #fafaf9;
               margin: 0;
               padding: 20px;
@@ -426,8 +429,8 @@ export class OAuthServer {
               max-width: 380px;
             }
             h1 {
-              font-family: ui-monospace, "SF Mono", Menlo, Monaco, Consolas,
-                monospace;
+              font-family:
+                ui-monospace, "SF Mono", Menlo, Monaco, Consolas, monospace;
               font-size: 28px;
               font-weight: 600;
               color: #1c1917;
@@ -562,11 +565,7 @@ export class OAuthServer {
             ${hasForm && hasRedirect ? html `<div class="divider">or</div>` : ""}
             ${hasForm
             ? html `<form method="POST" action="${formAction}">
-                  <input
-                    type="hidden"
-                    name="session_id"
-                    value="${sessionId}"
-                  />
+                  <input type="hidden" name="session_id" value="${sessionId}" />
                   <div class="field">
                     <label for="username">Username</label>
                     <input

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
@@ -17,28 +19,6 @@ export declare const OAuthUserSchema: z.ZodObject<{
     username: z.ZodString;
     password: z.ZodString;
 }, z.core.$strict>;
-/**
- * Local identity provider — users defined in config.
- * @package
- */
-export declare const LocalIdPSchema: z.ZodObject<{
-    type: z.ZodLiteral<"local">;
-    users: z.ZodArray<z.ZodObject<{
-        username: z.ZodString;
-        password: z.ZodString;
-    }, z.core.$strict>>;
-}, z.core.$strict>;
-/**
- * GitHub identity provider — OAuth web flow.
- * @package
- */
-export declare const GitHubIdPSchema: z.ZodObject<{
-    type: z.ZodLiteral<"github">;
-    clientId: z.ZodString;
-    clientSecret: z.ZodString;
-    allowedOrgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    allowedUsers: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strict>;
 /**
  * Identity provider configuration — discriminated union.
  * @package
@@ -204,6 +184,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 +198,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,19 +266,13 @@ 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>;
-export type OAuthUser = z.infer<typeof OAuthUserSchema>;
 export type OAuthClient = z.infer<typeof OAuthClientSchema>;
-export type IdentityProviderConfig = z.infer<typeof IdentityProviderSchema>;
-export type LocalIdPConfig = z.infer<typeof LocalIdPSchema>;
-export type GitHubIdPConfig = z.infer<typeof GitHubIdPSchema>;
-export type AuthConfig = z.infer<typeof AuthConfigSchema>;
-export type ServerConfig = z.infer<typeof ServerConfigSchema>;
 export type LogConfig = z.infer<typeof LogConfigSchema>;
-export type StorageConfig = z.infer<typeof StorageConfigSchema>;
-export type RawConfig = z.infer<typeof RawConfigSchema>;
+export type McpServerEntry = z.infer<typeof McpServerEntrySchema>;
 export type McpConfig = z.infer<typeof McpConfigSchema>;
 export type Config = z.infer<typeof ConfigSchema>;
 export interface LoadConfigResult {

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();
 /**
@@ -33,7 +35,7 @@ export const OAuthUserSchema = z
  * Local identity provider — users defined in config.
  * @package
  */
-export const LocalIdPSchema = z
+const LocalIdPSchema = z
     .object({
     type: z.literal("local"),
     users: z.array(OAuthUserSchema).min(1, "At least one user is required"),
@@ -43,7 +45,7 @@ export const LocalIdPSchema = z
  * GitHub identity provider — OAuth web flow.
  * @package
  */
-export const GitHubIdPSchema = z
+const GitHubIdPSchema = z
     .object({
     type: z.literal("github"),
     clientId: z.string().min(1, "GitHub clientId is required"),
@@ -201,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/config/types.d.ts

@@ -1,5 +1 @@
-export type { AuthConfig, Config, GitHubIdPConfig, IdentityProviderConfig, LocalIdPConfig, LogConfig, McpConfig, McpServerEntry, OAuthClient, OAuthUser, ServerConfig, StorageConfig, } from "./schema.js";
-export type GrantType = "authorization_code" | "client_credentials";
-export type McpServersConfig = {
-    mcpServers: Record<string, import("./schema.js").McpServerEntry>;
-};
+export type { Config, LogConfig, McpConfig, OAuthClient } from "./schema.js";

package/dist/mcp/manager.d.ts

@@ -1,15 +1,5 @@
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.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;
-    client: Client;
-    transport: StdioClientTransport;
-    tools: Tool[];
-    resources: Resource[];
-    prompts: Prompt[];
-}
 export declare class McpManager {
     private mcps;
     private toolToMcp;

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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcpbox",
-  "version": "0.2.2",
+  "version": "0.3.2",
   "description": "A lightweight gateway that exposes local stdio-based MCP servers via Streamable HTTP",
   "main": "dist/index.js",
   "bin": {
@@ -17,8 +17,13 @@
     "test:conformance:mcp": "node --disable-warning=ExperimentalWarning --import tsx test/conformance-mcp/run.ts",
     "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'",
+    "test:mutation": "stryker run",
     "format": "biome check --write .",
-    "check": "biome check ."
+    "check": "biome check .",
+    "knip": "knip",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs"
   },
   "keywords": [
     "mcp",
@@ -50,17 +55,23 @@
   "type": "module",
   "dependencies": {
     "@hono/node-server": "^1.19.9",
-    "@modelcontextprotocol/sdk": "^1.25.3",
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "bcryptjs": "^3.0.0",
-    "hono": "^4.11.7",
+    "hono": "^4.12.7",
     "pino": "^10.3.0",
     "pino-pretty": "^13.1.3",
     "zod": "^4.3.6"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.14",
+    "@biomejs/biome": "^2.4.7",
+    "@stryker-mutator/core": "^9.6.0",
+    "@stryker-mutator/tap-runner": "^9.6.0",
+    "@stryker-mutator/typescript-checker": "^9.6.0",
     "@types/node": "^25.1.0",
+    "knip": "^5.86.0",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitepress": "^1.6.4",
+    "vitepress-plugin-llms": "^1.11.0"
   }
 }