@aiwerk/mcp-bridge 1.7.2 → 1.9.0

package/dist/src/standalone-server.js

@@ -207,11 +207,24 @@ export class StandaloneServer {
                                 type: "object",
                                 properties: {
                                     server: { type: "string", description: "Server name" },
-                                    action: { type: "string", description: "list | call | refresh | status" },
-                                    tool: { type: "string", description: "Tool name for action=call" },
-                                    params: { type: "object", description: "Tool arguments" }
+                                    action: { type: "string", description: "list | call | batch | refresh | status | intent | schema | promotions" },
+                                    tool: { type: "string", description: "Tool name for action=call/schema" },
+                                    params: { type: "object", description: "Tool arguments" },
+                                    calls: {
+                                        type: "array",
+                                        description: "Batch calls for action=batch",
+                                        items: {
+                                            type: "object",
+                                            properties: {
+                                                server: { type: "string" },
+                                                tool: { type: "string" },
+                                                params: { type: "object" }
+                                            },
+                                            required: ["server", "tool"]
+                                        }
+                                    }
                                 },
-                                required: ["server"]
+                                required: []
                             }
                         }]
                 }
@@ -244,7 +257,10 @@ export class StandaloneServer {
                     error: { code: -32004, message: `Unknown tool: ${toolName}. In router mode, use the 'mcp' tool.` }
                 };
             }
