@darkiceinteractive/mcp-conductor 1.1.0 → 3.0.0-beta.1

package/dist/observability/hot-path.js

@@ -0,0 +1,125 @@
+/**
+ * Hot-Path Profiler
+ *
+ * Wraps every backend call in a latency tracker and aggregates per (server, tool).
+ * Uses a rolling window so old samples expire automatically. Surfaces top-K
+ * paths by total time or by p99 latency.
+ */
+import { logger } from '../utils/index.js';
+export const DEFAULT_HOT_PATH_CONFIG = {
+    enabled: true,
+    windowMs: 3_600_000,
+    maxSamplesPerBucket: 1_000,
+};
+function p99(sorted) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = Math.ceil(sorted.length * 0.99) - 1;
+    return sorted[Math.max(0, idx)] ?? 0;
+}
+export class HotPathProfiler {
+    config;
+    buckets = new Map();
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_HOT_PATH_CONFIG, ...config };
+    }
+    bucketKey(server, tool) {
+        return `${server}::${tool}`;
+    }
+    /** Record a completed call with its measured latency. */
+    record(server, tool, latencyMs) {
+        if (!this.config.enabled)
+            return;
+        const key = this.bucketKey(server, tool);
+        let bucket = this.buckets.get(key);
+        if (!bucket) {
+            bucket = { server, tool, samples: [] };
+            this.buckets.set(key, bucket);
+        }
+        bucket.samples.push({ latencyMs, timestamp: Date.now() });
+        // Trim to max window size
+        if (bucket.samples.length > this.config.maxSamplesPerBucket) {
+            bucket.samples.splice(0, bucket.samples.length - this.config.maxSamplesPerBucket);
+        }
+        logger.debug('HotPathProfiler: recorded', { server, tool, latencyMs });
+    }
+    /** Evict samples older than windowMs from all buckets. */
+    evictExpired() {
+        const cutoff = Date.now() - this.config.windowMs;
+        for (const [key, bucket] of this.buckets.entries()) {
+            bucket.samples = bucket.samples.filter((s) => s.timestamp >= cutoff);
+            if (bucket.samples.length === 0) {
+                this.buckets.delete(key);
+            }
+        }
+    }
+    computeEntry(bucket, liveSamples) {
+        const latencies = liveSamples.map((s) => s.latencyMs).sort((a, b) => a - b);
+        const total = latencies.reduce((s, v) => s + v, 0);
+        const n = latencies.length;
+        return {
+            server: bucket.server,
+            tool: bucket.tool,
+            callCount: n,
+            totalLatencyMs: total,
+            meanLatencyMs: n > 0 ? Math.round(total / n) : 0,
+            p99LatencyMs: p99(latencies),
+        };
+    }
+    /**
+     * Return top-K paths. sortBy controls ranking:
+     *   'totalLatency' — highest cumulative cost first (default)
+     *   'p99'          — highest tail latency first
+     *   'callCount'    — most called first
+     */
+    getHotPaths(options = {}) {
+        this.evictExpired();
+        const { sinceMs, topK = 10, sortBy = 'totalLatency' } = options;
+        const cutoff = sinceMs !== undefined ? Date.now() - sinceMs : 0;
+        const entries = [];
+        for (const bucket of this.buckets.values()) {
+            const live = sinceMs !== undefined
+                ? bucket.samples.filter((s) => s.timestamp >= cutoff)
+                : bucket.samples;
+            if (live.length === 0)
+                continue;
+            entries.push(this.computeEntry(bucket, live));
+        }
+        // Deterministic sort: primary key, then server+tool as tiebreaker
+        entries.sort((a, b) => {
+            let diff = 0;
+            switch (sortBy) {
+                case 'p99':
+                    diff = b.p99LatencyMs - a.p99LatencyMs;
+                    break;
+                case 'callCount':
+                    diff = b.callCount - a.callCount;
+                    break;
+                default: diff = b.totalLatencyMs - a.totalLatencyMs;
+            }
+            if (diff !== 0)
+                return diff;
+            // Tiebreak by server then tool for stable ordering
+            const sk = a.server.localeCompare(b.server);
+            if (sk !== 0)
+                return sk;
+            return a.tool.localeCompare(b.tool);
+        });
+        return entries.slice(0, topK);
+    }
+    reset() {
+        this.buckets.clear();
+    }
+}
+// Module-level singleton
+let _instance = null;
+export function getHotPathProfiler(config) {
+    if (!_instance) {
+        _instance = new HotPathProfiler(config);
+    }
+    return _instance;
+}
+export function shutdownHotPathProfiler() {
+    _instance = null;
+}
+//# sourceMappingURL=hot-path.js.map

