mcp-squared 0.3.3 → 0.4.0

package/README.md

@@ -72,6 +72,9 @@ bun run build
 # Run tests
 bun test
 
+# Evaluate tool-routing behavior (discovery-first quality check)
+bun run eval:routing
+
 # Dependency audit
 bun run audit
 ```
@@ -103,6 +106,7 @@ mcp-squared config          # Launch configuration TUI
 mcp-squared test [upstream] # Test upstream server connections
 mcp-squared auth <upstream> # OAuth auth for SSE/HTTP upstreams
 mcp-squared import          # Import MCP configs from other tools
+mcp-squared migrate         # Apply one-time config migrations
 mcp-squared install         # Install MCP² into other MCP clients
 mcp-squared monitor         # Launch server monitor TUI
 mcp-squared --help          # Full command reference
@@ -159,6 +163,23 @@ auth = true
 
 Security policies (allow/block/confirm) live under `security.tools`. Confirmation flows return a short-lived token that must be provided to `execute` to proceed. OAuth tokens for SSE upstreams are stored under `~/.config/mcp-squared/tokens/<upstream>.json`.
 
+`mcp-squared init` now seeds code-search routing preferences so `find_tools` prioritizes common code indexers by default:
+
+```toml
+[operations.findTools.preferredNamespacesByIntent]
+codeSearch = ["auggie", "ctxdb"]
+```
+
+Tune this list (or set it to `[]`) if your environment uses different namespaces.
+
+For existing configs created before this default, run:
+
+```bash
+mcp-squared migrate
+```
+
+Use `mcp-squared migrate --dry-run` to preview without writing.
+
 ## Tool API (Meta-Tools)
 
 MCP² exposes these tools to MCP clients:
@@ -168,6 +189,14 @@ MCP² exposes these tools to MCP clients:
 - `list_namespaces` - List upstream namespaces (optionally with tool names)
 - `clear_selection_cache` - Reset co-occurrence based suggestions
 
+Recommended workflow for LLM clients:
+1. Call `find_tools` first to discover candidate tools for the task.
+2. Call `describe_tools` for selected candidates to confirm exact argument schemas.
+3. Call `execute` with a qualified tool name (`namespace:tool_name`).
+4. Use `list_namespaces` if tool names are ambiguous or you need namespace context.
+
+For codebase-search tasks, `find_tools` applies intent-aware ranking and may return namespace guidance (for example preferring configured code-search namespaces like `auggie`).
+
 ## Search Modes
 
 `find_tools` supports three search modes:

package/dist/index.js

@@ -354,6 +354,11 @@ maxLimit = 50
 defaultMode = "fast"
 defaultDetailLevel = "L1"
 
+[operations.findTools.preferredNamespacesByIntent]
+# Default-on code-search namespace preference.
+# Adjust or clear if your stack uses different code indexers.
+codeSearch = ["auggie", "ctxdb"]
+
 [operations.embeddings]
 # Enable to use semantic or hybrid search modes.
 # Requires onnxruntime shared library on the system.
@@ -455,6 +460,9 @@ function parseArgs(args) {
       project: false,
       force: false
     },
+    migrate: {
+      dryRun: false
+    },
     install: {
       interactive: true,
       dryRun: false,
@@ -511,6 +519,9 @@ function parseArgs(args) {
       case "init":
         result.mode = "init";
         break;
+      case "migrate":
+        result.mode = "migrate";
+        break;
       case "monitor":
         result.mode = "monitor";
         break;
@@ -561,6 +572,7 @@ function parseArgs(args) {
       case "--dry-run":
         result.import.dryRun = true;
         result.install.dryRun = true;
+        result.migrate.dryRun = true;
         break;
       case "--no-interactive":
         result.import.interactive = false;
@@ -685,6 +697,7 @@ Usage:
   mcp-squared auth <upstream>   Authenticate with an OAuth-protected upstream
   mcp-squared import [options]  Import MCP configs from other tools
   mcp-squared init [options]    Generate a starter config file with security profile
+  mcp-squared migrate [options] Apply config migrations to existing config
   mcp-squared install [options] Install MCP\xB2 into other MCP clients
   mcp-squared monitor [options] Launch server monitor TUI
   mcp-squared daemon [options]  Start shared MCP\xB2 daemon
@@ -698,6 +711,7 @@ Commands:
   auth <name>                   Authenticate with an OAuth-protected upstream
   import                        Import MCP server configs from other tools
   init                          Generate a starter config with security profile
+  migrate                       Apply one-time config migrations to existing config
   install                       Install MCP\xB2 as a server in other MCP clients
   monitor                       Launch server monitor TUI
   daemon                        Start shared daemon for multiple clients
@@ -724,6 +738,9 @@ Init Options:
   --project                     Write to project-local mcp-squared.toml (default: user-level)
   --force                       Overwrite existing config without prompting
 
+Migrate Options:
+  --dry-run                     Preview migration changes without writing
+
 Install Options:
   --tool=<tool>                 Target tool (skip selection prompt)
   --scope=<scope>               Scope: user or project
@@ -760,6 +777,8 @@ Examples:
   mcp-squared init              Generate hardened config (confirm-all by default)
   mcp-squared init --security=permissive  Generate permissive config (allow-all)
   mcp-squared init --project    Generate project-local config
+  mcp-squared migrate           Apply config migrations to current config file
+  mcp-squared migrate --dry-run Preview config migrations without writing
   mcp-squared import --list     List all discovered MCP configs
   mcp-squared import --dry-run  Preview import changes
   mcp-squared import            Import with interactive conflict resolution
@@ -1076,11 +1095,17 @@ var SecuritySchema = z.object({
 });
 var SearchModeSchema = z.enum(["fast", "semantic", "hybrid"]);
 var DetailLevelSchema = z.enum(["L0", "L1", "L2"]);
+var PreferredNamespacesByIntentSchema = z.object({
+  codeSearch: z.array(z.string().min(1)).default([])
+});
 var FindToolsSchema = z.object({
   defaultLimit: z.number().int().min(1).default(5),
   maxLimit: z.number().int().min(1).max(200).default(50),
   defaultMode: SearchModeSchema.default("fast"),
-  defaultDetailLevel: DetailLevelSchema.default("L1")
+  defaultDetailLevel: DetailLevelSchema.default("L1"),
+  preferredNamespacesByIntent: PreferredNamespacesByIntentSchema.default({
+    codeSearch: []
+  })
 });
 var IndexSchema = z.object({
   refreshIntervalMs: z.number().int().min(1000).default(30000)
@@ -1101,7 +1126,8 @@ var OperationsSchema = z.object({
     defaultLimit: 5,
     maxLimit: 50,
     defaultMode: "fast",
-    defaultDetailLevel: "L1"
+    defaultDetailLevel: "L1",
+    preferredNamespacesByIntent: { codeSearch: [] }
   }),
   index: IndexSchema.default({ refreshIntervalMs: 30000 }),
   logging: LoggingSchema.default({ level: "info" }),
@@ -1116,7 +1142,8 @@ var OperationsSchema = z.object({
     defaultLimit: 5,
     maxLimit: 50,
     defaultMode: "fast",
-    defaultDetailLevel: "L1"
+    defaultDetailLevel: "L1",
+    preferredNamespacesByIntent: { codeSearch: [] }
   },
   index: { refreshIntervalMs: 30000 },
   logging: { level: "info" },
@@ -1872,18 +1899,32 @@ function readManifestFile(manifestUrl) {
 }
 function readBundledManifestFile() {
   const require2 = createRequire(import.meta.url);
-  return require2("../package.json");
+  const candidates = ["../package.json", "../../package.json"];
+  for (const candidate of candidates) {
+    try {
+      return require2(candidate);
+    } catch {}
+  }
+  throw new Error("Unable to resolve bundled package.json");
+}
+function getDefaultManifestUrls() {
+  return [
+    new URL("../package.json", import.meta.url),
+    new URL("../../package.json", import.meta.url)
+  ];
 }
 function resolveVersion(options = {}) {
   const readManifest = options.readManifest ?? readManifestFile;
-  const manifestUrl = options.manifestUrl ?? new URL("../package.json", import.meta.url);
-  try {
-    const manifest = readManifest(manifestUrl);
-    const manifestVersion = normalizeVersion(manifest.version);
-    if (manifestVersion) {
-      return manifestVersion;
-    }
-  } catch {}
+  const manifestUrls = options.manifestUrls ? [...options.manifestUrls] : options.manifestUrl ? [options.manifestUrl] : getDefaultManifestUrls();
+  for (const manifestUrl of manifestUrls) {
+    try {
+      const manifest = readManifest(manifestUrl);
+      const manifestVersion = normalizeVersion(manifest.version);
+      if (manifestVersion) {
+        return manifestVersion;
+      }
+    } catch {}
+  }
   const envVersion = normalizeVersion((options.env ?? process.env)["npm_package_version"]);
   if (envVersion) {
     return envVersion;
@@ -4263,6 +4304,81 @@ Installation cancelled.`);
   process.exit(0);
 }
 
