@aiwerk/mcp-bridge 1.7.1 → 1.8.0

package/README.md

@@ -59,6 +59,26 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
 }
 ```
 
+## Recipe Spec v2
+
+Bundled servers now ship with `recipe.json` using **Universal Recipe Spec v2.0**.
+During install, MCP Bridge prefers `recipe.json` when present and falls back to legacy `config.json` (v1) for backwards compatibility.
+
+- Spec: [`docs/universal-recipe-spec.md`](docs/universal-recipe-spec.md)
+- Runtime compatibility: v1 and v2 are both supported
+- Existing v1-only servers continue to work unchanged
+
+For third-party recipe authors:
+
+1. Author `recipe.json` per the spec above.
+2. Validate your recipe before publishing:
+
+```bash
+npx @aiwerk/mcp-bridge validate-recipe ./recipe.json
+```
+
+`config.json` (v1) remains supported, but `recipe.json` (v2) is the recommended format going forward.
+
 ## Use with Cursor / Windsurf
 
 Add to your MCP config:

package/dist/bin/mcp-bridge.js

@@ -153,7 +153,7 @@ All logs go to stderr. Stdout is reserved for the MCP protocol (stdio mode).
 function cmdInit(logger) {
     initConfigDir(logger);
 }
-function cmdCatalog(logger, offline) {
+function cmdCatalog(logger) {
     const catalogPath = join(PACKAGE_ROOT, "servers", "index.json");
     if (!existsSync(catalogPath)) {
         logger.error("Server catalog not found");
@@ -303,7 +303,7 @@ async function main() {
             cmdInit(logger);
             break;
         case "catalog":
-            cmdCatalog(logger, args.offline);
+            cmdCatalog(logger);
             break;
         case "servers":
             cmdServers(logger, args.configPath);

package/dist/bin/validate-recipe.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for the Universal MCP Recipe Validator.
+ * Usage: npx tsx bin/validate-recipe.ts <path-to-recipe.json>
+ */
+export {};

package/dist/bin/validate-recipe.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for the Universal MCP Recipe Validator.
+ * Usage: npx tsx bin/validate-recipe.ts <path-to-recipe.json>
+ */
+import { validateRecipeFile, formatValidationResult } from "../src/validate-recipe.js";
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        console.log("Usage: validate-recipe <path-to-recipe.json>");
+        console.log("");
+        console.log("Validates a Universal MCP Recipe against spec v2.0.");
+        console.log("Exits 0 if valid, 1 if invalid.");
+        process.exit(0);
+    }
+    const filePath = args[0];
+    let result;
+    try {
+        result = await validateRecipeFile(filePath);
+    }
+    catch (e) {
+        console.error(`❌ Could not read file: ${filePath}`);
+        console.error(`   ${e.message}`);
+        process.exit(1);
+    }
+    const output = formatValidationResult(filePath, result);
+    console.log(output);
+    process.exit(result.valid ? 0 : 1);
+}
+main().catch((e) => {
+    console.error("Unexpected error:", e);
+    process.exit(1);
+});

package/dist/src/config.js

@@ -108,7 +108,11 @@ export function loadConfig(options = {}) {
     }
     // Read and parse config
     const rawConfig = JSON.parse(readFileSync(configPath, "utf-8"));
-    // Resolve ${VAR} placeholders using .env + process.env
+    // Merge order: .env file values take priority over process.env for config resolution.
+    // This is intentional: .env is the user-controlled secrets file, process.env may have
+    // stale or system-level values. Note: dotenv loads .env INTO process.env without
+    // overwriting (opposite direction), but our config resolver uses this merged map
+    // where .env wins.
     const mergedEnv = { ...dotEnv };
     for (const [k, v] of Object.entries(process.env)) {
         if (mergedEnv[k] === undefined)

package/dist/src/embeddings.js

@@ -84,7 +84,13 @@ export class OpenAIEmbedding {
             .map((item) => item.embedding);
     }
     dimensions() {
-        return 1536;
+        if (this.model.includes("3-large"))
+            return 3072;
+        if (this.model.includes("3-small"))
+            return 1536;
+        if (this.model.includes("ada-002"))
+            return 1536;
+        return 1536; // safe default
     }
 }
 export class OllamaEmbedding {

package/dist/src/mcp-router.d.ts

@@ -81,7 +81,7 @@ export declare class McpRouter {
     private readonly maxConcurrent;
     private readonly states;
     private intentRouter;
-    private readonly promotion;
+    private promotion;
     constructor(servers: Record<string, McpServerConfig>, clientConfig: McpClientConfig, logger: Logger, transportRefs?: Partial<RouterTransportRefs>);
     static generateDescription(servers: Record<string, McpServerConfig>): string;
     dispatch(server?: string, action?: string, tool?: string, params?: any): Promise<RouterDispatchResponse>;

package/dist/src/security.d.ts

@@ -23,6 +23,7 @@ export declare function applyMaxResultSize(result: any, serverConfig: McpServerC
  */
 export declare function applyTrustLevel(result: any, serverName: string, serverConfig: McpServerConfig): any;
 /**
- * Full security pipeline: truncate → sanitize → trust-tag
+ * Full security pipeline: truncate → trust-tag (which includes sanitize for trust="sanitize")
+ * Note: sanitization only runs when trust="sanitize". trust="untrusted" wraps without sanitizing.
  */
 export declare function processResult(result: any, serverName: string, serverConfig: McpServerConfig, clientConfig: McpClientConfig): any;

package/dist/src/security.js

@@ -117,7 +117,8 @@ export function applyTrustLevel(result, serverName, serverConfig) {
     }
 }
 /**
- * Full security pipeline: truncate → sanitize → trust-tag
+ * Full security pipeline: truncate → trust-tag (which includes sanitize for trust="sanitize")
+ * Note: sanitization only runs when trust="sanitize". trust="untrusted" wraps without sanitizing.
  */
 export function processResult(result, serverName, serverConfig, clientConfig) {
     let processed = applyMaxResultSize(result, serverConfig, clientConfig);

package/dist/src/standalone-server.d.ts

@@ -9,6 +9,7 @@ export declare class StandaloneServer {
     private logger;
     private router;
     private initialized;
+    private lspMode;
     private directTools;
     private directConnections;
     constructor(config: BridgeConfig, logger: Logger);

package/dist/src/standalone-server.js

@@ -14,6 +14,7 @@ export class StandaloneServer {
     logger;
     router = null;
     initialized = false;
+    lspMode = false;
     // Direct mode state
     directTools = [];
     directConnections = new Map();
@@ -45,9 +46,12 @@ export class StandaloneServer {
                 progress = false;
                 // If we're reading an LSP body, check if we have enough bytes
                 if (lspContentLength >= 0 && lspHeadersDone) {
-                    if (buffer.length >= lspContentLength) {
-                        const body = buffer.slice(0, lspContentLength);
-                        buffer = buffer.slice(lspContentLength);
+                    const bufferBytes = Buffer.byteLength(buffer, "utf8");
+                    if (bufferBytes >= lspContentLength) {
+                        // Extract exactly lspContentLength bytes (LSP spec defines Content-Length in bytes)
+                        const bodyBuffer = Buffer.from(buffer, "utf8").slice(0, lspContentLength);
+                        const body = bodyBuffer.toString("utf8");
+                        buffer = buffer.substring(body.length);
                         lspContentLength = -1;
                         lspHeadersDone = false;
                         const trimmed = body.trim();
@@ -80,6 +84,7 @@ export class StandaloneServer {
                 }
                 if (trimmed.startsWith("Content-Length:")) {
                     // Start of LSP-framed message
+                    this.lspMode = true;
                     const lengthStr = trimmed.slice("Content-Length:".length).trim();
                     const length = parseInt(lengthStr, 10);
                     if (!isNaN(length) && length > 0) {
@@ -135,7 +140,14 @@ export class StandaloneServer {
         });
     }
     writeResponse(stdout, response) {
-        stdout.write(JSON.stringify(response) + "\n");
+        const json = JSON.stringify(response);
+        if (this.lspMode) {
+            const byteLength = Buffer.byteLength(json, "utf8");
+            stdout.write(`Content-Length: ${byteLength}\r\n\r\n${json}`);
+        }
+        else {
+            stdout.write(json + "\n");
+        }
     }
     /** Handle a single MCP JSON-RPC request. */
     async handleRequest(request) {

package/dist/src/transport-sse.d.ts

@@ -3,7 +3,7 @@ import { BaseTransport } from "./transport-base.js";
 export declare class SseTransport extends BaseTransport {
     private endpointUrl;
     private sseAbortController;
-    private currentDataBuffer;
+    private resolvedHeaders;
     protected get transportName(): string;
     connect(): Promise<void>;
     private _onEndpointReceived;

package/dist/src/transport-sse.js

@@ -3,15 +3,15 @@ import { BaseTransport, resolveEnvRecord, warnIfNonTlsRemoteUrl } from "./transp
 export class SseTransport extends BaseTransport {
     endpointUrl = null;
     sseAbortController = null;
-    currentDataBuffer = [];
+    resolvedHeaders = null;
     get transportName() { return "SSE"; }
     async connect() {
         if (!this.config.url) {
             throw new Error("SSE transport requires URL");
         }
         warnIfNonTlsRemoteUrl(this.config.url, this.logger);
-        // Validate that all header env vars resolve (fail fast)
-        resolveEnvRecord(this.config.headers || {}, "header");
+        // Resolve headers once and cache for all subsequent requests
+        this.resolvedHeaders = resolveEnvRecord(this.config.headers || {}, "header");
         if (this.sseAbortController) {
             this.sseAbortController.abort();
         }
@@ -36,10 +36,8 @@ export class SseTransport extends BaseTransport {
     async startEventStream() {
         if (!this.config.url)
             return;
-        const headers = resolveEnvRecord({
-            ...this.config.headers,
-            "Accept": "text/event-stream"
-        }, "header");
+        const base = this.resolvedHeaders ?? resolveEnvRecord(this.config.headers || {}, "header");
+        const headers = { ...base, "Accept": "text/event-stream" };
         try {
             const response = await fetch(this.config.url, {
                 method: "GET",
@@ -132,10 +130,8 @@ export class SseTransport extends BaseTransport {
         if (!this.connected || !this.endpointUrl) {
             throw new Error("SSE transport not connected or no endpoint URL");
         }
-        const headers = resolveEnvRecord({
-            ...this.config.headers,
-            "Content-Type": "application/json"
-        }, "header");
+        const base = this.resolvedHeaders ?? resolveEnvRecord(this.config.headers || {}, "header");
+        const headers = { ...base, "Content-Type": "application/json" };
         const response = await fetch(this.endpointUrl, {
             method: "POST",
             headers,
@@ -158,10 +154,8 @@ export class SseTransport extends BaseTransport {
                 reject(new Error(`Request timeout after ${requestTimeout}ms`));
             }, requestTimeout);
             this.pendingRequests.set(id, { resolve, reject, timeout });
-            const headers = resolveEnvRecord({
-                ...this.config.headers,
-                "Content-Type": "application/json"
-            }, "header");
+            const base = this.resolvedHeaders ?? resolveEnvRecord(this.config.headers || {}, "header");
+            const headers = { ...base, "Content-Type": "application/json" };
             // The response arrives via the SSE stream (handleMessage), not from this fetch.
             // The fetch only confirms the server accepted the request (HTTP 200).
             // If the fetch fails, we reject immediately; otherwise we wait for the SSE stream.

package/dist/src/types.js

@@ -1,5 +1,8 @@
-let globalRequestId = 1;
+let globalRequestId = 0;
 export function nextRequestId() {
-    globalRequestId = (globalRequestId + 1) % Number.MAX_SAFE_INTEGER;
+    globalRequestId++;
+    if (globalRequestId >= Number.MAX_SAFE_INTEGER) {
+        globalRequestId = 1;
+    }
     return globalRequestId;
 }

package/dist/src/validate-recipe.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Universal MCP Recipe Validator (spec v2.0, §7)
+ */
+export interface RecipeTransport {
+    type: string;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    url?: string;
+    headers?: Record<string, string>;
+    framing?: string;
+}
+export interface RecipeInstall {
+    method: string;
+    package?: string;
+    image?: string;
+    repository?: string;
+    buildCommand?: string;
+    binary?: string;
+    version?: string;
+    preInstall?: string[];
+    postInstall?: string[];
+    platforms?: Record<string, unknown>;
+}
+export interface RecipeAuth {
+    required?: boolean;
+    type?: string;
+    envVars?: string[];
+    credentialsUrl?: string;
+    instructions?: string;
+    scopes?: string[];
+    bootstrap?: string;
+}
+export interface RecipeMetadata {
+    homepage?: string;
+    license?: string;
+    author?: string;
+    tags?: string[];
+    category?: string;
+    languages?: string[];
+    pricing?: string;
+    maturity?: string;
+    firstPublished?: string;
+    lastVerified?: string;
+    toolCount?: number;
+    toolExamples?: Array<{
+        name: string;
+        description: string;
+    }>;
+}
+export interface UniversalRecipe {
+    schemaVersion?: unknown;
+    id?: unknown;
+    name?: unknown;
+    description?: unknown;
+    repository?: unknown;
+    transports?: unknown;
+    auth?: RecipeAuth;
+    install?: RecipeInstall;
+    metadata?: RecipeMetadata;
+    capabilities?: unknown;
+    [key: string]: unknown;
+}
+export interface ValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    /** Convenience fields for success output */
+    id?: string;
+    toolCount?: number;
+    primaryTransport?: string;
+    installMethod?: string;
+}
+export declare function validateRecipe(recipe: UniversalRecipe): ValidationResult;
+export declare function validateRecipeFile(filePath: string): Promise<ValidationResult>;
+export declare function formatValidationResult(filePath: string, result: ValidationResult): string;

package/dist/src/validate-recipe.js

@@ -0,0 +1,241 @@
+/**
+ * Universal MCP Recipe Validator (spec v2.0, §7)
+ */
+// ─── Known categories (§3.1) ─────────────────────────────────────────────────
+const KNOWN_CATEGORIES = new Set([
+    "productivity",
+    "development",
+    "communication",
+    "data",
+    "finance",
+    "infrastructure",
+    "analytics",
+    "content",
+    "search",
+    "automation",
+    "security",
+    "ai",
+    "other",
+]);
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+/** Extract all ${VAR} references from a string */
+function extractVarRefs(s) {
+    const matches = s.matchAll(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g);
+    return [...matches].map((m) => m[1]);
+}
+/** Recursively collect all ${VAR} references from an object's string values */
+function collectVarRefs(obj, refs = new Set()) {
+    if (typeof obj === "string") {
+        for (const v of extractVarRefs(obj))
+            refs.add(v);
+    }
+    else if (Array.isArray(obj)) {
+        for (const item of obj)
+            collectVarRefs(item, refs);
+    }
+    else if (obj && typeof obj === "object") {
+        for (const val of Object.values(obj)) {
+            collectVarRefs(val, refs);
+        }
+    }
+    return refs;
+}
+// ─── Core validator ───────────────────────────────────────────────────────────
+export function validateRecipe(recipe) {
+    const errors = [];
+    const warnings = [];
+    // ── §7.1 Rule 1: schemaVersion === 2 ──────────────────────────────────────
+    if (recipe.schemaVersion !== 2) {
+        errors.push(`schemaVersion must be 2, got: ${JSON.stringify(recipe.schemaVersion)}`);
+    }
+    // ── §7.1 Rule 2: id format ─────────────────────────────────────────────────
+    const id = recipe.id;
+    if (typeof id !== "string" || id.length === 0) {
+        errors.push("id is required and must be a non-empty string");
+    }
+    else {
+        if (id.length < 2 || id.length > 64) {
+            errors.push(`id must be 2-64 characters, got ${id.length}`);
+        }
+        if (!/^[a-z0-9][a-z0-9-]*[a-z0-9]$/.test(id)) {
+            errors.push(`id must match ^[a-z0-9][a-z0-9-]*[a-z0-9]$ (lowercase alphanumeric with internal hyphens only), got: "${id}"`);
+        }
+    }
+    // ── §7.1 Rule 3: name ──────────────────────────────────────────────────────
+    const name = recipe.name;
+    if (typeof name !== "string" || name.trim().length === 0) {
+        errors.push("name is required and must be a non-empty string");
+    }
+    else if (name.length > 128) {
+        errors.push(`name must be max 128 chars, got ${name.length}`);
+    }
+    // ── §7.1 Rule 4: description ───────────────────────────────────────────────
+    const desc = recipe.description;
+    if (typeof desc !== "string" || desc.trim().length === 0) {
+        errors.push("description is required and must be a non-empty string");
+    }
+    else if (desc.length > 512) {
+        errors.push(`description must be max 512 chars, got ${desc.length}`);
+    }
+    // ── §7.1 Rule 5: repository or metadata.homepage ──────────────────────────
+    const hasRepository = typeof recipe.repository === "string" && recipe.repository.trim().length > 0;
+    const hasHomepage = typeof recipe.metadata?.homepage === "string" &&
+        recipe.metadata.homepage.trim().length > 0;
+    if (!hasRepository && !hasHomepage) {
+        errors.push("At least one of repository or metadata.homepage must be present");
+    }
+    // ── §7.1 Rules 6 & 7: transports ──────────────────────────────────────────
+    const transports = recipe.transports;
+    if (!Array.isArray(transports) || transports.length === 0) {
+        errors.push("transports must be a non-empty array");
+    }
+    else {
+        let hasStdio = false;
+        let allRemote = true;
+        for (let i = 0; i < transports.length; i++) {
+            const t = transports[i];
+            if (!t || typeof t !== "object") {
+                errors.push(`transports[${i}]: must be an object`);
+                continue;
+            }
+            if (typeof t.type !== "string" || t.type.trim().length === 0) {
+                errors.push(`transports[${i}]: type is required`);
+                continue;
+            }
+            const type = t.type;
+            if (type === "stdio") {
+                hasStdio = true;
+                allRemote = false;
+                if (typeof t.command !== "string" || t.command.trim().length === 0) {
+                    errors.push(`transports[${i}] (stdio): command is required`);
+                }
+            }
+            else if (type === "sse" || type === "streamable-http") {
+                if (typeof t.url !== "string" || t.url.trim().length === 0) {
+                    errors.push(`transports[${i}] (${type}): url is required`);
+                }
+            }
+            else {
+                errors.push(`transports[${i}]: unknown type "${type}", must be "stdio", "sse", or "streamable-http"`);
+            }
+        }
+        // ── §7.1 Rule 9 & 10: install required for stdio ───────────────────────
+        if (hasStdio) {
+            if (!recipe.install) {
+                errors.push('install is required when any transport has type "stdio"');
+            }
+            else if (typeof recipe.install.method !== "string" ||
+                recipe.install.method.trim().length === 0) {
+                errors.push("install.method is required and must be a non-empty string");
+            }
+        }
+        // allRemote → install is optional, nothing to check
+        // ── §7.1 Rule 8: auth.envVars covers all ${VAR} references ────────────
+        // Collect all ${VAR} refs from transports (env, headers, args, url)
+        const transportVarRefs = new Set();
+        for (const t of transports) {
+            if (t && typeof t === "object") {
+                collectVarRefs(t.env, transportVarRefs);
+                collectVarRefs(t.headers, transportVarRefs);
+                collectVarRefs(t.args, transportVarRefs);
+                if (typeof t.url === "string")
+                    collectVarRefs(t.url, transportVarRefs);
+            }
+        }
+        if (transportVarRefs.size > 0) {
+            const declaredEnvVars = new Set(recipe.auth?.envVars ?? []);
+            const missing = [...transportVarRefs].filter((v) => !declaredEnvVars.has(v));
+            if (missing.length > 0) {
+                errors.push(`auth.envVars is missing these \${VAR} references found in transports: ${missing.join(", ")}`);
+            }
+        }
+    }
+    // ── §7.2 Warnings ──────────────────────────────────────────────────────────
+    // Warning: metadata.lastVerified older than 90 days
+    if (typeof recipe.metadata?.lastVerified === "string") {
+        const lastVerified = new Date(recipe.metadata.lastVerified);
+        if (!isNaN(lastVerified.getTime())) {
+            const ageMs = Date.now() - lastVerified.getTime();
+            const ninetyDaysMs = 90 * 24 * 60 * 60 * 1000;
+            if (ageMs > ninetyDaysMs) {
+                warnings.push(`metadata.lastVerified is >90 days old (${recipe.metadata.lastVerified})`);
+            }
+        }
+    }
+    // Warning: unknown category
+    if (typeof recipe.metadata?.category === "string" &&
+        !KNOWN_CATEGORIES.has(recipe.metadata.category)) {
+        warnings.push(`metadata.category "${recipe.metadata.category}" is not in the known category list`);
+    }
+    // Warning: non-empty preInstall / postInstall
+    if (Array.isArray(recipe.install?.preInstall) &&
+        recipe.install.preInstall.length > 0) {
+        warnings.push("Recipe contains preInstall commands - review before executing");
+    }
+    if (Array.isArray(recipe.install?.postInstall) &&
+        recipe.install.postInstall.length > 0) {
+        warnings.push("Recipe contains postInstall commands - review before executing");
+    }
+    // Warning: missing metadata.homepage when repository also absent
+    if (!hasRepository && !hasHomepage) {
+        // Already an error, skip duplicate warning
+    }
+    else if (!hasHomepage) {
+        warnings.push("metadata.homepage is missing - consider adding it for better discoverability");
+    }
+    // Warning: maturity deprecated
+    if (recipe.metadata?.maturity === "deprecated") {
+        warnings.push("metadata.maturity is set to 'deprecated'");
+    }
+    // ── Build result ───────────────────────────────────────────────────────────
+    const valid = errors.length === 0;
+    const result = { valid, errors, warnings };
+    if (valid && typeof id === "string") {
+        result.id = id;
+        result.toolCount = recipe.metadata?.toolCount ?? 0;
+        // Primary transport (first one)
+        const firstTransport = Array.isArray(recipe.transports) && recipe.transports.length > 0
+            ? recipe.transports[0].type
+            : undefined;
+        result.primaryTransport = firstTransport;
+        result.installMethod = recipe.install?.method;
+    }
+    return result;
+}
+// ─── File loader ─────────────────────────────────────────────────────────────
+export async function validateRecipeFile(filePath) {
+    const { readFile } = await import("node:fs/promises");
+    const raw = await readFile(filePath, "utf-8");
+    let recipe;
+    try {
+        recipe = JSON.parse(raw);
+    }
+    catch (e) {
+        return {
+            valid: false,
+            errors: [`Failed to parse JSON: ${e.message}`],
+            warnings: [],
+        };
+    }
+    return validateRecipe(recipe);
+}
+// ─── Output formatting ────────────────────────────────────────────────────────
+export function formatValidationResult(filePath, result) {
+    const lines = [];
+    for (const w of result.warnings) {
+        lines.push(`⚠️  Warning: ${w}`);
+    }
+    if (result.valid) {
+        const toolCount = result.toolCount ?? 0;
+        const transport = result.primaryTransport ?? "unknown";
+        const method = result.installMethod ?? "remote";
+        lines.push(`✅ Valid recipe: ${result.id} (${toolCount} tools, ${transport}, ${method})`);
+    }
+    else {
+        lines.push(`❌ Invalid recipe: ${filePath}`);
+        for (const err of result.errors) {
+            lines.push(`   - ${err}`);
+        }
+    }
+    return lines.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwerk/mcp-bridge",
-  "version": "1.7.1",
+  "version": "1.8.0",
   "description": "Standalone MCP server that multiplexes multiple MCP servers into one interface",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -44,7 +44,8 @@
     "build": "tsc",
     "test": "node --import tsx --test tests/*.test.ts",
     "typecheck": "tsc --noEmit",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "validate-recipe": "npx tsx bin/validate-recipe.ts"
   },
   "dependencies": {
     "@sinclair/typebox": "^0.34.0"