driftseal 0.4.0 → 0.5.0

package/README.md

@@ -59,12 +59,42 @@ Fix the server to one repository when starting it:
 driftseal-mcp --root /absolute/path/to/repository
 ```
 
-For Codex, add the installed command as a stdio MCP server:
+Install the server into the current repository's agent config with one of the
+supported targets:
 
 ```sh
-codex mcp add driftseal -- driftseal-mcp --root /absolute/path/to/repository
+cd /path/to/repository
+driftseal mcp install --target codex
+driftseal mcp install --target kimi-code
+driftseal mcp install --target opencode
+driftseal mcp install --target claude-code
+driftseal mcp install --target cursor
 ```
 
+Project scope is the default because each DriftSeal MCP server belongs to one
+repository. Every target pins `--root` to the repository's canonical absolute
+path, and repeated installs are idempotent.
+
+| Target | Project config | Global config |
+| --- | --- | --- |
+| `codex` | `.codex/config.toml` | `~/.codex/config.toml` |
+| `kimi-code` | `.kimi-code/mcp.json` | `~/.kimi-code/mcp.json` or `$KIMI_CODE_HOME/mcp.json` |
+| `opencode` | `opencode.json` | `~/.config/opencode/opencode.json` |
+| `claude-code` | `.mcp.json` | `~/.claude.json` |
+| `cursor` | `.cursor/mcp.json` | `~/.cursor/mcp.json` |
+
+Use `--root <repository>` when running the installer elsewhere, or choose the
+agent's user-level config explicitly:
+
+```sh
+driftseal mcp install --target <target> --scope global --root /absolute/path/to/repository
+```
+
+Global installs remain pinned to the selected repository. If the chosen config
+already contains a different DriftSeal server entry, the installer leaves it
+untouched unless `--force` is supplied. Other agent settings and MCP servers are
+preserved.
+
 The root is startup configuration, not a tool input. In MCP mode DriftSeal also
 ignores inherited `DRIFTSEAL_HOME` and `DRIFTSEAL_DECISION_HOME` overrides, so a
 tool call cannot redirect writes outside the selected repository.
@@ -121,6 +151,7 @@ Single-step commands that only build, check, or record work already done — com
 | `driftseal decision update <id> [-s status] -n "..."` | Reconcile a linked decision in the open intent. |
 | `driftseal decision list [-s status] [--last N \| --count]` | List or count decision records, optionally filtered by status. |
 | `driftseal decision show <id>` | Read one decision record. |
+| `driftseal mcp install --target TARGET [--scope project\|global] [--root path] [--force]` | Install the repository-pinned MCP server into Codex, Kimi Code, OpenCode, Claude Code, or Cursor. |
 | `driftseal init` | Add the adoption protocol to `AGENTS.md`. |
 | `driftseal help` | Print CLI usage. |
 

package/README.zh-CN.md

@@ -59,12 +59,40 @@ atomic write、schema 和 recovery 实现。server 不会启动 `driftseal` 子
 driftseal-mcp --root /absolute/path/to/repository
 ```
 
-在 Codex 中，可以把安装后的命令添加为 stdio MCP server：
+选择对应 target，即可把 server 安装到当前 repository 的 agent 配置：
 
 ```sh
-codex mcp add driftseal -- driftseal-mcp --root /absolute/path/to/repository
+cd /path/to/repository
+driftseal mcp install --target codex
+driftseal mcp install --target kimi-code
+driftseal mcp install --target opencode
+driftseal mcp install --target claude-code
+driftseal mcp install --target cursor
 ```
 
