mcpbox 0.1.1 → 0.2.1

package/README.md

@@ -7,12 +7,15 @@
 
 **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.
 
-- Aggregate multiple local stdio servers behind a single HTTP endpoint
+- Runs multiple MCP stdio servers behind a single HTTP endpoint
 - Exposes Tools, Resources & Prompts
-- Namespaces with `servername__` prefix to avoid collisions (e.g., `github__create_issue`)
+- Namespaces with `servername__` prefix to avoid collisions
 - OAuth or API key authentication
 
-![mcpbox diagram](assets/diagram.excalidraw.png)
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/diagram-dark.excalidraw.png">
+  <img src="assets/diagram.excalidraw.png" alt="mcpbox diagram">
+</picture>
 
 ## Quick Start
 
@@ -62,25 +65,18 @@ For remote access with authentication, see [Deployment](#deployment) and [Connec
 
 ## Configuration
 
-See [`mcpbox.example.jsonc`](mcpbox.example.jsonc) for all options.
+See [`mcpbox.example.jsonc`](mcpbox.example.jsonc) for all options. All string values support `${VAR_NAME}` environment variable substitution.
 
-**Authentication** — choose one:
-- **None** — default
-- **API Key** — `auth.type: "apikey"` with `auth.apiKey`
-- **OAuth** — `auth.type: "oauth"` with users, clients, and optional dynamic registration
-
-**Storage** (for OAuth):
-- **Memory** — default, tokens lost on restart
-- **SQLite** — `storage.type: "sqlite"` for persistence
+**[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:
-- [ ] Use `storage.type: "sqlite"` for persistence across restarts
-- [ ] Set `auth.issuer` to your public URL when using OAuth
-- [ ] Use bcrypt hashes for passwords
+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.
@@ -100,8 +96,10 @@ Then update your config with the generated public URL:
   "auth": {
     "type": "oauth",
     "issuer": "https://<tunnel-id>.trycloudflare.com",
-    "users": [{ "username": "admin", "password": "${MCPBOX_PASSWORD}" }],
-    "dynamic_registration": true
+    "identityProviders": [
+      { "type": "local", "users": [{ "username": "admin", "password": "${MCPBOX_PASSWORD}" }] }
+    ],
+    "dynamicRegistration": true
   },
   "storage": {
     "type": "sqlite",
@@ -123,7 +121,7 @@ docker run -v ./mcpbox.json:/config/config.json -v ./data:/data -p 8080:8080 ghc
 
 Settings → Connectors → Add Custom Connector → enter your URL → Connect
 
-Requires `dynamic_registration: true` in your config.
+Requires `dynamicRegistration: true` in your config.
 
 ### Claude Code
 
@@ -131,14 +129,30 @@ Requires `dynamic_registration: true` in your config.
 claude mcp add --transport http mcpbox https://your-mcpbox-url.com
 ```
 
-Requires `dynamic_registration: true` in your config.
+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"
+    }
+  }
+}
+```
 
-### MCP clients with JSON config
+**With API key:**
 
 ```json
 {
   "mcpServers": {
     "mcpbox": {
+      "type": "http",
       "url": "https://your-mcpbox-url.com",
       "headers": {
         "Authorization": "Bearer YOUR_API_KEY"

package/dist/auth/crypto.d.ts

@@ -1,4 +1,5 @@
 /**
  * Timing-safe string comparison to prevent timing attacks.
+ * @package
  */
 export declare function safeCompare(a: string, b: string): boolean;

package/dist/auth/crypto.js

@@ -1,6 +1,7 @@
 import { timingSafeEqual } from "node:crypto";
 /**
  * Timing-safe string comparison to prevent timing attacks.
+ * @package
  */
 export function safeCompare(a, b) {
     try {

package/dist/auth/oauth-utils.d.ts

@@ -2,28 +2,34 @@ import type { StoredClient } from "../storage/types.js";
 /**
  * Hash a secret using SHA-256.
  * Used for storing tokens and client secrets.
+ * @package
  */
 export declare function hashSecret(secret: string): string;
 /**
  * Verify a client secret against a stored hash using timing-safe comparison.
+ * @package
  */
 export declare function verifyClientSecret(input: string, storedHash: string): boolean;
 /**
  * Check if a password string is a bcrypt hash.
+ * @package
  */
 export declare function isBcryptHash(password: string): boolean;
 /**
  * Verify a password against a stored value.
  * Supports both plain text (timing-safe) and bcrypt hashed passwords.
+ * @package
  */
 export declare function verifyPassword(input: string, stored: string): boolean;
 /**
  * Check if a redirect URI is allowed for a client.
  * Uses exact string matching as required by OAuth 2.0 spec.
+ * @package
  */
 export declare function isRedirectUriAllowed(redirectUri: string, client: StoredClient): boolean;
 /**
  * Parse a Bearer token from an Authorization header.
  * Returns null if the header is missing or malformed.
+ * @package
  */
 export declare function parseBearerToken(authHeader: string | undefined): string | null;

package/dist/auth/oauth-utils.js

@@ -4,18 +4,21 @@ import { safeCompare } from "./crypto.js";
 /**
  * Hash a secret using SHA-256.
  * Used for storing tokens and client secrets.
+ * @package
  */
 export function hashSecret(secret) {
     return createHash("sha256").update(secret).digest("hex");
 }
 /**
  * Verify a client secret against a stored hash using timing-safe comparison.
+ * @package
  */
 export function verifyClientSecret(input, storedHash) {
     return safeCompare(hashSecret(input), storedHash);
 }
 /**
  * Check if a password string is a bcrypt hash.
+ * @package
  */
 export function isBcryptHash(password) {
     return /^\$2[aby]\$\d{2}\$/.test(password);
@@ -23,6 +26,7 @@ export function isBcryptHash(password) {
 /**
  * Verify a password against a stored value.
  * Supports both plain text (timing-safe) and bcrypt hashed passwords.
+ * @package
  */
 export function verifyPassword(input, stored) {
     if (isBcryptHash(stored)) {
@@ -33,13 +37,15 @@ export function verifyPassword(input, stored) {
 /**
  * Check if a redirect URI is allowed for a client.
  * Uses exact string matching as required by OAuth 2.0 spec.
+ * @package
  */
 export function isRedirectUriAllowed(redirectUri, client) {
-    return client.redirect_uris?.includes(redirectUri) ?? false;
+    return client.redirectUris?.includes(redirectUri) ?? false;
 }
 /**
  * Parse a Bearer token from an Authorization header.
  * Returns null if the header is missing or malformed.
+ * @package
  */
 export function parseBearerToken(authHeader) {
     if (!authHeader) {

package/dist/auth/oauth.d.ts

@@ -1,12 +1,10 @@
 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 {
     issuer: string;
-    users?: Array<{
-        username: string;
-        password: string;
-    }>;
+    providers: IdentityProvider[];
     clients?: OAuthClient[];
     dynamicRegistration?: boolean;
 }
@@ -22,6 +20,9 @@ export declare class OAuthServer {
     handleRegister(c: Context, body: string): Promise<Response>;
     private getClient;
     handleAuthorize(c: Context, query: URLSearchParams, body?: string): Promise<Response>;
+    private issueAuthorizationCode;
+    private redirectToProvider;
+    handleIdPCallback(c: Context, providerId: string, query: URLSearchParams): Promise<Response>;
     private showLoginForm;
     handleToken(c: Context, body: string): Promise<Response>;
     private handleClientCredentialsGrant;