package/dist/observability/hot-path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hot-path.js","sourceRoot":"","sources":["../../src/observability/hot-path.ts"],"names":[],"mappings":"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"}

package/dist/observability/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Observability module barrel
+ *
+ * Cost prediction, hot-path profiling, anomaly detection, and replay.
+ */
+export * from './cost-predictor.js';
+export * from './hot-path.js';
+export * from './anomaly.js';
+export * from './replay.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/observability/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}

package/dist/observability/index.js

@@ -0,0 +1,10 @@
+/**
+ * Observability module barrel
+ *
+ * Cost prediction, hot-path profiling, anomaly detection, and replay.
+ */
+export * from './cost-predictor.js';
+export * from './hot-path.js';
+export * from './anomaly.js';
+export * from './replay.js';
+//# sourceMappingURL=index.js.map

package/dist/observability/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,qBAAqB,CAAC;AACpC,cAAc,eAAe,CAAC;AAC9B,cAAc,cAAc,CAAC;AAC7B,cAAc,aAAa,CAAC"}

package/dist/observability/replay.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Replay Recorder
+ *
+ * Records execute_code sessions to JSONL journals under
+ * ~/.mcp-conductor/recordings/. Supports deterministic replay with optional
+ * per-event modifications (replace or skip). Detects divergence when the
+ * replayed result differs from the recorded result.
+ *
+ * Journal line format (one JSON object per line):
+ *   { "seq": <number>, "ts": <epoch-ms>, "type": "tool_call"|"tool_result"|"code_result",
+ *     "server": <string>, "tool": <string>, "args": <object>, "result": <unknown> }
+ *
+ * Rotation: when total bytes across all recordings exceed maxTotalBytes
+ * (default 1 GB), the oldest file is removed.
+ */
+export interface ReplayConfig {
+    /** Directory for recording files */
+    recordingsDir: string;
+    /** Maximum total bytes across all recordings before rotation (default 1 GB) */
+    maxTotalBytes: number;
+}
+export declare const DEFAULT_REPLAY_CONFIG: ReplayConfig;
+export type JournalEventType = 'tool_call' | 'tool_result' | 'code_result';
+export interface JournalEvent {
+    seq: number;
+    ts: number;
+    type: JournalEventType;
+    server?: string;
+    tool?: string;
+    args?: Record<string, unknown>;
+    result?: unknown;
+}
+export interface ReplayModification {
+    /** Zero-based sequence index to target */
+    at: number;
+    op: 'replace' | 'skip';
+    /** Replacement result value (only used when op === 'replace') */
+    with?: unknown;
+}
+export declare class ReplayRecorder {
+    private config;
+    private activeSessions;
+    constructor(config?: Partial<ReplayConfig>);
+    private ensureDir;
+    private rotate;
+    private appendEvent;
+    /** Start a new recording session. Returns the sessionId and recording path. */
+    startRecording(sessionId?: string): {
+        sessionId: string;
+        recordingPath: string;
+    };
+    /** Stop an active recording session. Returns the path and event count. */
+    stopRecording(sessionId: string): {
+        recordingPath: string;
+        eventCount: number;
+    };
+    /** Record a tool call event into an active session. */
+    recordToolCall(sessionId: string, server: string, tool: string, args: Record<string, unknown>): void;
+    /** Record a tool result event into an active session. */
+    recordToolResult(sessionId: string, server: string, tool: string, result: unknown): void;
+    /** Record the final code execution result. */
+    recordCodeResult(sessionId: string, result: unknown): void;
+    /** Return whether a session is currently active. */
+    isRecording(sessionId: string): boolean;
+    /**
+     * Load and parse a recording file. Returns the ordered events.
+     */
+    loadRecording(recordingPath: string): JournalEvent[];
+    /**
+     * Replay a recorded session.
+     *
+     * For each tool_call/tool_result pair in the journal the recorded result is
+     * returned unless a modification targets that sequence number:
+     *   - op:'skip'    → the tool call is omitted from the replayed sequence
+     *   - op:'replace' → the recorded result is replaced with modification.with
+     *
+     * The final code_result is compared against the replayed sequence to detect
+     * divergence.
+     *
+     * This implementation operates fully in-memory against the journal — it does
+     * NOT re-execute Deno code (that would require a live executor). It reconstructs
+     * the recorded call sequence and applies modifications, returning what the
+     * sandbox would have seen.
+     */
+    replay(recordingPath: string, modifications?: ReplayModification[]): {
+        result: unknown;
+        events: JournalEvent[];
+        divergence?: {
+            at: number;
+            expected: unknown;
+            actual: unknown;
+        };
+    };
+    /** List all recording files sorted by modification time (newest first). */
+    listRecordings(): Array<{
+        sessionId: string;
+        path: string;
+        sizeBytes: number;
+        createdAt: number;
+    }>;
+}
+export declare function getReplayRecorder(config?: Partial<ReplayConfig>): ReplayRecorder;
+export declare function shutdownReplayRecorder(): void;
+//# sourceMappingURL=replay.d.ts.map