+// src/migrate/runner.ts
+import { readFileSync as readFileSync5 } from "fs";
+import { parse as parseToml4 } from "smol-toml";
+var DEFAULT_CODE_SEARCH_NAMESPACES = ["auggie", "ctxdb"];
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function hasOwn(obj, key) {
+  return Object.hasOwn(obj, key);
+}
+function isCodeSearchExplicitlyConfigured(rawConfig) {
+  if (!isRecord(rawConfig)) {
+    return false;
+  }
+  const operations = rawConfig["operations"];
+  if (!isRecord(operations)) {
+    return false;
+  }
+  const findTools = operations["findTools"];
+  if (!isRecord(findTools)) {
+    return false;
+  }
+  const preferredNamespacesByIntent = findTools["preferredNamespacesByIntent"];
+  if (!isRecord(preferredNamespacesByIntent)) {
+    return false;
+  }
+  return hasOwn(preferredNamespacesByIntent, "codeSearch");
+}
+function applyCodeSearchPreferenceMigration(config, options) {
+  if (options.codeSearchExplicitlyConfigured) {
+    return { config, changed: false };
+  }
+  return {
+    changed: true,
+    config: {
+      ...config,
+      operations: {
+        ...config.operations,
+        findTools: {
+          ...config.operations.findTools,
+          preferredNamespacesByIntent: {
+            ...config.operations.findTools.preferredNamespacesByIntent,
+            codeSearch: [...DEFAULT_CODE_SEARCH_NAMESPACES]
+          }
+        }
+      }
+    }
+  };
+}
+async function runMigrate(args) {
+  const discovered = discoverConfigPath();
+  if (!discovered) {
+    console.error("No configuration file found. Run 'mcp-squared init' to create one first.");
+    process.exit(1);
+  }
+  const loaded = await loadConfigFromPath(discovered.path, discovered.source);
+  const rawConfig = parseToml4(readFileSync5(discovered.path, "utf-8"));
+  const codeSearchExplicitlyConfigured = isCodeSearchExplicitlyConfigured(rawConfig);
+  const { config: migratedConfig, changed } = applyCodeSearchPreferenceMigration(loaded.config, {
+    codeSearchExplicitlyConfigured
+  });
+  if (!changed) {
+    console.log(`No migration needed: code-search preferences already configured in ${discovered.path}`);
+    return;
+  }
+  if (args.dryRun) {
+    console.log(`[dry-run] Would update ${discovered.path}`);
+    console.log('[dry-run] Set operations.findTools.preferredNamespacesByIntent.codeSearch = ["auggie", "ctxdb"]');
+    return;
+  }
+  await saveConfig(discovered.path, migratedConfig);
+  console.log(`Updated ${discovered.path}`);
+  console.log('Set operations.findTools.preferredNamespacesByIntent.codeSearch = ["auggie", "ctxdb"]');
+}
+
 // src/oauth/browser.ts
 import { spawn as spawn2 } from "child_process";
 async function openBrowser(url) {
@@ -4650,7 +4766,7 @@ import {
   chmodSync,
   existsSync as existsSync8,
   mkdirSync as mkdirSync5,
-  readFileSync as readFileSync5,
+  readFileSync as readFileSync6,
   unlinkSync as unlinkSync4,
   writeFileSync as writeFileSync4
 } from "fs";
@@ -4688,7 +4804,7 @@ class TokenStorage {
       return;
     }
     try {
-      const content = readFileSync5(filePath, "utf-8");
+      const content = readFileSync6(filePath, "utf-8");
       return JSON.parse(content);
     } catch {
       return;
@@ -4876,6 +4992,15 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport as StdioServerTransport2 } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z as z3 } from "zod";
 