-            const result = await this.router.dispatch(toolArgs.server, toolArgs.action, toolArgs.tool, toolArgs.params);
+            const dispatchParams = toolArgs.action === "batch"
+                ? { ...(toolArgs.params ?? {}), calls: toolArgs.calls }
+                : toolArgs.params;
+            const result = await this.router.dispatch(toolArgs.server, toolArgs.action, toolArgs.tool, dispatchParams);
             // Check if result is an error
             if ("error" in result) {
                 return {

package/dist/src/tool-resolution.d.ts

@@ -0,0 +1,32 @@
+export interface ToolResolutionCandidate {
+    server: string;
+    tool: string;
+    score: number;
+    suggested?: true;
+}
+export type ToolResolutionResult = {
+    server: string;
+    tool: string;
+} | {
+    ambiguous: true;
+    message: string;
+    candidates: ToolResolutionCandidate[];
+} | null;
+export declare class ToolResolver {
+    private readonly basePriority;
+    private readonly toolsByName;
+    private readonly toolNamesByServer;
+    private readonly recentCalls;
+    constructor(serverOrder: string[]);
+    registerServerTools(server: string, tools: Array<{
+        name: string;
+        inputSchema: any;
+    }>): void;
+    removeServer(server: string): void;
+    resolve(toolName: string, params?: Record<string, unknown>, serverHint?: string): ToolResolutionResult;
+    recordCall(server: string, tool: string): void;
+    getKnownToolNames(): string[];
+    private scoreCandidate;
+    private wasUsedRecently;
+    private computeParamMatch;
+}

package/dist/src/tool-resolution.js

@@ -0,0 +1,130 @@
+const RECENT_CALL_LIMIT = 5;
+const BASE_PRIORITY_STEP = 0.1;
+const BASE_PRIORITY_MIN = 0.1;
+const RECENCY_BOOST = 0.3;
+const PARAM_MATCH_WEIGHT = 0.2;
+const AUTO_RESOLVE_DELTA = 0.15;
+export class ToolResolver {
+    basePriority = new Map();
+    toolsByName = new Map();
+    toolNamesByServer = new Map();
+    recentCalls = [];
+    constructor(serverOrder) {
+        const reversed = [...serverOrder].reverse();
+        reversed.forEach((server, index) => {
+            const score = Math.max(1.0 - (index * BASE_PRIORITY_STEP), BASE_PRIORITY_MIN);
+            this.basePriority.set(server, score);
+        });
+    }
+    registerServerTools(server, tools) {
+        this.removeServer(server);
+        const names = new Set();
+        for (const tool of tools) {
+            if (!tool?.name)
+                continue;
+            const registered = {
+                server,
+                tool: tool.name,
+                inputSchema: tool.inputSchema
+            };
+            const existing = this.toolsByName.get(tool.name) ?? [];
+            existing.push(registered);
+            this.toolsByName.set(tool.name, existing);
+            names.add(tool.name);
+        }
+        this.toolNamesByServer.set(server, names);
+    }
+    removeServer(server) {
+        const previousNames = this.toolNamesByServer.get(server);
+        if (previousNames) {
+            for (const toolName of previousNames) {
+                const filtered = (this.toolsByName.get(toolName) ?? []).filter((entry) => entry.server !== server);
+                if (filtered.length === 0) {
+                    this.toolsByName.delete(toolName);
+                    continue;
+                }
+                this.toolsByName.set(toolName, filtered);
+            }
+        }
+        this.toolNamesByServer.delete(server);
+    }
+    resolve(toolName, params, serverHint) {
+        const candidates = this.toolsByName.get(toolName) ?? [];
+        if (candidates.length === 0) {
+            return null;
+        }
+        if (serverHint) {
+            const explicit = candidates.find((candidate) => candidate.server === serverHint);
+            if (!explicit) {
+                return null;
+            }
+            return { server: explicit.server, tool: explicit.tool };
+        }
+        if (candidates.length === 1) {
+            return { server: candidates[0].server, tool: candidates[0].tool };
+        }
+        const scored = candidates
+            .map((candidate) => ({
+            ...candidate,
+            score: this.scoreCandidate(candidate.server, candidate.inputSchema, params)
+        }))
+            .sort((a, b) => {
+            if (b.score !== a.score) {
+                return b.score - a.score;
+            }
+            return (this.basePriority.get(b.server) ?? BASE_PRIORITY_MIN) - (this.basePriority.get(a.server) ?? BASE_PRIORITY_MIN);
+        });
+        const first = scored[0];
+        const second = scored[1];
+        if (!second || (first.score - second.score) >= AUTO_RESOLVE_DELTA) {
+            return { server: first.server, tool: first.tool };
+        }
+        return {
+            ambiguous: true,
+            message: `Multiple servers provide '${toolName}'. Please specify server=`,
+            candidates: scored.map((candidate, index) => ({
+                server: candidate.server,
+                tool: candidate.tool,
+                score: Number(candidate.score.toFixed(2)),
+                ...(index === 0 ? { suggested: true } : {})
+            }))
+        };
+    }
+    recordCall(server, tool) {
+        this.recentCalls.push({ server, tool });
+        if (this.recentCalls.length > RECENT_CALL_LIMIT) {
+            this.recentCalls.shift();
+        }
+    }
+    getKnownToolNames() {
+        return [...this.toolsByName.keys()];
+    }
+    scoreCandidate(server, inputSchema, params) {
+        const base = this.basePriority.get(server) ?? BASE_PRIORITY_MIN;
+        const recency = this.wasUsedRecently(server) ? RECENCY_BOOST : 0;
+        const paramMatch = this.computeParamMatch(inputSchema, params) * PARAM_MATCH_WEIGHT;
+        return base + recency + paramMatch;
+    }
+    wasUsedRecently(server) {
+        return this.recentCalls.some((call) => call.server === server);
+    }
+    computeParamMatch(inputSchema, params) {
+        if (!params || typeof params !== "object") {
+            return 0;
+        }
+        const paramNames = Object.keys(params);
+        if (paramNames.length === 0) {
+            return 0;
+        }
+        const schemaProperties = inputSchema?.properties;
+        if (!schemaProperties || typeof schemaProperties !== "object") {
+            return 0;
+        }
+        const propertyNames = new Set(Object.keys(schemaProperties));
+        if (propertyNames.size === 0) {
+            return 0;
+        }
+        const matching = paramNames.filter((paramName) => propertyNames.has(paramName)).length;
+        return matching / paramNames.length;
+    }
+}

package/dist/src/types.d.ts

@@ -30,6 +30,7 @@ export interface McpClientConfig {
     requestTimeoutMs?: number;
     routerIdleTimeoutMs?: number;
     routerMaxConcurrent?: number;
+    maxBatchSize?: number;
     schemaCompression?: {
         enabled?: boolean;
         maxDescriptionLength?: number;
@@ -48,6 +49,12 @@ export interface McpClientConfig {
         minCalls?: number;
         decayMs?: number;
     };
+    resultCache?: {
+        enabled?: boolean;
+        maxEntries?: number;
+        defaultTtlMs?: number;
+        cacheTtl?: Record<string, number>;
+    };
 }
 export interface McpTool {
     name: string;

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.2",
+  "version": "1.9.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"