@znmin/claude-remote-cli 0.3.2 → 0.4.0

package/src/local/mcp-config.js

@@ -0,0 +1,320 @@
+import * as fs from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { parseArgs } from 'node:util';
+import { readJSON, withLock, writeJSON } from '../system.js';
+
+// MCP servers configured by the developer. They run on the LOCAL computer, so
+// they can reach intranet services and local programs, and are exposed to the
+// server Claude through the existing reverse tunnel.
+//
+// Scopes follow Claude Code: local (private to one project, stored in our
+// config directory) > project (.mcp.json in the project) > user (all projects).
+
+export const PROJECT_FILE = '.mcp.json';
+export const SCOPES = ['local', 'project', 'user'];
+const NAME = /^[A-Za-z0-9_-]{1,64}$/;
+const RESERVED = new Set(['local']);
+
+export function validateServerName(name) {
+  if (typeof name !== 'string' || !NAME.test(name))
+    throw new Error(`MCP 名称 ${JSON.stringify(name)} 无效：只能使用字母、数字、下划线和短横线，最长 64 个字符。`);
+  if (RESERVED.has(name)) throw new Error('名称 local 已被本地工具占用，请换一个名称。');
+  return name;
+}
+
+const isObject = value => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+function stringMap(value, label) {
+  if (value === undefined) return {};
+  if (!isObject(value) || Object.values(value).some(item => typeof item !== 'string'))
+    throw new Error(`${label} 必须是值为字符串的对象。`);
+  return { ...value };
+}
+
+// Validate one server entry and keep only the fields this tool understands.
+export function normalizeServer(config) {
+  if (!isObject(config)) throw new Error('配置必须是 JSON 对象。');
+  const type = config.type ?? (config.command !== undefined ? 'stdio' : config.url !== undefined ? 'http' : undefined);
+  if (type === 'stdio') {
+    if (typeof config.command !== 'string' || !config.command) throw new Error('stdio 类型需要 command。');
+    if (config.args !== undefined && (!Array.isArray(config.args) || config.args.some(arg => typeof arg !== 'string')))
+      throw new Error('args 必须是字符串数组。');
+    return { type, command: config.command, args: [...(config.args || [])], env: stringMap(config.env, 'env') };
+  }
+  if (type === 'http' || type === 'sse') {
+    if (typeof config.url !== 'string' || !config.url) throw new Error(`${type} 类型需要 url。`);
+    if (config.oauth !== undefined || config.headersHelper !== undefined)
+      throw new Error('暂不支持 OAuth 登录和 headersHelper；请改用固定 headers（可引用本机环境变量，如 "Authorization": "Bearer ${TOKEN}"）。');
+    return { type, url: config.url, headers: stringMap(config.headers, 'headers') };
+  }
+  throw new Error(type === undefined ? '缺少 type、command 或 url。' : `不支持的类型 ${type}；支持 stdio、http、sse。`);
+}
+
+// ${VAR} and ${VAR:-default}, expanded with the LOCAL environment so secrets
+// never leave this computer.
+export function expandServer(server, env) {
+  const missing = new Set();
+  const expand = value => value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (_, name, fallback) => {
+    if (env[name] !== undefined) return env[name];
+    if (fallback !== undefined) return fallback;
+    missing.add(name); return '';
+  });
+  const map = object => Object.fromEntries(Object.entries(object).map(([key, value]) => [key, expand(value)]));
+  const result = server.type === 'stdio'
+    ? { ...server, command: expand(server.command), args: server.args.map(expand), env: map(server.env) }
+    : { ...server, url: expand(server.url), headers: map(server.headers) };
+  if (missing.size) throw new Error(`缺少本机环境变量 ${[...missing].join('、')}。`);
+  if (result.type !== 'stdio') {
+    let url;
+    try { url = new URL(result.url); } catch { throw new Error(`url 无效：${result.url}`); }
+    if (!['http:', 'https:'].includes(url.protocol)) throw new Error('url 只支持 http 或 https。');
+  }
+  return result;
+}
+
+export function describeServer(server) {
+  if (server.type === 'stdio') return [server.command, ...server.args].join(' ');
+  return `${server.type.toUpperCase()} ${server.url}`;
+}
+
+const fingerprint = raw => createHash('sha256').update(JSON.stringify(raw)).digest('hex');
+
+export class McpStore {
+  constructor({ directory, lockFile, root }) {
+    this.file = path.join(directory, 'mcp.json');
+    this.lockFile = lockFile;
+    this.root = root;
+    this.projectFile = path.join(root, PROJECT_FILE);
+  }
+
+  async read() {
+    const data = await readJSON(this.file, {});
+    if (!isObject(data)) throw new Error(`${this.file} 格式无效。`);
+    data.mcpServers = isObject(data.mcpServers) ? data.mcpServers : {};
+    data.projects = isObject(data.projects) ? data.projects : {};
+    return data;
+  }
+
+  project(data) { return data.projects[this.root] ||= {}; }
+
+  update(callback) {
+    return withLock(this.lockFile, async () => {
+      const data = await this.read();
+      const result = await callback(data);
+      await writeJSON(this.file, data);
+      return result;
+    });
+  }
+
+  // Returns the parsed .mcp.json, or {} when absent. Throws on invalid JSON.
+  async readProjectFile() {
+    let text;
+    try { text = await fs.readFile(this.projectFile, 'utf8'); }
+    catch (error) { if (error.code === 'ENOENT') return {}; throw error; }
+    let data;
+    try { data = JSON.parse(text); } catch (error) { throw new Error(`${PROJECT_FILE} 不是有效的 JSON：${error.message}`); }
+    if (!isObject(data)) throw new Error(`${PROJECT_FILE} 必须是 JSON 对象。`);
+    return data;
+  }
+
+  async writeProjectFile(data) {
+    // Meant to be committed: keep normal permissions, unlike our private files.
+    await fs.writeFile(this.projectFile, JSON.stringify(data, null, 2) + '\n');
+  }
+
+  // Every configured entry by scope, unvalidated.
+  async entries() {
+    const data = await this.read();
+    const warnings = [];
+    let projectServers = {};
+    try {
+      const file = await this.readProjectFile();
+      if (file.mcpServers !== undefined && !isObject(file.mcpServers)) throw new Error(`${PROJECT_FILE} 的 mcpServers 必须是对象。`);
+      projectServers = file.mcpServers || {};
+    } catch (error) { warnings.push(error.message + ' 已忽略项目 MCP 配置。'); }
+    return {
+      data, warnings, scopes: {
+        user: data.mcpServers,
+        project: projectServers,
+        local: isObject(data.projects[this.root]?.mcpServers) ? data.projects[this.root].mcpServers : {}
+      }
+    };
+  }
+}
+
+// Merge scopes (local > project > user) and validate the winning entries.
+export async function loadServers(store) {
+  const { data, warnings, scopes } = await store.entries();
+  const chosen = new Map();
+  for (const scope of ['user', 'project', 'local'])
+    for (const [name, raw] of Object.entries(scopes[scope])) chosen.set(name, { name, scope, raw });
+  const servers = [];
+  for (const entry of chosen.values()) {
+    try {
+      validateServerName(entry.name);
+      servers.push({ ...entry, config: normalizeServer(entry.raw) });
+    } catch (error) { warnings.push(`MCP ${entry.name}（${entry.scope}）配置无效，已跳过：${error.message}`); }
+  }
+  const choices = data.projects[store.root]?.projectServerChoices || {};
+  for (const server of servers) if (server.scope === 'project') {
+    const choice = choices[server.name];
+    server.approved = choice?.hash === fingerprint(server.raw) ? Boolean(choice.approved) : undefined;
+  }
+  return { servers, warnings };
+}
+
+// Project .mcp.json can start arbitrary local programs, so each entry needs the
+// developer's approval. Choices are remembered per project until the entry changes.
+export async function approveServers(store, servers, { confirm, warn }) {
+  const pending = servers.filter(server => server.scope === 'project' && server.approved === undefined);
+  if (pending.length && confirm) {
+    const decisions = [];
+    for (const server of pending) {
+      server.approved = await confirm(server);
+      decisions.push(server);
+    }
+    await store.update(data => {
+      const choices = store.project(data).projectServerChoices ||= {};
+      for (const server of decisions) choices[server.name] = { hash: fingerprint(server.raw), approved: server.approved };
+    });
+  } else for (const server of pending)
+    warn(`项目 MCP ${server.name} 尚未确认，本次不启用。请在交互终端中启动 claude 进行确认。`);
+  return servers.filter(server => server.scope !== 'project' || server.approved === true);
+}
+
+const USAGE = `用法：
+  claude-remote mcp list
+  claude-remote mcp get <名称>
+  claude-remote mcp add [-s local|project|user] [-e KEY=值]... <名称> -- <命令> [参数...]
+  claude-remote mcp add -t http|sse [-s 范围] [-H "名称: 值"]... <名称> <URL>
+  claude-remote mcp add-json [-s 范围] <名称> '<JSON>'
+  claude-remote mcp remove [-s 范围] <名称>
+  claude-remote mcp reset-project-choices
+
+这些 MCP 在本机运行或从本机连接（可访问内网），通过本地模式的 SSH 隧道提供给服务器上的 Claude。
+默认范围 local 只对当前项目生效；project 写入项目的 .mcp.json；user 对所有项目生效。
+值中的 \${VAR} 在本机启动时展开，凭据不会发送到服务器。`;
+
+function scopeOption(value, fallback = 'local') {
+  const scope = value ?? fallback;
+  if (!SCOPES.includes(scope)) throw new Error(`范围只能是 ${SCOPES.join('、')}。`);
+  return scope;
+}
+
+async function saveServer(store, scope, name, raw) {
+  validateServerName(name);
+  normalizeServer(raw);
+  if (scope === 'project') {
+    const file = await store.readProjectFile();
+    if (file.mcpServers !== undefined && !isObject(file.mcpServers)) throw new Error(`${PROJECT_FILE} 的 mcpServers 必须是对象。`);
+    file.mcpServers = { ...file.mcpServers, [name]: raw };
+    await store.writeProjectFile(file);
+    // Whoever adds the entry here approves it for this computer.
+    await store.update(data => {
+      const choices = store.project(data).projectServerChoices ||= {};
+      choices[name] = { hash: fingerprint(raw), approved: true };
+    });
+  } else await store.update(data => {
+    const target = scope === 'user' ? data.mcpServers : (store.project(data).mcpServers ||= {});
+    target[name] = raw;
+  });
+}
+
+export async function runMcpCommand(store, args, { out = console.log } = {}) {
+  const [action, ...rest] = args;
+  if (!action || ['help', '--help', '-h'].includes(action)) { out(USAGE); return 0; }
+  if (action === 'list') {
+    if (rest.length) throw new Error(USAGE);
+    const { servers, warnings } = await loadServers(store);
+    for (const warning of warnings) out('警告：' + warning);
+    if (!servers.length) { out('尚未配置 MCP。运行 claude-remote mcp add --help 查看用法。'); return 0; }
+    for (const server of servers) {
+      const status = server.scope !== 'project' ? '' : server.approved === true ? '' : server.approved === false ? '，已拒绝' : '，待确认';
+      out(`${server.name}（${server.scope}${status}）：${describeServer(server.config)}`);
+    }
+    return 0;
+  }
+  if (action === 'get') {
+    if (rest.length !== 1) throw new Error(USAGE);
+    const { scopes } = await store.entries();
+    const found = SCOPES.filter(scope => scopes[scope][rest[0]] !== undefined);
+    if (!found.length) throw new Error(`没有找到 MCP ${rest[0]}。`);
+    for (const scope of found) out(`${rest[0]}（${scope}）：\n${JSON.stringify(scopes[scope][rest[0]], null, 2)}`);
+    return 0;
+  }
+  if (action === 'add') {
+    const { values, positionals } = parseArgs({ args: rest, allowPositionals: true, options: {
+      transport: { type: 'string', short: 't' }, scope: { type: 'string', short: 's' },
+      env: { type: 'string', short: 'e', multiple: true }, header: { type: 'string', short: 'H', multiple: true }
+    } });
+    const [name, target, ...commandArgs] = positionals;
+    if (!name || !target) throw new Error(USAGE);
+    const type = values.transport ?? 'stdio';
+    let raw;
+    if (type === 'stdio') {
+      if (values.header) throw new Error('-H 只用于 http/sse 类型。');
+      const env = {};
+      for (const item of values.env || []) {
+        const index = item.indexOf('=');
+        if (index < 1) throw new Error(`环境变量格式应为 KEY=值：${item}`);
+        env[item.slice(0, index)] = item.slice(index + 1);
+      }
+      raw = { type, command: target, args: commandArgs, ...(Object.keys(env).length ? { env } : {}) };
+    } else if (type === 'http' || type === 'sse') {
+      if (values.env) throw new Error('-e 只用于 stdio 类型。');
+      if (commandArgs.length) throw new Error('http/sse 类型只接受一个 URL。');
+      const headers = {};
+      for (const item of values.header || []) {
+        const index = item.indexOf(':');
+        if (index < 1) throw new Error(`请求头格式应为 "名称: 值"：${item}`);
+        headers[item.slice(0, index).trim()] = item.slice(index + 1).trim();
+      }
+      raw = { type, url: target, ...(Object.keys(headers).length ? { headers } : {}) };
+    } else throw new Error('类型只能是 stdio、http 或 sse。');
+    const scope = scopeOption(values.scope);
+    await saveServer(store, scope, name, raw);
+    out(`已添加 MCP ${name}（${scope}）：${describeServer(normalizeServer(raw))}`);
+    return 0;
+  }
+  if (action === 'add-json') {
+    const { values, positionals } = parseArgs({ args: rest, allowPositionals: true, options: { scope: { type: 'string', short: 's' } } });
+    if (positionals.length !== 2) throw new Error(USAGE);
+    let raw;
+    try { raw = JSON.parse(positionals[1]); } catch (error) { throw new Error('JSON 无效：' + error.message); }
+    const scope = scopeOption(values.scope);
+    await saveServer(store, scope, positionals[0], raw);
+    out(`已添加 MCP ${positionals[0]}（${scope}）：${describeServer(normalizeServer(raw))}`);
+    return 0;
+  }
+  if (action === 'remove') {
+    const { values, positionals } = parseArgs({ args: rest, allowPositionals: true, options: { scope: { type: 'string', short: 's' } } });
+    if (positionals.length !== 1) throw new Error(USAGE);
+    const name = positionals[0];
+    const { scopes } = await store.entries();
+    const found = SCOPES.filter(scope => scopes[scope][name] !== undefined);
+    let scope = values.scope === undefined ? undefined : scopeOption(values.scope);
+    if (scope === undefined) {
+      if (found.length > 1) throw new Error(`MCP ${name} 存在于多个范围（${found.join('、')}），请用 -s 指定。`);
+      scope = found[0];
+    }
+    if (!scope || !found.includes(scope)) throw new Error(`没有找到 MCP ${name}${values.scope ? `（${values.scope}）` : ''}。`);
+    if (scope === 'project') {
+      const file = await store.readProjectFile();
+      delete file.mcpServers[name];
+      await store.writeProjectFile(file);
+    } else await store.update(data => {
+      if (scope === 'user') delete data.mcpServers[name];
+      else delete store.project(data).mcpServers?.[name];
+    });
+    out(`已删除 MCP ${name}（${scope}）。`);
+    return 0;
+  }
+  if (action === 'reset-project-choices') {
+    if (rest.length) throw new Error(USAGE);
+    await store.update(data => { delete store.project(data).projectServerChoices; });
+    out('已清除当前项目 .mcp.json 的确认记录，下次启动时重新询问。');
+    return 0;
+  }
+  throw new Error(`未知的 mcp 子命令 ${action}。\n${USAGE}`);
+}