package/dist/observability/replay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../../src/observability/replay.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAiBH,MAAM,WAAW,YAAY;IAC3B,oCAAoC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,qBAAqB,EAAE,YAGnC,CAAC;AAMF,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,aAAa,GAAG,aAAa,CAAC;AAE3E,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,gBAAgB,CAAC;IACvB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAMD,MAAM,WAAW,kBAAkB;IACjC,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,SAAS,GAAG,MAAM,CAAC;IACvB,iEAAiE;IACjE,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AA4CD,qBAAa,cAAc;IACzB,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,cAAc,CAAyC;gBAEnD,MAAM,GAAE,OAAO,CAAC,YAAY,CAAM;IAI9C,OAAO,CAAC,SAAS;IAMjB,OAAO,CAAC,MAAM;IASd,OAAO,CAAC,WAAW;IAcnB,+EAA+E;IAC/E,cAAc,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE;IAuBhF,0EAA0E;IAC1E,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG;QAAE,aAAa,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE;IAa/E,uDAAuD;IACvD,cAAc,CACZ,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,IAAI;IAMP,yDAAyD;IACzD,gBAAgB,CACd,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,OAAO,GACd,IAAI;IAMP,8CAA8C;IAC9C,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,GAAG,IAAI;IAM1D,oDAAoD;IACpD,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO;IAQvC;;OAEG;IACH,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,YAAY,EAAE;IAUpD;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CACJ,aAAa,EAAE,MAAM,EACrB,aAAa,GAAE,kBAAkB,EAAO,GACvC;QACD,MAAM,EAAE,OAAO,CAAC;QAChB,MAAM,EAAE,YAAY,EAAE,CAAC;QACvB,UAAU,CAAC,EAAE;YAAE,EAAE,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,OAAO,CAAC;YAAC,MAAM,EAAE,OAAO,CAAA;SAAE,CAAC;KACjE;IA4CD,2EAA2E;IAC3E,cAAc,IAAI,KAAK,CAAC;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CAgBnG;AAMD,wBAAgB,iBAAiB,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,cAAc,CAKhF;AAED,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/observability/replay.js

