@memoket-ai/cli 2.0.1

package/src/cli.js

@@ -0,0 +1,475 @@
+// Command definitions.
+
+import { Command } from "commander";
+import { connect, listTools, callTool } from "./mcp-client.js";
+import { login, ensureToken, loadCreds, fetchWellKnown } from "./oauth.js";
+import { loginBasic } from "./auth-basic.js";
+import { listGatewayTools, callGatewayTool, getGatewayTool } from "./gateway.js";
+import { registerClaude, registerVSCode } from "./register.js";
+import { defaultName, version, credentialsPath, mcpURLFromBase } from "./config.js";
+import { tierOf, stripTier, firstLine, short, or, toolParams, requiredParamNames } from "./utils.js";
+import {
+  createAPIToken,
+  listAPITokens,
+  revokeAPIToken,
+  rotateAPIToken,
+} from "./http-integration.js";
+import {
+  listEndpoints,
+  useEndpoint,
+  activeMcpURL,
+  activeName,
+  activeBase,
+} from "./endpoints.js";
+
+// resolveURL 优先级：--url 一次性覆盖 > 当前激活的命名环境（补 /mcp）> 默认(prod)。
+// 激活环境读 ~/.memoket/config.json（同步），activeMcpURL 内部已回退默认 prod。
+function resolveURL(opts) {
+  if (opts.url) return opts.url;
+  return activeMcpURL();
+}
+
+// printToolParams 打印一个工具的参数清单（对齐 name / (必填) / 类型 / 描述）。
+// log 允许写到 stdout(describe) 或 stderr(报错提示)；full=true 时不截断描述。
+function printToolParams(tool, { log = console.log, full = false } = {}) {
+  const params = toolParams(tool);
+  if (params.length === 0) {
+    log("  (无参数)");
+    return;
+  }
+  const w = Math.max(...params.map((p) => p.name.length));
+  for (const p of params) {
+    const tag = p.required ? "(必填)" : "(可选)";
+    const type = (p.type || "").padEnd(9);
+    const desc = full ? p.description : firstLine(p.description);
+    log(`  ${p.name.padEnd(w)} ${tag} ${type} ${desc}`.replace(/\s+$/, ""));
+  }
+}
+
+// exampleFor 造一条 key=value 示例：优先拿必填参数，否则第一个参数；值用样例或占位。
+function exampleFor(tool, sampleValue) {
+  const params = toolParams(tool);
+  const pick = params.find((p) => p.required) || params[0];
+  const key = pick ? pick.name : "key";
+  const val = sampleValue !== undefined ? sampleValue : "value";
+  return `memoket call ${tool.name} ${key}=${val}`;
+}
+
+export function buildProgram() {
+  const program = new Command();
+  program
+    .name("memoket")
+    .description("Memoket MCP onboarding & passthrough CLI")
+    .version(version)
+    .option("--url <url>", "one-off MCP endpoint override (see `memoket endpoints`)")
+    .option("--name <name>", "service name when registering into a client", defaultName);
+
+  program
+    .command("setup")
+    .description("register Memoket MCP into local AI clients and log in (most common)")
+    .action(async (opts, cmd) => {
+      const root = cmd.parent;
+      const mcpURL = resolveURL(root.opts());
+      const name = root.opts().name;
+      console.log("== Memoket setup wizard ==");
+      console.log("MCP endpoint:", mcpURL);
+      console.log();
+
+      console.log("1) Register MCP into local AI clients");
+      const claude = await registerClaude(name, mcpURL);
+      if (claude.ok) {
+        console.log(`   - Claude Code: registered ✓\n       ${claude.cmd}`);
+      } else {
+        console.log(`   - Claude Code: skipped/failed — run manually:\n       ${claude.cmd}\n       (${claude.err.message})`);
+      }
+      const vscode = await registerVSCode(name, mcpURL);
+      if (vscode.ok) {
+        console.log("   - VS Code: registered ✓");
+      } else {
+        console.log(`   - VS Code: skipped/failed — run manually:\n       ${vscode.cmd}`);
+      }
+      console.log(`   - ChatGPT / Claude.ai: in Settings → Connectors, paste this URL: ${mcpURL}`);
+      console.log();
+
+      console.log("2) Log in (browser authorization)");
+      try {
+        await login(mcpURL);
+      } catch (e) {
+        throw new Error(`login failed: ${e.message}`);
+      }
+      console.log("   ✓ CLI obtained an access token (for `memoket tools` / `call`)");
+      console.log();
+
+      console.log("3) Done");
+      console.log("   - Claude Code needs its own login: in a session run /mcp, choose memoket, authorize in browser");
+      console.log("     (the CLI's token is not shared with Claude Code)");
+      console.log("   - Verify: memoket tools    or    memoket call get_memoket_overview");
+      process.exit(0);
+    });
+
+  program
+    .command("login")
+    .description("login (browser OAuth by default; --email/--password/--basic for email+password → gateway) and save token")
+    .option("--browser", "use the browser OAuth flow (default; kept for compatibility)")
+    .option("--basic", "use email/password login → gateway instead of the browser")
+    .option("--email <email>", "account email for email/password login (or set MEMOKET_EMAIL)")
+    .option("--password <password>", "account password for email/password login (or set MEMOKET_PASSWORD)")
+    .action(async (opts, cmd) => {
+      const mcpURL = resolveURL(cmd.parent.opts());
+      // 默认走浏览器 OAuth；仅当用户显式选择邮箱密码（--basic 或传了 --email/--password）时走 loginBasic。
+      const wantBasic = opts.basic || opts.email !== undefined || opts.password !== undefined;
+      if (wantBasic) {
+        // 邮箱密码登录 → gateway /auth/v1/login，存 userToken。
+        const p = await loginBasic(mcpURL, { email: opts.email, password: opts.password });
+        console.log(`✓ Logged in; userToken saved to ${p}`);
+        console.log("  Next: memoket call list_recordings   (mtok 会用 userToken 自动签发)");
+      } else {
+        // 默认：浏览器 OAuth（--browser 为显式/兼容用，效果同默认）。
+        console.log("Logging in (browser OAuth):", mcpURL);
+        await login(mcpURL);
+        const p = await credentialsPath();
+        console.log(`✓ Logged in; credentials saved to ${p}`);
+      }
+      // Force exit — OAuth callback server / undici pool / open 子进程可能吊着事件循环。
+      process.exit(0);
+    });
+
+  // 隐藏别名：`status` 的信息已并进 `doctor`，但旧脚本仍可跑等价逻辑。
+  program
+    .command("status", { hidden: true })
+    .description("show endpoint, token status, and run an initialize handshake (legacy; see `memoket doctor`)")
+    .action(async (opts, cmd) => {
+      const mcpURL = resolveURL(cmd.parent.opts());
+      console.log("endpoint:", mcpURL);
+      const c = await loadCreds();
+      if (c) {
+        const exp = c.expires_at
+          ? new Date(c.expires_at * 1000).toISOString()
+          : "no expiry recorded";
+        console.log(`token:    logged in (client_id=${c.client_id}, expires=${exp})`);
+      } else {
+        console.log("token:    not logged in — run `memoket login`");
+      }
+      const token = await ensureToken(mcpURL);
+      const s = await connect(mcpURL, token);
+      const info = s.info;
+      console.log(
+        `server:   ${info.serverInfo?.name} v${info.serverInfo?.version} (protocol ${info.protocolVersion}, session ${short(s.id)})`,
+      );
+    });
+
+  program
+    .command("tools")
+    .description("list tools exposed by the gateway (GET /v1/tools)")
+    .action(async (opts, cmd) => {
+      const mcpURL = resolveURL(cmd.parent.opts());
+      const tools = await listGatewayTools(mcpURL);
+
+      const groups = new Map();
+      for (const t of tools) {
+        const g = tierOf(t.description);
+        if (!groups.has(g)) groups.set(g, []);
+        groups.get(g).push(t);
+      }
+      const order = [...groups.keys()].sort();
+
+      console.log(`gateway  ·  ${tools.length} tools`);
+      for (const g of order) {
+        console.log(`\n[${g}]`);
+        for (const t of groups.get(g)) {
+          const name = (t.name || "").padEnd(28);
+          const scopes = (t.required_scopes || []).join(",");
+          // 行尾带上必填参数名（如 [query]），让用户一眼看到关键入参；无必填则不加。
+          const req = requiredParamNames(t);
+          const reqHint = req.length ? `  [${req.join(",")}]` : "";
+          console.log(`  ${name} ${firstLine(stripTier(t.description))}${scopes ? `  (scope: ${scopes})` : ""}${reqHint}`);
+        }
+      }
+    });
+
+  program
+    .command("call <tool> [args...]")
+    .description("call a tool: memoket call <tool> [key=value ...] [--json '{...}']")
+    .option("--json <payload>", "JSON object merged into the call args (mutually composable with key=value)")
+    .action(async (tool, rest, options, cmd) => {
+      const mcpURL = resolveURL(cmd.parent.opts());
+      const args = {};
+
+      // commander 已显式声明 --json；这里负责把它 parse 进 args。
+      // 任意拼写错（--jsno / --Json / 等等）都会在 commander 层被拒，不会走到这里。
+      if (options.json !== undefined) {
+        try {
+          Object.assign(args, JSON.parse(options.json));
+        } catch (e) {
+          throw new Error(`--json parse failed: ${e.message}`);
+        }
+      }
+
+      const positionals = []; // 不含 "=" 的裸参数 —— 后端解析不了，需拦下来给提示。
+      for (const a of rest) {
+        const eq = a.indexOf("=");
+        if (eq > 0) {
+          const { coerce } = await import("./utils.js");
+          args[a.slice(0, eq)] = coerce(a.slice(eq + 1));
+        } else {
+          positionals.push(a);
+        }
+      }
+
+      // 用户最常见的困惑：传了位置参数（如 `call search_recordings Elisa`），
+      // 后端只认 JSON body 里的 key，位置参数被静默丢弃 → 报 "query is required"。
+      // 这里拦下来，用该工具的真实参数给出 key=value 示例，而不是干巴巴报错。
+      if (positionals.length > 0) {
+        let toolDef = null;
+        try {
+          toolDef = await getGatewayTool(mcpURL, tool);
+        } catch {
+          /* schema 取不到就退化成通用提示 */
+        }
+        console.error(`参数要用 key=value 形式，位置参数（${positionals.join(" ")}）已被忽略。`);
+        if (toolDef) {
+          console.error(`\n${tool} 的参数:`);
+          printToolParams(toolDef, { log: console.error });
+          console.error(`\n例: ${exampleFor(toolDef, positionals[0])}`);
+          console.error(`详情: memoket describe ${tool}`);
+        } else {
+          console.error(`\n例: memoket call ${tool} key=${positionals[0]}   （参数名见: memoket describe ${tool}）`);
+        }
+        process.exit(1);
+      }
+
+      // 无参调用且该工具有必填参数：先打印参数说明，别把用户直接推给后端报错。
+      // （whoami / list_recordings 这类无必填参数的工具不受影响，照常调用。）
+      if (Object.keys(args).length === 0) {
+        let toolDef = null;
+        try {
+          toolDef = await getGatewayTool(mcpURL, tool);
+        } catch {
+          /* 取不到 schema 就照常调用，让后端决定 */
+        }
+        if (toolDef && requiredParamNames(toolDef).length > 0) {
+          console.error(`${tool} 需要参数（key=value 形式）:`);
+          printToolParams(toolDef, { log: console.error });
+          console.error(`\n例: ${exampleFor(toolDef)}`);
+          console.error(`详情: memoket describe ${tool}`);
+          process.exit(1);
+        }
+      }
+
+      const res = await callGatewayTool(mcpURL, tool, args);
+      console.log(JSON.stringify(res, null, 2));
+    });
+
+  program
+    .command("describe <tool>")
+    .description("show a tool's input parameters (name / required / type / description)")
+    .action(async (tool, opts, cmd) => {
+      const mcpURL = resolveURL(cmd.parent.opts());
+      const toolDef = await getGatewayTool(mcpURL, tool);
+      if (!toolDef) {
+        console.error(`unknown tool: ${tool}   （列表: memoket tools）`);
+        process.exit(1);
+      }
+      const tier = tierOf(toolDef.description);
+      console.log(`${toolDef.name}  [${tier}]`);
+      console.log(stripTier(toolDef.description));
+      const scopes = (toolDef.required_scopes || []).join(",");
+      if (scopes) console.log(`scope: ${scopes}`);
+      console.log("\n参数:");
+      printToolParams(toolDef, { full: true });
+      if (toolParams(toolDef).length > 0) {
+        console.log(`\n例: ${exampleFor(toolDef)}`);
+      } else {
+        console.log(`\n例: memoket call ${tool}`);
+      }
+    });
+
+
+  // `endpoints` 管理本地预置的命名环境（持久化到 ~/.memoket/config.json）。
+  // 无子命令 → 列出所有环境并标记 ACTIVE。
+  const endpointsCmd = program
+    .command("endpoints")
+    .description("list named endpoints (use `endpoints use <name>` to switch the active one)")
+    .action(() => {
+      // 先打印当前激活环境的清爽块：endpoint(补 /mcp) / environment(激活名) / api-gateway(激活 base)。
+      const envName = activeName();
+      const base = activeBase();
+      const endpoint = mcpURLFromBase(base);
+      const lw = "api/gateway".length; // 标签列宽(最长标签)
+      console.log("Memoket endpoints");
+      console.log();
+      console.log(`  ${"endpoint".padEnd(lw)}   ${endpoint}`);
+      console.log(`  ${"environment".padEnd(lw)}   ${envName}`);
+      console.log(`  ${"api/gateway".padEnd(lw)}   ${base}`);
+      console.log();
+
+      // 下面再列可切换的别名（NAME / BASE URL / ACTIVE）。
+      const rows = listEndpoints();
+      const w = Math.max(4, ...rows.map((r) => r.name.length));
+      const bw = Math.max(8, ...rows.map((r) => r.base.length));
+      console.log(`${"NAME".padEnd(w)}  ${"BASE URL".padEnd(bw)}  ACTIVE`);
+      for (const r of rows) {
+        console.log(`${r.name.padEnd(w)}  ${r.base.padEnd(bw)}  ${r.active ? "*" : ""}`.replace(/\s+$/, ""));
+      }
+    });
+
+  endpointsCmd
+    .command("use <name>")
+    .description("switch the active endpoint (persisted)")
+    .action((name) => {
+      try {
+        useEndpoint(name);
+        console.log(`✓ active -> ${name}`);
+      } catch (e) {
+        console.error(`unknown endpoint: ${name}`);
+        if (e.known) console.error(`available: ${e.known.join(", ")}`);
+        process.exit(1);
+      }
+    });
+
+  endpointsCmd
+    .command("add <name> <baseURL>")
+    .description("add or override a custom named endpoint (base host root, no /mcp)")
+    .action(async (name, baseURL) => {
+      const { addEndpoint } = await import("./endpoints.js");
+      const saved = addEndpoint(name, baseURL);
+      console.log(`✓ endpoint ${name} -> ${saved}`);
+    });
+
+  endpointsCmd
+    .command("remove <name>")
+    .description("remove a custom named endpoint (built-ins cannot be removed)")
+    .action(async (name) => {
+      const { removeEndpoint } = await import("./endpoints.js");
+      removeEndpoint(name);
+      console.log(`✓ removed endpoint ${name}`);
+    });
+
+  // `token` 拍平成 1 层：无子命令时默认「签发」，靠 flags 路由到列/撤。
+  // 旧的 create/list/revoke 子命令仍保留（隐藏，功能不变）。
+  const apiTokens = program
+    .command("token")
+    .description("issue / list / revoke Personal API Tokens (default action = issue)")
+    .option("--name <name>", "token name", "HTTP integration")
+    .option("--scope <scope...>", "API scopes (repeat or comma-separated)")
+    .option("--expires-in <days>", "token lifetime in days", "90")
+    .option("--list", "list API tokens instead of issuing")
+    .option("--revoke <id>", "revoke the API token with this id instead of issuing")
+    .option("--rotate <id>", "rotate (旧换新) the API token with this id: sign a new mtok, revoke the old")
+    .action(async (opts, cmd) => {
+      const rootCmd = cmd.parent;
+      const mcpURL = resolveURL(rootCmd.opts());
+      // 全局 --name（服务注册名）与本命令 --name 同名，commander 会把命令行里的
+      // --name 归给 root，token 自己的 --name 收不到。若用户在命令行显式传了 --name，
+      // 就把它当作 token 名；没传时用本命令默认 "HTTP integration"。
+      if (rootCmd.getOptionValueSource("name") === "cli") {
+        opts.name = rootCmd.opts().name;
+      }
+      // 互斥路由：--rotate 优先 → 旧换新；--revoke → 撤；--list → 列；都没传 → 默认签发。
+      if (opts.rotate !== undefined) {
+        await rotateAPIToken(mcpURL, opts.rotate);
+      } else if (opts.revoke !== undefined) {
+        await revokeAPIToken(mcpURL, opts.revoke);
+      } else if (opts.list) {
+        await listAPITokens(mcpURL);
+      } else {
+        await createAPIToken(mcpURL, opts);
+      }
+    });
+
+  // 隐藏的旧子命令：向后兼容，功能与拍平前完全一致。
+  apiTokens
+    .command("create", { hidden: true })
+    .description("create a scoped Personal API Token (legacy; use `memoket token`)")
+    .option("--name <name>", "token name", "HTTP integration")
+    .option("--scope <scope...>", "API scopes (repeat or comma-separated)")
+    .option("--expires-in <days>", "token lifetime in days", "90")
+    .action(async (opts, cmd) => {
+      const mcpURL = resolveURL(cmd.parent.parent.opts());
+      await createAPIToken(mcpURL, opts);
+    });
+
+  apiTokens
+    .command("list", { hidden: true })
+    .description("list API tokens (legacy; use `memoket token --list`)")
+    .action(async (opts, cmd) => {
+      const mcpURL = resolveURL(cmd.parent.parent.opts());
+      await listAPITokens(mcpURL);
+    });
+
+  apiTokens
+    .command("revoke <id>", { hidden: true })
+    .description("revoke an API token (legacy; use `memoket token --revoke <id>`)")
+    .action(async (id, opts, cmd) => {
+      const mcpURL = resolveURL(cmd.parent.parent.opts());
+      await revokeAPIToken(mcpURL, id);
+    });
+
+  // `token rotate <id>`：旧换新。等价于 `token --rotate <id>`，作为子命令更直观。
+  apiTokens
+    .command("rotate <id>")
+    .description("rotate a token (旧换新): sign a new mtok from the old token's user+scopes, revoke the old")
+    .action(async (id, opts, cmd) => {
+      const mcpURL = resolveURL(cmd.parent.parent.opts());
+      await rotateAPIToken(mcpURL, id);
+    });
+
+  program
+    .command("doctor")
+    .description("check connectivity and OAuth discovery")
+    .action(async (opts, cmd) => {
+      const mcpURL = resolveURL(cmd.parent.opts());
+      console.log("endpoint:", mcpURL);
+
+      // 并进原 `status` 的登录态信息（client_id / expiry）。
+      const c = await loadCreds();
+      if (c) {
+        const exp = c.expires_at
+          ? new Date(c.expires_at * 1000).toISOString()
+          : "no expiry recorded";
+        console.log(`token:    logged in (client_id=${c.client_id}, expires=${exp})`);
+      } else {
+        console.log("token:    not logged in — run `memoket login`");
+      }
+
+      let ok = true;
+      try {
+        const wk = await fetchWellKnown(mcpURL);
+        console.log("✓ OAuth discovery succeeded");
+        console.log("    authorize:", wk.authorization_endpoint);
+        console.log("    token:   ", wk.token_endpoint);
+        console.log("    register:", or(wk.registration_endpoint, "(no DCR)"));
+      } catch (e) {
+        ok = false;
+        console.log("✗ OAuth discovery failed:", e.message);
+      }
+
+      const token = await ensureToken(mcpURL);
+      try {
+        const s = await connect(mcpURL, token);
+        const info = s.info;
+        console.log(
+          `✓ initialize: ${info.serverInfo?.name} v${info.serverInfo?.version} (protocol ${info.protocolVersion})`,
+        );
+        const tools = await listTools(s);
+        console.log(`✓ tools/list: ${tools.length} tools`);
+      } catch (e) {
+        console.log("✗ initialize/tools/list failed:", e.message);
+        if (!ok) throw new Error("server unreachable or misconfigured");
+        throw e;
+      }
+    });
+
+  // 无参 → 打印帮助（exit 0）；带了不认识的子命令（如已删的 `connect`）→ 报未知命令并 exit 1。
+  program.action((options, cmd) => {
+    const extra = cmd.args || [];
+    if (extra.length) {
+      console.error(`error: unknown command '${extra[0]}'`);
+      console.error("run `memoket --help` for the command list");
+      process.exit(1);
+    }
+    program.help();
+  });
+
+  return program;
+}

