mcp-squared 0.3.4 → 0.6.0

package/dist/index.js

@@ -124,6 +124,274 @@ function ensureConfigDir(configPath) {
 var SOCKET_FILENAME = "mcp-squared.sock", INSTANCE_DIR_NAME = "instances", SOCKET_DIR_NAME = "sockets", DAEMON_DIR_NAME = "daemon", DAEMON_REGISTRY_FILENAME = "daemon.json", DAEMON_SOCKET_FILENAME = "daemon.sock", CONFIG_FILENAME = "mcp-squared.toml", CONFIG_DIR_NAME = ".mcp-squared", APP_NAME = "mcp-squared";
 var init_paths = () => {};
 
+// src/capabilities/inference.ts
+function createEmptyScores() {
+  return CAPABILITY_IDS.reduce((acc, capability) => {
+    acc[capability] = 0;
+    return acc;
+  }, {});
+}
+function extractSchemaSignal(schema) {
+  if (!schema || schema.type !== "object") {
+    return "";
+  }
+  const keys = Object.keys(schema.properties ?? {});
+  const required = schema.required ?? [];
+  return `${keys.join(" ")} ${required.join(" ")}`;
+}
+function scoreTextSignals(scores, text) {
+  for (const capability of CAPABILITY_IDS) {
+    for (const pattern of CAPABILITY_PATTERNS[capability]) {
+      if (pattern.test(text)) {
+        scores[capability] += 4;
+      }
+    }
+  }
+}
+function getHighestScoringCapability(scores) {
+  const bestScore = Math.max(...Object.values(scores));
+  if (bestScore <= 0) {
+    return "general";
+  }
+  for (const capability of CAPABILITY_PRIORITY) {
+    if (scores[capability] === bestScore) {
+      return capability;
+    }
+  }
+  return "general";
+}
+function inferNamespaceCapability(namespace, tools, capabilityOverrides = {}) {
+  const override = capabilityOverrides[namespace];
+  if (override) {
+    return override;
+  }
+  const scores = createEmptyScores();
+  const namespaceText = namespace.toLowerCase();
+  for (const hint of NAMESPACE_HINTS) {
+    if (hint.pattern.test(namespaceText)) {
+      scores[hint.capability] += hint.score;
+    }
+  }
+  for (const tool of tools) {
+    const signal = [
+      tool.name,
+      tool.description ?? "",
+      extractSchemaSignal(tool.inputSchema)
+    ].join(" ").toLowerCase();
+    scoreTextSignals(scores, signal);
+  }
+  return getHighestScoringCapability(scores);
+}
+function groupNamespacesByCapability(inventories, capabilityOverrides = {}) {
+  const grouped = CAPABILITY_IDS.reduce((acc, capability) => {
+    acc[capability] = [];
+    return acc;
+  }, {});
+  const byNamespace = {};
+  const sorted = [...inventories].sort((a, b) => a.namespace.localeCompare(b.namespace));
+  for (const inventory of sorted) {
+    const capability = inferNamespaceCapability(inventory.namespace, inventory.tools, capabilityOverrides);
+    byNamespace[inventory.namespace] = capability;
+    grouped[capability].push(inventory.namespace);
+  }
+  return { byNamespace, grouped };
+}
+var CAPABILITY_IDS, CAPABILITY_PRIORITY, NAMESPACE_HINTS, CAPABILITY_PATTERNS;
+var init_inference = __esm(() => {
+  CAPABILITY_IDS = [
+    "code_search",
+    "docs",
+    "browser_automation",
+    "issue_tracking",
+    "cms_content",
+    "design",
+    "ai_media_generation",
+    "hosting_deploy",
+    "time_util",
+    "research",
+    "general"
+  ];
+  CAPABILITY_PRIORITY = [
+    "code_search",
+    "docs",
+    "browser_automation",
+    "issue_tracking",
+    "cms_content",
+    "design",
+    "ai_media_generation",
+    "hosting_deploy",
+    "time_util",
+    "research",
+    "general"
+  ];
+  NAMESPACE_HINTS = [
+    {
+      capability: "code_search",
+      pattern: /(auggie|augment|ctxdb|code|source|repo|symbol|search)/i,
+      score: 24
+    },
+    {
+      capability: "docs",
+      pattern: /(context7|ref|docs?|documentation|shadcn)/i,
+      score: 18
+    },
+    {
+      capability: "browser_automation",
+      pattern: /(chrome|devtools|browser|playwright|puppeteer|webdriver)/i,
+      score: 24
+    },
+    {
+      capability: "issue_tracking",
+      pattern: /(linear|jira|issue|ticket|project|milestone)/i,
+      score: 20
+    },
+    {
+      capability: "cms_content",
+      pattern: /(sanity|content|cms|dataset|schema|studio)/i,
+      score: 20
+    },
+    {
+      capability: "design",
+      pattern: /(pencil|figma|ui|design|artifact|visual)/i,
+      score: 20
+    },
+    {
+      capability: "hosting_deploy",
+      pattern: /(vercel|host|hosting|domain|dns|vps|deploy|infra)/i,
+      score: 22
+    },
+    {
+      capability: "time_util",
+      pattern: /(time|timezone|clock|date|utc)/i,
+      score: 22
+    },
+    {
+      capability: "ai_media_generation",
+      pattern: /(wavespeed|stability|replicate|midjourney|dall.?e|runway|imagen|flux|fal\.ai|dreamstudio)/i,
+      score: 24
+    },
+    {
+      capability: "research",
+      pattern: /(exa|perplexity|firecrawl|crawl|scrape|research|search)/i,
+      score: 16
+    }
+  ];
+  CAPABILITY_PATTERNS = {
+    code_search: [
+      /\bcodebase\b/i,
+      /\bsource\b/i,
+      /\brepo(?:sitory)?\b/i,
+      /\bsymbol(?:s)?\b/i,
+      /\bdefinition(?:s)?\b/i,
+      /\breference(?:s)?\b/i,
+      /\busage(?:s)?\b/i,
+      /\bsearch_context\b/i,
+      /\bcodebase-retrieval\b/i,
+      /\bdirectory_path\b/i
+    ],
+    docs: [
+      /\bdoc(?:s|umentation)?\b/i,
+      /\bread_docs\b/i,
+      /\bquery-docs\b/i,
+      /\breference\b/i,
+      /\bmanual\b/i,
+      /\bknowledge\b/i,
+      /\bregist(?:ry|ries)\b/i,
+      /\bcomponent(?:s)?\b/i,
+      /\bexample(?:s)?\b/i
+    ],
+    browser_automation: [
+      /\bbrowser\b/i,
+      /\bdevtools\b/i,
+      /\bnavigate\b/i,
+      /\bclick\b/i,
+      /\bhover\b/i,
+      /\bnetwork\b/i,
+      /\bconsole\b/i,
+      /\bscreenshot\b/i,
+      /\bpage\b/i
+    ],
+    issue_tracking: [
+      /\bissue(?:s)?\b/i,
+      /\bticket(?:s)?\b/i,
+      /\bmilestone(?:s)?\b/i,
+      /\bcycle(?:s)?\b/i,
+      /\bproject(?:s)?\b/i,
+      /\bcomment(?:s)?\b/i,
+      /\blinear\b/i
+    ],
+    cms_content: [
+      /\bcms\b/i,
+      /\bcontent\b/i,
+      /\bdocument(?:s)?\b/i,
+      /\bdataset(?:s)?\b/i,
+      /\bschema\b/i,
+      /\bpublish\b/i,
+      /\bdraft(?:s)?\b/i,
+      /\bsanity\b/i,
+      /\bmigration\b/i
+    ],
+    design: [
+      /\bdesign\b/i,
+      /\bui\b/i,
+      /\bartifact\b/i,
+      /\bstyle_guide\b/i,
+      /\bscreenshot\b/i,
+      /\bdiagram\b/i,
+      /\bimage\b/i,
+      /\blayout\b/i,
+      /\bframe\b/i
+    ],
+    ai_media_generation: [
+      /\btext.to.image\b/i,
+      /\bimage.to.image\b/i,
+      /\btext.to.video\b/i,
+      /\binpaint(?:ing)?\b/i,
+      /\bupscal(?:e|ing)\b/i,
+      /\bgenerat(?:e|ion)\b.*\bimage/i,
+      /\bimage\b.*\bgenerat(?:e|ion)\b/i,
+      /\bai\b.*\b(?:image|photo|video)\b/i,
+      /\bstable.diffusion\b/i,
+      /\bdiffusion\b/i,
+      /\bprompt\b.*\b(?:image|visual)\b/i
+    ],
+    hosting_deploy: [
+      /\bdeploy(?:ment)?\b/i,
+      /\bhosting\b/i,
+      /\bdomain(?:s)?\b/i,
+      /\bdns\b/i,
+      /\bvps\b/i,
+      /\bvirtual_machine(?:s)?\b/i,
+      /\bfirewall\b/i,
+      /\bwebsite\b/i,
+      /\bbilling\b/i,
+      /\bnameserver(?:s)?\b/i
+    ],
+    time_util: [
+      /\btime\b/i,
+      /\btimezone\b/i,
+      /\butc\b/i,
+      /\bclock\b/i,
+      /\bdate\b/i,
+      /\bconvert_time\b/i,
+      /\bget_current_time\b/i
+    ],
+    research: [
+      /\bresearch\b/i,
+      /\bcrawl\b/i,
+      /\bscrape\b/i,
+      /\bextract\b/i,
+      /\bsemantic_search\b/i,
+      /\bweb_search\b/i,
+      /\bask\b/i,
+      /\bperplexity\b/i,
+      /\bfirecrawl\b/i,
+      /\bexa\b/i
+    ],
+    general: []
+  };
+});
+
 // src/embeddings/generator.ts
 import {
   env,
@@ -281,33 +549,147 @@ var init_embeddings = __esm(() => {
   init_generator();
 });
 
+// src/capabilities/semantic-classifier.ts
+var exports_semantic_classifier = {};
+__export(exports_semantic_classifier, {
+  SemanticCapabilityClassifier: () => SemanticCapabilityClassifier
+});
+
+class SemanticCapabilityClassifier {
+  generator;
+  confidenceThreshold;
+  referenceEmbeddings = null;
+  constructor(generator, options) {
+    this.generator = generator;
+    this.confidenceThreshold = options?.confidenceThreshold ?? 0.45;
+  }
+  async initializeReferences() {
+    const texts = CAPABILITY_IDS.map((id) => CAPABILITY_REFERENCE_TEXTS[id]);
+    const result = await this.generator.embedBatch(texts, false);
+    this.referenceEmbeddings = new Map;
+    for (let i = 0;i < CAPABILITY_IDS.length; i++) {
+      this.referenceEmbeddings.set(CAPABILITY_IDS[i], result.embeddings[i]);
+    }
+  }
+  isInitialized() {
+    return this.referenceEmbeddings !== null;
+  }
+  async classify(namespace, tools) {
+    if (!this.referenceEmbeddings) {
+      throw new Error("SemanticCapabilityClassifier not initialized. Call initializeReferences() first.");
+    }
+    const startTime = performance.now();
+    const signalText = this.buildSignalText(namespace, tools);
+    const signalResult = await this.generator.embed(signalText, true);
+    const scores = [];
+    for (const [capId, refEmb] of this.referenceEmbeddings) {
+      const similarity = EmbeddingGenerator.cosineSimilarity(signalResult.embedding, refEmb);
+      scores.push({ capability: capId, similarity });
+    }
+    scores.sort((a, b) => b.similarity - a.similarity);
+    const best = scores[0];
+    if (!best) {
+      throw new Error("No capability references available for classification");
+    }
+    const runnerUp = scores[1];
+    const inferenceMs = performance.now() - startTime;
+    return {
+      capability: best.capability,
+      confidence: best.similarity,
+      inferenceMs,
+      runnerUp: runnerUp ? { capability: runnerUp.capability, confidence: runnerUp.similarity } : undefined
+    };
+  }
+  async classifyBatch(inventories) {
+    const startTime = performance.now();
+    const overrides = {};
+    const classifications = [];
+    for (const { namespace, tools } of inventories) {
+      const result = await this.classify(namespace, tools);
+      classifications.push({ namespace, ...result });
+      if (result.confidence >= this.confidenceThreshold) {
+        overrides[namespace] = result.capability;
+      }
+    }
+    return {
+      overrides,
+      classifications,
+      inferenceMs: performance.now() - startTime
+    };
+  }
+  buildSignalText(namespace, tools) {
+    const parts = [namespace];
+    for (const tool of tools) {
+      parts.push(tool.name);
+      if (tool.description) {
+        parts.push(tool.description);
+      }
+      const schemaSignal = extractSchemaSignal(tool.inputSchema);
+      if (schemaSignal) {
+        parts.push(schemaSignal);
+      }
+    }
+    return parts.join(" ");
+  }
+}
+var CAPABILITY_REFERENCE_TEXTS;
+var init_semantic_classifier = __esm(() => {
+  init_generator();
+  init_inference();
+  CAPABILITY_REFERENCE_TEXTS = {
+    code_search: "Search source code, symbols, function definitions, class references, and code context across repositories and codebases. Find implementations, usages, and navigate source files.",
+    docs: "Query technical documentation, API references, library guides, SDK docs, component registries, and code example lookups. Read documentation pages and fetch reference material.",
+    browser_automation: "Automate web browser interactions: click elements, fill forms, take screenshots, inspect DOM nodes, navigate URLs, execute JavaScript in page context, and run browser diagnostics.",
+    issue_tracking: "Manage project management tickets, kanban boards, sprints, and work items. Create, update, and track issues in project trackers like Jira, Linear, Asana, and ClickUp.",
+    cms_content: "Manage wiki pages, knowledge base articles, content documents, blog posts, editorial workflows, and structured content. Create and organize content in systems like Notion, Confluence, and Sanity.",
+    design: "Create and inspect visual design artifacts, UI mockups, wireframes, and design system components. Work with design tools like Figma, Sketch, and Pencil for visual layout and styling.",
+    ai_media_generation: "Generate and edit images, videos, and visual media using AI models. Create images from text prompts, edit existing images with AI, upscale resolution, apply style transfer, inpaint or outpaint regions, and generate sequential or consistent media. Supports text-to-image, image-to-image, and AI-powered visual content creation.",
+    hosting_deploy: "Manage server deployments, cloud infrastructure, hosting configurations, CI/CD pipelines, containers, databases, DNS records, and domain management.",
+    time_util: "Convert between timezones, get current time, format dates, calculate time differences, and resolve scheduling utilities.",
+    research: "Search the web, collect information from multiple sources, synthesize findings, and perform web research and data gathering operations.",
+    general: "General-purpose utility operations, API integrations, data transformations, notifications, messaging, payments, and miscellaneous tool actions."
+  };
+});
+
 // src/tui/monitor-loader.ts
 var exports_monitor_loader = {};
 __export(exports_monitor_loader, {
   runMonitorTui: () => runMonitorTui
 });
+function getMonitorModuleSpecifier() {
+  const self = import.meta.url;
+  if (self.includes("/tui/")) {
+    return new URL("./monitor.js", self).href;
+  }
+  return "./tui/monitor.js";
+}
 async function loadMonitorModule() {
-  return import(MONITOR_MODULE_SPECIFIER);
+  return import(getMonitorModuleSpecifier());
 }
 async function runMonitorTui(options = {}) {
   const { runMonitorTui: runMonitor } = await loadMonitorModule();
   return runMonitor(options);
 }
-var MONITOR_MODULE_SPECIFIER = "./tui/monitor.js";
 
 // src/tui/config-loader.ts
 var exports_config_loader = {};
 __export(exports_config_loader, {
   runConfigTui: () => runConfigTui
 });
+function getConfigModuleSpecifier() {
+  const self = import.meta.url;
+  if (self.includes("/tui/")) {
+    return new URL("./config.js", self).href;
+  }
+  return "./tui/config.js";
+}
 function loadConfigModule() {
-  return import(CONFIG_MODULE_SPECIFIER);
+  return import(getConfigModuleSpecifier());
 }
 async function runConfigTui() {
   const { runConfigTui: _run } = await loadConfigModule();
   return _run();
 }
-var CONFIG_MODULE_SPECIFIER = "./tui/config.js";
 
 // src/init/runner.ts
 var exports_runner = {};
@@ -354,6 +736,20 @@ 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.dynamicToolSurface]
+# Capability-first tool surface is always enabled.
+inference = "heuristic_with_overrides"
+refresh = "on_connect"
+
+[operations.dynamicToolSurface.capabilityOverrides]
+# Optional namespace -> capability pinning.
+# auggie = "code_search"
+
 [operations.embeddings]
 # Enable to use semantic or hybrid search modes.
 # Requires onnxruntime shared library on the system.
@@ -455,6 +851,9 @@ function parseArgs(args) {
       project: false,
       force: false
     },
+    migrate: {
+      dryRun: false
+    },
     install: {
       interactive: true,
       dryRun: false,
@@ -511,9 +910,15 @@ function parseArgs(args) {
       case "init":
         result.mode = "init";
         break;
+      case "migrate":
+        result.mode = "migrate";
+        break;
       case "monitor":
         result.mode = "monitor";
         break;
+      case "status":
+        result.mode = "status";
+        break;
       case "daemon":
         result.mode = "daemon";
         break;
@@ -561,6 +966,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,7 +1091,9 @@ 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 status [options]  Show upstream server status and capability routing
   mcp-squared monitor [options] Launch server monitor TUI
   mcp-squared daemon [options]  Start shared MCP\xB2 daemon
   mcp-squared proxy [options]   Start stdio proxy (connects to daemon)
@@ -698,7 +1106,9 @@ 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
+  status                        Show upstream status and capability routing
   monitor                       Launch server monitor TUI
   daemon                        Start shared daemon for multiple clients
   proxy                         Start stdio proxy for daemon
@@ -724,6 +1134,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
@@ -735,6 +1148,9 @@ Install Options:
   --dry-run                     Preview changes without writing
   --no-interactive              Disable interactive prompts
 
+Status Options:
+  --verbose, -V                 Show schema parameters and extra detail
+
 Monitor Options:
   (daemon-first; attaches to shared daemon monitor by default)
   --refresh-interval=<ms>       Auto-refresh interval in milliseconds (default: 2000)
@@ -754,12 +1170,16 @@ Supported Tools:
   ${VALID_TOOL_IDS.join(", ")}
 
 Examples:
+  mcp-squared status            Show upstream status and capability routing table
+  mcp-squared status --verbose  Show status with schema parameters
   mcp-squared test github       Test connection to 'github' upstream
   mcp-squared test              Test all configured upstreams
   mcp-squared auth vercel-mcp   Authenticate with 'vercel-mcp' upstream (OAuth)
   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
@@ -1020,6 +1440,7 @@ import { parse as parseToml } from "smol-toml";
 import { ZodError } from "zod";
 
 // src/config/schema.ts
+init_inference();
 import { z } from "zod";
 var LATEST_SCHEMA_VERSION = 1;
 var LogLevelSchema = z.enum([
@@ -1076,11 +1497,29 @@ var SecuritySchema = z.object({
 });
 var SearchModeSchema = z.enum(["fast", "semantic", "hybrid"]);
 var DetailLevelSchema = z.enum(["L0", "L1", "L2"]);
+var CapabilityIdSchema = z.enum(CAPABILITY_IDS);
+var DynamicToolSurfaceInferenceSchema = z.enum([
+  "heuristic_with_overrides",
+  "hybrid"
+]);
+var DynamicToolSurfaceRefreshSchema = z.enum(["on_connect"]);
+var DynamicToolSurfaceSchema = z.object({
+  inference: DynamicToolSurfaceInferenceSchema.default("heuristic_with_overrides"),
+  refresh: DynamicToolSurfaceRefreshSchema.default("on_connect"),
+  capabilityOverrides: z.record(z.string().min(1), CapabilityIdSchema).default({}),
+  semanticConfidenceThreshold: z.number().min(0).max(1).default(0.45)
+});
+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 +1540,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" }),
@@ -1110,13 +1550,20 @@ var OperationsSchema = z.object({
     enabled: true,
     minCooccurrenceThreshold: 2,
     maxBundleSuggestions: 3
+  }),
+  dynamicToolSurface: DynamicToolSurfaceSchema.default({
+    inference: "heuristic_with_overrides",
+    refresh: "on_connect",
+    capabilityOverrides: {},
+    semanticConfidenceThreshold: 0.45
   })
 }).default({
   findTools: {
     defaultLimit: 5,
     maxLimit: 50,
     defaultMode: "fast",
-    defaultDetailLevel: "L1"
+    defaultDetailLevel: "L1",
+    preferredNamespacesByIntent: { codeSearch: [] }
   },
   index: { refreshIntervalMs: 30000 },
   logging: { level: "info" },
@@ -1125,6 +1572,12 @@ var OperationsSchema = z.object({
     enabled: true,
     minCooccurrenceThreshold: 2,
     maxBundleSuggestions: 3
+  },
+  dynamicToolSurface: {
+    inference: "heuristic_with_overrides",
+    refresh: "on_connect",
+    capabilityOverrides: {},
+    semanticConfidenceThreshold: 0.45
   }
 });
 var ConfigSchema = z.object({
@@ -1178,6 +1631,34 @@ function migrateV0ToV1(config) {
 
 // src/config/load.ts
 init_paths();
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function getDeprecatedDynamicToolSurfaceKeys(raw) {
+  const operations = raw["operations"];
+  if (!isRecord(operations)) {
+    return [];
+  }
+  const dynamicToolSurface = operations["dynamicToolSurface"];
+  if (!isRecord(dynamicToolSurface)) {
+    return [];
+  }
+  const deprecated = [];
+  if ("mode" in dynamicToolSurface) {
+    deprecated.push("operations.dynamicToolSurface.mode");
+  }
+  if ("naming" in dynamicToolSurface) {
+    deprecated.push("operations.dynamicToolSurface.naming");
+  }
+  return deprecated;
+}
+function warnDeprecatedDynamicToolSurfaceKeys(filePath, keys) {
+  if (keys.length === 0) {
+    return;
+  }
+  console.warn(`[mcp\xB2] Deprecated config keys in ${filePath}: ${keys.join(", ")}. Run 'mcp-squared migrate' to clean up legacy settings.`);
+}
+
 class ConfigError extends Error {
   cause;
   constructor(message, cause) {
@@ -1245,6 +1726,7 @@ async function loadConfigFromPath(filePath, source) {
   } catch (err) {
     throw new ConfigParseError(filePath, err);
   }
+  warnDeprecatedDynamicToolSurfaceKeys(filePath, getDeprecatedDynamicToolSurfaceKeys(rawConfig));
   const migrated = migrateConfig(rawConfig);
   let config;
   try {
@@ -4277,6 +4759,233 @@ Installation cancelled.`);
   process.exit(0);
 }
 
+// src/migrate/runner.ts
+init_inference();
+import { readFileSync as readFileSync5 } from "fs";
+import { parse as parseToml4 } from "smol-toml";
+var DEFAULT_CODE_SEARCH_NAMESPACES = ["auggie", "ctxdb"];
+var RESERVED_DESCRIBE_ACTION = "__describe_actions";
+function isRecord2(value) {
+  return typeof value === "object" && value !== null;
+}
+function hasOwn(obj, key) {
+  return Object.hasOwn(obj, key);
+}
+function toActionToken(value) {
+  const normalized = value.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").replace(/_+/g, "_");
+  const token = normalized.length > 0 ? normalized : "tool";
+  const reservedNormalized = RESERVED_DESCRIBE_ACTION.replace(/^_+|_+$/g, "").replace(/_+/g, "_");
+  if (token === reservedNormalized) {
+    return `${RESERVED_DESCRIBE_ACTION}__tool`;
+  }
+  return token;
+}
+function isCapabilityId(value) {
+  return CAPABILITY_IDS.includes(value);
+}
+function hasLegacyDynamicToolSurfaceKeys(rawConfig) {
+  if (!isRecord2(rawConfig)) {
+    return false;
+  }
+  const operations = rawConfig["operations"];
+  if (!isRecord2(operations)) {
+    return false;
+  }
+  const dynamicToolSurface = operations["dynamicToolSurface"];
+  if (!isRecord2(dynamicToolSurface)) {
+    return false;
+  }
+  return hasOwn(dynamicToolSurface, "mode") || hasOwn(dynamicToolSurface, "naming");
+}
+function isCodeSearchExplicitlyConfigured(rawConfig) {
+  if (!isRecord2(rawConfig)) {
+    return false;
+  }
+  const operations = rawConfig["operations"];
+  if (!isRecord2(operations)) {
+    return false;
+  }
+  const findTools = operations["findTools"];
+  if (!isRecord2(findTools)) {
+    return false;
+  }
+  const preferredNamespacesByIntent = findTools["preferredNamespacesByIntent"];
+  if (!isRecord2(preferredNamespacesByIntent)) {
+    return false;
+  }
+  return hasOwn(preferredNamespacesByIntent, "codeSearch");
+}
+function dedupePreserveOrder(values) {
+  const seen = new Set;
+  const result = [];
+  for (const value of values) {
+    if (seen.has(value)) {
+      continue;
+    }
+    seen.add(value);
+    result.push(value);
+  }
+  return result;
+}
+function translateSecurityPattern(pattern, config) {
+  const [scopeRaw, actionRaw] = pattern.split(":", 2);
+  if (!scopeRaw || !actionRaw) {
+    return {
+      original: pattern,
+      translated: pattern,
+      changed: false,
+      unresolvedReason: "invalid pattern format"
+    };
+  }
+  const translatedAction = actionRaw === "*" ? "*" : toActionToken(actionRaw);
+  if (scopeRaw === "*") {
+    const translated2 = `*:${translatedAction}`;
+    return {
+      original: pattern,
+      translated: translated2,
+      changed: translated2 !== pattern
+    };
+  }
+  if (isCapabilityId(scopeRaw)) {
+    const translated2 = `${scopeRaw}:${translatedAction}`;
+    return {
+      original: pattern,
+      translated: translated2,
+      changed: translated2 !== pattern
+    };
+  }
+  const override = config.operations.dynamicToolSurface.capabilityOverrides[scopeRaw];
+  const capability = override ?? inferNamespaceCapability(scopeRaw, [], {});
+  const translated = `${capability}:${translatedAction}`;
+  return {
+    original: pattern,
+    translated,
+    changed: translated !== pattern
+  };
+}
+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]
+          }
+        }
+      }
+    }
+  };
+}
+function applySecurityPatternMigration(config) {
+  const report = {
+    translated: [],
+    unresolved: []
+  };
+  const migrateList = (patterns) => {
+    const next = [];
+    for (const pattern of patterns) {
+      const translation = translateSecurityPattern(pattern, config);
+      next.push(translation.translated);
+      if (translation.unresolvedReason) {
+        report.unresolved.push({
+          pattern: translation.original,
+          reason: translation.unresolvedReason
+        });
+      } else if (translation.changed) {
+        report.translated.push({
+          from: translation.original,
+          to: translation.translated
+        });
+      }
+    }
+    return dedupePreserveOrder(next);
+  };
+  const allow = migrateList(config.security.tools.allow);
+  const block = migrateList(config.security.tools.block);
+  const confirm = migrateList(config.security.tools.confirm);
+  const changed = allow.join("|") !== config.security.tools.allow.join("|") || block.join("|") !== config.security.tools.block.join("|") || confirm.join("|") !== config.security.tools.confirm.join("|");
+  if (!changed && report.unresolved.length === 0) {
+    return { config, changed: false, report };
+  }
+  return {
+    changed,
+    report,
+    config: {
+      ...config,
+      security: {
+        ...config.security,
+        tools: {
+          allow,
+          block,
+          confirm
+        }
+      }
+    }
+  };
+}
+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 hasLegacySurfaceKeys = hasLegacyDynamicToolSurfaceKeys(rawConfig);
+  const codeSearchMigration = applyCodeSearchPreferenceMigration(loaded.config, {
+    codeSearchExplicitlyConfigured
+  });
+  const securityMigration = applySecurityPatternMigration(codeSearchMigration.config);
+  const changed = codeSearchMigration.changed || securityMigration.changed || hasLegacySurfaceKeys;
+  if (!changed && securityMigration.report.unresolved.length === 0) {
+    console.log(`No migration needed for ${discovered.path}`);
+    return;
+  }
+  if (args.dryRun) {
+    console.log(`[dry-run] Would update ${discovered.path}`);
+    if (codeSearchMigration.changed) {
+      console.log('[dry-run] Set operations.findTools.preferredNamespacesByIntent.codeSearch = ["auggie", "ctxdb"]');
+    }
+    if (securityMigration.report.translated.length > 0) {
+      for (const item of securityMigration.report.translated) {
+        console.log(`[dry-run] Translate security pattern: ${item.from} -> ${item.to}`);
+      }
+    }
+    if (hasLegacySurfaceKeys) {
+      console.log("[dry-run] Remove deprecated keys: operations.dynamicToolSurface.mode, operations.dynamicToolSurface.naming");
+    }
+    if (securityMigration.report.unresolved.length > 0) {
+      for (const unresolved of securityMigration.report.unresolved) {
+        console.warn(`[dry-run] Unresolved security pattern '${unresolved.pattern}': ${unresolved.reason}`);
+      }
+    }
+    return;
+  }
+  await saveConfig(discovered.path, securityMigration.config);
+  console.log(`Updated ${discovered.path}`);
+  if (codeSearchMigration.changed) {
+    console.log('Set operations.findTools.preferredNamespacesByIntent.codeSearch = ["auggie", "ctxdb"]');
+  }
+  for (const item of securityMigration.report.translated) {
+    console.log(`Translated security pattern: ${item.from} -> ${item.to}`);
+  }
+  if (hasLegacySurfaceKeys) {
+    console.log("Removed deprecated keys: operations.dynamicToolSurface.mode, operations.dynamicToolSurface.naming");
+  }
+  for (const unresolved of securityMigration.report.unresolved) {
+    console.warn(`Unresolved security pattern '${unresolved.pattern}': ${unresolved.reason}. Please review manually.`);
+  }
+}
+
 // src/oauth/browser.ts
 import { spawn as spawn2 } from "child_process";
 async function openBrowser(url) {
@@ -4664,7 +5373,7 @@ import {
   chmodSync,
   existsSync as existsSync8,
   mkdirSync as mkdirSync5,
-  readFileSync as readFileSync5,
+  readFileSync as readFileSync6,
   unlinkSync as unlinkSync4,
   writeFileSync as writeFileSync4
 } from "fs";
@@ -4702,7 +5411,7 @@ class TokenStorage {
       return;
     }
     try {
-      const content = readFileSync5(filePath, "utf-8");
+      const content = readFileSync6(filePath, "utf-8");
       return JSON.parse(content);
     } catch {
       return;
@@ -4890,6 +5599,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;
@@ -5027,16 +5745,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;
@@ -5246,7 +5954,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";
 
@@ -5309,7 +6017,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;
@@ -5329,6 +6037,7 @@ function load_policy(options = {}) {
     rules: playbook.rules
   };
 }
+
 // agent_safety_kit/observability/sinks/null.ts
 class NullSpan {
   setAttributes(_attributes) {}
@@ -5776,6 +6485,83 @@ class SelectionTracker {
     this.sessionTools.clear();
   }
 }
+// src/server/index.ts
+init_inference();
+
+// src/capabilities/routing.ts
+var DESCRIBE_ACTION = "__describe_actions";
+function toActionToken2(value) {
+  const normalized = value.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").replace(/_+/g, "_");
+  return normalized.length > 0 ? normalized : "tool";
+}
+function buildCapabilityRouters(inventories, grouping, summarize) {
+  if (inventories.length === 0) {
+    return [];
+  }
+  const defaultSummarize = (desc, cap) => {
+    if (desc) {
+      const firstLine = desc.split(`
+`)[0]?.trim();
+      if (firstLine && firstLine.length > 0) {
+        return firstLine.length > 120 ? `${firstLine.slice(0, 117)}...` : firstLine;
+      }
+    }
+    const title = cap.split("_").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+    return `Execute ${title} action`;
+  };
+  const resolveSummary = summarize ?? defaultSummarize;
+  const candidates = [];
+  const reservedNormalized = toActionToken2(DESCRIBE_ACTION);
+  for (const inventory of inventories) {
+    const capability = grouping.byNamespace[inventory.namespace] ?? "general";
+    const sortedTools = [...inventory.tools].sort((a, b) => a.name.localeCompare(b.name));
+    for (const tool of sortedTools) {
+      let baseAction = toActionToken2(tool.name);
+      if (baseAction === DESCRIBE_ACTION || baseAction === reservedNormalized) {
+        baseAction = `${DESCRIBE_ACTION}__tool`;
+      }
+      candidates.push({
+        capability,
+        action: baseAction,
+        baseAction,
+        serverKey: inventory.namespace,
+        toolName: tool.name,
+        qualifiedName: `${inventory.namespace}:${tool.name}`,
+        inputSchema: tool.inputSchema ?? { type: "object" },
+        summary: resolveSummary(tool.description ?? undefined, capability)
+      });
+    }
+  }
+  const byCapabilityAction = new Map;
+  for (const candidate of candidates) {
+    const key = `${candidate.capability}:${candidate.baseAction}`;
+    const existing = byCapabilityAction.get(key) ?? [];
+    existing.push(candidate);
+    byCapabilityAction.set(key, existing);
+  }
+  const resolved = [];
+  const sortedKeys = [...byCapabilityAction.keys()].sort((a, b) => a.localeCompare(b));
+  for (const key of sortedKeys) {
+    const records = (byCapabilityAction.get(key) ?? []).sort((a, b) => a.qualifiedName.localeCompare(b.qualifiedName));
+    records.forEach((record, index) => {
+      resolved.push({
+        ...record,
+        action: index === 0 ? record.baseAction : `${record.baseAction}__${index + 1}`
+      });
+    });
+  }
+  const byCapability = new Map;
+  for (const route of resolved) {
+    const existing = byCapability.get(route.capability) ?? [];
+    existing.push(route);
+    byCapability.set(route.capability, existing);
+  }
+  return [...byCapability.entries()].map(([capability, actions]) => ({
+    capability,
+    actions: actions.sort((a, b) => a.action.localeCompare(b.action))
+  })).sort((a, b) => a.capability.localeCompare(b.capability));
+}
+
 // src/index/store.ts
 import { Database } from "bun:sqlite";
 function hashSchema2(schema) {
@@ -6322,6 +7108,9 @@ class Retriever {
   clearIndex() {
     this.indexStore.clear();
   }
+  getEmbeddingGenerator() {
+    return this.embeddingGenerator;
+  }
   async initializeEmbeddings() {
     if (!this.embeddingsAvailable) {
       return;
@@ -6443,60 +7232,68 @@ function cleanupExpiredTokens() {
     }
   }
 }
-function validateConfirmationToken(token, serverKey, toolName) {
+function validateConfirmationToken(token, capability, action) {
   cleanupExpiredTokens();
   const confirmation = pendingConfirmations.get(token);
   if (!confirmation) {
     return false;
   }
-  if (confirmation.serverKey !== serverKey || confirmation.toolName !== toolName) {
+  if (confirmation.capability !== capability || confirmation.action !== action) {
     return false;
   }
   pendingConfirmations.delete(token);
   return true;
 }
-function createConfirmationToken(serverKey, toolName) {
+function createConfirmationToken(capability, action) {
   cleanupExpiredTokens();
   const token = generateToken();
   pendingConfirmations.set(token, {
-    serverKey,
-    toolName,
+    capability,
+    action,
     createdAt: Date.now()
   });
   return token;
 }
 function evaluatePolicy(context, config) {
-  const { serverKey, toolName, confirmationToken } = context;
+  const capability = context.capability ?? context.serverKey;
+  const action = context.action ?? context.toolName;
+  const confirmationToken = context.confirmationToken;
   const { block, confirm, allow } = config.security.tools;
-  if (matchesAnyPattern(block, serverKey, toolName)) {
+  if (!capability || !action) {
     return {
       decision: "block",
-      reason: `Tool "${toolName}" on server "${serverKey}" is blocked by security policy`
+      reason: "Missing capability/action in security policy context"
     };
   }
-  if (matchesAnyPattern(allow, serverKey, toolName)) {
+  if (matchesAnyPattern(block, capability, action)) {
+    return {
+      decision: "block",
+      reason: `Action "${action}" in capability "${capability}" is blocked by security policy`
+    };
+  }
+  if (matchesAnyPattern(allow, capability, action)) {
     return {
       decision: "allow",
-      reason: `Tool "${toolName}" is allowed by security policy`
+      reason: `Action "${action}" is allowed by security policy`
     };
   }
-  if (matchesAnyPattern(confirm, serverKey, toolName)) {
-    if (confirmationToken && validateConfirmationToken(confirmationToken, serverKey, toolName)) {
+  if (matchesAnyPattern(confirm, capability, action)) {
+    if (confirmationToken && validateConfirmationToken(confirmationToken, capability, action)) {
       return {
         decision: "allow",
-        reason: `Tool "${toolName}" confirmed with valid token`
+        reason: `Action "${action}" confirmed with valid token`
       };
     }
-    const token = createConfirmationToken(serverKey, toolName);
+    const token = createConfirmationToken(capability, action);
     return {
       decision: "confirm",
-      reason: `Tool "${toolName}" on server "${serverKey}" requires confirmation`,
+      reason: `Action "${action}" in capability "${capability}" requires confirmation`,
       confirmationToken: token
     };
   }
   return {
     decision: "block",
-    reason: `Tool "${toolName}" on server "${serverKey}" is not in the allow or confirm list`
+    reason: `Action "${action}" in capability "${capability}" is not in the allow or confirm list`
   };
 }
 function compilePolicy(config) {
@@ -6661,6 +7458,26 @@ async function waitForProcessExit(proc, timeoutMs) {
 }
 
 // src/upstream/cataloger.ts
+var AUTH_ERROR_PATTERNS = [
+  "invalid_token",
+  "invalid token",
+  "unauthorized",
+  "no token provided",
+  "no authorization",
+  "api key",
+  "api_key",
+  "authentication required",
+  "authentication failed",
+  "invalid credentials",
+  "invalid api",
+  "forbidden",
+  "access denied",
+  "not authenticated"
+];
+function isAuthError(message) {
+  const lower = message.toLowerCase();
+  return AUTH_ERROR_PATTERNS.some((pattern) => lower.includes(pattern));
+}
 function resolveEnvVars(env2) {
   const resolved = {};
   for (const [key, value] of Object.entries(env2)) {
@@ -6741,7 +7558,7 @@ class Cataloger {
         if (err instanceof UnauthorizedError2 && connection.authProvider) {
           if (connection.authProvider.isNonInteractive()) {
             connection.authPending = true;
-            connection.status = "error";
+            connection.status = "needs_auth";
             connection.error = `OAuth authorization required. Run: mcp-squared auth ${key}`;
             return;
           }
@@ -6765,8 +7582,9 @@ class Cataloger {
       }));
       connection.status = "connected";
     } catch (err) {
-      connection.status = "error";
-      connection.error = err instanceof Error ? err.message : String(err);
+      const errorMsg = err instanceof Error ? err.message : String(err);
+      connection.status = isAuthError(errorMsg) ? "needs_auth" : "error";
+      connection.error = errorMsg;
       try {
         await this.cleanupConnection(connection);
       } catch (_cleanupErr) {}
@@ -6928,13 +7746,14 @@ class Cataloger {
       if (err instanceof UnauthorizedError2 && connection.authProvider) {
         if (connection.authProvider.isNonInteractive()) {
           connection.authPending = true;
-          connection.status = "error";
+          connection.status = "needs_auth";
           connection.error = `OAuth authorization required. Run: mcp-squared auth ${key}`;
           return;
         }
       }
-      connection.status = "error";
-      connection.error = err instanceof Error ? err.message : String(err);
+      const errorMsg = err instanceof Error ? err.message : String(err);
+      connection.status = isAuthError(errorMsg) ? "needs_auth" : "error";
+      connection.error = errorMsg;
     }
   }
   async refreshAllTools() {
@@ -7239,6 +8058,37 @@ async function testUpstreamConnection(name, config, options = {}) {
     log("Done");
   }
 }
+// src/utils/capability-meta.ts
+function capabilityTitle(capability) {
+  return capability.split("_").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join(" ");
+}
+function capabilitySummary(capability) {
+  switch (capability) {
+    case "code_search":
+      return "Search and retrieve source-code context.";
+    case "docs":
+      return "Query and read technical documentation.";
+    case "browser_automation":
+      return "Automate browser interactions and diagnostics.";
+    case "issue_tracking":
+      return "Work with issues, tickets, and project tracking.";
+    case "cms_content":
+      return "Manage content and CMS resources.";
+    case "design":
+      return "Create and inspect design artifacts and visuals.";
+    case "ai_media_generation":
+      return "Generate and edit images and media using AI models.";
+    case "hosting_deploy":
+      return "Manage deployments, hosting, and infrastructure operations.";
+    case "time_util":
+      return "Resolve time, timezone, and date utilities.";
+    case "research":
+      return "Run web/research collection and synthesis operations.";
+    default:
+      return "Run general-purpose capability actions.";
+  }
+}
+
 // src/server/monitor-server.ts
 import { existsSync as existsSync10, unlinkSync as unlinkSync5 } from "fs";
 import { createServer as createServer3 } from "net";
@@ -7676,12 +8526,16 @@ class StatsCollector {
 }
 
 // src/server/index.ts
+var DESCRIBE_ACTION2 = "__describe_actions";
+function isRecord3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 class McpSquaredServer {
   mcpServer;
   cataloger;
   retriever;
   config;
-  maxLimit;
   transport = null;
   ownsCataloger;
   selectionTracker;
@@ -7695,6 +8549,8 @@ class McpSquaredServer {
   safetyAgent;
   obsSink;
   guard;
+  baseToolsRegistered = false;
+  computedCapabilityOverrides = {};
   constructor(options = {}) {
     const name = options.name ?? "mcp-squared";
     const version = options.version ?? VERSION;
@@ -7709,11 +8565,11 @@ class McpSquaredServer {
     }
     this.config = options.config ?? DEFAULT_CONFIG;
     const findToolsConfig = this.config.operations.findTools;
-    this.maxLimit = options.maxLimit ?? findToolsConfig.maxLimit;
+    const retrieverMaxLimit = options.maxLimit ?? findToolsConfig.maxLimit;
     this.retriever = new Retriever(this.cataloger, {
       indexDbPath: options.indexDbPath,
       defaultLimit: options.defaultLimit ?? findToolsConfig.defaultLimit,
-      maxLimit: this.maxLimit,
+      maxLimit: retrieverMaxLimit,
       defaultMode: findToolsConfig.defaultMode
     });
     const safetyEnv = readSafetyEnv();
@@ -7764,20 +8620,36 @@ class McpSquaredServer {
         });
       }
     });
-    this.registerMetaTools(this.mcpServer);
   }
   createMcpServer(name, version) {
-    return new McpServer({ name, version }, {
+    return new McpServer({
+      name,
+      version,
+      title: "MCP\xB2 Capability Router",
+      description: "Execute capability-first tools routed to connected upstream MCP servers."
+    }, {
       capabilities: {
         tools: {}
-      }
+      },
+      instructions: this.buildServerInstructions()
     });
   }
+  buildServerInstructions() {
+    return [
+      "Tool surface is generated at connect time from inferred upstream capabilities.",
+      "Each capability tool accepts `action`, `arguments`, and optional `confirmation_token`.",
+      'Call a capability tool with `action = "__describe_actions"` to inspect available actions and schemas.',
+      "Use returned action IDs for execution calls; if disambiguation is required, choose one candidate action and retry."
+    ].join(" ");
+  }
   createSessionServer() {
     const server = this.createMcpServer(this.serverName, this.serverVersion);
-    this.registerMetaTools(server);
+    this.registerConfiguredToolSurface(server);
     return server;
   }
+  registerConfiguredToolSurface(server) {
+    this.registerCapabilityRouters(server);
+  }
   runTaskSpan(taskName, run) {
     return task_span(this.obsSink, {
       agent: this.safetyAgent,
@@ -7786,358 +8658,239 @@ class McpSquaredServer {
       env: this.guard.agentEnv
     }, run);
   }
-  filterToolsByPolicy(tools) {
-    return tools.map((tool) => {
-      const visibility = getToolVisibilityCompiled(tool.serverKey, tool.name, this.compiledPolicy);
-      if (!visibility.visible) {
-        return null;
-      }
-      return visibility.requiresConfirmation ? { ...tool, requiresConfirmation: true } : tool;
-    }).filter((t) => t !== null);
-  }
-  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.",
-      inputSchema: {
-        query: z3.string().describe("Natural language search query to find relevant tools"),
-        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)')
-      }
-    }, async (args) => this.runTaskSpan("find_tools", async () => {
-      const requestId = this.statsCollector.startRequest();
-      const startTime = Date.now();
-      let success = false;
-      try {
-        const result = await this.retriever.search(args.query, {
-          limit: args.limit,
-          mode: args.mode
-        });
-        const filteredTools = this.filterToolsByPolicy(result.tools);
-        const detailLevel = args.detail_level ?? this.config.operations.findTools.defaultDetailLevel;
-        const tools = this.formatToolsForDetailLevel(filteredTools, detailLevel);
-        const selectionCacheConfig = this.config.operations.selectionCache;
-        let suggestedTools;
-        if (selectionCacheConfig.enabled && selectionCacheConfig.maxBundleSuggestions > 0) {
-          const toolKeys = filteredTools.map((t) => `${t.serverKey}:${t.name}`);
-          const suggestions = this.retriever.getIndexStore().getSuggestedBundles(toolKeys, selectionCacheConfig.minCooccurrenceThreshold, selectionCacheConfig.maxBundleSuggestions);
-          if (suggestions.length > 0) {
-            suggestedTools = suggestions.map((s) => ({
-              tools: [s.toolKey],
-              frequency: s.count
-            }));
-          }
-        }
-        success = true;
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                query: result.query,
-                totalMatches: filteredTools.length,
-                detailLevel,
-                searchMode: result.searchMode,
-                embeddingsAvailable: this.retriever.hasEmbeddings(),
-                tools,
-                ...suggestedTools && { suggestedTools }
-              })
-            }
-          ]
-        };
-      } finally {
-        const responseTime = Date.now() - startTime;
-        this.statsCollector.endRequest(requestId, success, responseTime, "find_tools", "mcp-squared");
+  capabilityTitle(capability) {
+    return capabilityTitle(capability);
+  }
+  capabilitySummary(capability) {
+    return capabilitySummary(capability);
+  }
+  actionSummary(description, capability) {
+    if (typeof description === "string") {
+      const singleLine = description.split(/\r?\n/, 1)[0]?.trim() ?? "";
+      if (singleLine.length > 0) {
+        return singleLine;
       }
-    }));
-    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.",
-      inputSchema: {
-        tool_names: z3.array(z3.string()).min(1).max(20).describe("List of tool names to get schemas for")
-      }
-    }, async (args) => this.runTaskSpan("describe_tools", async () => {
-      const requestId = this.statsCollector.startRequest();
-      const startTime = Date.now();
-      let success = false;
-      try {
-        const result = this.retriever.getTools(args.tool_names);
-        const filteredTools = this.filterToolsByPolicy(result.tools);
-        const schemas = filteredTools.map((tool) => ({
-          name: tool.name,
-          qualifiedName: `${tool.serverKey}:${tool.name}`,
-          description: tool.description,
-          serverKey: tool.serverKey,
-          inputSchema: tool.inputSchema,
-          ...tool.requiresConfirmation && { requiresConfirmation: true }
-        }));
-        const toolKey = (tool) => `${tool.serverKey}:${tool.name}`;
-        const filteredKeys = new Set(filteredTools.map(toolKey));
-        const blocked = result.tools.filter((tool) => !filteredKeys.has(toolKey(tool))).map(toolKey);
-        const foundQualified = new Set(result.tools.map(toolKey));
-        const foundBare = new Set(result.tools.map((t) => t.name));
-        const ambiguousNames = new Set(result.ambiguous.map((a) => a.name));
-        const notFound = args.tool_names.filter((name) => !ambiguousNames.has(name) && !foundQualified.has(name) && !foundBare.has(name));
-        success = true;
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                schemas,
-                ambiguous: result.ambiguous.length > 0 ? result.ambiguous : undefined,
-                notFound: notFound.length > 0 ? notFound : undefined,
-                blocked: blocked.length > 0 ? blocked : undefined
-              })
-            }
-          ]
-        };
-      } finally {
-        const responseTime = Date.now() - startTime;
-        this.statsCollector.endRequest(requestId, success, responseTime, "describe_tools", "mcp-squared");
+    }
+    return `Execute ${this.capabilityTitle(capability)} action`;
+  }
+  buildCapabilityRouters() {
+    const status = this.cataloger.getStatus();
+    const inventories = [...status.entries()].filter(([, info]) => info.status === "connected").map(([namespace]) => ({
+      namespace,
+      tools: this.cataloger.getToolsForServer(namespace)
+    })).sort((a, b) => a.namespace.localeCompare(b.namespace));
+    if (inventories.length === 0) {
+      return [];
+    }
+    const overrides = {
+      ...this.computedCapabilityOverrides,
+      ...this.config.operations.dynamicToolSurface.capabilityOverrides
+    };
+    const grouping = groupNamespacesByCapability(inventories, overrides);
+    return buildCapabilityRouters(inventories, grouping, (desc, cap) => this.actionSummary(desc, cap));
+  }
+  registerCapabilityRouters(server) {
+    const routers = this.buildCapabilityRouters();
+    for (const router of routers) {
+      if (router.actions.length === 0) {
+        continue;
       }
-    }));
-    server.registerTool("execute", {
-      description: "Execute a tool on an upstream MCP server. The tool must exist and the arguments must match its schema.",
-      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"),
-        confirmation_token: z3.string().optional().describe("Optional confirmation token for tools that require explicit confirmation")
-      }
-    }, async (args) => this.runTaskSpan("execute", async () => {
-      const requestId = this.statsCollector.startRequest();
-      const startTime = Date.now();
-      let success = false;
-      let toolName;
-      let serverKey;
-      try {
-        const lookupResult = this.cataloger.findTool(args.tool_name);
-        if (lookupResult.ambiguous) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: JSON.stringify({
-                  error: `Ambiguous tool name "${args.tool_name}". Use a qualified name.`,
-                  alternatives: lookupResult.alternatives
-                })
-              }
-            ],
-            isError: true
-          };
+      server.registerTool(router.capability, {
+        title: this.capabilityTitle(router.capability),
+        description: this.capabilitySummary(router.capability),
+        annotations: {
+          readOnlyHint: false,
+          destructiveHint: false,
+          openWorldHint: true
+        },
+        inputSchema: {
+          action: z3.string().describe(`Action ID for ${router.capability}. Use "${DESCRIBE_ACTION2}" to inspect available actions and schemas.`),
+          arguments: z3.record(z3.string(), z3.unknown()).default({}).describe("Arguments for the selected capability action"),
+          confirmation_token: z3.string().optional().describe("Optional confirmation token for actions that require explicit confirmation")
         }
-        if (!lookupResult.tool) {
-          return {
-            content: [
-              {
-                type: "text",
-                text: JSON.stringify({
-                  error: `Tool not found: ${args.tool_name}`
-                })
-              }
-            ],
-            isError: true
-          };
-        }
-        const tool = lookupResult.tool;
-        toolName = tool.name;
-        serverKey = tool.serverKey;
-        const policyResult = evaluatePolicy({
-          serverKey: tool.serverKey,
-          toolName: tool.name,
-          confirmationToken: args.confirmation_token
-        }, this.config);
-        if (policyResult.decision === "block") {
+      }, async (rawArgs) => this.runTaskSpan(router.capability, async () => {
+        const requestId = this.statsCollector.startRequest();
+        const startTime = Date.now();
+        let success = false;
+        try {
+          const parsedArgs = isRecord3(rawArgs) ? { ...rawArgs } : {};
+          const action = typeof parsedArgs["action"] === "string" ? parsedArgs["action"] : "";
+          const confirmationToken = typeof parsedArgs["confirmation_token"] === "string" ? parsedArgs["confirmation_token"] : undefined;
+          const actionArgs = isRecord3(parsedArgs["arguments"]) ? parsedArgs["arguments"] : {};
+          if (action.length === 0) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({
+                    error: "Missing required action",
+                    capability: router.capability
+                  })
+                }
+              ],
+              isError: true
+            };
+          }
+          const visibleActions = router.actions.map((route2) => {
+            const visibility = getToolVisibilityCompiled(router.capability, route2.action, this.compiledPolicy);
+            if (!visibility.visible) {
+              return null;
+            }
+            return {
+              action: route2.action,
+              summary: route2.summary,
+              inputSchema: route2.inputSchema,
+              requiresConfirmation: visibility.requiresConfirmation
+            };
+          }).filter((entry) => entry !== null).sort((a, b) => a.action.localeCompare(b.action));
+          if (action === DESCRIBE_ACTION2) {
+            success = true;
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({
+                    capability: router.capability,
+                    actions: visibleActions,
+                    totalActions: visibleActions.length
+                  })
+                }
+              ]
+            };
+          }
+          const ambiguousCandidates = router.actions.filter((route2) => route2.baseAction === action).map((route2) => route2.action).sort((a, b) => a.localeCompare(b));
+          if (ambiguousCandidates.length > 1) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({
+                    requires_disambiguation: true,
+                    capability: router.capability,
+                    action,
+                    candidates: ambiguousCandidates
+                  })
+                }
+              ],
+              isError: true
+            };
+          }
+          const route = router.actions.find((entry) => entry.action === action);
+          if (!route) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: JSON.stringify({
+                    error: "Unknown action",
+                    capability: router.capability,
+                    action,
+                    availableActions: visibleActions.map((a) => a.action)
+                  })
+                }
+              ],
+              isError: true
+            };
+          }
+          const callResult = await this.executeRoutedTool({
+            capability: router.capability,
+            action: route.action,
+            qualifiedToolName: route.qualifiedName,
+            toolNameForCall: route.qualifiedName,
+            args: actionArgs,
+            ...confirmationToken != null ? { confirmationToken } : {}
+          });
+          success = !callResult.isError;
+          return callResult;
+        } catch {
           return {
             content: [
               {
                 type: "text",
                 text: JSON.stringify({
-                  error: policyResult.reason,
-                  blocked: true
+                  error: "Action execution failed"
                 })
               }
             ],
             isError: true
           };
+        } finally {
+          const responseTime = Date.now() - startTime;
+          this.statsCollector.endRequest(requestId, success, responseTime, router.capability, "capability");
         }
-        if (policyResult.decision === "confirm") {
-          return {
-            content: [
-              {
-                type: "text",
-                text: JSON.stringify({
-                  requires_confirmation: true,
-                  confirmation_token: policyResult.confirmationToken,
-                  message: policyResult.reason
-                })
-              }
-            ],
-            isError: false
-          };
-        }
-        const qualifiedToolName = `${tool.serverKey}:${tool.name}`;
-        this.guard.enforce({
-          agent: this.safetyAgent,
-          tool: qualifiedToolName,
-          action: "call",
-          params: args.arguments
-        });
-        const result = await tool_span(this.obsSink, {
-          agent: this.safetyAgent,
-          tool: qualifiedToolName,
-          action: "call",
-          playbook: this.guard.playbook,
-          env: this.guard.agentEnv
-        }, () => this.cataloger.callTool(args.tool_name, args.arguments));
-        if (!result.isError && this.config.operations.selectionCache.enabled) {
-          const toolKey = `${tool.serverKey}:${tool.name}`;
-          this.selectionTracker.trackToolUsage(toolKey);
-          if (this.selectionTracker.getSessionToolCount() >= 2) {
-            this.selectionTracker.flushToStore(this.retriever.getIndexStore());
-          }
-        }
-        success = !result.isError;
-        return {
-          content: result.content.map((c) => {
-            if (typeof c === "object" && c !== null && "type" in c) {
-              return c;
-            }
-            return {
-              type: "text",
-              text: JSON.stringify(c)
-            };
-          }),
-          isError: result.isError
-        };
-      } catch (err) {
-        const errorMessage2 = err instanceof Error ? err.message : String(err);
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                error: errorMessage2
-              })
-            }
-          ],
-          isError: true
-        };
-      } finally {
-        const responseTime = Date.now() - startTime;
-        this.statsCollector.endRequest(requestId, success, responseTime, toolName, serverKey);
-      }
-    }));
-    server.registerTool("clear_selection_cache", {
-      description: "Clears all learned tool co-occurrence patterns. Use this to reset the selection cache if suggestions become stale or irrelevant.",
-      inputSchema: {}
-    }, async () => this.runTaskSpan("clear_selection_cache", async () => {
-      const requestId = this.statsCollector.startRequest();
-      const startTime = Date.now();
-      let success = false;
-      try {
-        const countBefore = this.retriever.getIndexStore().getCooccurrenceCount();
-        this.retriever.getIndexStore().clearCooccurrences();
-        this.selectionTracker.reset();
-        success = true;
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                message: "Selection cache cleared",
-                patternsRemoved: countBefore
-              })
-            }
-          ]
-        };
-      } finally {
-        const responseTime = Date.now() - startTime;
-        this.statsCollector.endRequest(requestId, success, responseTime, "clear_selection_cache", "mcp-squared");
+      }));
+    }
+  }
+  normalizeToolResultContent(content) {
+    return content.map((entry) => {
+      if (typeof entry === "object" && entry !== null && "type" in entry) {
+        return entry;
       }
-    }));
-    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).",
-      inputSchema: {
-        include_tools: z3.boolean().default(false).describe("If true, includes the list of tool names available in each namespace")
-      }
-    }, async (args) => this.runTaskSpan("list_namespaces", async () => {
-      const requestId = this.statsCollector.startRequest();
-      const startTime = Date.now();
-      let success = false;
-      try {
-        const status = this.cataloger.getStatus();
-        const namespaces = [];
-        for (const [key, info] of status) {
-          const tools = this.cataloger.getToolsForServer(key);
-          const namespace = {
-            name: key,
-            status: info.status,
-            toolCount: tools.length
-          };
-          if (info.error) {
-            namespace.error = info.error;
+      return {
+        type: "text",
+        text: JSON.stringify(entry)
+      };
+    });
+  }
+  async executeRoutedTool(args) {
+    const policyResult = evaluatePolicy({
+      capability: args.capability,
+      action: args.action,
+      confirmationToken: args.confirmationToken
+    }, this.config);
+    if (policyResult.decision === "block") {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              error: "Action blocked by security policy",
+              blocked: true
+            })
           }
-          if (args.include_tools && tools.length > 0) {
-            namespace.tools = tools.map((t) => t.name);
+        ],
+        isError: true
+      };
+    }
+    if (policyResult.decision === "confirm") {
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              requires_confirmation: true,
+              confirmation_token: policyResult.confirmationToken,
+              message: "Action requires confirmation by security policy"
+            })
           }
-          namespaces.push(namespace);
-        }
-        const conflicts = this.cataloger.getConflictingTools();
-        const conflictingTools = {};
-        for (const [toolName, qualifiedNames] of conflicts) {
-          conflictingTools[toolName] = qualifiedNames;
-        }
-        success = true;
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                namespaces,
-                totalNamespaces: namespaces.length,
-                connectedCount: namespaces.filter((n) => n.status === "connected").length,
-                ...Object.keys(conflictingTools).length > 0 && {
-                  conflictingTools,
-                  conflictNote: "These tools exist on multiple servers. Use qualified names (namespace:tool_name) to disambiguate."
-                }
-              })
-            }
-          ]
-        };
-      } finally {
-        const responseTime = Date.now() - startTime;
-        this.statsCollector.endRequest(requestId, success, responseTime, "list_namespaces", "mcp-squared");
-      }
-    }));
-  }
-  formatToolsForDetailLevel(tools, level) {
-    switch (level) {
-      case "L0":
-        return tools.map((t) => ({
-          name: t.name,
-          serverKey: t.serverKey,
-          ...t.requiresConfirmation && { requiresConfirmation: true }
-        }));
-      case "L2": {
-        return tools.map((t) => {
-          const { tool } = this.cataloger.findTool(`${t.serverKey}:${t.name}`);
-          return {
-            name: t.name,
-            description: t.description,
-            serverKey: t.serverKey,
-            inputSchema: tool?.inputSchema ?? { type: "object" },
-            ...t.requiresConfirmation && { requiresConfirmation: true }
-          };
-        });
+        ],
+        isError: false
+      };
+    }
+    this.guard.enforce({
+      agent: this.safetyAgent,
+      tool: `${args.capability}:${args.action}`,
+      action: "call",
+      params: args.args
+    });
+    const result = await tool_span(this.obsSink, {
+      agent: this.safetyAgent,
+      tool: `${args.capability}:${args.action}`,
+      action: "call",
+      playbook: this.guard.playbook,
+      env: this.guard.agentEnv
+    }, () => this.cataloger.callTool(args.toolNameForCall, args.args));
+    if (!result.isError && this.config.operations.selectionCache.enabled) {
+      const toolKey = `${args.capability}:${args.action}`;
+      this.selectionTracker.trackToolUsage(toolKey);
+      if (this.selectionTracker.getSessionToolCount() >= 2) {
+        this.selectionTracker.flushToStore(this.retriever.getIndexStore());
       }
-      default:
-        return tools.map((t) => ({
-          name: t.name,
-          description: t.description,
-          serverKey: t.serverKey,
-          ...t.requiresConfirmation && { requiresConfirmation: true }
-        }));
     }
+    return {
+      content: this.normalizeToolResultContent(result.content),
+      isError: result.isError ?? false
+    };
   }
   syncIndex() {
     this.retriever.syncFromCataloger();
@@ -8161,8 +8914,39 @@ class McpSquaredServer {
   getToolStats(limit = 100) {
     return this.statsCollector.getToolStats(limit);
   }
+  async classifyNamespacesSemantic() {
+    const generator = this.retriever.getEmbeddingGenerator();
+    if (!generator) {
+      console.error("[mcp\xB2] Hybrid inference: embeddings not available, falling back to heuristic.");
+      return;
+    }
+    try {
+      const { SemanticCapabilityClassifier: SemanticCapabilityClassifier2 } = await Promise.resolve().then(() => (init_semantic_classifier(), exports_semantic_classifier));
+      const threshold = this.config.operations.dynamicToolSurface.semanticConfidenceThreshold;
+      const classifier = new SemanticCapabilityClassifier2(generator, {
+        confidenceThreshold: threshold
+      });
+      await classifier.initializeReferences();
+      const status = this.cataloger.getStatus();
+      const inventories = [...status.entries()].filter(([, info]) => info.status === "connected").map(([namespace]) => ({
+        namespace,
+        tools: this.cataloger.getToolsForServer(namespace)
+      }));
+      const result = await classifier.classifyBatch(inventories);
+      this.computedCapabilityOverrides = result.overrides;
+      const count = Object.keys(result.overrides).length;
+      console.error(`[mcp\xB2] Hybrid inference: classified ${count}/${inventories.length} namespaces semantically (${Math.round(result.inferenceMs)}ms).`);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      console.error(`[mcp\xB2] Hybrid inference: classification failed \u2014 ${message}. Falling back to heuristic.`);
+    }
+  }
   async start() {
     await this.startCore();
+    if (!this.baseToolsRegistered) {
+      this.registerConfiguredToolSurface(this.mcpServer);
+      this.baseToolsRegistered = true;
+    }
     this.transport = new StdioServerTransport2;
     await this.mcpServer.connect(this.transport);
     this.statsCollector.incrementActiveConnections();
@@ -8200,6 +8984,9 @@ class McpSquaredServer {
         console.error(`[mcp\xB2] Embeddings: initialization failed \u2014 ${message}. Falling back to fast (FTS5) search.`);
       }
     }
+    if (this.config.operations.dynamicToolSurface.inference === "hybrid") {
+      await this.classifyNamespacesSemantic();
+    }
     this.statsCollector.updateIndexRefreshTime(Date.now());
     this.indexRefreshManager.start();
     await this.monitorServer.start();
@@ -8227,6 +9014,249 @@ class McpSquaredServer {
   }
 }
 
+// src/status/runner.ts
+init_inference();
+
+// src/utils/context-stats.ts
+var CHARS_PER_TOKEN_ESTIMATE = 4;
+function estimateTokens(text) {
+  return Math.ceil(text.length / CHARS_PER_TOKEN_ESTIMATE);
+}
+function reconstructCapabilityToolMetadata(router) {
+  return {
+    name: router.capability,
+    title: capabilityTitle(router.capability),
+    description: capabilitySummary(router.capability),
+    annotations: {
+      readOnlyHint: false,
+      destructiveHint: false,
+      openWorldHint: true
+    },
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          description: `Action ID for ${router.capability}. Use "__describe_actions" to inspect available actions and schemas.`
+        },
+        arguments: {
+          type: "object",
+          additionalProperties: {},
+          default: {},
+          description: "Arguments for the selected capability action"
+        },
+        confirmation_token: {
+          type: "string",
+          description: "Optional confirmation token for actions that require explicit confirmation"
+        }
+      },
+      required: ["action"]
+    }
+  };
+}
+function computeContextStats(upstreamTools, routers) {
+  const withoutTokens = upstreamTools.reduce((sum, tool) => {
+    const serialized = JSON.stringify({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema
+    });
+    return sum + estimateTokens(serialized);
+  }, 0);
+  const activeRouters = routers.filter((r) => r.actions.length > 0);
+  const withTokens = activeRouters.reduce((sum, router) => {
+    const meta = reconstructCapabilityToolMetadata(router);
+    return sum + estimateTokens(JSON.stringify(meta));
+  }, 0);
+  const saved = withoutTokens - withTokens;
+  const percent = withoutTokens > 0 ? saved / withoutTokens * 100 : 0;
+  return {
+    withoutMcp2Tokens: withoutTokens,
+    withMcp2Tokens: withTokens,
+    savedTokens: saved,
+    savedPercent: Math.round(percent * 10) / 10,
+    upstreamToolCount: upstreamTools.length,
+    capabilityToolCount: activeRouters.length
+  };
+}
+
+// src/status/runner.ts
+var GREEN = "\x1B[32m";
+var YELLOW = "\x1B[33m";
+var RED = "\x1B[31m";
+var DIM = "\x1B[90m";
+var BOLD = "\x1B[1m";
+var RESET = "\x1B[0m";
+async function collectStatus(config) {
+  const cataloger = new Cataloger({ connectTimeoutMs: 15000 });
+  const upstreams = [];
+  try {
+    await cataloger.connectAll(config);
+    const status = cataloger.getStatus();
+    for (const [name, serverConfig] of Object.entries(config.upstreams)) {
+      if (!serverConfig.enabled) {
+        upstreams.push({
+          name,
+          enabled: false,
+          status: "disconnected",
+          toolCount: 0
+        });
+        continue;
+      }
+      const connStatus = status.get(name);
+      const connection = cataloger.getConnection(name);
+      upstreams.push({
+        name,
+        enabled: true,
+        status: connStatus?.status ?? "disconnected",
+        error: connStatus?.error,
+        toolCount: connection?.tools.length ?? 0,
+        serverName: connection?.serverName,
+        serverVersion: connection?.serverVersion
+      });
+    }
+    const inventories = [...status.entries()].filter(([, info]) => info.status === "connected").map(([namespace]) => ({
+      namespace,
+      tools: cataloger.getToolsForServer(namespace)
+    })).sort((a, b) => a.namespace.localeCompare(b.namespace));
+    let routers = [];
+    if (inventories.length > 0) {
+      const overrides = config.operations.dynamicToolSurface.capabilityOverrides ?? {};
+      const grouping = groupNamespacesByCapability(inventories, overrides);
+      routers = buildCapabilityRouters(inventories, grouping);
+    }
+    const allUpstreamTools = inventories.flatMap((inv) => inv.tools);
+    const contextStats = computeContextStats(allUpstreamTools, routers);
+    return { upstreams, routers, contextStats };
+  } finally {
+    await cataloger.disconnectAll();
+  }
+}
+function formatStatus(result, options) {
+  const lines = [];
+  lines.push("");
+  lines.push(`${BOLD}MCP\xB2 Status Report${RESET}`);
+  lines.push("");
+  lines.push(`${DIM}\u2500\u2500 Upstream Servers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500${RESET}`);
+  if (result.upstreams.length === 0) {
+    lines.push(`  ${DIM}(no upstreams configured)${RESET}`);
+  }
+  for (const upstream of result.upstreams) {
+    if (!upstream.enabled) {
+      lines.push(`  ${DIM}\u2298 ${upstream.name.padEnd(24)} disabled${RESET}`);
+      continue;
+    }
+    if (upstream.status === "connected") {
+      const toolInfo = `(${upstream.toolCount} tool${upstream.toolCount !== 1 ? "s" : ""})`;
+      const version = upstream.serverVersion ? `  ${DIM}v${upstream.serverVersion}${RESET}` : "";
+      lines.push(`  ${GREEN}\u2713${RESET} ${upstream.name.padEnd(24)} connected  ${toolInfo}${version}`);
+    } else if (upstream.status === "needs_auth") {
+      const errorMsg = upstream.error ?? "Authentication required";
+      lines.push(`  ${YELLOW}\u26A0${RESET} ${upstream.name.padEnd(24)} needs auth ${DIM}${errorMsg}${RESET}`);
+    } else if (upstream.status === "error") {
+      const errorMsg = upstream.error ?? "Unknown error";
+      lines.push(`  ${RED}\u2717${RESET} ${upstream.name.padEnd(24)} error      ${DIM}${errorMsg}${RESET}`);
+    } else {
+      lines.push(`  ${DIM}? ${upstream.name.padEnd(24)} ${upstream.status}${RESET}`);
+    }
+  }
+  lines.push("");
+  lines.push(`${DIM}\u2500\u2500 Capability Routing \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500${RESET}`);
+  if (result.routers.length === 0) {
+    lines.push(`  ${DIM}(no capabilities routed \u2014 no connected upstreams)${RESET}`);
+  }
+  let totalActions = 0;
+  for (const router of result.routers) {
+    const count = router.actions.length;
+    totalActions += count;
+    const plural = count !== 1 ? "s" : "";
+    lines.push(`  ${BOLD}${router.capability}${RESET} ${DIM}(${count} action${plural})${RESET}`);
+    if (count === 0) {
+      lines.push(`    ${DIM}(no actions)${RESET}`);
+    }
+    for (const action of router.actions) {
+      const actionName = action.action.padEnd(28);
+      const mapping = `${DIM}\u2192${RESET} ${action.qualifiedName}`;
+      if (options.verbose) {
+        const schemaKeys = Object.keys(action.inputSchema?.properties ?? {});
+        const params = schemaKeys.length > 0 ? ` ${DIM}(${schemaKeys.join(", ")})${RESET}` : "";
+        lines.push(`    ${actionName} ${mapping}${params}`);
+      } else {
+        lines.push(`    ${actionName} ${mapping}`);
+      }
+    }
+    lines.push("");
+  }
+  if (options.verbose && result.contextStats) {
+    const cs = result.contextStats;
+    if (cs.upstreamToolCount > 0) {
+      lines.push(`${DIM}\u2500\u2500 Context Savings \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500${RESET}`);
+      const fmt = (n) => n.toLocaleString("en-US");
+      const withoutLabel = `Without MCP\xB2:`;
+      const withLabel = `With MCP\xB2:`;
+      const savedLabel = `Saved:`;
+      lines.push(`  ${withoutLabel.padEnd(16)} ${fmt(cs.withoutMcp2Tokens).padStart(8)} tokens  ${DIM}(${cs.upstreamToolCount} tool${cs.upstreamToolCount !== 1 ? "s" : ""})${RESET}`);
+      lines.push(`  ${withLabel.padEnd(16)} ${fmt(cs.withMcp2Tokens).padStart(8)} tokens  ${DIM}(${cs.capabilityToolCount} tool${cs.capabilityToolCount !== 1 ? "s" : ""})${RESET}`);
+      if (cs.savedTokens > 0) {
+        lines.push(`  ${DIM}${"\u2500".repeat(40)}${RESET}`);
+        lines.push(`  ${GREEN}${savedLabel.padEnd(16)} ${fmt(cs.savedTokens).padStart(8)} tokens  (${cs.savedPercent}%)${RESET}`);
+      }
+      lines.push("");
+    }
+  }
+  const connected = result.upstreams.filter((u) => u.status === "connected").length;
+  const needsAuth = result.upstreams.filter((u) => u.status === "needs_auth").length;
+  const errors = result.upstreams.filter((u) => u.status === "error").length;
+  const disabled = result.upstreams.filter((u) => !u.enabled).length;
+  const capCount = result.routers.filter((r) => r.actions.length > 0).length;
+  const parts = [];
+  if (connected > 0)
+    parts.push(`${GREEN}${connected} connected${RESET}`);
+  if (needsAuth > 0)
+    parts.push(`${YELLOW}${needsAuth} needs auth${RESET}`);
+  if (errors > 0)
+    parts.push(`${RED}${errors} error${RESET}`);
+  if (disabled > 0)
+    parts.push(`${DIM}${disabled} disabled${RESET}`);
+  const actionSummary = totalActions > 0 ? `${totalActions} action${totalActions !== 1 ? "s" : ""} across ${capCount} capabilit${capCount !== 1 ? "ies" : "y"}` : "no actions";
+  lines.push(`${DIM}Summary:${RESET} ${parts.join(", ")} | ${actionSummary}`);
+  lines.push("");
+  return lines.join(`
+`);
+}
+async function runStatus(options) {
+  let config;
+  let configPath;
+  try {
+    const loaded = await loadConfig();
+    config = loaded.config;
+    configPath = loaded.path;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`Error loading configuration: ${message}`);
+    console.error("Run 'mcp-squared config' to create or fix your configuration.");
+    process.exit(1);
+  }
+  const upstreamEntries = Object.entries(config.upstreams);
+  if (upstreamEntries.length === 0) {
+    console.error("Error: No upstreams configured. Run 'mcp-squared config' to add one.");
+    process.exit(1);
+  }
+  const validationIssues = validateConfig(config);
+  if (validationIssues.length > 0) {
+    console.error(formatValidationIssues(validationIssues));
+    console.error("");
+  }
+  if (options.verbose && configPath) {
+    console.log(`${DIM}Config: ${configPath}${RESET}`);
+  }
+  console.log("Connecting to upstream servers...");
+  const result = await collectStatus(config);
+  result.configPath = configPath;
+  const output = formatStatus(result, options);
+  console.log(output);
+}
+
 // src/index.ts
 function logSecurityProfile(config) {
   const { allow, confirm } = config.security.tools;
@@ -8945,9 +9975,15 @@ 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;
+    case "status":
+      await runStatus({ verbose: args.testVerbose });
+      break;
     case "daemon":
       await runDaemon(args.daemon);
       break;