@@ -0,0 +1,239 @@
+/**
+ * Replay Recorder
+ *
+ * Records execute_code sessions to JSONL journals under
+ * ~/.mcp-conductor/recordings/. Supports deterministic replay with optional
+ * per-event modifications (replace or skip). Detects divergence when the
+ * replayed result differs from the recorded result.
+ *
+ * Journal line format (one JSON object per line):
+ *   { "seq": <number>, "ts": <epoch-ms>, "type": "tool_call"|"tool_result"|"code_result",
+ *     "server": <string>, "tool": <string>, "args": <object>, "result": <unknown> }
+ *
+ * Rotation: when total bytes across all recordings exceed maxTotalBytes
+ * (default 1 GB), the oldest file is removed.
+ */
+import { appendFileSync, existsSync, mkdirSync, readdirSync, statSync, unlinkSync, readFileSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, basename } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { logger } from '../utils/index.js';
+export const DEFAULT_REPLAY_CONFIG = {
+    recordingsDir: join(homedir(), '.mcp-conductor', 'recordings'),
+    maxTotalBytes: 1_073_741_824, // 1 GB
+};
+// ---------------------------------------------------------------------------
+// Helper: directory total bytes
+// ---------------------------------------------------------------------------
+function dirTotalBytes(dir) {
+    if (!existsSync(dir))
+        return 0;
+    return readdirSync(dir)
+        .filter((f) => f.endsWith('.jsonl'))
+        .reduce((total, f) => {
+        try {
+            return total + statSync(join(dir, f)).size;
+        }
+        catch {
+            return total;
+        }
+    }, 0);
+}
+function oldestFile(dir) {
+    if (!existsSync(dir))
+        return null;
+    const files = readdirSync(dir)
+        .filter((f) => f.endsWith('.jsonl'))
+        .map((f) => ({ name: f, mtime: statSync(join(dir, f)).mtimeMs }))
+        .sort((a, b) => a.mtime - b.mtime);
+    const first = files[0];
+    return first ? join(dir, first.name) : null;
+}
+// ---------------------------------------------------------------------------
+// ReplayRecorder
+// ---------------------------------------------------------------------------
+export class ReplayRecorder {
+    config;
+    activeSessions = new Map();
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_REPLAY_CONFIG, ...config };
+    }
+    ensureDir() {
+        if (!existsSync(this.config.recordingsDir)) {
+            mkdirSync(this.config.recordingsDir, { recursive: true });
+        }
+    }
+    rotate() {
+        while (dirTotalBytes(this.config.recordingsDir) > this.config.maxTotalBytes) {
+            const oldest = oldestFile(this.config.recordingsDir);
+            if (!oldest)
+                break;
+            logger.info('ReplayRecorder: rotating old recording', { file: basename(oldest) });
+            unlinkSync(oldest);
+        }
+    }
+    appendEvent(session, event) {
+        const fullEvent = {
+            seq: session.seq++,
+            ts: Date.now(),
+            ...event,
+        };
+        appendFileSync(session.recordingPath, JSON.stringify(fullEvent) + '\n', 'utf8');
+        session.eventCount++;
+    }
+    // ---------------------------------------------------------------------------
+    // Public API
+    // ---------------------------------------------------------------------------
+    /** Start a new recording session. Returns the sessionId and recording path. */
+    startRecording(sessionId) {
+        this.ensureDir();
+        this.rotate();
+        const id = sessionId ?? randomUUID();
+        const filename = `${id}.jsonl`;
+        const recordingPath = join(this.config.recordingsDir, filename);
+        // Create an empty file to claim the name
+        writeFileSync(recordingPath, '', 'utf8');
+        const session = {
+            sessionId: id,
+            recordingPath,
+            seq: 0,
+            eventCount: 0,
+        };
+        this.activeSessions.set(id, session);
+        logger.info('ReplayRecorder: started recording', { sessionId: id, recordingPath });
+        return { sessionId: id, recordingPath };
+    }
+    /** Stop an active recording session. Returns the path and event count. */
+    stopRecording(sessionId) {
+        const session = this.activeSessions.get(sessionId);
+        if (!session) {
+            throw new Error(`No active recording session: ${sessionId}`);
+        }
+        this.activeSessions.delete(sessionId);
+        logger.info('ReplayRecorder: stopped recording', {
+            sessionId,
+            eventCount: session.eventCount,
+        });
+        return { recordingPath: session.recordingPath, eventCount: session.eventCount };
+    }
+    /** Record a tool call event into an active session. */
+    recordToolCall(sessionId, server, tool, args) {
+        const session = this.activeSessions.get(sessionId);
+        if (!session)
+            return;
+        this.appendEvent(session, { type: 'tool_call', server, tool, args });
+    }
+    /** Record a tool result event into an active session. */
+    recordToolResult(sessionId, server, tool, result) {
+        const session = this.activeSessions.get(sessionId);
+        if (!session)
+            return;
+        this.appendEvent(session, { type: 'tool_result', server, tool, result });
+    }
+    /** Record the final code execution result. */
+    recordCodeResult(sessionId, result) {
+        const session = this.activeSessions.get(sessionId);
+        if (!session)
+            return;
+        this.appendEvent(session, { type: 'code_result', result });
+    }
+    /** Return whether a session is currently active. */
+    isRecording(sessionId) {
+        return this.activeSessions.has(sessionId);
+    }
+    // ---------------------------------------------------------------------------
+    // Replay
+    // ---------------------------------------------------------------------------
+    /**
+     * Load and parse a recording file. Returns the ordered events.
+     */
+    loadRecording(recordingPath) {
+        if (!existsSync(recordingPath)) {
+            throw new Error(`Recording not found: ${recordingPath}`);
+        }
+        const lines = readFileSync(recordingPath, 'utf8')
+            .split('\n')
+            .filter((l) => l.trim().length > 0);
+        return lines.map((l) => JSON.parse(l));
+    }
+    /**
+     * Replay a recorded session.
+     *
+     * For each tool_call/tool_result pair in the journal the recorded result is
+     * returned unless a modification targets that sequence number:
+     *   - op:'skip'    → the tool call is omitted from the replayed sequence
+     *   - op:'replace' → the recorded result is replaced with modification.with
+     *
+     * The final code_result is compared against the replayed sequence to detect
+     * divergence.
+     *
+     * This implementation operates fully in-memory against the journal — it does
+     * NOT re-execute Deno code (that would require a live executor). It reconstructs
+     * the recorded call sequence and applies modifications, returning what the
+     * sandbox would have seen.
+     */
+    replay(recordingPath, modifications = []) {
+        const events = this.loadRecording(recordingPath);
+        const modMap = new Map(modifications.map((m) => [m.at, m]));
+        const replayed = [];
+        let replayedResult = undefined;
+        let divergence;
+        let replaySeq = 0;
+        for (const event of events) {
+            const mod = modMap.get(event.seq);
+            if (mod?.op === 'skip') {
+                // Skip this event — do not include in replayed sequence
+                logger.debug('ReplayRecorder: skipping event', { seq: event.seq });
+                continue;
+            }
+            if (event.type === 'code_result') {
+                // Compare recorded result with what we've accumulated
+                const expected = event.result;
+                // In no-modification replay the result is identical to recorded
+                const actual = mod?.op === 'replace' ? mod.with : event.result;
+                replayedResult = actual;
+                if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+                    divergence = { at: event.seq, expected, actual };
+                }
+                replayed.push({ ...event, seq: replaySeq++, result: actual });
+                continue;
+            }
+            if (mod?.op === 'replace' && event.type === 'tool_result') {
+                replayed.push({ ...event, seq: replaySeq++, result: mod.with });
+                continue;
+            }
+            replayed.push({ ...event, seq: replaySeq++ });
+        }
+        return { result: replayedResult, events: replayed, divergence };
+    }
+    /** List all recording files sorted by modification time (newest first). */
+    listRecordings() {
+        if (!existsSync(this.config.recordingsDir))
+            return [];
+        return readdirSync(this.config.recordingsDir)
+            .filter((f) => f.endsWith('.jsonl'))
+            .map((f) => {
+            const p = join(this.config.recordingsDir, f);
+            const stat = statSync(p);
+            return {
+                sessionId: f.replace('.jsonl', ''),
+                path: p,
+                sizeBytes: stat.size,
+                createdAt: stat.mtimeMs,
+            };
+        })
+            .sort((a, b) => b.createdAt - a.createdAt);
+    }
+}
+// Module-level singleton
+let _instance = null;
+export function getReplayRecorder(config) {
+    if (!_instance) {
+        _instance = new ReplayRecorder(config);
+    }
+    return _instance;
+}
+export function shutdownReplayRecorder() {
+    _instance = null;
+}
+//# sourceMappingURL=replay.js.map

