@hncode/hncode 0.3.1 → 0.3.3

package/src/index.js

@@ -9,6 +9,7 @@ import { Agent, SYSTEM_PROMPT } from './agent.js';
 import { llmTools } from './tools/index.js';
 import { setToolsList } from './llm.js';
 import { localVersion } from './version.js';
+import { EXIT, FORMATS, isValidFormat, buildResult, exitCodeFor, resultLine, createRunTracker, trackEvent, finalReply } from './ci.js';
 
 // The version shown by `hncode -V` and the help banner. Read from package.json
 // (via version.js) so it can never drift from the published version again.
@@ -29,7 +30,11 @@ Options:
   --auto                        Never ask; everything runs automatically.
   -m, --model <model>           Model alias to use for this invocation.
   -p, --prompt <prompt>         Run one prompt non-interactively and print the reply.
-  --output-format <format>      Output format for prompt mode: text (default) or stream-json.
+  --output-format <format>      Prompt mode output: text (default), json, or stream-json.
+                                json prints one result object; stream-json streams events then a result.
+                                Exit code reflects the outcome: 0 ok, 1 failure, 2 config, 3 no answer, 4 interrupted.
+  --control                     Expose a local control socket (prompt/status/interrupt) while the TUI runs.
+  --control <path>              Same, at an explicit socket path.
   --plan                        Start in plan mode (research only, no writes).
   --add-dir <dir>               Add an additional workspace directory. Repeatable.
   -h, --help                    Show help.
@@ -40,6 +45,12 @@ Commands:
   doctor config [path]          Validate a config.toml (default: merged config).
   init                          Create ~/.hncode/config.toml with defaults.
   export [id]                   Export a session to ~/.hncode/export/<id>.json.