package/src/local/mcp-proxy.js

@@ -0,0 +1,199 @@
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import {
+  CallToolRequestSchema, GetPromptRequestSchema, ListPromptsRequestSchema, ListResourceTemplatesRequestSchema,
+  ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema
+} from '@modelcontextprotocol/sdk/types.js';
+import { describeServer, expandServer } from './mcp-config.js';
+
+const PACKAGE = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8'));
+
+// Claude persists very large MCP results on the server, where local mode cannot
+// read them back, so results are kept below this many characters.
+export const MAX_RESULT = 40000;
+export const CONNECT_TIMEOUT = 30000;
+export const CALL_TIMEOUT = 180000;
+const STDERR_LIMIT = 4000;
+
+// Shorten long text fields until the whole result fits. Binary data (images,
+// blobs) is left alone: cutting it would corrupt it.
+export function boundResult(result) {
+  if (JSON.stringify(result).length <= MAX_RESULT) return result;
+  const note = { type: 'text', text: '[结果过大，已截断较长文本。请缩小查询范围或分页读取。]' };
+  const shrink = (value, size) => {
+    if (Array.isArray(value)) return value.map(item => shrink(item, size));
+    if (!value || typeof value !== 'object') return value;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) =>
+      [key, key === 'text' && typeof item === 'string' && item.length > size
+        ? item.slice(0, size) + `…[已截断 ${item.length - size} 字符]` : shrink(item, size)]));
+  };
+  // Truncated text no longer matches structured output, so drop it.
+  const rest = { ...result };
+  delete rest.structuredContent;
+  for (let size = 16000; size >= 100; size = Math.floor(size / 2)) {
+    const shrunk = shrink(rest, size);
+    if (Array.isArray(shrunk.content)) shrunk.content = [...shrunk.content, note];
+    if (JSON.stringify(shrunk).length <= MAX_RESULT) return shrunk;
+  }
+  return { ...(result.isError ? { isError: true } : {}),
+    content: [{ type: 'text', text: JSON.stringify(rest).slice(0, 16000) }, note] };
+}
+
+function windowsTreeKill(pid, env) {
+  const taskkill = path.win32.join(env.SystemRoot || env.SYSTEMROOT || 'C:\\Windows', 'System32', 'taskkill.exe');
+  return new Promise(resolve => {
+    const killer = spawn(taskkill, ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+    killer.once('error', resolve); killer.once('close', resolve);
+  });
+}
+
+// One MCP server reached from this computer. Reconnects once if a stdio
+// process exits or an HTTP session drops during the Claude session.
+export class Upstream {
+  constructor(server, { root, env = process.env, debug = () => {}, platform = process.platform } = {}) {
+    this.name = server.name; this.scope = server.scope; this.server = server;
+    this.root = root; this.env = env; this.debug = debug; this.platform = platform;
+    this.stderr = ''; this.closed = false; this.current = null;
+  }
+
+  describe() { return describeServer(this.server.config); }
+
+  async open(signal) {
+    const config = expandServer(this.server.config, this.env);
+    const client = new Client({ name: 'claude-remote-proxy', version: PACKAGE.version }, { capabilities: {} });
+    let transport;
+    if (config.type === 'stdio') {
+      // Same environment as the local terminal, like Claude Code gives stdio servers.
+      transport = new StdioClientTransport({ command: config.command, args: config.args,
+        env: { ...this.env, ...config.env }, cwd: this.root, stderr: 'pipe' });
+      // Keep stderr off the terminal: the remote Claude UI is drawn there.
+      transport.stderr?.setEncoding('utf8');
+      transport.stderr?.on('data', chunk => {
+        this.stderr = (this.stderr + chunk).slice(-STDERR_LIMIT);
+        this.debug(`[MCP ${this.name}] ${chunk.trimEnd()}`);
+      });
+    } else {
+      const requestInit = { headers: config.headers };
+      transport = config.type === 'http'
+        ? new StreamableHTTPClientTransport(new URL(config.url), { requestInit })
+        : new SSEClientTransport(new URL(config.url), { requestInit });
+    }
+    const connection = { client, transport };
+    client.onclose = () => { if (this.current?.connection === connection) this.current = null; };
+    try { await client.connect(transport, { signal, timeout: CONNECT_TIMEOUT }); }
+    catch (error) {
+      await this.closeConnection(connection);
+      const detail = this.stderr.trim() ? `\n${this.stderr.trim().split('\n').slice(-5).join('\n')}` : '';
+      throw new Error(error.message + detail);
+    }
+    return connection;
+  }
+
+  // Connected client; opens or re-opens the connection when needed.
+  async client(signal) {
+    if (this.closed) throw new Error(`MCP ${this.name} 已关闭。`);
+    if (!this.current) {
+      const pending = { promise: this.open(signal) };
+      this.current = pending;
+      pending.promise.then(connection => { pending.connection = connection; },
+        () => { if (this.current === pending) this.current = null; });
+    }
+    return (await this.current.promise).client;
+  }
+
+  async connect(signal) {
+    const client = await this.client(signal);
+    this.info = { capabilities: client.getServerCapabilities() || {}, instructions: client.getInstructions(),
+      version: client.getServerVersion() };
+    return this;
+  }
+
+  async closeConnection({ client, transport }) {
+    const pid = transport.pid;
+    const closing = client.close().catch(() => {});
+    if (this.platform === 'win32' && pid) {
+      // Commands such as npx run through cmd.exe; stop the whole tree if the
+      // server does not exit after stdin closes.
+      const finished = await Promise.race([closing.then(() => true), new Promise(resolve => setTimeout(resolve, 1500, false))]);
+      if (!finished) await windowsTreeKill(pid, this.env);
+    }
+    await closing;
+  }
+
+  async close() {
+    this.closed = true;
+    const pending = this.current; this.current = null;
+    if (!pending) return;
+    const connection = await pending.promise.catch(() => null);
+    if (connection) await this.closeConnection(connection);
+  }
+
+  // A fresh MCP server for one stateless HTTP request from the remote Claude,
+  // mirroring the upstream's tools, resources and prompts.
+  createServer() {
+    const capabilities = {}, upstream = this.info?.capabilities || {};
+    if (upstream.tools) capabilities.tools = {};
+    if (upstream.resources) capabilities.resources = {};
+    if (upstream.prompts) capabilities.prompts = {};
+    const server = new Server({ name: this.info?.version?.name || this.name, version: this.info?.version?.version || '0.0.0' },
+      { capabilities, ...(this.info?.instructions ? { instructions: this.info.instructions } : {}) });
+    const forward = (schema, call) => server.setRequestHandler(schema, async (request, extra) =>
+      call(await this.client(extra.signal), request.params, { signal: extra.signal }));
+    if (capabilities.tools) {
+      forward(ListToolsRequestSchema, async (client, params, options) => {
+        const result = await client.listTools(params, options);
+        // Results may be truncated on the way back, so do not promise a schema.
+        return { ...result, tools: result.tools.map(tool => { const copy = { ...tool }; delete copy.outputSchema; return copy; }) };
+      });
+      forward(CallToolRequestSchema, async (client, params, options) => {
+        try {
+          const result = await client.callTool(params, undefined,
+            { ...options, timeout: CALL_TIMEOUT, resetTimeoutOnProgress: true });
+          if (!result.content?.length && result.structuredContent !== undefined)
+            result.content = [{ type: 'text', text: JSON.stringify(result.structuredContent) }];
+          return boundResult(result);
+        } catch (error) {
+          return { isError: true, content: [{ type: 'text', text: `MCP ${this.name} 调用失败：${error.message}` }] };
+        }
+      });
+    }
+    if (capabilities.resources) {
+      forward(ListResourcesRequestSchema, (client, params, options) => client.listResources(params, options));
+      forward(ListResourceTemplatesRequestSchema, (client, params, options) => client.listResourceTemplates(params, options));
+      forward(ReadResourceRequestSchema, async (client, params, options) => boundResult(await client.readResource(params, options)));
+    }
+    if (capabilities.prompts) {
+      forward(ListPromptsRequestSchema, (client, params, options) => client.listPrompts(params, options));
+      forward(GetPromptRequestSchema, async (client, params, options) => boundResult(await client.getPrompt(params, options)));
+    }
+    return server;
+  }
+}
+
+// Connect all servers in parallel. A server that fails is reported and left
+// out; it never blocks the session.
+export async function connectUpstreams(servers, { root, env, debug, warn, signal, create = server => new Upstream(server, { root, env, debug }) }) {
+  const connected = new Map();
+  await Promise.all(servers.map(async server => {
+    const upstream = create(server);
+    try {
+      await upstream.connect(signal);
+      connected.set(server.name, upstream);
+    } catch (error) {
+      await upstream.close();
+      if (!signal?.aborted) warn(`MCP ${server.name} 连接失败，本次不可用：${error.message}`);
+    }
+  }));
+  return connected;
+}
+
+export async function closeUpstreams(upstreams) {
+  await Promise.allSettled([...upstreams.values()].map(upstream => upstream.close()));
+  upstreams.clear();
+}