+默认使用项目级配置，因为每个 DriftSeal MCP server 都只属于一个 repository。
+所有 target 都会把 `--root` 固定为 repository 的规范化绝对路径，并且可以安全地
+重复执行。
+
+| Target | 项目级配置 | 全局配置 |
+| --- | --- | --- |
+| `codex` | `.codex/config.toml` | `~/.codex/config.toml` |
+| `kimi-code` | `.kimi-code/mcp.json` | `~/.kimi-code/mcp.json` 或 `$KIMI_CODE_HOME/mcp.json` |
+| `opencode` | `opencode.json` | `~/.config/opencode/opencode.json` |
+| `claude-code` | `.mcp.json` | `~/.claude.json` |
+| `cursor` | `.cursor/mcp.json` | `~/.cursor/mcp.json` |
+
+在其他目录执行时可以显式传入 `--root <repository>`；也可以明确选择对应 agent
+的用户级配置：
+
+```sh
+driftseal mcp install --target <target> --scope global --root /absolute/path/to/repository
+```
+
+全局安装仍会固定到所选 repository。如果目标配置中已经存在不同的 DriftSeal
+server entry，安装器不会修改它；只有显式传入 `--force` 才会替换。其他 agent
+设置与 MCP servers 会被保留。
+
 root 只能在启动时配置，不是 tool input。MCP 模式也会忽略继承到进程中的
 `DRIFTSEAL_HOME` 和 `DRIFTSEAL_DECISION_HOME` override，因此 tool call 不能把
 写入重定向到所选 repository 之外。
@@ -121,6 +149,7 @@ driftseal end \
 | `driftseal decision update <id> [-s status] -n "..."` | 在当前 intent 中 reconcile 已关联的 decision。 |
 | `driftseal decision list [-s status] [--last N \| --count]` | 列出或统计 decision records，也可按 status 筛选。 |
 | `driftseal decision show <id>` | 查看单条 decision record。 |
+| `driftseal mcp install --target TARGET [--scope project\|global] [--root path] [--force]` | 把固定到 repository 的 MCP server 安装到 Codex、Kimi Code、OpenCode、Claude Code 或 Cursor。 |
 | `driftseal init` | 把接入协议写入 `AGENTS.md`。 |
 | `driftseal help` | 查看 CLI 用法。 |
 

package/bin/driftseal.js