+  control status                Ask a running session (started with --control) for its status.
+  control prompt <text>         Queue a prompt on a running session.
+  control interrupt             Interrupt the running turn.
+  hooks list                    Show configured shell hooks.
+  skills list                   List installed skills.
+  mcp list                      Show configured MCP servers.
 `;
 
 function printHelp() { process.stdout.write(HELP); }
@@ -55,7 +66,7 @@ export function parseArgs(argv) {
       if (eq >= 0) { key = a.slice(2, eq); val = a.slice(eq + 1); }
       else { key = a.slice(2); val = null; }
       if (key === 'resume') key = 'session'; // `--resume <id>` is an alias for `--session <id>`
-      if (['session'].includes(key) && val === null) { const nx = argv[i + 1]; out[key] = nx !== undefined && !nx.startsWith('-') ? (i++, nx) : true; }
+      if (['session', 'control'].includes(key) && val === null) { const nx = argv[i + 1]; out[key] = nx !== undefined && !nx.startsWith('-') ? (i++, nx) : true; }
 else if (key === 'model' || key === 'prompt' || key === 'output-format' || key === 'add-dir') {
         if (val === null) {
           const nx = argv[i + 1];
@@ -177,14 +188,42 @@ const SUBCOMMANDS = {
   'doctor': { 'config': cmdDoctorConfig },
   'init': cmdInit,
   'export': cmdExport,
+  'control': {
+    // Subcommands pass only positional[2] to their handler, so bind the op.
+    'status': (rest) => cmdControl('status', rest),
+    'prompt': (rest) => cmdControl('prompt', rest),
+    'interrupt': (rest) => cmdControl('interrupt', rest),
+  },
 };
 
+// ---- control (talk to a running --control session) --------------------------
+// `hncode control status|prompt|interrupt` — the client half of the control
+// socket the TUI opens with --control. Prints the JSON reply so a script can
+// parse it; exits non-zero when the running session could not be reached.
+async function cmdControl(sub, arg) {
+  const { sendControl } = await import('./ci.js');
+  const op = sub || 'status';
+  if (!['status', 'prompt', 'interrupt'].includes(op)) {
+    console.error(`unknown control op: ${op}. Use status | prompt <text> | interrupt.`);
+    return 1;
+  }
+  const req = { op };
+  if (op === 'prompt') {
+    const text = String(arg || '').trim();
+    if (!text) { console.error('control prompt requires text.'); return 1; }
+    req.text = text;
+  }
+  const res = await sendControl(req, { path: process.env.HNCODE_CONTROL_SOCKET || undefined });
+  console.log(JSON.stringify(res));
+  return res && res.ok ? 0 : 1;
+}
+
 // ---- headless prompt mode ----
 async function runPrompt({ cfg, prompt, format, session, modelArg }) {
   cfg = resolveModelArg(cfg, modelArg);
   if (!cfg.apiKey) {
     console.error('hncode: no api_key configured. Set HNCODE_API_KEY or configure a provider first. Run `hncode doctor config` to check.');
-    return 2;
+    return EXIT.CONFIG;
   }
   const messages = [];
   if (session && session.messages) for (const m of session.messages.slice(-30)) messages.push(m);
@@ -195,19 +234,28 @@ async function runPrompt({ cfg, prompt, format, session, modelArg }) {
   if (personal) sysText += '\n\n' + personal;
   messages.push({ role: 'system', content: sysText });
   const saved = session || { id: sess.newId(), title: prompt.slice(0, 60), workspace: path.resolve(process.cwd()), model: cfg.model, createdAt: Date.now(), messages: [] };
+  const tracker = createRunTracker();
+  const startedAt = Date.now();
+  let fatal = null;
   const agent = new Agent({
     cfg,
     messages,
     // Uncapped: run until the model finishes (see agent.js).
     onEvent: (e) => {
-      if (format === 'stream-json') {
-        if (e.type === 'context') return; // TUI-only gauge; not part of the JSON stream
-        const line = { type: e.type };
-        if (e.text) line.text = e.text;
-        if (e.name) line.name = e.name;
-        if (e.id) line.id = e.id;
-        if (e.content != null) line.content = e.content;
-        process.stdout.write(JSON.stringify(line) + '\n');
+      trackEvent(tracker, e);
+      if (e.type === 'error') fatal = (e.error && e.error.message) || String(e.error);
+      if (format === 'stream-json' || format === 'json') {
+        // `json` mode keeps stdout clean for the final envelope, so events go to
+        // stderr there. `stream-json` is the streaming contract: one event/line.
+        if (format === 'stream-json') {
+          if (e.type === 'context') return; // TUI-only gauge; not part of the stream
+          const line = { type: e.type };
+          if (e.text) line.text = e.text;
+          if (e.name) line.name = e.name;
+          if (e.id) line.id = e.id;
+          if (e.content != null) line.content = e.content;
+          process.stdout.write(JSON.stringify(line) + '\n');
+        }
       } else if (e.type === 'data') {
         process.stdout.write(e.text);
       }
@@ -216,8 +264,30 @@ async function runPrompt({ cfg, prompt, format, session, modelArg }) {
   saved.messages = messages;
   await agent.run();
   sess.saveSession(saved);
-  if (format !== 'stream-json') process.stdout.write('\n');
-  return 0;
+
+  const reply = finalReply(messages, tracker.text);
+  const result = buildResult({
+    reply,
+    toolCalls: tracker.toolCalls,
+    files: tracker.files,
+    error: fatal || (tracker.errors.length ? tracker.errors[tracker.errors.length - 1] : null),
+    stopped: !!agent.stopRequested,
+    durationMs: Date.now() - startedAt,
+    model: cfg.model,
+    sessionId: saved.id,
+  });
+
+  if (format === 'json') {
+    // Exactly one JSON object on stdout, so `| jq` / `tail -1` works.
+    process.stdout.write(resultLine(result) + '\n');
+  } else if (format === 'stream-json') {
+    // A terminating event tells a streaming reader the run is over and carries
+    // the same envelope, so both formats end with a `result` record.
+    process.stdout.write(resultLine(result) + '\n');
+  } else {
+    process.stdout.write('\n');
+  }
+  return exitCodeFor(result, false);
 }
 
 // ---- TUI dispatch ----
@@ -286,17 +356,44 @@ export async function main(argv) {
     await loadPlugins(cfg.pluginDir);
   }
 
+  // Connect configured MCP servers and register their tools, so a headless
+  // `-p` run and the TUI both see them. Failures are reported but never fatal:
+  // an unreachable server must not stop the session from starting.
+  if (cfg.mcp !== false) {
+    try {
+      const mcp = await import('./mcp.js');
+      const { API } = await import('./plugin.js');
+      const mcpCfg = mcp.loadMcpConfig(cfg.workspace);
+      if (Object.keys(mcpCfg.servers).length) {
+        const res = await mcp.connectAll(mcpCfg, (spec) => API.registerTool(spec));
+        mcp.setLiveConnections(res.servers);
+        if (process.env.HNCODE_MCP_VERBOSE === '1') {
+          for (const s of res.servers) {
+            console.error(s.ok ? `[hncode-mcp] ${s.name}: ${s.toolCount} tool(s)` : `[hncode-mcp] ${s.name}: ${s.error}`);
+          }
+        }
+      }
+    } catch (e) {
+      console.error(`hncode: MCP setup failed: ${e.message}`);
+    }
+  }
+
   // headless prompt
   if (args.prompt) {
+    const format = args['output-format'];
+    if (!isValidFormat(format)) {
+      console.error(`hncode: unknown --output-format "${format}". Use one of: ${FORMATS.join(', ')}.`);
+      return EXIT.CONFIG;
+    }
     let session = null;
     if (args.session) session = typeof args.session === 'string' ? sess.loadSession(args.session) : sess.latestSession(undefined, undefined, { skipEmpty: true });
     else if (args.continue) session = sess.latestSession(undefined, undefined, { skipEmpty: true });
-    return runPrompt({ cfg, prompt: args.prompt, format: args['output-format'], session, modelArg: args.model });
+    return runPrompt({ cfg, prompt: args.prompt, format, session, modelArg: args.model });
   }
 
   if (!process.stdout.isTTY) {
     console.error('hncode: interactive mode requires a TTY. Use `hncode -p "prompt"` for non-interactive use.');
-    return 1;
+    return EXIT.FAILURE;
   }
 
   const opts = {
@@ -308,10 +405,13 @@ export async function main(argv) {
     auto: !!args.auto,
     plan: !!args.plan,
     addDirs: args['add-dir'] || [],
+    // Remote control: expose a local socket so a script can queue a prompt or
+    // query status on the running session (see ci.js).
+    control: args.control === true ? '' : (typeof args.control === 'string' ? args.control : null),
     session: loadOrCreateSession(args, cfg),
   };
   await startTui(opts);
-  return 0;
+  return EXIT.OK;
 }
 
 // main() is invoked by bin/hncode (the CLI entry point), which imports this module

package/src/llm.js

@@ -9,6 +9,7 @@
 
 import { llmTools } from './tools/index.js';
 import { effortWire } from './config.js';
+import { applyPromptCache } from './cache.js';
 
 export function openAiToolDefs(tools) {
   return tools.map((t) => ({
@@ -101,9 +102,20 @@ function buildBody(cfg, messages, streaming = true) {
   const wire = effortWire(cfg, cfg.effort) || {};
   if (cfg.protocol === 'anthropic') {
     const { system, messages: am } = toAnthropic(messages);
-    return JSON.stringify({ model: cfg.innerModel, system, messages: am, tools: anthropicToolDefs(llmToolsList), ...common, ...wire });
+    const body = { model: cfg.innerModel, system, messages: am, tools: anthropicToolDefs(llmToolsList), ...common, ...wire };
+    // Prompt caching: mark the stable prefix (tools + system + conversation head)
+    // so the provider bills it as a cache READ instead of fresh input. The key is
+    // the SESSION id, so it stays identical across turns and never thrashes.
+    return JSON.stringify(applyPromptCache('anthropic', body, {
+      enabled: cfg.promptCache !== false,
+      sessionKey: cfg.sessionId,
+    }));
   }
-  return JSON.stringify({ model: cfg.innerModel, messages: toOpenAi(messages), tools: openAiToolDefs(llmToolsList), ...common, ...wire });
+  const body = { model: cfg.innerModel, messages: toOpenAi(messages), tools: openAiToolDefs(llmToolsList), ...common, ...wire };
+  return JSON.stringify(applyPromptCache('openai', body, {
+    enabled: cfg.promptCache !== false,
+    sessionKey: cfg.sessionId,
+  }));
 }
 
 // tool list used for defs (injected via setTools)

package/src/mcp.js

@@ -0,0 +1,376 @@
+// MCP client — connect to Model Context Protocol servers and expose their tools.
+//
+// The Model Context Protocol is an open JSON-RPC 2.0 standard. A server speaks it
+// over stdio (a child process) or HTTP. This module implements the CLIENT side so
+// an hncode session can use tools from servers the user configures.
+//
+// Config (`~/.hncode/mcp.json`, or a per-project `<workspace>/.hncode/mcp.json`):
+//
+//   {
+//     "mcpServers": {
+//       "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] },
+//       "remote":     { "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer ..." } }
+//     }
+//   }
+//
+// Lifecycle, per the spec:
+//   1. start the transport
+//   2. `initialize`                 (protocolVersion + clientInfo) -> capabilities
+//   3. `notifications/initialized`
+//   4. `tools/list`                 -> tool definitions
+//   5. `tools/call`                 -> per invocation
+//
+// Discovered tools are registered through plugin.registerTool() so they reach the
+// model with no changes to the toolbelt, the agent loop, or the LLM adapters.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import cp from 'node:child_process';
+
+// The protocol revision this client speaks. Servers negotiate down if needed.
+export const PROTOCOL_VERSION = '2024-11-05';
+export const CLIENT_INFO = { name: 'hncode', version: '0.3.1' };
+
+// Live connections made at startup, shared by every consumer of the MCP client
+// (the CLI startup and the TUI's /mcp). Kept in this module rather than passed
+// around so the status view can always see the real state.
+let liveConnections = [];
+export function setLiveConnections(conns) { liveConnections = conns || []; }
+export function getLiveConnections() { return liveConnections; }
+
+export function globalMcpFile() {
+  return process.env.HNCODE_MCP_FILE || path.join(os.homedir(), '.hncode', 'mcp.json');
+}
+export function projectMcpFile(workspace) {
+  return path.join(workspace || process.cwd(), '.hncode', 'mcp.json');
+}
+
+// Merge global + project server definitions (project wins on a name clash).
+// Returns { servers: {name: def}, errors: [string] }. Never throws.
+export function loadMcpConfig(workspace) {
+  const out = { servers: {}, errors: [] };
+  const files = workspace ? [globalMcpFile(), projectMcpFile(workspace)] : [globalMcpFile()];
+  const seen = new Set();
+  for (const f of files) {
+    const abs = path.resolve(f);
+    if (seen.has(abs)) continue;
+    seen.add(abs);
+    let text;
+    try { text = fs.readFileSync(abs, 'utf8'); } catch { continue; }
+    let doc;
+    try { doc = JSON.parse(text); } catch (e) { out.errors.push(`${abs}: invalid JSON (${e.message})`); continue; }
+    const servers = (doc && doc.mcpServers) || {};
+    for (const [name, def] of Object.entries(servers)) {
+      if (!def || typeof def !== 'object') { out.errors.push(`${abs}: server "${name}" must be an object`); continue; }
+      if (!def.command && !def.url) { out.errors.push(`${abs}: server "${name}" needs "command" or "url"`); continue; }
+      out.servers[name] = { ...def, _source: abs };
+    }
+  }
+  return out;
+}
+
+// ---- JSON-RPC framing -------------------------------------------------------
+
+// A stdio connection: newline-delimited JSON-RPC over the child's stdin/stdout.
+// MCP's stdio transport is line-delimited (NOT Content-Length framed — that is
+// the LSP convention, and mixing them up is the usual way this breaks).
+export function createStdioTransport(command, args, opts = {}) {
+  const child = cp.spawn(command, args || [], {
+    stdio: ['pipe', 'pipe', 'pipe'],
+    env: { ...process.env, ...(opts.env || {}) },
+    cwd: opts.cwd || process.cwd(),
+    windowsHide: true,
+    // npm-installed shims are `.cmd` on Windows and need a shell to run.
+    shell: process.platform === 'win32' && /\.(cmd|bat)$/i.test(command),
+  });
+  const state = {
+    child,
+    buffer: '',
+    nextId: 1,
+    pending: new Map(),   // id -> { resolve, reject, timer }
+    closed: false,
+    stderr: '',
+    handlers: [],
+  };
+  child.stdout.on('data', (d) => {
+    state.buffer += d.toString('utf8');
+    let i;
+    while ((i = state.buffer.indexOf('\n')) >= 0) {
+      const line = state.buffer.slice(0, i).trim();
+      state.buffer = state.buffer.slice(i + 1);
+      if (!line) continue;
+      let msg;
+      try { msg = JSON.parse(line); } catch { continue; }   // ignore non-JSON noise
+      handleMessage(state, msg);
+    }
+  });
+  child.stderr.on('data', (d) => { state.stderr = (state.stderr + d.toString('utf8')).slice(-4000); });
+  child.on('error', (e) => failAll(state, `server process error: ${e.message}`));
+  child.on('close', (code) => { state.closed = true; failAll(state, `server exited (code ${code})`); });
+  return state;
+}
+
+function handleMessage(state, msg) {
+  if (msg.id != null && state.pending.has(msg.id)) {
+    const p = state.pending.get(msg.id);
+    state.pending.delete(msg.id);
+    clearTimeout(p.timer);
+    if (msg.error) p.reject(new Error(msg.error.message || JSON.stringify(msg.error)));
+    else p.resolve(msg.result);
+    return;
+  }
+  // A server-initiated REQUEST (e.g. sampling). Answer politely so the server
+  // does not hang; hncode does not implement sampling, so it is "not supported".
+  if (msg.method && msg.id != null) {
+    try {
+      writeMessage(state, { jsonrpc: '2.0', id: msg.id, error: { code: -32601, message: `method not supported: ${msg.method}` } });
+    } catch { /* transport closed */ }
+    return;
+  }
+  for (const h of state.handlers) { try { h(msg); } catch { /* a notification handler must not throw */ } }
+}
+
+function failAll(state, reason) {
+  for (const [, p] of state.pending) { clearTimeout(p.timer); p.reject(new Error(reason)); }
+  state.pending.clear();
+}
+
+function writeMessage(state, msg) {
+  if (state.closed || !state.child.stdin || state.child.stdin.destroyed) throw new Error('transport closed');
+  state.child.stdin.write(JSON.stringify(msg) + '\n');
+}
+
+// Send a request and await its reply. `timeoutMs` guards a wedged server.
+export function request(state, method, params, timeoutMs = 30_000) {
+  const id = state.nextId++;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      state.pending.delete(id);
+      reject(new Error(`${method} timed out after ${timeoutMs}ms`));
+    }, timeoutMs);
+    state.pending.set(id, { resolve, reject, timer });
+    try { writeMessage(state, { jsonrpc: '2.0', id, method, params: params || {} }); }
+    catch (e) { state.pending.delete(id); clearTimeout(timer); reject(e); }
+  });
+}
+
+function notify(state, method, params) {
+  try { writeMessage(state, { jsonrpc: '2.0', method, params: params || {} }); } catch { /* best-effort */ }
+}
+
+// ---- HTTP transport ---------------------------------------------------------
+
+// Streamable-HTTP transport: one POST per JSON-RPC message. The server may reply
+// with JSON or an SSE stream; both are parsed here.
+export function createHttpTransport(url, headers) {
+  return {
+    kind: 'http',
+    url,
+    headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', ...(headers || {}) },
+    sessionId: null,
+    nextId: 1,
+  };
+}
+
+export async function httpRequest(state, method, params, timeoutMs = 30_000) {
+  const id = state.nextId++;
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const res = await fetch(state.url, {
+      method: 'POST',
+      headers: state.sessionId ? { ...state.headers, 'mcp-session-id': state.sessionId } : state.headers,
+      body: JSON.stringify({ jsonrpc: '2.0', id, method, params: params || {} }),
+      signal: ctrl.signal,
+    });
+    const sid = res.headers.get('mcp-session-id');
+    if (sid) state.sessionId = sid;
+    if (!res.ok) throw new Error(`HTTP ${res.status} ${res.statusText}`);
+    const ct = (res.headers.get('content-type') || '').toLowerCase();
+    if (ct.includes('text/event-stream')) {
+      const msg = parseSseForId(await res.text(), id);
+      if (!msg) throw new Error('no response message in SSE stream');
+      if (msg.error) throw new Error(msg.error.message || JSON.stringify(msg.error));
+      return msg.result;
+    }
+    const json = await res.json();
+    if (json.error) throw new Error(json.error.message || JSON.stringify(json.error));
+    return json.result;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// Pull the JSON-RPC reply for `id` out of an SSE body.
+export function parseSseForId(body, id) {
+  for (const line of String(body || '').split('\n')) {
+    const l = line.trim();
+    if (!l.startsWith('data:')) continue;
+    const payload = l.slice(5).trim();
+    if (!payload || payload === '[DONE]') continue;
+    try {
+      const msg = JSON.parse(payload);
+      if (msg && msg.id === id) return msg;
+    } catch { /* not JSON: skip */ }
+  }
+  return null;
+}
+
+// ---- connection + tool discovery -------------------------------------------
+
+// Connect to one server, handshake, and list its tools.
+// Returns { ok, tools, error, serverInfo, transport, isHttp } — never throws.
+export async function connectServer(name, def, opts = {}) {
+  const timeoutMs = opts.timeoutMs || 30_000;
+  let transport;
+  const isHttp = !!def.url;
+  try {
+    transport = isHttp
+      ? createHttpTransport(def.url, def.headers)
+      : createStdioTransport(def.command, def.args, { env: def.env, cwd: def.cwd });
+  } catch (e) {
+    return { ok: false, tools: [], error: `could not start "${name}": ${e.message}` };
+  }
+
+  const send = (method, params) => (isHttp
+    ? httpRequest(transport, method, params, timeoutMs)
+    : request(transport, method, params, timeoutMs));
+
+  try {
+    const init = await send('initialize', {
+      protocolVersion: PROTOCOL_VERSION,
+      capabilities: { tools: {} },
+      clientInfo: CLIENT_INFO,
+    });
+    if (!isHttp) notify(transport, 'notifications/initialized', {});
+    const list = await send('tools/list', {});
+    const tools = Array.isArray(list && list.tools) ? list.tools : [];
+    return { ok: true, tools, error: null, serverInfo: (init && init.serverInfo) || {}, transport, isHttp };
+  } catch (e) {
+    try { if (!isHttp) transport.child.kill(); } catch { /* already gone */ }
+    return { ok: false, tools: [], error: `"${name}": ${e.message}` };
+  }
+}
+
+// Call one tool on a connected server. Returns { ok, text, error, raw }.
+export async function callTool(transport, isHttp, toolName, args, timeoutMs = 60_000) {
+  try {
+    const result = isHttp
+      ? await httpRequest(transport, 'tools/call', { name: toolName, arguments: args || {} }, timeoutMs)
+      : await request(transport, 'tools/call', { name: toolName, arguments: args || {} }, timeoutMs);
+    return { ok: true, text: flattenContent(result), error: null, raw: result };
+  } catch (e) {
+    return { ok: false, text: '', error: e.message, raw: null };
+  }
+}
+
+// MCP tool results carry a `content` array of typed blocks. Flatten to text for
+// the model; non-text blocks are described rather than dropped silently.
+export function flattenContent(result) {
+  if (!result) return '';
+  if (typeof result === 'string') return result;
+  const blocks = Array.isArray(result.content) ? result.content : [];
+  const parts = [];
+  for (const b of blocks) {
+    if (!b || typeof b !== 'object') continue;
+    if (b.type === 'text' && typeof b.text === 'string') parts.push(b.text);
+    else if (b.type === 'resource' && b.resource) parts.push(`[resource ${b.resource.uri || ''}]`);
+    else if (b.type === 'image') parts.push(`[image ${b.mimeType || ''}]`);
+    else parts.push(`[${b.type || 'unknown'} block]`);
+  }
+  if (!parts.length && typeof result.text === 'string') parts.push(result.text);
+  return parts.join('\n');
+}
+
+// A tool name safe for every provider's function-name rules and for matching
+// back to its server + original name. Providers want [A-Za-z0-9_-], so
+// "server.tool" becomes "mcp__server__tool".
+export function mcpToolName(server, tool) {
+  const clean = (s) => String(s || '').replace(/[^A-Za-z0-9_-]/g, '_');
+  return `mcp__${clean(server)}__${clean(tool)}`;
+}
+
+// Convert an MCP tool definition into an hncode tool spec whose execute() calls
+// back into the server.
+export function toHncodeSpec(server, tool, transport, isHttp) {
+  return {
+    name: mcpToolName(server, tool.name),
+    description: (tool.description || `MCP tool ${tool.name} from ${server}.`).slice(0, 4000),
+    parameters: tool.inputSchema && typeof tool.inputSchema === 'object'
+      ? tool.inputSchema
+      : { type: 'object', properties: {} },
+    _mcp: { server, tool: tool.name },
+    async execute(args) {
+      const r = await callTool(transport, isHttp, tool.name, args);
+      if (!r.ok) return `Error calling ${server}/${tool.name}: ${r.error}`;
+      // MCP signals tool-level failure with isError, not a JSON-RPC error.
+      if (r.raw && r.raw.isError) return `Error from ${server}/${tool.name}: ${r.text}`;
+      return r.text || '(no output)';
+    },
+  };
+}
+
+// Connect every configured server and register its tools through the plugin API.
+// Returns { servers: [...], toolCount }.
+export async function connectAll(config, registerTool, opts = {}) {
+  const servers = [];
+  let toolCount = 0;
+  const only = opts.only;
+  for (const [name, def] of Object.entries((config && config.servers) || {})) {
+    if (only && !only.includes(name)) continue;
+    const conn = await connectServer(name, def, opts);
+    if (!conn.ok) {
+      servers.push({ name, ok: false, toolCount: 0, error: conn.error, serverInfo: {} });
+      continue;
+    }
+    let registered = 0;
+    let err = null;
+    for (const tool of conn.tools) {
+      if (!tool || !tool.name) continue;
+      try {
+        registerTool(toHncodeSpec(name, tool, conn.transport, conn.isHttp));
+        registered++;
+      } catch (e) {
+        // A name clash with a built-in is reported, not fatal: keep the rest.
+        err = err || `tool "${tool.name}": ${e.message}`;
+      }
+    }
+    toolCount += registered;
+    servers.push({ name, ok: true, toolCount: registered, error: err, serverInfo: conn.serverInfo, transport: conn.transport, isHttp: conn.isHttp });
+  }
+  return { servers, toolCount };
+}
+
+// Disconnect every connected server (kills stdio children). HTTP needs nothing.
+export function disconnectAll(connections) {
+  for (const c of connections || []) {
+    if (c && c.transport && c.transport.child) {
+      try { c.transport.child.kill(); } catch { /* already gone */ }
+    }
+  }
+}
+
+// Human-readable status for /mcp.
+export function describeServers(config, connections) {
+  const names = Object.keys((config && config.servers) || {});
+  if (!names.length) {
+    return ['No MCP servers configured.', '', `Config file: ${globalMcpFile()}`,
+      'Add one with /mcp-config add <name> <command|url> [args...]'];
+  }
+  const byName = new Map((connections || []).map((c) => [c.name, c]));
+  const lines = [`MCP servers (${names.length}) — config: ${globalMcpFile()}`, ''];
+  for (const n of names) {
+    const def = config.servers[n];
+    const conn = byName.get(n);
+    const target = def.url ? def.url : `${def.command || ''} ${(def.args || []).join(' ')}`.trim();
+    let status;
+    if (!conn) status = 'not connected';
+    else if (!conn.ok) status = `FAILED: ${conn.error}`;
+    else status = `connected — ${conn.toolCount} tool(s)${conn.serverInfo && conn.serverInfo.name ? ` (${conn.serverInfo.name})` : ''}`;
+    lines.push(`  ${n}: ${status}`);
+    lines.push(`      ${target}`);
+    if (conn && conn.error) lines.push(`      ! ${conn.error}`);
+  }
+  return lines;
+}