mcpbox 0.2.2 → 0.3.1

package/README.md

@@ -11,7 +11,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,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
 {
@@ -62,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();
 /**
@@ -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/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.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",
@@ -61,6 +64,7 @@
     "@biomejs/biome": "^2.3.14",
     "@types/node": "^25.1.0",
     "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "vitepress": "^1.6.4"
   }
 }