dsh-desktop-kit 2.2.1 → 2.7.3

package/plugins/dsh-mcp-manager/lib/api.js

@@ -0,0 +1,250 @@
+/**
+ * Authenticated Connection RPC for the MCP Settings section.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import {
+  globalConfigPath,
+  loadConfig,
+  loadSecrets,
+  removeGlobalServer,
+  saveSecrets,
+  setGlobalServerFlags,
+  upsertGlobalServer,
+} from "./config.js";
+
+export const RPC_NAMESPACE = "dsh-mcp-manager";
+const ROUTE_BASE = "/api/dsh-mcp-manager";
+
+function okEnvelope(rpcId, value) {
+  return Response.json({ type: "server-response", rpcId, result: { ok: true, value } });
+}
+
+function errorEnvelope(rpcId, code, message) {
+  return Response.json({ type: "server-response", rpcId, result: { ok: false, error: { code, message, details: {} } } });
+}
+
+async function readEnvelope(request) {
+  const body = await request.json();
+  if (!body || body.type !== "client-request" || typeof body.rpcId !== "string" || typeof body.method !== "string") {
+    throw new Error("bad Connection envelope");
+  }
+  return { rpcId: body.rpcId, method: body.method, payload: body.payload ?? {} };
+}
+
+function publicServer(server) {
+  return {
+    id: server.id,
+    scope: server.scope,
+    transport: server.url ? "http" : "stdio",
+    command: server.command,
+    argsCount: server.args.length,
+    url: server.url ? (() => { try { return new URL(server.url).origin; } catch { return "invalid"; } })() : "",
+    enabled: server.enabled,
+    trusted: server.trusted,
+  };
+}
+
+function presets() {
+  return [
+    {
+      id: "github",
+      title: "GitHub",
+      subtitle: "Issues, pull requests, code search и Actions",
+      transport: "stdio",
+      command: "npx",
+      args: ["-y", "@modelcontextprotocol/server-github"],
+      tokenEnv: "GITHUB_TOKEN",
+      tokenLabel: "GitHub token",
+      tokenPlaceholder: "ghp_… или github_pat_…",
+      trusted: true,
+    },
+    {
+      id: "postgres",
+      title: "PostgreSQL",
+      subtitle: "Схема и read-only запросы; отдельная роль обязательна",
+      transport: "stdio",
+      command: "npx",
+      args: ["-y", "@modelcontextprotocol/server-postgres", "postgresql://readonly@localhost:5432/postgres"],
+      tokenEnv: "PGPASSWORD",
+      tokenLabel: "Пароль read-only роли",
+      tokenPlaceholder: "пароль",
+      trusted: true,
+    },
+    {
+      id: "filesystem",
+      title: "Filesystem",
+      subtitle: "Доступ к папке проекта; без токена",
+      transport: "stdio",
+      command: "npx",
+      args: ["-y", "@modelcontextprotocol/server-filesystem", "${cwd}"],
+      trusted: true,
+    },
+  ];
+}
+
+function configSnapshot(manager) {
+  const config = loadConfig({ cwd: process.cwd() });
+  const status = new Map(manager.status().map((row) => [row.id, row]));
+  return {
+    globalConfig: globalConfigPath(),
+    projectConfig: config.projectConfig,
+    secretsFile: path.join(path.dirname(globalConfigPath()), "mcp.secrets.json"),
+    servers: config.servers.filter((server) => server.scope === "global").map((server) => {
+      const row = status.get(server.id);
+      return {
+        ...publicServer(server),
+        connected: Boolean(row?.connected),
+        tools: row?.tools ?? 0,
+        error: row?.error ?? "",
+        serverInfo: row?.serverInfo ?? null,
+        projectTrusted: server.scope !== "project" || Boolean(server.trusted),
+      };
+    }),
+  };
+}
+
+async function restartGlobal(manager) {
+  await manager.close();
+  manager.reopen();
+  const config = loadConfig({ cwd: process.cwd() });
+  await manager.connectAll(config.servers.filter((server) => server.scope === "global" && server.enabled && server.trusted));
+  manager.registerTools();
+}
+
+function validateServer(payload) {
+  const id = String(payload.id ?? "").trim();
+  if (!/^[a-z0-9][a-z0-9_-]{0,32}$/u.test(id)) throw new Error("id: строчные латинские буквы, цифры, _ и -");
+  const transport = payload.transport === "http" ? "http" : "stdio";
+  if (transport === "http") {
+    if (!/^https?:\/\//u.test(String(payload.url ?? ""))) throw new Error("URL должен начинаться с http:// или https://");
+  } else if (String(payload.command ?? "").trim().length === 0) {
+    throw new Error("command обязателен");
+  }
+  return { id, transport, trusted: payload.trusted === true };
+}
+
+export function registerApi(ctx, manager) {
+  const operation = (name, handler) => {
+    const route = {
+      path: `${ROUTE_BASE}/${name}`,
+      methods: ["POST"],
+      requestBody: "buffered",
+      fetch: async (request) => {
+        let rpcId = "invalid-request";
+        try {
+          const envelope = await readEnvelope(request);
+          rpcId = envelope.rpcId;
+          if (envelope.method !== `${RPC_NAMESPACE}/${name}`) throw new Error("endpoint/method mismatch");
+          const value = await handler(envelope.payload);
+          return okEnvelope(rpcId, value);
+        } catch (error) {
+          return errorEnvelope(rpcId, "mcp/bad-request", error instanceof Error ? error.message : String(error));
+        }
+      },
+    };
+    ctx.effect(() => {
+      const dispose = ctx.connection.fetch.register(route);
+      return () => { try { void Promise.resolve(dispose()).catch(() => {}); } catch { /* unloading */ } };
+    }, `mcp-manager: ${name}`);
+  };
+
+  operation("status", async () => configSnapshot(manager));
+  operation("presets", async () => ({ presets: presets() }));
+  operation("trust-project", async () => {
+    const config = loadConfig({ cwd: process.cwd() });
+    if (!config.projectConfig) throw new Error("нет .dsh/mcp.json");
+    const marker = path.join(path.dirname(config.projectConfig), "mcp.trusted");
+    fs.writeFileSync(marker, `${new Date().toISOString()}\n`, "utf8");
+    await restartGlobal(manager);
+    return configSnapshot(manager);
+  });
+  operation("save", async (payload) => {
+    const { id, transport, trusted } = validateServer(payload);
+    const secrets = { ...loadSecrets() };
+    if (payload.tokenEnv && !payload.token && !secrets[`${id}.${String(payload.tokenEnv)}`]) {
+      throw new Error(`для ${payload.tokenEnv} нужен токен`);
+    }
+    if (payload.tokenHeader && payload.token && !payload.tokenHeader) throw new Error("tokenHeader обязателен для HTTP-токена");
+    const raw = { trusted, enabled: payload.enabled !== false };
+    if (transport === "http") {
+      raw.url = String(payload.url).trim();
+      const headers = {};
+      if (payload.token && payload.tokenHeader) {
+        headers[String(payload.tokenHeader)] = `Bearer \${secret:${id}.token}`;
+        secrets[`${id}.token`] = String(payload.token);
+      }
+      if (payload.headers && typeof payload.headers === "object") {
+        for (const [key, value] of Object.entries(payload.headers)) {
+          if (/^[A-Za-z0-9-]+$/u.test(key)) headers[key] = String(value);
+        }
+      }
+      if (Object.keys(headers).length > 0) raw.headers = headers;
+    } else {
+      raw.command = String(payload.command).trim();
+      raw.args = Array.isArray(payload.args) ? payload.args.map(String) : [];
+      const env = {};
+      if (payload.token && payload.tokenEnv) {
+        env[String(payload.tokenEnv)] = `\${secret:${id}.${String(payload.tokenEnv)}}`;
+        secrets[`${id}.${String(payload.tokenEnv)}`] = String(payload.token);
+      }
+      if (payload.env && typeof payload.env === "object") {
+        for (const [key, value] of Object.entries(payload.env)) {
+          if (/^[A-Za-z_][A-Za-z0-9_]*$/u.test(key)) env[key] = String(value);
+        }
+      }
+      if (Object.keys(env).length > 0) raw.env = env;
+    }
+    upsertGlobalServer(id, raw, Object.fromEntries(Object.entries(secrets).filter(([key]) => key.startsWith(`${id}.`))));
+    saveSecrets(secrets);
+    await restartGlobal(manager);
+    return configSnapshot(manager);
+  });
+  operation("remove", async (payload) => {
+    const id = String(payload.id ?? "");
+    removeGlobalServer(id);
+    await restartGlobal(manager);
+    return configSnapshot(manager);
+  });
+  operation("toggle", async (payload) => {
+    const id = String(payload.id ?? "");
+    setGlobalServerFlags(id, { enabled: payload.enabled, trusted: payload.trusted });
+    await restartGlobal(manager);
+    return configSnapshot(manager);
+  });
+  operation("test", async (payload) => {
+    const config = loadConfig({ cwd: process.cwd() });
+    const server = config.servers.find((item) => item.id === String(payload.id ?? ""));
+    if (!server) throw new Error("server not found");
+    const record = await manager.connect(server);
+    manager.registerTools();
+    return {
+      connected: Boolean(record.client?.connected),
+      tools: record.tools.length,
+      error: record.error,
+      serverInfo: record.client?.serverInfo ?? null,
+    };
+  });
+  operation("tools", async (payload) => {
+    const config = loadConfig({ cwd: process.cwd() });
+    const server = config.servers.find((item) => item.id === String(payload.id ?? ""));
+    if (!server) throw new Error("server not found");
+    const record = await manager.connect(server);
+    return {
+      tools: record.tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description ?? "",
+        schema: tool.inputSchema ?? null,
+      })),
+      error: record.error,
+    };
+  });
+  operation("call", async (payload) => {
+    const config = loadConfig({ cwd: process.cwd() });
+    const server = config.servers.find((item) => item.id === String(payload.id ?? ""));
+    if (!server) throw new Error("server not found");
+    await manager.connect(server);
+    const text = await manager.call(server.id, String(payload.tool ?? ""), payload.arguments ?? {});
+    return { text };
+  });
+}

