@geminilight/mindos 0.1.6 → 0.1.8

package/README.md

@@ -65,42 +65,45 @@ Static documents are hard to synchronize and weak as execution systems in real h
 
 ## ✨ Features
 
-### For Humans
+**For Humans**
 
 - **GUI Collaboration Workbench**: use one command entry to browse, edit, and search efficiently (`⌘K` / `⌘/`).
 - **Built-in Agent Assistant**: converse in context while edits are captured into managed knowledge.
 - **Plugin Views**: use scenario-focused views like TODO, Kanban, and Timeline.
 
-### For Agents
+**For Agents**
 
 - **MCP Server + Skills**: connect any compatible agent to read, write, search, and run workflows.
 - **Structured Templates**: start quickly with Profile, Workflows, and Configurations scaffolds.
 - **Experience Auto-Distillation**: automatically distill daily work into reusable, executable SOP experience.
 
-### Infrastructure
+**Infrastructure**
 
 - **Reference Sync**: keep cross-file status and context aligned via links/backlinks.
 - **Knowledge Graph**: visualize relationships and dependencies across notes.
 - **Git Time Machine**: track every edit, audit history, and roll back safely.
 
-**Coming Soon:**
+<details>
+<summary><strong>Coming Soon</strong></summary>
 
 - [ ] ACP (Agent Communication Protocol): connect external Agents (e.g., Claude Code, Cursor) and turn the knowledge base into a multi-Agent collaboration hub
 - [ ] Deep RAG integration: retrieval-augmented generation grounded in your knowledge base for more accurate, context-aware AI responses
 - [ ] Backlinks View: display all files that reference the current file, helping you understand how a note fits into the knowledge network
 - [ ] Agent Inspector: render Agent operation logs as a filterable timeline to audit every tool call in detail
 
+</details>
+
 ---
 
 ## 🚀 Getting Started
 
 > [!IMPORTANT]