package/dist/observability/replay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay.js","sourceRoot":"","sources":["../../src/observability/replay.ts"],"names":[],"mappings":"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"}

package/dist/registry/built-in-recommendations.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Built-in routing recommendations for well-known MCP servers.
+ *
+ * These defaults apply when a server is discovered but has no user-provided
+ * routing annotation. User config always takes precedence — these are applied
+ * only when `routing` is absent from a tool's existing registry entry.
+ *
+ * Rationale for each entry:
+ * - github: read-only identity/listing tools are safe direct passthrough;
+ *   mutation tools stay execute_code to preserve sandbox audit trail.
+ * - filesystem: read-only traversal is passthrough; writes/deletes stay in
+ *   execute_code so the sandbox can enforce path policies.
+ * - brave-search: single query → result, no side effects, tiny response.
+ *
+ * @module registry/built-in-recommendations
+ */
+/**
+ * Per-server routing recommendations.
+ *
+ * Each entry maps a server name to:
+ *   - `passthrough`: tools that should be exposed as first-class MCP tools.
+ *
+ * Every tool not listed in `passthrough` defaults to `execute_code`.
+ */
+export interface ServerRoutingRecommendation {
+    /** Tool names that should be routed as passthrough. */
+    passthrough: string[];
+}
+/**
+ * Default routing table for known public MCP servers.
+ *
+ * Apply with `applyBuiltInRecommendations()` after `registry.refresh()`.
+ * User config overrides (any existing `routing` annotation) are preserved.
+ */
+export declare const BUILT_IN_ROUTING: Record<string, ServerRoutingRecommendation>;
+/**
+ * Apply built-in routing recommendations to registry-discovered tools.
+ *
+ * Only sets `routing` when none is already present — user annotations and
+ * config-file overrides are never overwritten.
+ *
+ * Returns the number of tools that were annotated.
+ *
+ * @param tools   All tools returned by `registry.getAllTools()`.
+ * @param annotate  The `registry.annotate()` method bound to the ToolRegistry.
+ */
+export declare function applyBuiltInRecommendations(tools: Array<{
+    server: string;
+    name: string;
+    routing?: string;
+}>, annotate: (server: string, name: string, meta: {
+    routing: 'passthrough' | 'execute_code';
+}) => void): number;
+//# sourceMappingURL=built-in-recommendations.d.ts.map