package/plugins/dsh-mcp-manager/lib/client.js

@@ -0,0 +1,219 @@
+/**
+ * Minimal MCP client: JSON-RPC 2.0 over stdio or streamable HTTP.
+ *
+ * No SDK dependency: the kit stays installable as one package. Supports the
+ * primitives the manager needs today: initialize, tools/list, tools/call,
+ * resources/list, resources/read, resources/templates/list.
+ */
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+
+const PROTOCOL_VERSION = "2025-06-18";
+
+function makeId() {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+function parseJsonRpc(line) {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
+class StdioTransport {
+  constructor(config) {
+    this.config = config;
+    this.pending = new Map();
+    this.child = null;
+    this.closed = false;
+    this.stderr = "";
+  }
+
+  async start() {
+    this.child = spawn(this.config.command, this.config.args, {
+      cwd: this.config.cwd || process.cwd(),
+      env: { ...process.env, ...this.config.env },
+      stdio: ["pipe", "pipe", "pipe"],
+      windowsHide: true,
+    });
+    const reader = createInterface({ input: this.child.stdout });
+    reader.on("line", (line) => {
+      const message = parseJsonRpc(line);
+      if (!message) return;
+      if (message.id !== undefined && this.pending.has(String(message.id))) {
+        const waiter = this.pending.get(String(message.id));
+        this.pending.delete(String(message.id));
+        clearTimeout(waiter.timer);
+        if (message.error) waiter.reject(new Error(message.error.message || "MCP error"));
+        else waiter.resolve(message.result);
+      }
+    });
+    this.child.stderr.on("data", (chunk) => {
+      this.stderr = `${this.stderr}${chunk.toString("utf8")}`.slice(-4_000);
+    });
+    this.child.on("exit", (code) => {
+      for (const waiter of this.pending.values()) {
+        clearTimeout(waiter.timer);
+        waiter.reject(new Error(`MCP server exited (${code ?? "?"}): ${this.stderr.trim().slice(-500)}`));
+      }
+      this.pending.clear();
+      this.closed = true;
+    });
+  }
+
+  async request(method, params, timeoutMs) {
+    if (this.closed || !this.child?.stdin?.writable) throw new Error("MCP server is not running");
+    const id = makeId();
+    const payload = { jsonrpc: "2.0", id, method, params: params ?? {} };
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`MCP ${method} timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+      this.child.stdin.write(`${JSON.stringify(payload)}\n`, (error) => {
+        if (!error) return;
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(error);
+      });
+    });
+  }
+
+  notify(method, params) {
+    if (this.closed || !this.child?.stdin?.writable) return;
+    this.child.stdin.write(`${JSON.stringify({ jsonrpc: "2.0", method, params: params ?? {} })}\n`);
+  }
+
+  async close() {
+    this.closed = true;
+    for (const waiter of this.pending.values()) {
+      clearTimeout(waiter.timer);
+      waiter.reject(new Error("MCP server closed"));
+    }
+    this.pending.clear();
+    try { this.child?.stdin?.end(); } catch { /* best effort */ }
+    try { this.child?.kill(); } catch { /* best effort */ }
+  }
+}
+
+class HttpTransport {
+  constructor(config) {
+    this.config = config;
+    this.sessionId = "";
+    this.pending = new Map();
+  }
+
+  async request(method, params, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(new Error("timeout")), timeoutMs);
+    try {
+      const response = await fetch(this.config.url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          accept: "application/json, text/event-stream",
+          ...(this.sessionId ? { "mcp-session-id": this.sessionId } : {}),
+          ...this.config.headers,
+        },
+        body: JSON.stringify({ jsonrpc: "2.0", id: makeId(), method, params: params ?? {} }),
+        signal: controller.signal,
+      });
+      const sessionId = response.headers.get("mcp-session-id");
+      if (sessionId) this.sessionId = sessionId;
+      if (!response.ok) throw new Error(`MCP HTTP ${response.status}: ${(await response.text()).slice(0, 500)}`);
+      const text = await response.text();
+      if (text.trim() === "") return undefined;
+      const contentType = response.headers.get("content-type") || "";
+      if (contentType.includes("text/event-stream")) {
+        for (const line of text.split(/\r?\n/u)) {
+          if (!line.startsWith("data:")) continue;
+          const message = parseJsonRpc(line.slice(5).trim());
+          if (!message || message.id === undefined) continue;
+          if (message.error) throw new Error(message.error.message || "MCP error");
+          if (message.result !== undefined) return message.result;
+        }
+        throw new Error("MCP HTTP: no JSON-RPC response in event stream");
+      }
+      const message = parseJsonRpc(text);
+      if (!message) throw new Error("MCP HTTP: invalid JSON response");
+      if (message.error) throw new Error(message.error.message || "MCP error");
+      return message.result;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  notify() {
+    /* MCP streamable HTTP notifications are optional for our read-only tools. */
+  }
+
+  async close() {
+    /* stateless: nothing to close */
+  }
+}
+
+export class McpClient {
+  constructor(config, logger) {
+    this.config = config;
+    this.logger = logger;
+    this.transport = config.url ? new HttpTransport(config) : new StdioTransport(config);
+    this.connected = false;
+    this.serverInfo = null;
+    this.capabilities = {};
+    this.tools = [];
+    this.resources = [];
+  }
+
+  async connect() {
+    await this.transport.start?.();
+    const result = await this.transport.request(
+      "initialize",
+      {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {},
+        clientInfo: { name: "dsh-mcp-manager", version: "1.0.0" },
+      },
+      this.config.timeoutMs,
+    );
+    this.serverInfo = result?.serverInfo ?? null;
+    this.capabilities = result?.capabilities ?? {};
+    this.transport.notify("notifications/initialized");
+    this.connected = true;
+    return this;
+  }
+
+  async listTools() {
+    const tools = [];
+    let cursor;
+    do {
+      const result = await this.transport.request("tools/list", cursor ? { cursor } : {}, this.config.timeoutMs);
+      if (Array.isArray(result?.tools)) tools.push(...result.tools);
+      cursor = result?.nextCursor;
+    } while (cursor);
+    this.tools = tools;
+    return tools;
+  }
+
+  async callTool(name, args = {}) {
+    return this.transport.request("tools/call", { name, arguments: args }, this.config.timeoutMs);
+  }
+
+  async listResources() {
+    if (!this.capabilities.resources) return [];
+    const result = await this.transport.request("resources/list", {}, this.config.timeoutMs);
+    this.resources = Array.isArray(result?.resources) ? result.resources : [];
+    return this.resources;
+  }
+
+  async readResource(uri) {
+    return this.transport.request("resources/read", { uri }, this.config.timeoutMs);
+  }
+
+  async close() {
+    await this.transport.close?.();
+    this.connected = false;
+  }
+}

package/plugins/dsh-mcp-manager/lib/config.js

@@ -0,0 +1,217 @@
+/**
+ * MCP server configuration.
+ *
+ * Global: `~/.dsh/mcp.json`
+ * Project: `<project>/.dsh/mcp.json` (loaded by `/mcp`, not auto-started)
+ *
+ * Servers are never started unless `trusted: true`; this is deliberate because
+ * a stdio server is arbitrary process execution.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export function mcpHome() {
+  return process.env.DSH_HOME || path.join(os.homedir(), ".dsh");
+}
+
+export function globalConfigPath() {
+  return path.join(mcpHome(), "mcp.json");
+}
+
+export function secretsPath() {
+  return path.join(mcpHome(), "mcp.secrets.json");
+}
+
+export function loadSecrets(home = mcpHome()) {
+  const file = path.join(home, "mcp.secrets.json");
+  if (!fs.existsSync(file)) return {};
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+    return parsed && typeof parsed === "object" ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+export function saveSecrets(secrets, home = mcpHome()) {
+  const file = path.join(home, "mcp.secrets.json");
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(file, `${JSON.stringify(secrets, null, 2)}\n`, { mode: 0o600 });
+  return file;
+}
+
+export function readGlobalConfig() {
+  try {
+    return readJson(globalConfigPath()) ?? { mcpServers: {} };
+  } catch {
+    return { mcpServers: {} };
+  }
+}
+
+export function writeGlobalConfig(config) {
+  const file = globalConfigPath();
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  return file;
+}
+
+export function upsertGlobalServer(id, server, secrets = {}) {
+  if (!/^[a-z0-9][a-z0-9_-]{0,32}$/u.test(id)) throw new Error("server id must match [a-z0-9_-]{1,33}");
+  const config = readGlobalConfig();
+  config.mcpServers = config.mcpServers && typeof config.mcpServers === "object" ? config.mcpServers : {};
+  config.mcpServers[id] = server;
+  writeGlobalConfig(config);
+  const nextSecrets = { ...loadSecrets(), ...secrets };
+  if (Object.keys(secrets).length > 0) saveSecrets(nextSecrets);
+  return config;
+}
+
+export function removeGlobalServer(id) {
+  const config = readGlobalConfig();
+  if (config.mcpServers && typeof config.mcpServers === "object") delete config.mcpServers[id];
+  writeGlobalConfig(config);
+  const secrets = loadSecrets();
+  for (const key of Object.keys(secrets)) {
+    if (key.startsWith(`${id}.`)) delete secrets[key];
+  }
+  saveSecrets(secrets);
+  return config;
+}
+
+export function setGlobalServerFlags(id, flags) {
+  const config = readGlobalConfig();
+  const server = config.mcpServers?.[id];
+  if (!server) throw new Error(`server not found: ${id}`);
+  if (typeof flags.enabled === "boolean") server.enabled = flags.enabled;
+  if (typeof flags.trusted === "boolean") server.trusted = flags.trusted;
+  writeGlobalConfig(config);
+  return config;
+}
+
+export function findProject(start) {
+  let current = path.resolve(start || process.cwd());
+  for (let depth = 0; depth < 8; depth += 1) {
+    const dsh = path.join(current, ".dsh");
+    if (fs.existsSync(dsh)) return { root: current, config: path.join(dsh, "mcp.json") };
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return { root: path.resolve(start || process.cwd()), config: null };
+}
+
+function readJson(file) {
+  if (!file || !fs.existsSync(file)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    throw new Error(`${file}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function resolveValue(value, env, secrets) {
+  if (typeof value !== "string") return value;
+  return value
+    .replace(/\$\{secret:([A-Za-z0-9_.-]+)\}/gu, (_, key) => {
+      const resolved = secrets?.[key];
+      if (resolved === undefined) throw new Error(`нет секрета ${key}`);
+      return resolved;
+    })
+    .replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/gu, (_, key) => {
+      const resolved = env[key];
+      if (resolved === undefined) throw new Error(`нет переменной окружения ${key}`);
+      return resolved;
+    });
+}
+
+function normalizeServer(id, raw, env, secrets) {
+  if (!raw || typeof raw !== "object") throw new Error(`server ${id}: must be an object`);
+  const command = typeof raw.command === "string" ? raw.command.trim() : "";
+  const url = typeof raw.url === "string" ? raw.url.trim() : "";
+  if (!command && !url) throw new Error(`server ${id}: command or url is required`);
+  if (command && url) throw new Error(`server ${id}: choose command or url, not both`);
+  const args = Array.isArray(raw.args) ? raw.args.map((arg) => String(arg)) : [];
+  const rawEnv = raw.env && typeof raw.env === "object" ? raw.env : {};
+  const resolvedEnv = {};
+  for (const [key, value] of Object.entries(rawEnv)) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(key)) continue;
+    resolvedEnv[key] = resolveValue(String(value), env, secrets);
+  }
+  const headers = {};
+  if (raw.headers && typeof raw.headers === "object") {
+    for (const [key, value] of Object.entries(raw.headers)) {
+      if (!/^[A-Za-z0-9-]+$/u.test(key)) continue;
+      headers[key] = resolveValue(String(value), env, secrets);
+    }
+  }
+  return {
+    id,
+    command,
+    args,
+    url,
+    env: resolvedEnv,
+    headers,
+    cwd: typeof raw.cwd === "string" ? raw.cwd : undefined,
+    timeoutMs: Math.max(1_000, Math.min(120_000, Number(raw.timeoutMs) || 30_000)),
+    trusted: raw.trusted === true,
+    enabled: raw.enabled !== false,
+  };
+}
+
+export function loadConfig({ cwd = process.cwd(), env = process.env } = {}) {
+  const globalFile = globalConfigPath();
+  const project = findProject(cwd);
+  const projectTrusted = Boolean(project.config && fs.existsSync(path.join(path.dirname(project.config), "mcp.trusted")));
+  const secrets = loadSecrets();
+  const sources = [];
+  const servers = new Map();
+  for (const [file, scope] of [[globalFile, "global"], [project.config, "project"]]) {
+    if (!file) continue;
+    let parsed;
+    try {
+      parsed = readJson(file);
+    } catch (error) {
+      sources.push({ file, scope, error: error instanceof Error ? error.message : String(error) });
+      continue;
+    }
+    if (!parsed) continue;
+    sources.push({ file, scope });
+    const map = parsed.mcpServers && typeof parsed.mcpServers === "object" ? parsed.mcpServers : {};
+    for (const [id, raw] of Object.entries(map)) {
+      if (!/^[a-z0-9][a-z0-9_-]{0,32}$/u.test(id)) continue;
+      try {
+        const normalized = normalizeServer(id, raw, env, secrets);
+        if (scope === "project" && !projectTrusted) normalized.trusted = false;
+        servers.set(id, { ...normalized, scope });
+      } catch (error) {
+        sources.push({ file, scope, error: error instanceof Error ? error.message : String(error) });
+      }
+    }
+  }
+  return { servers: [...servers.values()], sources, projectRoot: project.root, projectConfig: project.config };
+}
+
+export function writeTemplate(file = globalConfigPath()) {
+  if (fs.existsSync(file)) return { created: false, file };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(
+    file,
+    `${JSON.stringify(
+      {
+        mcpServers: {
+          example: {
+            command: "npx",
+            args: ["-y", "@modelcontextprotocol/server-everything"],
+            trusted: false,
+            enabled: false,
+          },
+        },
+      },
+      null,
+      2,
+    )}\n`,
+    "utf8",
+  );
+  return { created: true, file };
+}