@aiwerk/mcp-bridge 1.2.3 → 1.4.0

package/README.md

@@ -115,10 +115,38 @@ Config: `~/.mcp-bridge/config.json` | Secrets: `~/.mcp-bridge/.env`
   },
   "toolPrefix": true,
   "connectionTimeoutMs": 5000,
-  "requestTimeoutMs": 60000
+  "requestTimeoutMs": 60000,
+  "schemaCompression": {
+    "enabled": true,
+    "maxDescriptionLength": 80
+  }
 }
 ```
 
+### Schema Compression
+
+In router mode, tool descriptions from upstream servers can be verbose (100-300+ chars each). Schema compression truncates them to save tokens:
+
+- **Enabled by default** — descriptions capped at 80 characters
+- Cuts at sentence boundary when possible, otherwise word boundary
+- Use `action=schema` to retrieve the full uncompressed schema for any tool on demand
+
+```json
+"schemaCompression": {
+  "enabled": true,
+  "maxDescriptionLength": 80
+}
+```
+
+**Token savings example:** 30 Todoist tools: ~2800 tokens uncompressed -> ~1200 compressed (~57% reduction).
+
+To get full details for a specific tool:
+```
+mcp(server="todoist", action="schema", tool="find-tasks")
+```
+
+Set `"enabled": false` to disable compression and return full descriptions.
+
 ### Modes
 
 | Mode | Tools exposed | Best for |
@@ -186,6 +214,9 @@ Built-in catalog with pre-configured servers:
 | wise | stdio | International payments |
 | tavily | stdio | AI-optimized web search |
 | apify | streamable-http | Web scraping and automation |
+| atlassian | stdio | Confluence and Jira |
+| chrome-devtools | stdio | Chrome browser automation |
+| hostinger | sse | Web hosting management |
 
 ```bash
 mcp-bridge install todoist    # Interactive setup with API key prompt

package/dist/src/embeddings.d.ts

@@ -0,0 +1,37 @@
+import type { Logger } from "./types.js";
+export interface EmbeddingProvider {
+    embed(texts: string[]): Promise<number[][]>;
+    dimensions(): number;
+}
+export declare class GeminiEmbedding implements EmbeddingProvider {
+    private readonly apiKey;
+    constructor(apiKey: string);
+    embed(texts: string[]): Promise<number[][]>;
+    dimensions(): number;
+}
+export declare class OpenAIEmbedding implements EmbeddingProvider {
+    private readonly apiKey;
+    private readonly model;
+    constructor(apiKey: string, model?: string);
+    embed(texts: string[]): Promise<number[][]>;
+    dimensions(): number;
+}
+export declare class OllamaEmbedding implements EmbeddingProvider {
+    private readonly model;
+    private readonly baseUrl;
+    constructor(model?: string, baseUrl?: string);
+    embed(texts: string[]): Promise<number[][]>;
+    dimensions(): number;
+}
+export declare class KeywordEmbedding implements EmbeddingProvider {
+    private vocabulary;
+    private vocabSize;
+    embed(texts: string[]): Promise<number[][]>;
+    dimensions(): number;
+    private tokenize;
+}
+export declare function createEmbeddingProvider(type: "auto" | "gemini" | "openai" | "ollama" | "keyword", config?: {
+    model?: string;
+    apiKey?: string;
+    ollamaUrl?: string;
+}, logger?: Logger): EmbeddingProvider;

package/dist/src/embeddings.js