package/dist/registry/built-in-recommendations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"built-in-recommendations.d.ts","sourceRoot":"","sources":["../../src/registry/built-in-recommendations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;GAOG;AACH,MAAM,WAAW,2BAA2B;IAC1C,uDAAuD;IACvD,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,2BAA2B,CAUxE,CAAC;AAEF;;;;;;;;;;GAUG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,KAAK,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,EAChE,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE;IAAE,OAAO,EAAE,aAAa,GAAG,cAAc,CAAA;CAAE,KAAK,IAAI,GAClG,MAAM,CAwBR"}

package/dist/registry/built-in-recommendations.js

@@ -0,0 +1,65 @@
+/**
+ * Built-in routing recommendations for well-known MCP servers.
+ *
+ * These defaults apply when a server is discovered but has no user-provided
+ * routing annotation. User config always takes precedence — these are applied
+ * only when `routing` is absent from a tool's existing registry entry.
+ *
+ * Rationale for each entry:
+ * - github: read-only identity/listing tools are safe direct passthrough;
+ *   mutation tools stay execute_code to preserve sandbox audit trail.
+ * - filesystem: read-only traversal is passthrough; writes/deletes stay in
+ *   execute_code so the sandbox can enforce path policies.
+ * - brave-search: single query → result, no side effects, tiny response.
+ *
+ * @module registry/built-in-recommendations
+ */
+/**
+ * Default routing table for known public MCP servers.
+ *
+ * Apply with `applyBuiltInRecommendations()` after `registry.refresh()`.
+ * User config overrides (any existing `routing` annotation) are preserved.
+ */
+export const BUILT_IN_ROUTING = {
+    github: {
+        passthrough: ['get_me', 'list_repositories'],
+    },
+    filesystem: {
+        passthrough: ['read_file', 'list_directory'],
+    },
+    'brave-search': {
+        passthrough: ['brave_web_search'],
+    },
+};
+/**
+ * Apply built-in routing recommendations to registry-discovered tools.
+ *
+ * Only sets `routing` when none is already present — user annotations and
+ * config-file overrides are never overwritten.
+ *
+ * Returns the number of tools that were annotated.
+ *
+ * @param tools   All tools returned by `registry.getAllTools()`.
+ * @param annotate  The `registry.annotate()` method bound to the ToolRegistry.
+ */
+export function applyBuiltInRecommendations(tools, annotate) {
+    let annotated = 0;
+    for (const tool of tools) {
+        // Never override a user-configured routing value.
+        if (tool.routing !== undefined) {
+            continue;
+        }
+        const rec = BUILT_IN_ROUTING[tool.server];
+        if (!rec) {
+            // Unknown server — default remains execute_code (no annotation needed).
+            continue;
+        }
+        const routing = rec.passthrough.includes(tool.name)
+            ? 'passthrough'
+            : 'execute_code';
+        annotate(tool.server, tool.name, { routing });
+        annotated++;
+    }
+    return annotated;
+}
+//# sourceMappingURL=built-in-recommendations.js.map

package/dist/registry/built-in-recommendations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"built-in-recommendations.js","sourceRoot":"","sources":["../../src/registry/built-in-recommendations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAeH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAgD;IAC3E,MAAM,EAAE;QACN,WAAW,EAAE,CAAC,QAAQ,EAAE,mBAAmB,CAAC;KAC7C;IACD,UAAU,EAAE;QACV,WAAW,EAAE,CAAC,WAAW,EAAE,gBAAgB,CAAC;KAC7C;IACD,cAAc,EAAE;QACd,WAAW,EAAE,CAAC,kBAAkB,CAAC;KAClC;CACF,CAAC;AAEF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,2BAA2B,CACzC,KAAgE,EAChE,QAAmG;IAEnG,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,kDAAkD;QAClD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;YAC/B,SAAS;QACX,CAAC;QAED,MAAM,GAAG,GAAG,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC1C,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,wEAAwE;YACxE,SAAS;QACX,CAAC;QAED,MAAM,OAAO,GAAmC,GAAG,CAAC,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC;YACjF,CAAC,CAAC,aAAa;YACf,CAAC,CAAC,cAAc,CAAC;QAEnB,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,CAAC,CAAC;QAC9C,SAAS,EAAE,CAAC;IACd,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC"}