-> **Quick Start with Agent:** Paste this prompt into any MCP-capable Agent (Claude Code, Cursor, etc.) to install automatically, then skip to [Step 4](#4-inject-your-personal-mind-with-mindos-agent):
+> **Quick Start with Agent:** Paste this prompt into any MCP-capable Agent (Claude Code, Cursor, etc.) to install automatically, then skip to [Step 3](#3-inject-your-personal-mind-with-mindos-agent):
 > ```
 > Help me install MindOS from https://github.com/GeminiLight/MindOS with MCP and Skills. Use English template.
 > ```
 
-> Already have a knowledge base? Skip to [Step 5](#5-make-any-agent-ready-mcp--skills) to configure MCP + Skills.
+> Already have a knowledge base? Skip to [Step 4](#4-make-any-agent-ready-mcp--skills) to configure MCP + Skills.
 
 ### 1. Install
 
@@ -129,10 +132,13 @@ mindos onboard --install-daemon
 
 The setup wizard will guide you through:
 1. Knowledge base path → default `~/.mindos/my-mind`
-2. Choose template language (en / zh)
-3. Optional Auth token to protect your API
-4. Configure AI Provider (Anthropic / OpenAI) + API Key — or choose **skip** to configure later via `mindos config set`
-5. Config saved to `~/.mindos/config.json` automatically
+2. Choose template (en / zh / empty / custom)
+3. Ports (Web UI + MCP)
+4. Auth token (auto-generated or passphrase-seeded)
+5. Web UI password (optional)
+6. AI Provider (Anthropic / OpenAI) + API Key — or **skip** to configure later via `mindos config set`
+
+Config is saved to `~/.mindos/config.json` automatically.
 
 <!-- For Agents: Before running setup, if the user has not provided LLM configuration, ask them:
 1. AI Provider — `anthropic` or `openai` (compatible)?
@@ -183,24 +189,10 @@ Multiple providers can be configured simultaneously — switch between them by c
 > [!NOTE]
 > If you want the MindOS GUI to be reachable from other devices, make sure the port is open in firewall/security-group settings and bound to an accessible host/network interface.
 
-### 3. Run
-
-```bash
-mindos start    # start app + MCP server (production, auto-rebuilds when a new version is detected)
-```
-
-On startup, MindOS prints your Web UI URL, MCP config snippet, and auth token — ready to copy into your Agent.
-
 > [!TIP]
-> **Upgrading?** Run `mindos update` to install the latest version.
+> With `--install-daemon`, MindOS is installed as a background OS service and starts automatically — no need to run `mindos start` manually. If you skipped the flag, run `mindos start` to start manually, or `mindos update` to upgrade to the latest version.
 
-> [!TIP]
-> If the port is already in use, set a different port during `mindos onboard` or update `~/.mindos/config.json`:
-> ```bash
-> MINDOS_WEB_PORT=3002 mindos
-> ```
-
-### 4. Inject Your Personal Mind with MindOS Agent
+### 3. Inject Your Personal Mind with MindOS Agent
 
 1. Open the built-in MindOS Agent chat panel in the GUI.
 2. Upload your resume or any personal/project material.
@@ -210,24 +202,51 @@ On startup, MindOS prints your Web UI URL, MCP config snippet, and auth token
   <img src="assets/images/gui-sync-cv.png" alt="Sync CV Example" width="800" />
 </p>
 
-### 5. Make Any Agent Ready (MCP + Skills)
+### 4. Make Any Agent Ready (MCP + Skills)
 
-#### 5.1 Configure MindOS MCP
+#### 4.1 Configure MindOS MCP
 
 <!-- For Agents: Register MindOS MCP as global (user-level) config by default, so all projects share the same knowledge base. -->
 
-> [!TIP]
-> Each Agent stores MCP config in a different file — see the **MCP Config Path** column in the [Supported Agents](#-supported-agents) table below for exact paths.
+Run one command to auto-install MCP config into your Agent:
 
-Register the MindOS MCP Server in your Agent client:
+```bash
+mindos mcp install
+```
+
+Supports Claude Code, Cursor, Windsurf, Cline, Trae, Gemini CLI, and more — interactively guides you through agent, scope, transport, and token.
 
-The MCP server starts automatically when you run `mindos start` or `mindos dev`. The MCP URL, auth token, and a ready-to-paste config snippet are printed on every startup.
+**Local (Agent and MindOS on the same machine)**
 
-> The MCP port defaults to `8787`. To use a different port, set `mcpPort` in `~/.mindos/config.json` via `mindos onboard`.
+Use `stdio` transport — no server process needed, most reliable:
 
-**Option A: Local (same machine)**
+```bash
+# Interactive
+mindos mcp install
 
-Via stdio — no server process needed:
+# One-shot, global scope (shared across all projects)
+mindos mcp install claude-code -g -y
+```
+
+**Remote (Agent on a different machine)**
+
+Use `http` transport — MindOS must be running (`mindos start`) on the remote machine:
+
+```bash
+mindos mcp install codex --transport http --url http://<server-ip>:8787/mcp --token your-token -g
+```
+
+> [!NOTE]
+> For remote access, ensure port `8787` is open in your firewall/security-group.
+
+> Add `-g` to install globally — MCP config is shared across all projects instead of the current directory only.
+
+> The MCP port defaults to `8787`. To use a different port, run `mindos onboard` and set `mcpPort`.
+
+<details>
+<summary>Manual config (JSON snippets)</summary>
+
+**Local via stdio** (no server process needed):
 
 ```json
 {
@@ -242,7 +261,7 @@ Via stdio — no server process needed:
 }
 ```
 
-Or via URL:
+**Local via URL:**
 
 ```json
 {
@@ -255,10 +274,7 @@ Or via URL:
 }
 ```
 
-**Option B: Remote URL (another device)**
-
-> [!NOTE]
-> Ensure port `8787` is open in your firewall/security-group so remote clients can reach the server.
+**Remote:**
 
 ```json
 {
@@ -271,7 +287,11 @@ Or via URL:
 }
 ```
 
-#### 5.2 Install MindOS Skills
+Each Agent stores config in a different file — see the **MCP Config Path** column in the [Supported Agents](#-supported-agents) table for exact paths.
+
+</details>
+
+#### 4.2 Install MindOS Skills
 
 | Skill | Description |
 |-------|-------------|
@@ -290,7 +310,7 @@ npx skills add https://github.com/GeminiLight/MindOS --skill mindos-zh -g -y
 
 MCP = connection capability, Skills = workflow capability. Enabling both gives the complete MindOS agent experience.
 
-#### 5.3 Common Pitfalls
+#### 4.3 Common Pitfalls
 
 - Only MCP, no Skills: tools are callable, but best-practice workflows are missing.
 - Only Skills, no MCP: workflow guidance exists, but the Agent cannot operate your local knowledge base.

package/README_zh.md

@@ -65,42 +65,45 @@ MindOS 是一个**人机协同心智系统**——基于本地优先的协作知
 
 ## ✨ 功能特性
 
-### 人类侧
+**人类侧**
 
 - **GUI 协作工作台**：以统一入口高效浏览、编辑与搜索（`⌘K` / `⌘/`）。
 - **内置 Agent 助手**：在上下文中对话，编辑内容可持续沉淀为可管理知识。
 - **插件视图**：按场景使用 TODO、看板、时间线等视图。
 
-### Agent 侧
+**Agent 侧**
 
 - **MCP Server + Skills**：让兼容 Agent 统一接入读写、搜索与工作流执行。
 - **结构化模板**：通过 Profile、Workflows、Configurations 快速冷启动。
 - **经验自动沉淀**：将日常记录自动化沉淀为可执行 SOP 经验。
 
-### 基础设施
+**基础设施**
 
 - **引用同步**：通过引用与反向链接保持跨文件状态一致。
 - **知识图谱**：可视化笔记间关系与依赖。
 - **Git 时光机**：记录修改历史，支持审计与安全回滚。
 
-**即将到来：**
+<details>
+<summary><strong>即将到来</strong></summary>
 
 - [ ] ACP（Agent Communication Protocol）：连接外部 Agent（如 Claude Code、Cursor），让知识库成为多 Agent 协作的中枢
 - [ ] RAG 深度集成：基于知识库内容的检索增强生成，让 AI 回答更精准、更有上下文
 - [ ] 反向链接视图（Backlinks）：展示所有引用当前文件的反向链接，理解笔记在知识网络中的位置
 - [ ] Agent 审计面板（Agent Inspector）：将 Agent 操作日志渲染为可筛选的时间线，审查每次工具调用的详情
 
+</details>
+
 ---
 
 ## 🚀 快速开始
 
 > [!IMPORTANT]
-> **用 Agent 一键安装：** 将以下指令粘贴到任意支持 MCP 的 Agent（Claude Code、Cursor 等），即可自动完成安装，然后跳到[第 4 步](#4-通过-mindos-agent-注入你的个人心智)：
+> **用 Agent 一键安装：** 将以下指令粘贴到任意支持 MCP 的 Agent（Claude Code、Cursor 等），即可自动完成安装，然后跳到[第 3 步](#3-通过-mindos-agent-注入你的个人心智)：
 > ```
 > 帮我从 https://github.com/GeminiLight/MindOS 安装 MindOS，包含 MCP 和 Skills，使用中文模板。
 > ```
 
-> 已有知识库？直接跳到[第 5 步](#5-让任意-agent-可用mcp--skills)配置 MCP + Skills。
+> 已有知识库？直接跳到[第 4 步](#4-让任意-agent-可用mcp--skills)配置 MCP + Skills。
 
 ### 1. 安装
 
@@ -129,10 +132,13 @@ mindos onboard --install-daemon
 
 配置向导将引导你完成：
 1. 知识库路径 → 默认 `~/.mindos/my-mind`
-2. 选择模板语言（en / zh / empty）
-3. 可选 Auth token，保护你的 API
-4. 配置 AI Provider（Anthropic / OpenAI）+ API Key — 或选择 **skip**，稍后通过 `mindos config set` 补填
-5. 配置自动保存到 `~/.mindos/config.json`
+2. 选择模板（en / zh / empty / custom）
+3. 端口配置（Web UI + MCP）
+4. Auth token（自动生成或口令派生）
+5. Web UI 访问密码（可选）
+6. 配置 AI Provider（Anthropic / OpenAI）+ API Key — 或选择 **skip**，稍后通过 `mindos config set` 补填
+
+配置自动保存到 `~/.mindos/config.json`。
 
 <!-- For Agents: 运行 onboard 前，如果用户未提供 LLM 配置，请询问：
 1. AI Provider — `anthropic` 还是 `openai`（兼容）？
@@ -183,24 +189,10 @@ mindos onboard --install-daemon
 > [!NOTE]
 > 如果你希望其他设备也能访问 MindOS GUI，请确保端口已在防火墙/安全组中放行，并绑定到可访问的主机地址/网卡。
 
-### 3. 启动
-
-```bash
-mindos start    # 启动 app + MCP 服务（生产模式，检测到新版本时自动重新构建）
-```
-
-启动后，MindOS 会自动打印 Web UI 地址、MCP 配置片段和 Auth token，直接复制到你的 Agent 即可。
-
 > [!TIP]
-> **升级？** 运行 `mindos update` 安装最新版本。
+> 使用 `--install-daemon` 时，MindOS 会作为后台 OS 服务安装并自动启动，无需手动执行 `mindos start`。如果跳过了该参数，运行 `mindos start` 手动启动，或运行 `mindos update` 升级到最新版本。
 
-> [!TIP]
-> 如果端口被占用，在 `mindos onboard` 时指定其他端口，或更新 `~/.mindos/config.json`，也可通过环境变量临时覆盖：
-> ```bash
-> MINDOS_WEB_PORT=3002 mindos
-> ```
-
-### 4. 通过 MindOS Agent 注入你的个人心智
+### 3. 通过 MindOS Agent 注入你的个人心智
 
 1. 打开 MindOS GUI 中内置的 Agent 对话面板。
 2. 上传你的简历或任意个人/项目资料。
@@ -210,24 +202,54 @@ mindos start    # 启动 app + MCP 服务（生产模式，检测到新版本时
   <img src="assets/images/gui-sync-cv.png" alt="同步简历示例" width="800" />
 </p>
 
-### 5. 让任意 Agent 可用（MCP + Skills）
+### 4. 让任意 Agent 可用（MCP + Skills）
 
-#### 5.1 配置 MindOS MCP
+#### 4.1 配置 MindOS MCP
 
 <!-- For Agents: MindOS MCP 默认注册为全局（user-level）配置，使所有项目共享同一知识库。-->
 
-> [!TIP]
-> 每个 Agent 的 MCP 配置文件路径不同——详见下方 [支持的 Agent](#-支持的-agent) 表格中的 **MCP 配置文件路径** 列。
+一条命令自动将 MCP 配置写入 Agent：
+
+```bash
+mindos mcp install
+```
+
+支持 Claude Code、Cursor、Windsurf、Cline、Trae、Gemini CLI 等主流 Agent，交互式引导完成 agent、scope、transport 和 token 的配置。
+
+**本机访问（Agent 和 MindOS 在同一台机器）**
 
-将 MindOS MCP Server 注册到你的 Agent 客户端：
+使用 `stdio` transport — 无需启动服务进程，最稳定：
 
-运行 `mindos start` 或 `mindos dev` 时，MCP 服务自动随之启动。每次启动都会打印 MCP URL、Auth token 及可直接粘贴的配置片段。
+```bash
+# 交互式
+mindos mcp install claude-code
+
+# 一键安装，无需交互（stdio + 项目级）
+mindos mcp install claude-code -y
+
+# 一键安装，全局（所有项目共享）
+mindos mcp install claude-code -g -y
+```
+
+**远程访问（Agent 在另一台机器）**
+
+使用 `http` transport — 远程机器上需先运行 `mindos start`：
+
+```bash
+mindos mcp install claude-code --transport http --url http://<服务器IP>:8787/mcp --token your-token
+```
 
-> MCP 端口默认为 `8787`。如需修改，通过 `mindos onboard` 设置 `~/.mindos/config.json` 中的 `mcpPort`。
+> [!NOTE]
+> 远程访问时，请确保端口 `8787` 已在防火墙/安全组中放行。
+
+> 加 `-g` 表示全局安装 — MCP 配置写入用户级配置文件，所有项目共享，而非仅当前目录。
 
-**方式 A：本机（同一台机器）**
+> MCP 端口默认为 `8787`。如需修改，运行 `mindos onboard` 设置 `mcpPort`。
 
-通过 stdio — 无需启动服务进程：
+<details>
+<summary>手动配置（JSON 片段）</summary>
+
+**本机 stdio**（无需启动服务进程）：
 
 ```json
 {
@@ -242,7 +264,7 @@ mindos start    # 启动 app + MCP 服务（生产模式，检测到新版本时
 }
 ```
 
-或通过 URL：
+**本机 URL：**
 
 ```json
 {
@@ -255,10 +277,7 @@ mindos start    # 启动 app + MCP 服务（生产模式，检测到新版本时
 }
 ```
 
-**方式 B：远程 URL（其他设备）**
-
-> [!NOTE]
-> 请确保端口 `8787` 已在防火墙/安全组中放行，远程客户端才能连接。
+**远程：**
 
 ```json
 {
@@ -271,7 +290,11 @@ mindos start    # 启动 app + MCP 服务（生产模式，检测到新版本时
 }
 ```
 
-#### 5.2 安装 MindOS Skills
+各 Agent 的配置文件路径不同，详见下方 [支持的 Agent](#-支持的-agent) 表格中的 **MCP 配置文件路径** 列。
+
+</details>
+
+#### 4.2 安装 MindOS Skills
 
 | Skill | 说明 |
 |-------|------|
@@ -290,7 +313,7 @@ npx skills add https://github.com/GeminiLight/MindOS --skill mindos-zh -g -y
 
 MCP = 连接能力，Skills = 工作流能力；两者都开启后体验完整。
 
-#### 5.3 常见误区
+#### 4.3 常见误区
 
 - 只配 MCP，不装 Skills：能调用工具，但缺少最佳实践指引。
 - 只装 Skills，不配 MCP：有流程提示，但无法操作本地知识库。

package/bin/cli.js

@@ -539,6 +539,158 @@ function spawnMcp(verbose = false) {
   return child;
 }
 
+// ── mcp install ───────────────────────────────────────────────────────────────
+
+const MCP_AGENTS = {
+  'claude-code':     { name: 'Claude Code',     project: '.mcp.json',                       global: '~/.claude.json',                                                                         key: 'mcpServers' },
+  'claude-desktop':  { name: 'Claude Desktop',  project: null,                               global: process.platform === 'darwin' ? '~/Library/Application Support/Claude/claude_desktop_config.json' : '~/.config/Claude/claude_desktop_config.json', key: 'mcpServers' },
+  'cursor':          { name: 'Cursor',           project: '.cursor/mcp.json',                global: '~/.cursor/mcp.json',                                                                     key: 'mcpServers' },
+  'windsurf':        { name: 'Windsurf',         project: null,                               global: '~/.codeium/windsurf/mcp_config.json',                                                   key: 'mcpServers' },
+  'cline':           { name: 'Cline',            project: null,                               global: process.platform === 'darwin' ? '~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json' : '~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json', key: 'mcpServers' },
+  'trae':            { name: 'Trae',             project: '.trae/mcp.json',                  global: '~/.trae/mcp.json',                                                                       key: 'mcpServers' },
+  'gemini-cli':      { name: 'Gemini CLI',       project: '.gemini/settings.json',           global: '~/.gemini/settings.json',                                                                key: 'mcpServers' },
+  'openclaw':        { name: 'OpenClaw',         project: null,                               global: '~/.openclaw/mcp.json',                                                                   key: 'mcpServers' },
+  'codebuddy':       { name: 'CodeBuddy',        project: null,                               global: '~/.claude-internal/.claude.json',                                                        key: 'mcpServers' },
+};
+
+function expandHome(p) {
+  return p.startsWith('~/') ? resolve(homedir(), p.slice(2)) : p;
+}
+
+async function mcpInstall() {
+  const args = process.argv.slice(4);
+
+  // parse flags
+  const hasGlobalFlag    = args.includes('-g') || args.includes('--global');
+  const hasYesFlag       = args.includes('-y') || args.includes('--yes');
+  const transportIdx     = args.findIndex(a => a === '--transport');
+  const urlIdx           = args.findIndex(a => a === '--url');
+  const tokenIdx         = args.findIndex(a => a === '--token');
+  const transportArg     = transportIdx >= 0 ? args[transportIdx + 1] : null;
+  const urlArg           = urlIdx     >= 0 ? args[urlIdx + 1]     : null;
+  const tokenArg         = tokenIdx   >= 0 ? args[tokenIdx + 1]   : null;
+
+  // agent positional arg: first non-flag arg after "mcp install"
+  const agentArg = args.find(a => !a.startsWith('-')) ?? null;
+
+  const readline = await import('node:readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q) => new Promise(r => rl.question(q, r));
+  const choose = async (prompt, options, defaultIdx = 0) => {
+    if (hasYesFlag) return options[defaultIdx];
+    console.log(`\n${bold(prompt)}\n`);
+    options.forEach((o, i) => console.log(`  ${dim(`${i + 1}.`)} ${o.label} ${o.hint ? dim(`(${o.hint})`) : ''}`));
+    const ans = await ask(`\n${bold(`Enter number`)} ${dim(`[${defaultIdx + 1}]:`)} `);
+    const idx = ans.trim() === '' ? defaultIdx : parseInt(ans.trim(), 10) - 1;
+    return options[idx >= 0 && idx < options.length ? idx : defaultIdx];
+  };
+
+  console.log(`\n${bold('🔌 MindOS MCP Install')}\n`);
+
+  // ── 1. agent ────────────────────────────────────────────────────────────────
+  let agentKey = agentArg;
+  if (!agentKey) {
+    const keys = Object.keys(MCP_AGENTS);
+    const picked = await choose('Which Agent would you like to configure?',
+      keys.map(k => ({ label: MCP_AGENTS[k].name, hint: k, value: k })));
+    agentKey = picked.value;
+  }
+
+  const agent = MCP_AGENTS[agentKey];
+  if (!agent) {
+    rl.close();
+    console.error(red(`\nUnknown agent: ${agentKey}`));
+    console.error(dim(`Supported: ${Object.keys(MCP_AGENTS).join(', ')}`));
+    process.exit(1);
+  }
+
+  // ── 2. scope (only ask if agent supports both) ───────────────────────────────
+  let isGlobal = hasGlobalFlag;
+  if (!hasGlobalFlag) {
+    if (agent.project && agent.global) {
+      const picked = await choose('Install scope?', [
+        { label: 'Project',  hint: agent.project, value: 'project' },
+        { label: 'Global',   hint: agent.global,  value: 'global'  },
+      ]);
+      isGlobal = picked.value === 'global';
+    } else {
+      // agent only supports one scope, no need to ask
+      isGlobal = !agent.project;
+    }
+  }
+
+  const configPath = isGlobal ? agent.global : agent.project;
+  if (!configPath) {
+    rl.close();
+    console.error(red(`${agent.name} does not support ${isGlobal ? 'global' : 'project'} scope.`));
+    process.exit(1);
+  }
+
+  // ── 3. transport ─────────────────────────────────────────────────────────────
+  let transport = transportArg;
+  if (!transport) {
+    const picked = await choose('Transport type?', [
+      { label: 'stdio', hint: 'local, no server process needed (recommended)' },
+      { label: 'http',  hint: 'URL-based, use when server is running separately or remotely' },
+    ]);
+    transport = picked.label;
+  }
+
+  // ── 4. url + token (only for http) ───────────────────────────────────────────
+  let url = urlArg;
+  let token = tokenArg;
+
+  if (transport === 'http') {
+    if (!url) {
+      url = hasYesFlag ? 'http://localhost:8787/mcp' : (await ask(`${bold('MCP URL')} ${dim('[http://localhost:8787/mcp]:')} `)).trim() || 'http://localhost:8787/mcp';
+    }
+
+    if (!token) {
+      // try reading from config.json first
+      try { token = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')).authToken || ''; } catch {}
+      if (!token && !hasYesFlag) {
+        token = (await ask(`${bold('Auth token')} ${dim('(leave blank to skip):')} `)).trim();
+      } else if (token) {
+        console.log(dim(`  Using auth token from ~/.mindos/config.json`));
+      }
+    }
+  }
+
+  rl.close();
+
+  // ── build entry ──────────────────────────────────────────────────────────────
+  const entry = transport === 'stdio'
+    ? { type: 'stdio', command: 'mindos', args: ['mcp'], env: { MCP_TRANSPORT: 'stdio' } }
+    : token
+      ? { url, headers: { Authorization: `Bearer ${token}` } }
+      : { url };
+
+  // ── read + merge existing config ─────────────────────────────────────────────
+  const absPath = expandHome(configPath);
+  let config = {};
+  if (existsSync(absPath)) {
+    try { config = JSON.parse(readFileSync(absPath, 'utf-8')); } catch {
+      console.error(red(`\nFailed to parse existing config: ${absPath}`));
+      process.exit(1);
+    }
+  }
+
+  if (!config[agent.key]) config[agent.key] = {};
+  const existed = !!config[agent.key].mindos;
+  config[agent.key].mindos = entry;
+
+  // ── preview + write ──────────────────────────────────────────────────────────
+  console.log(`\n${bold('Preview:')} ${dim(absPath)}\n`);
+  console.log(dim(JSON.stringify({ [agent.key]: { mindos: entry } }, null, 2)));
+
+  const dir = resolve(absPath, '..');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(absPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+
+  console.log(`\n${green('✔')} ${existed ? 'Updated' : 'Installed'} MindOS MCP for ${bold(agent.name)}`);
+  console.log(dim(`  Config: ${absPath}\n`));
+}
+
 // ── Commands ──────────────────────────────────────────────────────────────────
 
 const cmd       = process.argv[2];
@@ -644,7 +796,12 @@ const commands = {
     writeBuildStamp();
   },
 
-  mcp: () => { loadConfig(); run(`npx tsx src/index.ts`, resolve(ROOT, 'mcp')); },
+  mcp: async () => {
+    const sub = process.argv[3];
+    if (sub === 'install') { await mcpInstall(); return; }
+    loadConfig();
+    run(`npx tsx src/index.ts`, resolve(ROOT, 'mcp'));
+  },
 
   // ── stop / restart ─────────────────────────────────────────────────────────
   stop: () => stopMindos(),
@@ -1018,6 +1175,7 @@ ${row('mindos stop',                       'Stop running MindOS processes')}
 ${row('mindos restart',                    'Stop then start again')}
 ${row('mindos build',                      'Build the app for production')}
 ${row('mindos mcp',                        'Start MCP server only')}
+${row('mindos mcp install [agent]',        'Install MindOS MCP config into Agent (claude-code/cursor/windsurf/…) [-g]')}
 ${row('mindos token',                      'Show current auth token and MCP config snippet')}
 ${row('mindos gateway <subcommand>',       'Manage background service (install/uninstall/start/stop/status/logs)')}
 ${row('mindos doctor',                     'Health check (config, ports, build, daemon)')}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geminilight/mindos",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "MindOS — Human-Agent Collaborative Mind System. Local-first knowledge base that syncs your mind to all AI Agents via MCP.",
   "keywords": [
     "mindos",

package/scripts/setup.js

@@ -490,6 +490,42 @@ async function applyTemplate(tpl, mindDir) {
 async function main() {
   console.log(`\n${c.bold(t('title'))}\n\n${c.dim(t('langHint'))}\n`);
 
+  // ── Early overwrite check ─────────────────────────────────────────────────
+  if (existsSync(CONFIG_PATH)) {
+    let existing = {};
+    try { existing = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8')); } catch {}
+
+    const mask = (s) => s ? s.slice(0, 4) + '••••••••' + s.slice(-2) : c.dim('(not set)');
+    const row  = (label, val) => `  ${c.dim(label.padEnd(18))} ${val}`;
+    const providers = existing.ai?.providers;
+    const anthropicKey = providers?.anthropic?.apiKey || existing.ai?.anthropicApiKey || '';
+    const openaiKey    = providers?.openai?.apiKey    || existing.ai?.openaiApiKey    || '';
+
+    console.log(c.bold('\nExisting config:'));
+    console.log(row('Knowledge base:', c.cyan(existing.mindRoot || '(not set)')));
+    console.log(row('Web port:',       c.cyan(String(existing.port || '3000'))));
+    console.log(row('MCP port:',       c.cyan(String(existing.mcpPort || '8787'))));
+    console.log(row('Auth token:',     existing.authToken ? mask(existing.authToken) : c.dim('(not set)')));
+    console.log(row('Web password:',   existing.webPassword ? '••••••••' : c.dim('(none)')));
+    console.log(row('AI provider:',    c.cyan(existing.ai?.provider || '(not set)')));
+    if (anthropicKey) console.log(row('Anthropic key:', mask(anthropicKey)));
+    if (openaiKey)    console.log(row('OpenAI key:',    mask(openaiKey)));
+    write('\n');
+
+    const overwrite = await askYesNo('cfgExists', CONFIG_PATH);
+    if (!overwrite) {
+      const existingMode     = existing.startMode || 'start';
+      const existingMcpPort  = existing.mcpPort   || 8787;
+      const existingAuth     = existing.authToken || '';
+      const existingMindRoot = existing.mindRoot  || resolve(MINDOS_DIR, 'my-mind');
+      console.log(`\n${c.green(t('cfgKept'))}  ${c.dim(CONFIG_PATH)}`);
+      write(c.dim(t('cfgKeptNote') + '\n'));
+      const installDaemon = process.argv.includes('--install-daemon');
+      finish(existingMindRoot, existingMode, existingMcpPort, existingAuth, installDaemon);
+      return;
+    }
+  }
+
   // ── Step 1: Knowledge base path ───────────────────────────────────────────
   stepHeader(1);
 
@@ -559,28 +595,6 @@ async function main() {
   write('\n');
   stepHeader(6);
 
-  // if config exists, ask about overwrite first
-  if (existsSync(CONFIG_PATH)) {
-    const overwrite = await askYesNo('cfgExists', CONFIG_PATH);
-    if (!overwrite) {
-      let existingMode = 'start';
-      let existingMcpPort = 8787;
-      let existingAuth = '';
-      let existingMindRoot = mindDir;
-      try {
-        const existing = JSON.parse(readFileSync(CONFIG_PATH, 'utf-8'));
-        existingMode     = existing.startMode  || 'start';
-        existingMcpPort  = existing.mcpPort    || 8787;
-        existingAuth     = existing.authToken  || '';
-        existingMindRoot = existing.mindRoot   || mindDir;
-      } catch { /* ignore */ }
-      console.log(`\n${c.green(t('cfgKept'))}  ${c.dim(CONFIG_PATH)}`);
-      write(c.dim(t('cfgKeptNote') + '\n'));
-      finish(existingMindRoot, existingMode, existingMcpPort, existingAuth);
-      return;
-    }
-  }
-
   const provider = await select('providerPrompt', 'providerOpts', 'providerVals');
   const isSkip = provider === 'skip';
   const isAnthropic = provider === 'anthropic';