@@ -0,0 +1,176 @@
+export class GeminiEmbedding {
+    apiKey;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+    }
+    async embed(texts) {
+        const results = [];
+        for (const text of texts) {
+            const response = await fetch(`https://generativelanguage.googleapis.com/v1beta/models/gemini-embedding-001:embedContent?key=${this.apiKey}`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify({
+                    content: { parts: [{ text }] }
+                })
+            });
+            if (!response.ok) {
+                throw new Error(`Gemini API error: ${response.status} ${response.statusText}`);
+            }
+            const data = await response.json();
+            results.push(data.embedding.values);
+        }
+        return results;
+    }
+    dimensions() {
+        return 768;
+    }
+}
+export class OpenAIEmbedding {
+    apiKey;
+    model;
+    constructor(apiKey, model = "text-embedding-3-small") {
+        this.apiKey = apiKey;
+        this.model = model;
+    }
+    async embed(texts) {
+        const response = await fetch("https://api.openai.com/v1/embeddings", {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${this.apiKey}`
+            },
+            body: JSON.stringify({ input: texts, model: this.model })
+        });
+        if (!response.ok) {
+            throw new Error(`OpenAI API error: ${response.status} ${response.statusText}`);
+        }
+        const data = await response.json();
+        return data.data
+            .sort((a, b) => a.index - b.index)
+            .map((item) => item.embedding);
+    }
+    dimensions() {
+        return 1536;
+    }
+}
+export class OllamaEmbedding {
+    model;
+    baseUrl;
+    constructor(model = "nomic-embed-text", baseUrl = "http://localhost:11434") {
+        this.model = model;
+        this.baseUrl = baseUrl;
+    }
+    async embed(texts) {
+        const response = await fetch(`${this.baseUrl}/api/embed`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ model: this.model, input: texts })
+        });
+        if (!response.ok) {
+            throw new Error(`Ollama API error: ${response.status} ${response.statusText}`);
+        }
+        const data = await response.json();
+        return data.embeddings;
+    }
+    dimensions() {
+        return 768;
+    }
+}
+export class KeywordEmbedding {
+    vocabulary = new Map();
+    vocabSize = 0;
+    async embed(texts) {
+        // Build vocabulary from all texts
+        this.vocabulary.clear();
+        this.vocabSize = 0;
+        const tokenizedTexts = texts.map((text) => this.tokenize(text));
+        for (const tokens of tokenizedTexts) {
+            for (const token of tokens) {
+                if (!this.vocabulary.has(token)) {
+                    this.vocabulary.set(token, this.vocabSize++);
+                }
+            }
+        }
+        if (this.vocabSize === 0) {
+            return texts.map(() => [0]);
+        }
+        // Create TF vectors
+        const vectors = [];
+        for (const tokens of tokenizedTexts) {
+            const vector = new Array(this.vocabSize).fill(0);
+            for (const token of tokens) {
+                const idx = this.vocabulary.get(token);
+                vector[idx] += 1;
+            }
+            // Normalize by document length
+            const len = tokens.length || 1;
+            for (let i = 0; i < vector.length; i++) {
+                vector[i] /= len;
+            }
+            vectors.push(vector);
+        }
+        // Apply IDF weighting
+        const docCount = texts.length;
+        const idf = new Array(this.vocabSize).fill(0);
+        for (let i = 0; i < this.vocabSize; i++) {
+            let df = 0;
+            for (const vec of vectors) {
+                if (vec[i] > 0)
+                    df++;
+            }
+            idf[i] = Math.log((docCount + 1) / (df + 1)) + 1;
+        }
+        for (const vec of vectors) {
+            for (let i = 0; i < vec.length; i++) {
+                vec[i] *= idf[i];
+            }
+        }
+        return vectors;
+    }
+    dimensions() {
+        return this.vocabSize || 1;
+    }
+    tokenize(text) {
+        return text
+            .toLowerCase()
+            .replace(/[^a-z0-9\s]/g, " ")
+            .split(/\s+/)
+            .filter((t) => t.length > 1);
+    }
+}
+export function createEmbeddingProvider(type, config, logger) {
+    if (type === "gemini") {
+        const key = config?.apiKey || process.env.GEMINI_API_KEY;
+        if (!key)
+            throw new Error("GEMINI_API_KEY is required for gemini embedding provider");
+        return new GeminiEmbedding(key);
+    }
+    if (type === "openai") {
+        const key = config?.apiKey || process.env.OPENAI_API_KEY;
+        if (!key)
+            throw new Error("OPENAI_API_KEY is required for openai embedding provider");
+        return new OpenAIEmbedding(key, config?.model);
+    }
+    if (type === "ollama") {
+        return new OllamaEmbedding(config?.model, config?.ollamaUrl);
+    }
+    if (type === "keyword") {
+        return new KeywordEmbedding();
+    }
+    // auto: try gemini, openai, ollama, then keyword fallback
+    const geminiKey = config?.apiKey || process.env.GEMINI_API_KEY;
+    if (geminiKey) {
+        logger?.debug("[mcp-bridge] Intent routing: using Gemini embeddings");
+        return new GeminiEmbedding(geminiKey);
+    }
+    const openaiKey = process.env.OPENAI_API_KEY;
+    if (openaiKey) {
+        logger?.debug("[mcp-bridge] Intent routing: using OpenAI embeddings");
+        return new OpenAIEmbedding(openaiKey, config?.model);
+    }
+    // For ollama, we can't synchronously check reachability in factory,
+    // so we skip it in auto mode and fall back to keyword.
+    // Users who want ollama should specify type="ollama" explicitly.
+    logger?.debug("[mcp-bridge] Intent routing: using keyword fallback embeddings");
+    return new KeywordEmbedding();
+}

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

@@ -0,0 +1,25 @@
+import type { EmbeddingProvider } from "./embeddings.js";
+import type { Logger } from "./types.js";
+import type { McpTool } from "./types.js";
+export interface IntentMatch {
+    server: string;
+    tool: string;
+    score: number;
+    alternatives: Array<{
+        server: string;
+        tool: string;
+        score: number;
+    }>;
+}
+export declare class IntentRouter {
+    private readonly embeddingProvider;
+    private readonly logger;
+    private readonly store;
+    private indexed;
+    private minScore;
+    constructor(embeddingProvider: EmbeddingProvider, logger: Logger, minScore?: number);
+    indexTools(servers: Record<string, McpTool[]>): Promise<void>;
+    resolve(intent: string): Promise<IntentMatch | null>;
+    isIndexed(): boolean;
+    clearIndex(): void;
+}

package/dist/src/intent-router.js

@@ -0,0 +1,80 @@
+import { VectorStore } from "./vector-store.js";
+const DEFAULT_MIN_SCORE = 0.3;
+const DEFAULT_TOP_K = 4;
+export class IntentRouter {
+    embeddingProvider;
+    logger;
+    store = new VectorStore();
+    indexed = false;
+    minScore;
+    constructor(embeddingProvider, logger, minScore) {
+        this.embeddingProvider = embeddingProvider;
+        this.logger = logger;
+        this.minScore = minScore ?? DEFAULT_MIN_SCORE;
+    }
+    async indexTools(servers) {
+        this.store.clear();
+        this.indexed = false;
+        const entries = [];
+        for (const [serverName, tools] of Object.entries(servers)) {
+            for (const tool of tools) {
+                const text = `${tool.name}: ${tool.description || ""}`;
+                entries.push({
+                    id: `${serverName}/${tool.name}`,
+                    text,
+                    server: serverName,
+                    tool: tool.name
+                });
+            }
+        }
+        if (entries.length === 0) {
+            this.indexed = true;
+            return;
+        }
+        const texts = entries.map((e) => e.text);
+        const vectors = await this.embeddingProvider.embed(texts);
+        for (let i = 0; i < entries.length; i++) {
+            this.store.add(entries[i].id, vectors[i], {
+                server: entries[i].server,
+                tool: entries[i].tool,
+                description: entries[i].text
+            });
+        }
+        this.indexed = true;
+        this.logger.debug(`[mcp-bridge] Intent router indexed ${entries.length} tools`);
+    }
+    async resolve(intent) {
+        if (!this.indexed || this.store.size() === 0) {
+            return null;
+        }
+        // Embed the intent together with stored texts for keyword provider compatibility
+        // For API-based providers this is just a single text embedding
+        const [queryVector] = await this.embeddingProvider.embed([intent]);
+        const results = this.store.search(queryVector, DEFAULT_TOP_K);
+        if (results.length === 0) {
+            return null;
+        }
+        const best = results[0];
+        if (best.score < this.minScore) {
+            this.logger.debug(`[mcp-bridge] Intent "${intent}" best match score ${best.score.toFixed(3)} below threshold ${this.minScore}`);
+            return null;
+        }
+        return {
+            server: best.metadata.server,
+            tool: best.metadata.tool,
+            score: best.score,
+            alternatives: results.slice(1).map((r) => ({
+                server: r.metadata.server,
+                tool: r.metadata.tool,
+                score: r.score
+            }))
+        };
+    }
+    isIndexed() {
+        return this.indexed;
+    }
+    clearIndex() {
+        this.store.clear();
+        this.indexed = false;
+    }
+}

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

@@ -26,9 +26,28 @@ export type RouterDispatchResponse = {
     action: "call";
     tool: string;
     result: any;
+} | {
+    server: string;
+    action: "schema";
+    tool: string;
+    schema: any;
+    description: string;
 } | {
     action: "status";
     servers: RouterServerStatus[];
+} | {
+    action: "intent";
+    intent: string;
+    match: {
+        server: string;
+        tool: string;
+        score: number;
+    };
+    alternatives: Array<{
+        server: string;
+        tool: string;
+        score: number;
+    }>;
 } | {
     error: RouterErrorCode;
     message: string;
@@ -48,10 +67,12 @@ export declare class McpRouter {
     private readonly idleTimeoutMs;
     private readonly maxConcurrent;
     private readonly states;
+    private intentRouter;
     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>;
     getToolList(server: string): Promise<RouterToolHint[]>;
+    private resolveIntent;
     private getStatus;
     disconnectAll(): Promise<void>;
     private ensureConnected;

package/dist/src/mcp-router.js

@@ -2,6 +2,9 @@ import { SseTransport } from "./transport-sse.js";
 import { StdioTransport } from "./transport-stdio.js";
 import { StreamableHttpTransport } from "./transport-streamable-http.js";
 import { fetchToolsList, initializeProtocol, PACKAGE_VERSION } from "./protocol.js";
+import { compressDescription } from "./schema-compression.js";
+import { IntentRouter } from "./intent-router.js";
+import { createEmbeddingProvider } from "./embeddings.js";
 const DEFAULT_IDLE_TIMEOUT_MS = 10 * 60 * 1000;
 const DEFAULT_MAX_CONCURRENT = 5;
 export class McpRouter {
@@ -12,6 +15,7 @@ export class McpRouter {
     idleTimeoutMs;
     maxConcurrent;
     states = new Map();
+    intentRouter = null;
     constructor(servers, clientConfig, logger, transportRefs) {
         this.servers = servers;
         this.clientConfig = clientConfig;
@@ -44,6 +48,14 @@ export class McpRouter {
             if (normalizedAction === "status") {
                 return this.getStatus();
             }
+            // Intent action: find server+tool from natural language
+            if (normalizedAction === "intent") {
+                const intent = params?.intent || tool;
+                if (!intent) {
+                    return this.error("invalid_params", "intent string is required for action=intent");
+                }
+                return this.resolveIntent(intent);
+            }
             if (!server) {
                 return this.error("invalid_params", "server is required");
             }
@@ -59,11 +71,33 @@ export class McpRouter {
                     return this.error("connection_failed", `Failed to connect to ${server}: ${error instanceof Error ? error.message : String(error)}`);
                 }
             }
+            if (normalizedAction === "schema") {
+                if (!tool) {
+                    return this.error("invalid_params", "tool is required for action=schema");
+                }
+                try {
+                    await this.getToolList(server);
+                }
+                catch (error) {
+                    return this.error("connection_failed", `Failed to connect to ${server}: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                const state = this.states.get(server);
+                const fullTool = state.fullToolsMap?.get(tool);
+                if (!fullTool) {
+                    return this.error("unknown_tool", `Tool '${tool}' not found on server '${server}'`, state.toolNames);
+                }
+                return { server, action: "schema", tool, schema: fullTool.inputSchema, description: fullTool.description };
+            }
             if (normalizedAction === "refresh") {
                 try {
                     const state = await this.ensureConnected(server);
                     state.toolsCache = undefined;
+                    state.fullToolsMap = undefined;
                     state.toolNames = [];
+                    // Clear intent index so it re-indexes on next intent query
+                    if (this.intentRouter) {
+                        this.intentRouter.clearIndex();
+                    }
                     const tools = await this.getToolList(server);
                     return { server, action: "refresh", refreshed: true, tools };
                 }
@@ -72,7 +106,7 @@ export class McpRouter {
                 }
             }
             if (normalizedAction !== "call") {
-                return this.error("invalid_params", `action must be one of: list, call, refresh`);
+                return this.error("invalid_params", `action must be one of: list, call, refresh, schema, intent`);
             }
             if (!tool) {
                 return this.error("invalid_params", "tool is required for action=call");
@@ -116,14 +150,65 @@ export class McpRouter {
         }
         const tools = await fetchToolsList(state.transport);
         state.toolNames = tools.map((tool) => tool.name);
+        // Store full tool metadata for action=schema
+        state.fullToolsMap = new Map(tools.map((tool) => [tool.name, { description: tool.description || "", inputSchema: tool.inputSchema }]));
+        const compressionEnabled = this.clientConfig.schemaCompression?.enabled ?? true;
+        const maxLen = this.clientConfig.schemaCompression?.maxDescriptionLength ?? 80;
         state.toolsCache = tools.map((tool) => ({
             name: tool.name,
-            description: tool.description || "",
+            description: compressionEnabled
+                ? compressDescription(tool.description || "", maxLen)
+                : (tool.description || ""),
             requiredParams: this.extractRequiredParams(tool)
         }));
         this.markUsed(server);
         return state.toolsCache;
     }
+    async resolveIntent(intent) {
+        try {
+            // Lazily create the intent router
+            if (!this.intentRouter) {
+                const routingConfig = this.clientConfig.intentRouting;
+                const embeddingType = routingConfig?.embedding ?? "auto";
+                const provider = createEmbeddingProvider(embeddingType, { model: routingConfig?.model }, this.logger);
+                this.intentRouter = new IntentRouter(provider, this.logger, routingConfig?.minScore);
+            }
+            // Index tools if not already done
+            if (!this.intentRouter.isIndexed()) {
+                const allTools = {};
+                for (const serverName of Object.keys(this.servers)) {
+                    try {
+                        await this.getToolList(serverName);
+                        const state = this.states.get(serverName);
+                        if (state?.fullToolsMap) {
+                            allTools[serverName] = [...state.fullToolsMap.entries()].map(([name, meta]) => ({
+                                name,
+                                description: meta.description,
+                                inputSchema: meta.inputSchema
+                            }));
+                        }
+                    }
+                    catch (err) {
+                        this.logger.warn(`[mcp-bridge] Intent routing: failed to index tools from ${serverName}:`, err);
+                    }
+                }
+                await this.intentRouter.indexTools(allTools);
+            }
+            const match = await this.intentRouter.resolve(intent);
+            if (!match) {
+                return this.error("invalid_params", `No tool found matching intent: "${intent}"`);
+            }
+            return {
+                action: "intent",
+                intent,
+                match: { server: match.server, tool: match.tool, score: match.score },
+                alternatives: match.alternatives
+            };
+        }
+        catch (err) {
+            return this.error("mcp_error", `Intent resolution failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     getStatus() {
         const serverStatuses = Object.entries(this.servers).map(([name, config]) => {
             const state = this.states.get(name);
@@ -213,6 +298,7 @@ export class McpRouter {
         }
         state.initialized = false;
         state.toolsCache = undefined;
+        state.fullToolsMap = undefined;
         state.toolNames = [];
     }
     markUsed(server) {
@@ -240,6 +326,7 @@ export class McpRouter {
                 return;
             state.initialized = false;
             state.toolsCache = undefined;
+            state.fullToolsMap = undefined;
             state.toolNames = [];
         };
         if (serverConfig.transport === "sse") {

package/dist/src/schema-compression.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Compress tool descriptions to reduce token usage in router tool listings.
+ */
+export declare function compressDescription(desc: string, maxLen?: number): string;

package/dist/src/schema-compression.js

@@ -0,0 +1,21 @@
+/**
+ * Compress tool descriptions to reduce token usage in router tool listings.
+ */
+export function compressDescription(desc, maxLen = 80) {
+    if (desc.length <= maxLen) {
+        return desc;
+    }
+    // Try to cut at sentence boundary (". " before maxLen)
+    const searchArea = desc.slice(0, maxLen);
+    const sentenceEnd = searchArea.lastIndexOf(". ");
+    if (sentenceEnd > 0) {
+        return desc.slice(0, sentenceEnd + 1) + "\u2026";
+    }
+    // Fall back to word boundary
+    const lastSpace = searchArea.lastIndexOf(" ");
+    if (lastSpace > 0) {
+        return desc.slice(0, lastSpace) + "\u2026";
+    }
+    // No word boundary found, hard truncate
+    return desc.slice(0, maxLen) + "\u2026";
+}

package/dist/src/types.d.ts

@@ -24,6 +24,15 @@ export interface McpClientConfig {
     requestTimeoutMs?: number;
     routerIdleTimeoutMs?: number;
     routerMaxConcurrent?: number;
+    schemaCompression?: {
+        enabled?: boolean;
+        maxDescriptionLength?: number;
+    };
+    intentRouting?: {
+        embedding?: "auto" | "gemini" | "openai" | "ollama" | "keyword";
+        model?: string;
+        minScore?: number;
+    };
 }
 export interface McpTool {
     name: string;

package/dist/src/vector-store.d.ts

@@ -0,0 +1,17 @@
+export interface VectorMetadata {
+    server: string;
+    tool: string;
+    description: string;
+}
+export declare class VectorStore {
+    private entries;
+    add(id: string, vector: number[], metadata: VectorMetadata): void;
+    search(queryVector: number[], topK: number): Array<{
+        id: string;
+        score: number;
+        metadata: VectorMetadata;
+    }>;
+    clear(): void;
+    size(): number;
+}
+export declare function cosineSimilarity(a: number[], b: number[]): number;

package/dist/src/vector-store.js

@@ -0,0 +1,43 @@
+export class VectorStore {
+    entries = [];
+    add(id, vector, metadata) {
+        this.entries.push({ id, vector, metadata });
+    }
+    search(queryVector, topK) {
+        const scored = this.entries.map((entry) => ({
+            id: entry.id,
+            score: cosineSimilarity(queryVector, entry.vector),
+            metadata: entry.metadata
+        }));
+        scored.sort((a, b) => b.score - a.score);
+        return scored.slice(0, topK);
+    }
+    clear() {
+        this.entries = [];
+    }
+    size() {
+        return this.entries.length;
+    }
+}
+export function cosineSimilarity(a, b) {
+    const len = Math.min(a.length, b.length);
+    let dot = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < len; i++) {
+        dot += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    // Handle any extra dimensions (vectors may differ in length for keyword embeddings)
+    for (let i = len; i < a.length; i++) {
+        normA += a[i] * a[i];
+    }
+    for (let i = len; i < b.length; i++) {
+        normB += b[i] * b[i];
+    }
+    const denom = Math.sqrt(normA) * Math.sqrt(normB);
+    if (denom === 0)
+        return 0;
+    return dot / denom;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwerk/mcp-bridge",
-  "version": "1.2.3",
+  "version": "1.4.0",
   "description": "Standalone MCP server that multiplexes multiple MCP servers into one interface",
   "type": "module",
   "main": "./dist/src/index.js",