package/src/config.js

@@ -0,0 +1,77 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// version is overridable at build time if needed; keep in sync with package.json.
+export const version = "2.0.1";
+
+// Build-time endpoints / active default / api base: stamped into
+// src/config.local.js by scripts/build.js (npm run build:<env>). When the
+// file is missing (fresh checkout, build not yet run), we fall back to
+// the prod endpoint so the CLI still works out of the box.
+//
+// Note: internal dev/test endpoints live ONLY in config/dev.json and
+// config/test.json, which are NOT shipped in the public npm tarball (see
+// package.json#files). This file falls back to prod so a fresh install
+// from npm has a working default; team members running the CLI from a
+// clone should `npm run build:dev` first.
+const FALLBACK_DEFAULT_ENDPOINTS = {
+  prod: "https://mcp.memoket.ai",
+};
+const FALLBACK_DEFAULT_ACTIVE = "prod";
+const FALLBACK_API_BASE = "https://api.memoket.ai";
+
+let _defaultEndpoints = FALLBACK_DEFAULT_ENDPOINTS;
+let _defaultActiveEndpoint = FALLBACK_DEFAULT_ACTIVE;
+let _apiBase = FALLBACK_API_BASE;
+const localPath = join(__dirname, "config.local.js");
+if (existsSync(localPath)) {
+  const local = await import("./config.local.js");
+  if (local.defaultEndpoints && typeof local.defaultEndpoints === "object") {
+    _defaultEndpoints = local.defaultEndpoints;
+  }
+  if (typeof local.defaultActiveEndpoint === "string") {
+    _defaultActiveEndpoint = local.defaultActiveEndpoint;
+  }
+  if (typeof local.apiBase === "string") {
+    _apiBase = local.apiBase;
+  }
+}
+
+export const defaultEndpoints = _defaultEndpoints;
+export const defaultActiveEndpoint = _defaultActiveEndpoint;
+export const apiBase = _apiBase;
+
+// mcpURLFromBase 把主机根补成 mcp endpoint（下游沿用 /mcp 后缀的历史约定）。
+export function mcpURLFromBase(base) {
+  return `${String(base).replace(/\/$/, "")}/mcp`;
+}
+
+export const defaultName = "memoket";
+export const defaultScope = "read write"; // matches the existing backend client; server grants what it grants
+export const callbackPort = 8765;
+export const clientName = "memoket-cli";
+export const protocolVersion = "2025-03-26";
+
+// memoketDir 解析 ~/.memoket 目录（同步）；credentials.json / auth.json / config.json 都在这里。
+export function memoketDir() {
+  const home = process.env.HOME || process.env.USERPROFILE || "";
+  if (!home) throw new Error("cannot determine home directory");
+  const sep = process.platform === "win32" ? "\\" : "/";
+  return `${home}${sep}.memoket`;
+}
+
+// credentialsPath is where the CLI stores its own OAuth token (used by
+// `memoket tools` / `memoket call`). It does NOT feed any external client.
+export async function credentialsPath() {
+  const sep = process.platform === "win32" ? "\\" : "/";
+  return `${memoketDir()}${sep}credentials.json`;
+}
+
+// endpointsConfigPath 是命名环境的持久化文件（激活环境 + 自定义环境）。
+export function endpointsConfigPath() {
+  const sep = process.platform === "win32" ? "\\" : "/";
+  return `${memoketDir()}${sep}config.json`;
+}

