@xmemo/client 0.4.165 → 0.4.168

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmemo/client",
-  "version": "0.4.165",
+  "version": "0.4.168",
   "description": "Privacy-first CLI and MCP setup helper for XMemo.",
   "mcpName": "io.github.yonro/xmemo",
   "type": "module",

package/src/commands/setup.js

@@ -66,6 +66,7 @@ export async function setupCommand(args, io) {
   }
 
   const dryRun = hasFlag(optionArgs, '--dry-run') || hasFlag(optionArgs, '--preview');
+  const force = hasFlag(optionArgs, '--force');
   const writeConfig = !dryRun && (hasFlag(optionArgs, '--write') || hasFlag(optionArgs, '--yes') || shortClientSetup || (setupAll && (hasFlag(optionArgs, '--write') || hasFlag(optionArgs, '--yes'))));
   const timeoutMs = parsePositiveInteger(optionValue(optionArgs, '--timeout-ms') ?? '5000', '--timeout-ms');
 
@@ -102,7 +103,7 @@ export async function setupCommand(args, io) {
           clientPlan = copilotSetupPlan(setupPlan.mcpUrl, proxyPort, io.env);
           clientPlan.configPath = detection.path;
           if (writeConfig) {
-            await mergeCopilotMcpConfig(clientPlan.configPath, clientPlan.proxyUrl);
+            await mergeCopilotMcpConfig(clientPlan.configPath, clientPlan.proxyUrl, force);
             clientPlan.written = true;
           }
         } else {
@@ -111,7 +112,7 @@ export async function setupCommand(args, io) {
           clientPlan = clientSetupPlan(scanId, client, setupPlan.mcpUrl, io.env, identity);
           clientPlan.configPath = detection.path;
           if (writeConfig) {
-            await client.writeConfig(clientPlan.configPath, setupPlan.mcpUrl, identity);
+            await client.writeConfig(clientPlan.configPath, setupPlan.mcpUrl, identity, { force });
             clientPlan.written = true;
             if (profileClientConfig(scanId)) {
               const installProfile = hasFlag(optionArgs, '--yes') || hasFlag(optionArgs, '--profile');
@@ -134,7 +135,7 @@ export async function setupCommand(args, io) {
       const proxyPort = parsePositiveInteger(optionValue(optionArgs, '--port') ?? String(DEFAULT_PROXY_PORT), '--port');
       setupPlan.selectedClient = copilotSetupPlan(setupPlan.mcpUrl, proxyPort, io.env);
       if (writeConfig) {
-        await mergeCopilotMcpConfig(setupPlan.selectedClient.configPath, setupPlan.selectedClient.proxyUrl);
+        await mergeCopilotMcpConfig(setupPlan.selectedClient.configPath, setupPlan.selectedClient.proxyUrl, force);
         setupPlan.selectedClient.written = true;
       }
     } else {
@@ -146,7 +147,7 @@ export async function setupCommand(args, io) {
       const identity = writeConfig ? await agentIdentity(clientId, io.env) : envReferenceIdentity(clientId);
       setupPlan.selectedClient = clientSetupPlan(clientId, client, setupPlan.mcpUrl, io.env, identity);
       if (writeConfig) {
-        await client.writeConfig(setupPlan.selectedClient.configPath, setupPlan.mcpUrl, identity);
+        await client.writeConfig(setupPlan.selectedClient.configPath, setupPlan.mcpUrl, identity, { force });
         setupPlan.selectedClient.written = true;
       }
 

package/src/mcp/clients/registry.js

@@ -7,7 +7,7 @@ export function createMcpClients(deps) {
     label: 'Codex',
     defaultConfigPath: deps.defaultCodexConfigPath,
     buildSnippet: deps.codexTomlSnippet,
-    writeConfig: deps.appendTomlServerConfig,
+    writeConfig: (configPath, mcpUrl, identity, options = {}) => deps.appendTomlServerConfig(configPath, mcpUrl, identity, options.force),
     configKind: 'toml'
   });
 
@@ -15,7 +15,7 @@ export function createMcpClients(deps) {
     label: 'Grok',
     defaultConfigPath: deps.defaultGrokConfigPath,
     buildSnippet: deps.grokTomlSnippet,
-    writeConfig: deps.appendGrokServerConfig,
+    writeConfig: (configPath, mcpUrl, identity, options = {}) => deps.appendGrokServerConfig(configPath, mcpUrl, identity, options.force),
     configKind: 'toml'
   });
 
@@ -38,7 +38,7 @@ function jsonClient(definition, deps) {
     label: definition.label,
     defaultConfigPath: deps[definition.defaultConfigPath],
     buildSnippet: (mcpUrl, identity) => deps.jsonClientSnippet(definition.id, mcpUrl, identity),
-    writeConfig: (configPath, mcpUrl, identity) => deps.mergeJsonClientMcpConfig(definition.id, configPath, mcpUrl, identity),
+    writeConfig: (configPath, mcpUrl, identity, options = {}) => deps.mergeJsonClientMcpConfig(definition.id, configPath, mcpUrl, identity, options.force),
     configKind: definition.configKind,
     authentication: definition.authentication
   };
@@ -49,7 +49,7 @@ function hermesClient(deps) {
     label: 'Hermes',
     defaultConfigPath: deps.defaultHermesConfigPath,
     buildSnippet: deps.hermesYamlSnippet,
-    writeConfig: deps.mergeHermesMcpConfig,
+    writeConfig: (configPath, mcpUrl, identity, options = {}) => deps.mergeHermesMcpConfig(configPath, mcpUrl, identity, options.force),
     configKind: 'yaml'
   };
 }

package/src/mcp/formats/json.js

@@ -31,7 +31,7 @@ export const JSON_MCP_CLIENT_DEFINITIONS = Object.freeze([
   commandClientDefinition('claude-desktop', 'Claude Desktop', 'defaultClaudeConfigPath'),
   httpClientDefinition('openclaw', 'OpenClaw', 'defaultOpenclawConfigPath', { urlKey: 'url', authentication: 'env-bearer' }),
   commandClientDefinition('kiro', 'Kiro', 'defaultKiroConfigPath'),
-  httpClientDefinition('kimi-code', 'Kimi Code', 'defaultKimiCodeConfigPath', { urlKey: 'url', authentication: 'env-bearer' }),
+  httpClientDefinition('kimi-code', 'Kimi Code', 'defaultKimiCodeConfigPath', { urlKey: 'url', authentication: 'bearer-token-env-var', bearerTokenEnvVar: 'XMEMO_KEY' }),
   commandClientDefinition('zed', 'Zed', 'defaultZedConfigPath', { section: 'context_servers' }),
   nestedTransportClientDefinition('jetbrains', 'JetBrains', 'defaultJetbrainsConfigPath'),
   remoteClientDefinition('opencode', 'OpenCode', 'defaultOpencodeConfigPath'),
@@ -118,14 +118,14 @@ export function jsonClientServerConfig(clientId, mcpUrl, identity) {
   return serverConfigFromDefinition(definition, mcpUrl, resolvedIdentity);
 }
 
-export async function mergeJsonClientMcpConfig(clientId, configPath, mcpUrl, identity) {
+export async function mergeJsonClientMcpConfig(clientId, configPath, mcpUrl, identity, force = false) {
   const definition = requireJsonMcpClientDefinition(clientId);
   const serverConfig = serverConfigFromDefinition(definition, mcpUrl, identity);
   await mergeJsonSectionConfig(configPath, definition.section, serverConfig, definition.section, (parsed) => {
     if (definition.mergeExperimentalModelContextProtocolServers && isPlainObject(parsed.experimental)) {
       mergeExperimentalModelContextProtocolServers(parsed, serverConfig, mcpUrl);
     }
-  });
+  }, force);
 }
 
 function requireJsonMcpClientDefinition(clientId) {
@@ -168,6 +168,15 @@ function serverConfigFromDefinition(definition, mcpUrl, identity) {
     };
   }
 
+  if (definition.authentication === 'bearer-token-env-var') {
+    return {
+      ...(definition.extra ?? {}),
+      [definition.urlKey]: mcpUrl,
+      bearerTokenEnvVar: definition.bearerTokenEnvVar,
+      headers: headersForDefinition(definition, identity)
+    };
+  }
+
   return {
     ...(definition.extra ?? {}),
     [definition.urlKey]: mcpUrl,
@@ -227,7 +236,7 @@ function mcpRemoteCommandJsonServerConfig(mcpUrl, identity) {
   };
 }
 
-async function mergeJsonSectionConfig(configPath, sectionName, serverConfig, duplicatePath = sectionName, afterMerge) {
+async function mergeJsonSectionConfig(configPath, sectionName, serverConfig, duplicatePath = sectionName, afterMerge, force = false) {
   const existing = await readTextIfExists(configPath);
   const parsed = existing.trim().length === 0 ? {} : parseJsonConfig(existing, configPath);
   if (!isPlainObject(parsed)) {
@@ -237,8 +246,8 @@ async function mergeJsonSectionConfig(configPath, sectionName, serverConfig, dup
     parsed[sectionName] = {};
   }
   const existingName = existingJsonMcpServerName(parsed[sectionName]);
-  if (existingName) {
-    throw new UsageError(`MCP config already contains ${duplicatePath}.${existingName}. Edit ${configPath} manually to avoid duplicate server definitions.`);
+  if (existingName && !force) {
+    throw new UsageError(`MCP config already contains ${duplicatePath}.${existingName}. Edit ${configPath} manually to avoid duplicate server definitions, or use --force to overwrite.`);
   }
   parsed[sectionName][MCP_SERVER_NAME] = serverConfig;
   afterMerge?.(parsed);

package/src/mcp/formats/toml.js

@@ -47,17 +47,20 @@ ${AGENT_INSTANCE_HEADER} = "${escapeTomlString(agentInstanceId)}"
 `;
 }
 
-export async function appendGrokServerConfig(configPath, mcpUrl, identity) {
+export async function appendGrokServerConfig(configPath, mcpUrl, identity, force = false) {
   const snippet = grokTomlSnippet(mcpUrl, identity);
-  const existing = await readTextIfExists(configPath);
+  let existing = await readTextIfExists(configPath);
   const existingName = existingTomlMcpServerName(existing);
   if (existingName) {
-    throw new UsageError(`MCP config already contains [mcp_servers.${existingName}]. Edit ${configPath} manually to avoid duplicate server definitions.`);
+    if (!force) {
+      throw new UsageError(`MCP config already contains [mcp_servers.${existingName}]. Edit ${configPath} manually to avoid duplicate server definitions, or use --force to overwrite.`);
+    }
+    existing = removeTomlServerBlock(existing, existingName);
   }
 
   await fs.mkdir(path.dirname(configPath), { recursive: true, mode: 0o700 });
   const prefix = existing.trim().length === 0 ? '' : '\n\n';
-  await fs.appendFile(configPath, `${prefix}${snippet}`, { mode: 0o600 });
+  await fs.writeFile(configPath, `${existing.trimEnd()}${prefix}${snippet}\n`, { mode: 0o600 });
   await bestEffortChmod(configPath, 0o600);
 }
 
@@ -127,17 +130,20 @@ export async function codexSmokeReport(configPath, env) {
   };
 }
 
-export async function appendTomlServerConfig(configPath, mcpUrl, identity) {
+export async function appendTomlServerConfig(configPath, mcpUrl, identity, force = false) {
   const snippet = codexTomlSnippet(mcpUrl, identity);
-  const existing = await readTextIfExists(configPath);
+  let existing = await readTextIfExists(configPath);
   const existingName = existingTomlMcpServerName(existing);
   if (existingName) {
-    throw new UsageError(`MCP config already contains [mcp_servers.${existingName}]. Edit ${configPath} manually to avoid duplicate server definitions.`);
+    if (!force) {
+      throw new UsageError(`MCP config already contains [mcp_servers.${existingName}]. Edit ${configPath} manually to avoid duplicate server definitions, or use --force to overwrite.`);
+    }
+    existing = removeTomlServerBlock(existing, existingName);
   }
 
   await fs.mkdir(path.dirname(configPath), { recursive: true, mode: 0o700 });
   const prefix = existing.trim().length === 0 ? '' : '\n\n';
-  await fs.appendFile(configPath, `${prefix}${snippet}`, { mode: 0o600 });
+  await fs.writeFile(configPath, `${existing.trimEnd()}${prefix}${snippet}\n`, { mode: 0o600 });
   await bestEffortChmod(configPath, 0o600);
 }
 
@@ -176,6 +182,27 @@ function tomlServerBlock(content, serverName) {
   return block.join('\n');
 }
 
+function removeTomlServerBlock(content, serverName) {
+  const header = `[mcp_servers.${serverName}]`;
+  const lines = content.split(/\r?\n/);
+  const start = lines.findIndex((line) => line.trim() === header);
+  if (start === -1) {
+    return content;
+  }
+
+  let end = start + 1;
+  for (; end < lines.length; end += 1) {
+    const line = lines[end];
+    if (/^\s*\[/.test(line)) {
+      break;
+    }
+  }
+
+  const before = lines.slice(0, start).join('\n');
+  const after = lines.slice(end).join('\n');
+  return `${before}\n${after}`.trim();
+}
+
 function tomlStringValue(block, key) {
   const pattern = new RegExp(`^\\s*${escapeRegExp(key)}\\s*=\\s*"((?:\\\\.|[^"\\\\])*)"\\s*$`, 'm');
   const match = block.match(pattern);

package/src/mcp/formats/yaml.js

@@ -33,11 +33,14 @@ export function hermesYamlSnippet(mcpUrl, identity = envReferenceIdentity('herme
 `;
 }
 
-export async function mergeHermesMcpConfig(configPath, mcpUrl, identity) {
+export async function mergeHermesMcpConfig(configPath, mcpUrl, identity, force = false) {
   const existing = await readTextIfExists(configPath);
 
   if (existing.includes(`${MCP_SERVER_NAME}:`) || existing.includes('memory_os:') || existing.includes('memory-os:')) {
-    throw new UsageError(`MCP config already contains ${MCP_SERVER_NAME} in mcp_servers. Edit ${configPath} manually to avoid duplicate server definitions.`);
+    if (!force) {
+      throw new UsageError(`MCP config already contains ${MCP_SERVER_NAME} in mcp_servers. Edit ${configPath} manually to avoid duplicate server definitions, or use --force to overwrite.`);
+    }
+    throw new UsageError(`--force overwrite is not yet supported for Hermes YAML configs. Edit ${configPath} manually.`);
   }
 
   await fs.mkdir(path.dirname(configPath), { recursive: true, mode: 0o700 });

package/src/mcp/proxy/copilot.js

@@ -12,7 +12,7 @@ import {
 import { existingJsonMcpServerName } from '../core/names.js';
 export { mcpProxyCommand } from './server.js';
 
-export async function mergeCopilotMcpConfig(configPath, proxyUrl) {
+export async function mergeCopilotMcpConfig(configPath, proxyUrl, force = false) {
   const existing = await readTextIfExists(configPath);
   const parsed = existing.trim().length === 0 ? {} : parseJsonConfig(existing, configPath);
 
@@ -25,8 +25,8 @@ export async function mergeCopilotMcpConfig(configPath, proxyUrl) {
   }
 
   const existingName = existingJsonMcpServerName(parsed.mcpServers);
-  if (existingName) {
-    throw new UsageError(`MCP config already contains mcpServers.${existingName}. Edit ${configPath} manually to avoid duplicate server definitions.`);
+  if (existingName && !force) {
+    throw new UsageError(`MCP config already contains mcpServers.${existingName}. Edit ${configPath} manually to avoid duplicate server definitions, or use --force to overwrite.`);
   }
 
   parsed.mcpServers[MCP_SERVER_NAME] = copilotLocalProxyServerConfig(proxyUrl);

package/src/ui/help.js

@@ -14,14 +14,16 @@ export function writeHelp(io) {
   writeLine(io.stdout, `Official package: ${PACKAGE_NAME} | Legacy command: ${LEGACY_COMMAND_NAME}`);
   writeLine(io.stdout, '');
   writeLine(io.stdout, '💡 CORE ONBOARDING & SETUP COMMANDS:');
-  writeLine(io.stdout, `  ${COMMAND_NAME} setup --all [--write] [--profile]`);
+  writeLine(io.stdout, `  ${COMMAND_NAME} setup --all [--write] [--profile] [--force]`);
   writeLine(io.stdout, `      Auto-detects all local client installations (Cursor, VS Code, Continue, Trae, etc.).`);
   writeLine(io.stdout, `      Merges XMemo MCP configs. Pass --profile to auto-inject workspace prompt rules.`);
   writeLine(io.stdout, `      *Dry-run by default unless --write (or --yes/-y) is specified for safety.*`);
+  writeLine(io.stdout, `      Pass --force to overwrite an existing mcpServers.XMemo entry.`);
   writeLine(io.stdout, '');
-  writeLine(io.stdout, `  ${COMMAND_NAME} setup <client-id> [--url <url>] [--no-profile] [--json]`);
+  writeLine(io.stdout, `  ${COMMAND_NAME} setup <client-id> [--url <url>] [--no-profile] [--json] [--force]`);
   writeLine(io.stdout, `      Runs interactive setup wizard for a single client (e.g. cursor, gemini, antigravity).`);
   writeLine(io.stdout, `      Detects active workspace to auto-inject project-scoped instruction rules.`);
+  writeLine(io.stdout, `      Pass --force to overwrite an existing mcpServers.XMemo entry.`);
   writeLine(io.stdout, '');
   writeLine(io.stdout, `  ${COMMAND_NAME} login [--from-stdin] [--base-url <url>]`);
   writeLine(io.stdout, `      Starts secure OAuth2 browser-based device login flow to register the CLI.`);

package/src/ui/setup.js

@@ -223,6 +223,16 @@ export function writeSetupSummary(plan, io) {
         if (plan.tokenPortalUrl) {
           writeLine(io.stdout, `     (Token portal: ${plan.tokenPortalUrl})`);
         }
+      } else if (cid === 'kimi-code') {
+        writeLine(io.stdout, `💡 Next steps for ${plan.selectedClient.label}:`);
+        writeLine(io.stdout, '  1. Restart Kimi Code to load the new MCP configuration.');
+        writeLine(io.stdout, `  2. Make sure ${TOKEN_ENV_VAR} is exported in the SAME environment that starts Kimi Code.`);
+        writeLine(io.stdout, `     Kimi Code reads the token from process.env['${TOKEN_ENV_VAR}'] via bearerTokenEnvVar.`);
+        writeLine(io.stdout, `     Example (PowerShell): $env:${TOKEN_ENV_VAR}='<your-token>'; kimi`);
+        writeLine(io.stdout, `     Example (bash):       export ${TOKEN_ENV_VAR}=<your-token> && kimi`);
+        if (plan.tokenPortalUrl) {
+          writeLine(io.stdout, `     (Token portal: ${plan.tokenPortalUrl})`);
+        }
       } else if (usesClientOAuth(cid)) {
         writeLine(io.stdout, `💡 Next steps for ${plan.selectedClient.label}:`);
         writeLine(io.stdout, '  1. When the agent starts or first makes an XMemo tool call, a browser window will automatically pop up requesting OAuth authorization.');