+// agent_safety_kit/guard/errors.ts
+class PolicyDenied extends Error {
+  decision;
+  constructor(message, decision) {
+    super(message);
+    this.name = "PolicyDenied";
+    this.decision = decision;
+  }
+}
 // agent_safety_kit/policy/matchers.ts
 var GLOB_SPECIALS = /[.+^${}()|[\]\\]/g;
 var PATH_KEY_RE = /(path|file|dir|cwd|workspace|root)/i;
@@ -5013,16 +5138,6 @@ function valuesConstrainedByGlob(values, allowlist) {
   return values.every((value) => matchesAnyGlob(allowlist, value));
 }
 
-// agent_safety_kit/guard/errors.ts
-class PolicyDenied extends Error {
-  decision;
-  constructor(message, decision) {
-    super(message);
-    this.name = "PolicyDenied";
-    this.decision = decision;
-  }
-}
-
 // agent_safety_kit/guard/ratelimit.ts
 class SlidingWindowRateLimiter {
   requests = new Map;
@@ -5232,7 +5347,7 @@ class Guard {
   }
 }
 // agent_safety_kit/policy/load.ts
-import { existsSync as existsSync9, readFileSync as readFileSync6 } from "fs";
+import { existsSync as existsSync9, readFileSync as readFileSync7 } from "fs";
 import { resolve as resolve3 } from "path";
 import { parse as parseYaml } from "yaml";
 
@@ -5295,7 +5410,7 @@ function load_policy(options = {}) {
   if (!existsSync9(sourcePath)) {
     throw new Error(`Agent safety policy file not found at ${sourcePath}`);
   }
-  const raw = readFileSync6(sourcePath, "utf8");
+  const raw = readFileSync7(sourcePath, "utf8");
   const parsed = parseYaml(raw);
   const policy = AgentPolicySchema.parse(parsed);
   const playbookName = options.playbook ?? envConfig.playbook;
@@ -5315,6 +5430,7 @@ function load_policy(options = {}) {
     rules: playbook.rules
   };
 }