package/src/config.local.js

@@ -0,0 +1,11 @@
+// AUTO-GENERATED by scripts/build.js — do not edit.
+// Source: config/prod.json
+// Regenerate with: npm run build:prod
+
+export const defaultEndpoints = {
+  "prod": "https://mcp.memoket.ai"
+};
+
+export const defaultActiveEndpoint = "prod";
+
+export const apiBase = "https://api.memoket.ai";

package/src/endpoints.js

@@ -0,0 +1,112 @@
+// 命名环境（endpoints）：本地预置 + 用户可持久化覆盖/扩展，存到 ~/.memoket/config.json。
+// 只保存「主机根」（不带 /mcp）；resolveURL 用 mcpURLFromBase 补 /mcp。
+//
+// config.json 格式：
+//   {
+//     "active": "dev",
+//     "endpoints": { "myenv": "https://api.example.com" }   // 可选：自定义/覆盖
+//   }
+// endpoints 与内置 defaultEndpoints 合并（用户项覆盖同名内置项）。
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import {
+  defaultEndpoints,
+  defaultActiveEndpoint,
+  endpointsConfigPath,
+  memoketDir,
+  mcpURLFromBase,
+} from "./config.js";
+
+// loadConfig 读回持久化配置（同步）；文件不存在/损坏时回退空配置。
+function loadConfig() {
+  try {
+    const raw = readFileSync(endpointsConfigPath(), "utf8");
+    const obj = JSON.parse(raw);
+    return {
+      active: typeof obj.active === "string" ? obj.active : undefined,
+      endpoints: obj.endpoints && typeof obj.endpoints === "object" ? obj.endpoints : {},
+    };
+  } catch {
+    return { active: undefined, endpoints: {} };
+  }
+}
+
+function saveConfig(cfg) {
+  const dir = memoketDir();
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(endpointsConfigPath(), JSON.stringify(cfg, null, 2), { mode: 0o600 });
+}
+
+// mergedEndpoints 返回「内置 + 自定义」的完整环境表（自定义覆盖同名内置）。
+function mergedEndpoints(cfg = loadConfig()) {
+  return { ...defaultEndpoints, ...cfg.endpoints };
+}
+
+// activeName 返回当前激活环境名：持久化的 active（若仍有效）→ 否则默认 prod。
+export function activeName() {
+  const cfg = loadConfig();
+  const all = mergedEndpoints(cfg);
+  if (cfg.active && all[cfg.active]) return cfg.active;
+  return defaultActiveEndpoint;
+}
+
+// activeBase 返回当前激活环境的主机根（不带 /mcp）。
+export function activeBase() {
+  const all = mergedEndpoints();
+  const name = activeName();
+  return all[name];
+}
+
+// activeMcpURL 返回当前激活环境的 mcp endpoint（补 /mcp），供 resolveURL 使用。
+export function activeMcpURL() {
+  return mcpURLFromBase(activeBase());
+}
+
+// listEndpoints 返回 [{ name, base, active }]，顺序：内置(dev/test/prod) 优先，其后自定义。
+export function listEndpoints() {
+  const cfg = loadConfig();
+  const all = mergedEndpoints(cfg);
+  const active = activeName();
+  const names = [
+    ...Object.keys(defaultEndpoints),
+    ...Object.keys(cfg.endpoints || {}).filter((n) => !(n in defaultEndpoints)),
+  ];
+  return names.map((name) => ({ name, base: all[name], active: name === active }));
+}
+
+// useEndpoint 切换激活环境；未知名字抛错（由调用方列出可选项）。
+export function useEndpoint(name) {
+  const all = mergedEndpoints();
+  if (!all[name]) {
+    const err = new Error(`unknown endpoint: ${name}`);
+    err.known = Object.keys(all);
+    throw err;
+  }
+  const cfg = loadConfig();
+  cfg.active = name;
+  saveConfig(cfg);
+  return name;
+}
+
+// addEndpoint 新增/覆盖一个自定义环境（存主机根，去掉尾斜杠）。
+export function addEndpoint(name, baseURL) {
+  if (!name) throw new Error("endpoint name is required");
+  if (!baseURL) throw new Error("base URL is required");
+  const cfg = loadConfig();
+  cfg.endpoints = cfg.endpoints || {};
+  cfg.endpoints[name] = String(baseURL).replace(/\/$/, "");
+  saveConfig(cfg);
+  return cfg.endpoints[name];
+}
+
+// removeEndpoint 删除一个自定义环境；内置环境不可删。删掉的若是激活项则回退默认。
+export function removeEndpoint(name) {
+  if (name in defaultEndpoints) throw new Error(`cannot remove built-in endpoint: ${name}`);
+  const cfg = loadConfig();
+  if (!cfg.endpoints || !(name in cfg.endpoints)) {
+    throw new Error(`unknown custom endpoint: ${name}`);
+  }
+  delete cfg.endpoints[name];
+  if (cfg.active === name) cfg.active = defaultActiveEndpoint;
+  saveConfig(cfg);
+}