@@ -1319,6 +1319,221 @@ function upgradeManagedBlock({
   fail(`cannot safely upgrade customized protocol block beginning with ${marker}`);
 }
 
+const MCP_TARGETS = ['codex', 'kimi-code', 'opencode', 'claude-code', 'cursor'];
+const MCP_SCOPES = ['project', 'global'];
+const MCP_TARGET_LABELS = {
+  codex: 'Codex',
+  'kimi-code': 'Kimi Code',
+  opencode: 'OpenCode',
+  'claude-code': 'Claude Code',
+  cursor: 'Cursor',
+};
+
+function mcpInstallUsage() {
+  return 'usage: driftseal mcp install --target <codex|kimi-code|opencode|claude-code|cursor> [--scope project|global] [--root <repository>] [--force]';
+}
+
+function mcpConfigLocation(target, scope, root) {
+  const home = os.homedir();
+  if (target === 'codex') {
+    const configDir = scope === 'project' ? path.join(root, '.codex') : path.join(home, '.codex');
+    return { configDir, configFile: path.join(configDir, 'config.toml') };
+  }
+  if (target === 'kimi-code') {
+    const userDir = process.env.KIMI_CODE_HOME
+      ? path.resolve(process.env.KIMI_CODE_HOME)
+      : path.join(home, '.kimi-code');
+    const configDir = scope === 'project' ? path.join(root, '.kimi-code') : userDir;
+    return { configDir, configFile: path.join(configDir, 'mcp.json') };
+  }
+  if (target === 'opencode') {
+    const configDir =
+      scope === 'project' ? root : path.join(home, '.config', 'opencode');
+    return { configDir, configFile: path.join(configDir, 'opencode.json') };
+  }
+  if (target === 'claude-code') {
+    const configDir = scope === 'project' ? root : home;
+    return {
+      configDir,
+      configFile: path.join(configDir, scope === 'project' ? '.mcp.json' : '.claude.json'),
+    };
+  }
+  if (target === 'cursor') {
+    const configDir = scope === 'project' ? path.join(root, '.cursor') : path.join(home, '.cursor');
+    return { configDir, configFile: path.join(configDir, 'mcp.json') };
+  }
+  fail(`unsupported MCP target "${target}"`);
+}
+
+function parseMcpInstallRequest(argv) {
+  const [subcommand, ...rest] = argv;
+  if (subcommand !== 'install') {
+    fail(mcpInstallUsage());
+  }
+  const { positionals, flags } = parseArgs(rest, {
+    target: 'single',
+    scope: 'single',
+    root: 'single',
+    force: 'boolean',
+  });
+  if (positionals.length > 0 || !flags.target) {
+    fail(mcpInstallUsage());
+  }
+
+  const target = flags.target.toLowerCase();
+  if (!MCP_TARGETS.includes(target)) {
+    fail(`unsupported MCP target "${flags.target}" (expected: ${MCP_TARGETS.join(', ')})`);
+  }
+  const scope = (flags.scope || 'project').toLowerCase();
+  if (!MCP_SCOPES.includes(scope)) {
+    fail(`invalid MCP install scope "${scope}" (expected: ${MCP_SCOPES.join(', ')})`);
+  }
+  const root = repositoryRoot(flags.root || process.cwd());
+  const { configDir, configFile } = mcpConfigLocation(target, scope, root);
+  return {
+    target,
+    targetLabel: MCP_TARGET_LABELS[target],
+    scope,
+    root,
+    force: Boolean(flags.force),
+    configDir,
+    configFile,
+  };
+}
+
+function tomlString(value) {
+  return JSON.stringify(String(value));
+}
+
+function codexMcpSection(root, eol = '\n') {
+  return [
+    '[mcp_servers.driftseal]',
+    'command = "driftseal-mcp"',
+    `args = ["--root", ${tomlString(root)}]`,
+  ].join(eol);
+}
+
+function codexMcpSectionRange(content) {
+  const header = /^[ \t]*\[mcp_servers\.(?:driftseal|"driftseal"|'driftseal')\][ \t]*(?:#.*)?\r?$/gm;
+  const matches = [...content.matchAll(header)];
+  if (matches.length > 1) fail('Codex config contains duplicate mcp_servers.driftseal tables');
+  if (matches.length === 0) return null;
+
+  const start = matches[0].index;
+  const nextTable = /^[ \t]*\[[^\r\n]+\][ \t]*(?:#.*)?\r?$/gm;
+  nextTable.lastIndex = start + matches[0][0].length;
+  const next = nextTable.exec(content);
+  return { start, end: next ? next.index : content.length };
+}
+
+function installCodexMcp(request) {
+  const { configDir, configFile, force, root, scope, target, targetLabel } = request;
+  const existed = fs.existsSync(configFile);
+  const current = existed ? fs.readFileSync(configFile, 'utf8') : '';
+  const eol = current.includes('\r\n') ? '\r\n' : '\n';
+  const section = codexMcpSection(root, eol);
+  const range = codexMcpSectionRange(current);
+  let updated;
+
+  if (!range) {
+    const separator =
+      current.length === 0
+        ? ''
+        : current.endsWith(eol + eol)
+          ? ''
+          : current.endsWith(eol)
+            ? eol
+            : eol + eol;
+    updated = current + separator + section + eol;
+  } else {
+    const existingSection = current.slice(range.start, range.end).trim();
+    if (existingSection.replace(/\r\n/g, '\n') === section.replace(/\r\n/g, '\n')) {
+      printLine(`DriftSeal MCP is already installed for ${targetLabel} (${scope}): ${configFile}`);
+      return { changed: false, target, scope, root, configFile };
+    }
+    if (!force) {
+      fail(
+        `Codex config already defines mcp_servers.driftseal in ${configFile}; ` +
+          're-run with --force to replace that table'
+      );
+    }
+    const trailing = range.end < current.length ? eol + eol : eol;
+    updated = current.slice(0, range.start) + section + trailing + current.slice(range.end);
+  }
+
+  ensureDirectoryDurable(configDir);
+  atomicWriteFile(configFile, updated);
+  printLine(`Installed DriftSeal MCP for ${targetLabel} (${scope}): ${configFile}`);
+  printLine(`Repository root: ${root}`);
+  return { changed: true, target, scope, root, configFile };
+}
+
+function jsonObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function readJsonConfig(configFile, targetLabel, target) {
+  if (!fs.existsSync(configFile)) {
+    return target === 'opencode' ? { $schema: 'https://opencode.ai/config.json' } : {};
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+  } catch {
+    fail(`${targetLabel} config is not valid JSON: ${configFile}`);
+  }
+  if (!jsonObject(parsed)) fail(`${targetLabel} config must contain a JSON object: ${configFile}`);
+  return parsed;
+}
+
+function jsonMcpDefinition(target, root) {
+  if (target === 'opencode') {
+    return {
+      containerKey: 'mcp',
+      server: { type: 'local', command: ['driftseal-mcp', '--root', root] },
+    };
+  }
+  return {
+    containerKey: 'mcpServers',
+    server: { command: 'driftseal-mcp', args: ['--root', root] },
+  };
+}
+
+function installJsonMcp(request) {
+  const { configDir, configFile, force, root, scope, target, targetLabel } = request;
+  const config = readJsonConfig(configFile, targetLabel, target);
+  const { containerKey, server } = jsonMcpDefinition(target, root);
+  if (config[containerKey] === undefined) config[containerKey] = {};
+  if (!jsonObject(config[containerKey])) {
+    fail(`${targetLabel} config field ${containerKey} must be a JSON object: ${configFile}`);
+  }
+
+  const existing = config[containerKey].driftseal;
+  if (existing !== undefined) {
+    if (JSON.stringify(existing) === JSON.stringify(server)) {
+      printLine(`DriftSeal MCP is already installed for ${targetLabel} (${scope}): ${configFile}`);
+      return { changed: false, target, scope, root, configFile };
+    }
+    if (!force) {
+      fail(
+        `${targetLabel} config already defines the driftseal MCP server in ${configFile}; ` +
+          're-run with --force to replace that entry'
+      );
+    }
+  }
+
+  config[containerKey].driftseal = server;
+  ensureDirectoryDurable(configDir);
+  atomicWriteFile(configFile, JSON.stringify(config, null, 2) + '\n');
+  printLine(`Installed DriftSeal MCP for ${targetLabel} (${scope}): ${configFile}`);
+  printLine(`Repository root: ${root}`);
+  return { changed: true, target, scope, root, configFile };
+}
+
+function installMcp(request) {
+  return request.target === 'codex' ? installCodexMcp(request) : installJsonMcp(request);
+}
+
 const commands = {
   begin(argv) {
     const { positionals, flags } = parseArgs(argv, {
@@ -1719,6 +1934,11 @@ const commands = {
     fail('usage: driftseal decision add|update|list|show (run: driftseal help)');
   },
 
+  mcp(argv) {
+    const request = parseMcpInstallRequest(argv);
+    return installMcp(request);
+  },
+
   init(argv) {
     const { positionals } = parseArgs(argv, {});
     if (positionals.length > 0) fail('usage: driftseal init');
@@ -1805,6 +2025,9 @@ usage:
   driftseal decision list [--status STATUS] [--last N | --count]
                                  list or count filtered MADR decision records
   driftseal decision show <id>         print one MADR decision record
+  driftseal mcp install --target TARGET [--scope project|global] [--root <repository>] [--force]
+                                 install the repository-pinned MCP server (default: project)
+                                 targets: codex, kimi-code, opencode, claude-code, cursor
   driftseal init                       inject intent and decision protocols into ./AGENTS.md
   driftseal help
 
@@ -1829,6 +2052,7 @@ function requestedEndStatus(argv) {
 }
 
 function mutationResources(cmd, argv) {
+  if (cmd === 'mcp') return [parseMcpInstallRequest(argv).configDir];
   if (cmd === 'init') return [process.cwd()];
   if (cmd === 'reclaim' || cmd === 'unreclaim') return [logDir()];
   if (cmd === 'begin' && !argv.some((arg) => arg === '--decision' || arg.startsWith('--decision='))) {
@@ -1848,7 +2072,7 @@ function dispatch(argv) {
   const fn = commands[cmd];
   if (!fn) fail(`unknown command: ${cmd} (run: driftseal help)`);
   const mutates =
-    ['begin', 'end', 'init', 'reclaim', 'unreclaim'].includes(cmd) ||
+    ['begin', 'end', 'init', 'mcp', 'reclaim', 'unreclaim'].includes(cmd) ||
     (cmd === 'decision' && ['add', 'update'].includes(rest[0]));
   const readsIntentLog = ['status', 'log'].includes(cmd);
   if (mutates || readsIntentLog) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "driftseal",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Seal intent, verification, and decisions into an auditable workflow for agentic coding",
   "keywords": [
     "driftseal",