+
 // agent_safety_kit/observability/sinks/null.ts
 class NullSpan {
   setAttributes(_attributes) {}
@@ -7753,11 +7869,80 @@ class McpSquaredServer {
     this.registerMetaTools(this.mcpServer);
   }
   createMcpServer(name, version) {
-    return new McpServer({ name, version }, {
+    return new McpServer({
+      name,
+      version,
+      title: "MCP\xB2 Meta Router",
+      description: "Discover and execute tools across upstream MCP servers through a compact meta-tool interface."
+    }, {
       capabilities: {
         tools: {}
+      },
+      instructions: this.buildServerInstructions()
+    });
+  }
+  buildServerInstructions() {
+    const codeSearchNamespaces = this.getCodeSearchNamespaces();
+    const codeSearchHint = codeSearchNamespaces.length > 0 ? ` Prefer these configured code-search namespaces when relevant: ${codeSearchNamespaces.join(", ")}.` : "";
+    return [
+      "Use discovery-first workflow: call `find_tools` before defaulting to local shell discovery (for example `grep`/`rg`).",
+      `For codebase lookup tasks, start with \`find_tools\` queries such as "code search", "find symbol", or "references".${codeSearchHint}`,
+      "After choosing a candidate, call `describe_tools` to confirm schema, then call `execute` with a qualified tool name (`namespace:tool_name`).",
+      "If capabilities are unclear or a name is ambiguous, call `list_namespaces`."
+    ].join(" ");
+  }
+  getCodeSearchNamespaces() {
+    const configured = this.config.operations.findTools.preferredNamespacesByIntent.codeSearch;
+    const upstreamKeys = Object.keys(this.config.upstreams);
+    if (configured.length > 0) {
+      const deduped = [...new Set(configured)];
+      const present = deduped.filter((ns) => upstreamKeys.includes(ns));
+      return present.length > 0 ? present : deduped;
+    }
+    return upstreamKeys.filter((key) => /(auggie|augment|code|source|repo|search)/i.test(key));
+  }
+  isCodeSearchQuery(query) {
+    return /\b(codebase|source code|repository|repo)\b/i.test(query) || /\b(code search|search code|find symbol|symbol lookup|definition|references?|usages?)\b/i.test(query);
+  }
+  rankToolsForQuery(tools, query) {
+    if (!this.isCodeSearchQuery(query) || tools.length < 2) {
+      return tools;
+    }
+    const preferredNamespaces = new Set(this.getCodeSearchNamespaces());
+    const scored = tools.map((tool, index) => {
+      const haystack = `${tool.serverKey} ${tool.name} ${tool.description ?? ""}`.toLowerCase();
+      let score = 0;
+      if (preferredNamespaces.has(tool.serverKey))
+        score += 100;
+      if (/(auggie|augment)/i.test(tool.serverKey))
+        score += 40;
+      if (/\b(search|find|query|lookup)\b/.test(haystack))
+        score += 15;
+      if (/\b(code|symbol|definition|reference|repo|repository|source)\b/.test(haystack)) {
+        score += 20;
+      }
+      return { tool, index, score };
+    });
+    scored.sort((a, b) => {
+      if (a.score === b.score) {
+        return a.index - b.index;
       }
+      return b.score - a.score;
     });
+    return scored.map((entry) => entry.tool);
+  }
+  buildFindToolsGuidance(query) {
+    const guidance = {
+      nextStep: "Use describe_tools for selected candidates, then execute with a qualified name."
+    };
+    if (this.isCodeSearchQuery(query)) {
+      const preferredNamespaces = this.getCodeSearchNamespaces();
+      if (preferredNamespaces.length > 0) {
+        guidance.preferredNamespaces = preferredNamespaces;
+        guidance.note = "For codebase exploration, prefer these namespaces before local shell grep/rg.";
+      }
+    }
+    return guidance;
   }
   createSessionServer() {
     const server = this.createMcpServer(this.serverName, this.serverVersion);
@@ -7783,9 +7968,14 @@ class McpSquaredServer {
   }
   registerMetaTools(server) {
     server.registerTool("find_tools", {
-      description: "Search for available tools across all connected upstream MCP servers. Returns a list of tool summaries matching the query.",
+      title: "Discover Upstream Tools",
+      description: "Call this first for capability discovery. Search available tools across all connected upstream MCP servers and return ranked tool summaries matching the query.",
+      annotations: {
+        readOnlyHint: true,
+        openWorldHint: false
+      },
       inputSchema: {
-        query: z3.string().describe("Natural language search query to find relevant tools"),
+        query: z3.string().describe('Natural language query describing the task (for example: "code search", "find symbol", "create issue")'),
         limit: z3.number().int().min(1).max(this.maxLimit).default(this.config.operations.findTools.defaultLimit).describe("Maximum number of results to return"),
         mode: SearchModeSchema.optional().describe('Search mode: "fast" (FTS5), "semantic" (embeddings), or "hybrid" (FTS5 + rerank)'),
         detail_level: DetailLevelSchema.optional().describe('Level of detail: "L0" (name only), "L1" (summary with description, default), "L2" (full schema)')
@@ -7800,8 +7990,10 @@ class McpSquaredServer {
           mode: args.mode
         });
         const filteredTools = this.filterToolsByPolicy(result.tools);
+        const rankedTools = this.rankToolsForQuery(filteredTools, args.query);
         const detailLevel = args.detail_level ?? this.config.operations.findTools.defaultDetailLevel;
-        const tools = this.formatToolsForDetailLevel(filteredTools, detailLevel);
+        const tools = this.formatToolsForDetailLevel(rankedTools, detailLevel);
+        const guidance = this.buildFindToolsGuidance(args.query);
         const selectionCacheConfig = this.config.operations.selectionCache;
         let suggestedTools;
         if (selectionCacheConfig.enabled && selectionCacheConfig.maxBundleSuggestions > 0) {
@@ -7826,6 +8018,7 @@ class McpSquaredServer {
                 searchMode: result.searchMode,
                 embeddingsAvailable: this.retriever.hasEmbeddings(),
                 tools,
+                guidance,
                 ...suggestedTools && { suggestedTools }
               })
             }
@@ -7837,7 +8030,12 @@ class McpSquaredServer {
       }
     }));
     server.registerTool("describe_tools", {
-      description: "Get full JSON schemas for the specified tools. Use this after find_tools to get detailed parameter information before calling a tool.",
+      title: "Inspect Tool Schemas",
+      description: "After find_tools, fetch full JSON schemas for selected tools to validate required arguments before execution.",
+      annotations: {
+        readOnlyHint: true,
+        openWorldHint: false
+      },
       inputSchema: {
         tool_names: z3.array(z3.string()).min(1).max(20).describe("List of tool names to get schemas for")
       }
@@ -7883,7 +8081,13 @@ class McpSquaredServer {
       }
     }));
     server.registerTool("execute", {
-      description: "Execute a tool on an upstream MCP server. The tool must exist and the arguments must match its schema.",
+      title: "Execute Upstream Tool",
+      description: "Execute an upstream tool after find_tools/describe_tools selection. The tool must exist and the arguments must match its schema.",
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        openWorldHint: true
+      },
       inputSchema: {
         tool_name: z3.string().describe("Name of the tool to execute"),
         arguments: z3.record(z3.string(), z3.unknown()).default({}).describe("Arguments to pass to the tool"),
@@ -8014,7 +8218,14 @@ class McpSquaredServer {
       }
     }));
     server.registerTool("clear_selection_cache", {
+      title: "Reset Selection Cache",
       description: "Clears all learned tool co-occurrence patterns. Use this to reset the selection cache if suggestions become stale or irrelevant.",
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false
+      },
       inputSchema: {}
     }, async () => this.runTaskSpan("clear_selection_cache", async () => {
       const requestId = this.statsCollector.startRequest();
@@ -8042,7 +8253,12 @@ class McpSquaredServer {
       }
     }));
     server.registerTool("list_namespaces", {
-      description: "Lists all available namespaces (upstream MCP servers). Use this to discover available servers and understand which namespaces are available when disambiguating tool names with qualified format (namespace:tool_name).",
+      title: "List Upstream Namespaces",
+      description: "List available namespaces (upstream MCP servers) and optional tool names. Use this to discover routing options and disambiguate qualified names (namespace:tool_name).",
+      annotations: {
+        readOnlyHint: true,
+        openWorldHint: false
+      },
       inputSchema: {
         include_tools: z3.boolean().default(false).describe("If true, includes the list of tool names available in each namespace")
       }
@@ -8931,6 +9147,9 @@ async function main(argv = process.argv.slice(2)) {
       await runInit2(args.init);
       break;
     }
+    case "migrate":
+      await runMigrate(args.migrate);
+      break;
     case "monitor":
       await runMonitor(args.monitor);
       break;

package/dist/tui/config.js

@@ -434,11 +434,17 @@ var SecuritySchema = z.object({
 });
 var SearchModeSchema = z.enum(["fast", "semantic", "hybrid"]);
 var DetailLevelSchema = z.enum(["L0", "L1", "L2"]);
+var PreferredNamespacesByIntentSchema = z.object({
+  codeSearch: z.array(z.string().min(1)).default([])
+});
 var FindToolsSchema = z.object({
   defaultLimit: z.number().int().min(1).default(5),
   maxLimit: z.number().int().min(1).max(200).default(50),
   defaultMode: SearchModeSchema.default("fast"),
-  defaultDetailLevel: DetailLevelSchema.default("L1")
+  defaultDetailLevel: DetailLevelSchema.default("L1"),
+  preferredNamespacesByIntent: PreferredNamespacesByIntentSchema.default({
+    codeSearch: []
+  })
 });
 var IndexSchema = z.object({
   refreshIntervalMs: z.number().int().min(1000).default(30000)
@@ -459,7 +465,8 @@ var OperationsSchema = z.object({
     defaultLimit: 5,
     maxLimit: 50,
     defaultMode: "fast",
-    defaultDetailLevel: "L1"
+    defaultDetailLevel: "L1",
+    preferredNamespacesByIntent: { codeSearch: [] }
   }),
   index: IndexSchema.default({ refreshIntervalMs: 30000 }),
   logging: LoggingSchema.default({ level: "info" }),
@@ -474,7 +481,8 @@ var OperationsSchema = z.object({
     defaultLimit: 5,
     maxLimit: 50,
     defaultMode: "fast",
-    defaultDetailLevel: "L1"
+    defaultDetailLevel: "L1",
+    preferredNamespacesByIntent: { codeSearch: [] }
   },
   index: { refreshIntervalMs: 30000 },
   logging: { level: "info" },
@@ -1006,18 +1014,32 @@ function readManifestFile(manifestUrl) {
 }
 function readBundledManifestFile() {
   const require2 = createRequire(import.meta.url);
-  return require2("../package.json");
+  const candidates = ["../package.json", "../../package.json"];
+  for (const candidate of candidates) {
+    try {
+      return require2(candidate);
+    } catch {}
+  }
+  throw new Error("Unable to resolve bundled package.json");
+}
+function getDefaultManifestUrls() {
+  return [
+    new URL("../package.json", import.meta.url),
+    new URL("../../package.json", import.meta.url)
+  ];
 }
 function resolveVersion(options = {}) {
   const readManifest = options.readManifest ?? readManifestFile;
-  const manifestUrl = options.manifestUrl ?? new URL("../package.json", import.meta.url);
-  try {
-    const manifest = readManifest(manifestUrl);
-    const manifestVersion = normalizeVersion(manifest.version);
-    if (manifestVersion) {
-      return manifestVersion;
-    }
-  } catch {}
+  const manifestUrls = options.manifestUrls ? [...options.manifestUrls] : options.manifestUrl ? [options.manifestUrl] : getDefaultManifestUrls();
+  for (const manifestUrl of manifestUrls) {
+    try {
+      const manifest = readManifest(manifestUrl);
+      const manifestVersion = normalizeVersion(manifest.version);
+      if (manifestVersion) {
+        return manifestVersion;
+      }
+    } catch {}
+  }
   const envVersion = normalizeVersion((options.env ?? process.env)["npm_package_version"]);
   if (envVersion) {
     return envVersion;
@@ -2241,6 +2263,132 @@ async function testUpstreamConnection(name, config, options = {}) {
     log("Done");
   }
 }
+// src/tui/upstream-edit.ts
+function hasNameConflict(upstreams, nextName, existingName) {
+  return Boolean(existingName && nextName !== existingName && typeof upstreams[nextName] !== "undefined");
+}
+function parseKeyValuePairsInput(input) {
+  const result = {};
+  if (!input.trim())
+    return result;
+  const pairs = input.split(",").map((s) => s.trim()).filter(Boolean);
+  for (const pair of pairs) {
+    const eqIndex = pair.indexOf("=");
+    if (eqIndex > 0) {
+      const key = pair.substring(0, eqIndex).trim();
+      const value = pair.substring(eqIndex + 1).trim();
+      if (key) {
+        result[key] = value;
+      }
+    }
+  }
+  return result;
+}
+function stringifyKeyValuePairsInput(pairs) {
+  const entries = Object.entries(pairs || {});
+  if (entries.length === 0) {
+    return "";
+  }
+  return entries.map(([key, value]) => `${key}=${value}`).join(", ");
+}
+function saveStdioUpstreamFromForm(input) {
+  const trimmedName = input.name.trim();
+  const trimmedCommand = input.commandLine.trim();
+  if (!trimmedName) {
+    return { ok: false, reason: "name_required" };
+  }
+  if (!trimmedCommand) {
+    return { ok: false, reason: "command_required" };
+  }
+  if (hasNameConflict(input.upstreams, trimmedName, input.existingName)) {
+    return { ok: false, reason: "name_conflict" };
+  }
+  const parts = trimmedCommand.split(/\s+/);
+  const command = parts[0] || "";
+  const args = parts.slice(1);
+  const env = parseKeyValuePairsInput(input.envInput);
+  if (input.existingName && input.existingName !== trimmedName) {
+    delete input.upstreams[input.existingName];
+  }
+  input.upstreams[trimmedName] = {
+    transport: "stdio",
+    enabled: input.existingUpstream?.enabled ?? true,
+    env,
+    stdio: { command, args }
+  };
+  return { ok: true, savedName: trimmedName };
+}
+function saveSseUpstreamFromForm(input) {
+  const trimmedName = input.name.trim();
+  const trimmedUrl = input.url.trim();
+  if (!trimmedName) {
+    return { ok: false, reason: "name_required" };
+  }
+  if (!trimmedUrl) {
+    return { ok: false, reason: "url_required" };
+  }
+  try {
+    new URL(trimmedUrl);
+  } catch {
+    return { ok: false, reason: "invalid_url" };
+  }
+  if (hasNameConflict(input.upstreams, trimmedName, input.existingName)) {
+    return { ok: false, reason: "name_conflict" };
+  }
+  const headers = parseKeyValuePairsInput(input.headersInput);
+  const env = parseKeyValuePairsInput(input.envInput);
+  if (input.existingName && input.existingName !== trimmedName) {
+    delete input.upstreams[input.existingName];
+  }
+  input.upstreams[trimmedName] = {
+    transport: "sse",
+    enabled: input.existingUpstream?.enabled ?? true,
+    env,
+    sse: {
+      url: trimmedUrl,
+      headers,
+      auth: input.authEnabled ? true : undefined
+    }
+  };
+  return { ok: true, savedName: trimmedName };
+}
+function deleteUpstreamByName(upstreams, name) {
+  if (typeof upstreams[name] === "undefined") {
+    return false;
+  }
+  delete upstreams[name];
+  return true;
+}
+function getUpstreamEditMenuOptions(upstream) {
+  return [
+    {
+      name: "Edit Configuration",
+      description: "Update connection details and environment",
+      value: "edit"
+    },
+    {
+      name: "Test Connection",
+      description: "Connect and list available tools",
+      value: "test"
+    },
+    {
+      name: upstream.enabled ? "Disable" : "Enable",
+      description: upstream.enabled ? "Stop using this upstream" : "Start using this upstream",
+      value: "toggle"
+    },
+    {
+      name: "Delete",
+      description: "Remove this upstream configuration",
+      value: "delete"
+    },
+    {
+      name: "\u2190 Back",
+      description: "",
+      value: "back"
+    }
+  ];
+}
+
 // src/tui/config.ts
 var PROJECT_DESCRIPTION = "Mercury Control Plane";
 async function runConfigTui() {
@@ -2572,12 +2720,13 @@ class ConfigTuiApp {
     menu.focus();
     this.addInstructions("\u2191\u2193 Navigate | Enter Select | Esc Back");
   }
-  showAddStdioScreen() {
+  showAddStdioScreen(existingName, existingUpstream) {
     this.state.currentScreen = "add-stdio";
     this.clearScreen();
     this.addHeader();
     if (!this.container)
       return;
+    const isEditMode = Boolean(existingName && existingUpstream);
     const formBox = new BoxRenderable(this.renderer, {
       id: "add-stdio-box",
       width: 60,
@@ -2585,7 +2734,7 @@ class ConfigTuiApp {
       border: true,
       borderStyle: "single",
       borderColor: "#475569",
-      title: "Add Stdio Upstream",
+      title: isEditMode ? `Edit Stdio Upstream: ${existingName}` : "Add Stdio Upstream",
       titleAlignment: "center",
       backgroundColor: "#1e293b",
       flexDirection: "column",
@@ -2612,6 +2761,7 @@ class ConfigTuiApp {
       }
     });
     formBox.add(nameInput);
+    nameInput.value = existingName ?? "";
     const commandLabel = new TextRenderable(this.renderer, {
       id: "command-label",
       content: "Command (with arguments):",
@@ -2631,6 +2781,7 @@ class ConfigTuiApp {
       }
     });
     formBox.add(commandInput);
+    commandInput.value = existingUpstream ? [existingUpstream.stdio.command, ...existingUpstream.stdio.args].filter(Boolean).join(" ") : "";
     const envLabel = new TextRenderable(this.renderer, {
       id: "env-label",
       content: "Environment variables (optional, comma-separated):",
@@ -2651,6 +2802,7 @@ class ConfigTuiApp {
       }
     });
     formBox.add(envInput);
+    envInput.value = stringifyKeyValuePairsInput(existingUpstream?.env);
     const submitOptions = [
       { name: "[ Save Upstream ]", description: "", value: "save" },
       { name: "[ Cancel ]", description: "", value: "cancel" }
@@ -2675,44 +2827,28 @@ class ConfigTuiApp {
       if (field)
         field.focus();
     };
-    const parseEnvVars = (input) => {
-      const env = {};
-      if (!input.trim())
-        return env;
-      const pairs = input.split(",").map((s) => s.trim()).filter(Boolean);
-      for (const pair of pairs) {
-        const eqIndex = pair.indexOf("=");
-        if (eqIndex > 0) {
-          const key = pair.substring(0, eqIndex).trim();
-          const value = pair.substring(eqIndex + 1).trim();
-          if (key) {
-            env[key] = value;
-          }
-        }
-      }
-      return env;
-    };
     const saveUpstream = () => {
-      const trimmedName = nameInput.value?.trim() || "";
-      const trimmedCommand = commandInput.value?.trim() || "";
-      if (!trimmedName) {
-        nameInput.focus();
-        return;
-      }
-      if (!trimmedCommand) {
-        commandInput.focus();
-        return;
+      const result = saveStdioUpstreamFromForm({
+        upstreams: this.state.config.upstreams,
+        name: nameInput.value || "",
+        commandLine: commandInput.value || "",
+        envInput: envInput.value || "",
+        existingName: isEditMode ? existingName : undefined,
+        existingUpstream
+      });
+      if (!result.ok) {
+        switch (result.reason) {
+          case "name_required":
+          case "name_conflict":
+            nameInput.focus();
+            return;
+          case "command_required":
+            commandInput.focus();
+            return;
+          default:
+            return;
+        }
       }
-      const envVars = parseEnvVars(envInput.value || "");
-      const parts = trimmedCommand.split(/\s+/);
-      const command = parts[0] || "";
-      const args = parts.slice(1);
-      this.state.config.upstreams[trimmedName] = {
-        transport: "stdio",
-        enabled: true,
-        env: envVars,
-        stdio: { command, args }
-      };
       this.state.isDirty = true;
       cleanup();
       this.showUpstreamsScreen();
@@ -2722,13 +2858,21 @@ class ConfigTuiApp {
         saveUpstream();
       } else {
         cleanup();
-        this.showAddUpstreamScreen();
+        if (isEditMode && existingName) {
+          this.showEditUpstreamScreen(existingName);
+        } else {
+          this.showAddUpstreamScreen();
+        }
       }
     });
     const handleKeypress = (key) => {
       if (key.name === "escape") {
         cleanup();
-        this.showAddUpstreamScreen();
+        if (isEditMode && existingName) {
+          this.showEditUpstreamScreen(existingName);
+        } else {
+          this.showAddUpstreamScreen();
+        }
         return;
       }
       if (key.name === "tab" && !key.shift) {
@@ -2745,14 +2889,15 @@ class ConfigTuiApp {
     };
     this.renderer.keyInput.on("keypress", handleKeypress);
     focusField(0);
-    this.addInstructions("Tab: next field | Shift+Tab: prev | Esc: cancel");
+    this.addInstructions("Tab: next field | Shift+Tab: prev | Esc: back");
   }
-  showAddSseScreen() {
+  showAddSseScreen(existingName, existingUpstream) {
     this.state.currentScreen = "add-sse";
     this.clearScreen();
     this.addHeader();
     if (!this.container)
       return;
+    const isEditMode = Boolean(existingName && existingUpstream);
     const formBox = new BoxRenderable(this.renderer, {
       id: "add-sse-box",
       width: 60,
@@ -2760,7 +2905,7 @@ class ConfigTuiApp {
       border: true,
       borderStyle: "single",
       borderColor: "#475569",
-      title: "Add HTTP/SSE Upstream",
+      title: isEditMode ? `Edit HTTP/SSE Upstream: ${existingName}` : "Add HTTP/SSE Upstream",
       titleAlignment: "center",
       backgroundColor: "#1e293b",
       flexDirection: "column",
@@ -2787,6 +2932,7 @@ class ConfigTuiApp {
       }
     });
     formBox.add(nameInput);
+    nameInput.value = existingName ?? "";
     const urlLabel = new TextRenderable(this.renderer, {
       id: "url-label",
       content: "Server URL:",
@@ -2806,6 +2952,7 @@ class ConfigTuiApp {
       }
     });
     formBox.add(urlInput);
+    urlInput.value = existingUpstream?.sse.url ?? "";
     const headersLabel = new TextRenderable(this.renderer, {
       id: "headers-label",
       content: "HTTP Headers (optional, comma-separated):",
@@ -2826,6 +2973,7 @@ class ConfigTuiApp {
       }
     });
     formBox.add(headersInput);
+    headersInput.value = stringifyKeyValuePairsInput(existingUpstream?.sse.headers);
     const authLabel = new TextRenderable(this.renderer, {
       id: "auth-label",
       content: "OAuth Authentication:",
@@ -2833,7 +2981,14 @@ class ConfigTuiApp {
       marginBottom: 0
     });
     formBox.add(authLabel);
-    const authOptions = [
+    const authOptions = existingUpstream?.sse.auth ? [
+      {
+        name: "Enabled (default port 8089)",
+        description: "",
+        value: "enabled"
+      },
+      { name: "Disabled", description: "", value: "disabled" }
+    ] : [
       { name: "Disabled", description: "", value: "disabled" },
       {
         name: "Enabled (default port 8089)",
@@ -2874,6 +3029,7 @@ class ConfigTuiApp {
       }
     });
     formBox.add(envInput);
+    envInput.value = stringifyKeyValuePairsInput(existingUpstream?.env);
     const submitOptions = [
       { name: "[ Save Upstream ]", description: "", value: "save" },
       { name: "[ Cancel ]", description: "", value: "cancel" }
@@ -2899,63 +3055,41 @@ class ConfigTuiApp {
       submitSelect
     ];
     let focusIndex = 0;
-    let selectedAuthIndex = 0;
+    let selectedAuthValue = String(authOptions[0]?.value ?? "disabled");
     const focusField = (index) => {
       focusIndex = index;
       const field = fields[index];
       if (field)
         field.focus();
     };
-    authSelect.on(SelectRenderableEvents.ITEM_SELECTED, (index, _opt) => {
-      selectedAuthIndex = index;
-    });
-    const parseKeyValuePairs = (input) => {
-      const result = {};
-      if (!input.trim())
-        return result;
-      const pairs = input.split(",").map((s) => s.trim()).filter(Boolean);
-      for (const pair of pairs) {
-        const eqIndex = pair.indexOf("=");
-        if (eqIndex > 0) {
-          const key = pair.substring(0, eqIndex).trim();
-          const value = pair.substring(eqIndex + 1).trim();
-          if (key) {
-            result[key] = value;
-          }
-        }
-      }
-      return result;
-    };
+    authSelect.on(SelectRenderableEvents.ITEM_SELECTED, (_index, opt) => {
+      selectedAuthValue = String(opt.value);
+    });
     const saveUpstream = () => {
-      const trimmedName = nameInput.value?.trim() || "";
-      const trimmedUrl = urlInput.value?.trim() || "";
-      if (!trimmedName) {
-        nameInput.focus();
-        return;
-      }
-      if (!trimmedUrl) {
-        urlInput.focus();
-        return;
-      }
-      try {
-        new URL(trimmedUrl);
-      } catch {
-        urlInput.focus();
-        return;
-      }
-      const envVars = parseKeyValuePairs(envInput.value || "");
-      const headers = parseKeyValuePairs(headersInput.value || "");
-      const authEnabled = selectedAuthIndex === 1;
-      this.state.config.upstreams[trimmedName] = {
-        transport: "sse",
-        enabled: true,
-        env: envVars,
-        sse: {
-          url: trimmedUrl,
-          headers,
-          auth: authEnabled ? true : undefined
+      const result = saveSseUpstreamFromForm({
+        upstreams: this.state.config.upstreams,
+        name: nameInput.value || "",
+        url: urlInput.value || "",
+        headersInput: headersInput.value || "",
+        envInput: envInput.value || "",
+        authEnabled: selectedAuthValue === "enabled",
+        existingName: isEditMode ? existingName : undefined,
+        existingUpstream
+      });
+      if (!result.ok) {
+        switch (result.reason) {
+          case "name_required":
+          case "name_conflict":
+            nameInput.focus();
+            return;
+          case "url_required":
+          case "invalid_url":
+            urlInput.focus();
+            return;
+          default:
+            return;
         }
-      };
+      }
       this.state.isDirty = true;
       cleanup();
       this.showUpstreamsScreen();
@@ -2965,13 +3099,21 @@ class ConfigTuiApp {
         saveUpstream();
       } else {
         cleanup();
-        this.showAddUpstreamScreen();
+        if (isEditMode && existingName) {
+          this.showEditUpstreamScreen(existingName);
+        } else {
+          this.showAddUpstreamScreen();
+        }
       }
     });
     const handleKeypress = (key) => {
       if (key.name === "escape") {
         cleanup();
-        this.showAddUpstreamScreen();
+        if (isEditMode && existingName) {
+          this.showEditUpstreamScreen(existingName);
+        } else {
+          this.showAddUpstreamScreen();
+        }
         return;
       }
       if (key.name === "tab" && !key.shift) {
@@ -2988,7 +3130,7 @@ class ConfigTuiApp {
     };
     this.renderer.keyInput.on("keypress", handleKeypress);
     focusField(0);
-    this.addInstructions("Tab: next field | Shift+Tab: prev | Esc: cancel");
+    this.addInstructions("Tab: next field | Shift+Tab: prev | Esc: back");
   }
   showEditUpstreamScreen(name) {
     this.state.currentScreen = "edit-upstream";
@@ -3091,28 +3233,7 @@ class ConfigTuiApp {
       });
       menuBox.add(noEnvText);
     }
-    const options = [
-      {
-        name: "Test Connection",
-        description: "Connect and list available tools",
-        value: "test"
-      },
-      {
-        name: upstream.enabled ? "Disable" : "Enable",
-        description: upstream.enabled ? "Stop using this upstream" : "Start using this upstream",
-        value: "toggle"
-      },
-      {
-        name: "Delete",
-        description: "Remove this upstream configuration",
-        value: "delete"
-      },
-      {
-        name: "\u2190 Back",
-        description: "",
-        value: "back"
-      }
-    ];
+    const options = getUpstreamEditMenuOptions(upstream);
     const menu = new SelectRenderable(this.renderer, {
       id: "edit-menu",
       width: "100%",
@@ -3129,6 +3250,13 @@ class ConfigTuiApp {
     menuBox.add(menu);
     menu.on(SelectRenderableEvents.ITEM_SELECTED, (_index, option) => {
       switch (option.value) {
+        case "edit":
+          if (upstream.transport === "stdio") {
+            this.showAddStdioScreen(name, upstream);
+          } else {
+            this.showAddSseScreen(name, upstream);
+          }
+          break;
         case "test":
           this.showTestScreen(name, upstream);
           break;
@@ -3138,8 +3266,7 @@ class ConfigTuiApp {
           this.showEditUpstreamScreen(name);
           break;
         case "delete":
-          delete this.state.config.upstreams[name];
-          this.state.isDirty = true;
+          this.state.isDirty = deleteUpstreamByName(this.state.config.upstreams, name) || this.state.isDirty;
           this.showUpstreamsScreen();
           break;
         case "back":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-squared",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "MCP² (Mercury Control Plane) - A local-first meta-server and proxy for the Model Context Protocol",
   "author": "aditzel",
   "license": "Apache-2.0",
@@ -28,6 +28,7 @@
     "test": "bun test",
     "test:fast": "SKIP_SLOW_TESTS=true bun test",
     "test:watch": "bun test --watch",
+    "coverage:check": "bun run scripts/check-line-coverage.ts coverage/coverage-summary.txt 80",
     "typecheck": "tsc --noEmit",
     "lint": "biome check src tests scripts AGENTS.md CLAUDE.md WARP.md README.md CHANGELOG.md package.json biome.json tsconfig.json",
     "release:check": "bun run audit && bun test && bun run build && bun run build:verify && bun run lint && bun run typecheck && bun pm pack --dry-run",
@@ -35,7 +36,8 @@
     "lint:fix": "biome check --write .",
     "format": "biome format --write .",
     "clean": "rm -rf dist",
-    "safety:sim": "bun run agent_safety_kit/cost_model/simulate.ts --tasks agent_safety_kit/cost_model/tasks.csv --pricing agent_safety_kit/cost_model/pricing.csv --out agent_safety_kit/cost_model/report.md"
+    "safety:sim": "bun run agent_safety_kit/cost_model/simulate.ts --tasks agent_safety_kit/cost_model/tasks.csv --pricing agent_safety_kit/cost_model/pricing.csv --out agent_safety_kit/cost_model/report.md",
+    "eval:routing": "bun run scripts/eval-tool-routing.ts"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.4",