@geminilight/mindos 0.5.17 → 0.5.18

package/app/app/api/mcp/agents/route.ts

@@ -18,6 +18,12 @@ export async function GET() {
         hasProjectScope: !!agent.project,
         hasGlobalScope: !!agent.global,
         preferredTransport: agent.preferredTransport,
+        // Snippet generation fields
+        format: agent.format ?? 'json',
+        configKey: agent.key,
+        globalNestedKey: agent.globalNestedKey,
+        globalPath: agent.global,
+        projectPath: agent.project,
       };
     });
 

package/app/components/settings/McpTab.tsx

@@ -29,6 +29,12 @@ interface AgentInfo {
   hasProjectScope: boolean;
   hasGlobalScope: boolean;
   preferredTransport: 'stdio' | 'http';
+  // Snippet generation fields
+  format: 'json' | 'toml';
+  configKey: string;
+  globalNestedKey?: string;
+  globalPath: string;
+  projectPath?: string | null;
 }
 
 interface SkillInfo {
@@ -66,19 +72,72 @@ function CopyButton({ text, label }: { text: string; label: string }) {
   );
 }
 
+/* ── Config Snippet Generator ─────────────────────────────────── */
+
+function generateConfigSnippet(
+  agent: AgentInfo,
+  status: McpStatus,
+  token?: string,
+): { snippet: string; path: string } {
+  const isRunning = status.running;
+
+  // Determine entry (stdio vs http)
+  const stdioEntry: Record<string, unknown> = { type: 'stdio', command: 'mindos', args: ['mcp'] };
+  const httpEntry: Record<string, unknown> = { url: status.endpoint };
+  if (token) httpEntry.headers = { Authorization: `Bearer ${token}` };
+  const entry = isRunning ? httpEntry : stdioEntry;
+
+  // TOML format (Codex)
+  if (agent.format === 'toml') {
+    const lines: string[] = [`[${agent.configKey}.mindos]`];
+    if (isRunning) {
+      lines.push(`type = "http"`);
+      lines.push(`url = "${status.endpoint}"`);
+      if (token) {
+        lines.push('');
+        lines.push(`[${agent.configKey}.mindos.headers]`);
+        lines.push(`Authorization = "Bearer ${token}"`);
+      }
+    } else {
+      lines.push(`command = "mindos"`);
+      lines.push(`args = ["mcp"]`);
+      lines.push('');
+      lines.push(`[${agent.configKey}.mindos.env]`);
+      lines.push(`MCP_TRANSPORT = "stdio"`);
+    }
+    return { snippet: lines.join('\n'), path: agent.globalPath };
+  }
+
+  // JSON with globalNestedKey (VS Code project-level uses flat key)
+  if (agent.globalNestedKey) {
+    // project-level: flat key structure
+    const projectSnippet = JSON.stringify({ [agent.configKey]: { mindos: entry } }, null, 2);
+    return { snippet: projectSnippet, path: agent.projectPath ?? agent.globalPath };
+  }
+
+  // Standard JSON
+  const snippet = JSON.stringify({ [agent.configKey]: { mindos: entry } }, null, 2);
+  return { snippet, path: agent.globalPath };
+}
+
 /* ── MCP Server Status ─────────────────────────────────────────── */
 
-function ServerStatus({ status, t }: { status: McpStatus | null; t: any }) {
+function ServerStatus({ status, agents, t }: { status: McpStatus | null; agents: AgentInfo[]; t: any }) {
   const m = t.settings?.mcp;
+  const [selectedAgent, setSelectedAgent] = useState<string>('');
+
+  // Auto-select first installed or first detected agent
+  useEffect(() => {
+    if (agents.length > 0 && !selectedAgent) {
+      const first = agents.find(a => a.installed) ?? agents.find(a => a.present) ?? agents[0];
+      if (first) setSelectedAgent(first.key);
+    }
+  }, [agents, selectedAgent]);
+
   if (!status) return null;
 
-  const configSnippet = JSON.stringify({
-    mcpServers: {
-      mindos: status.running
-        ? { url: status.endpoint }
-        : { type: 'stdio', command: 'mindos', args: ['mcp'] },
-    },
-  }, null, 2);
+  const currentAgent = agents.find(a => a.key === selectedAgent);
+  const snippetResult = currentAgent ? generateConfigSnippet(currentAgent, status) : null;
 
   return (
     <div className="space-y-3">
@@ -123,8 +182,48 @@ function ServerStatus({ status, t }: { status: McpStatus | null; t: any }) {
 
       <div className="flex items-center gap-2 pl-11">
         <CopyButton text={status.endpoint} label={m?.copyEndpoint ?? 'Copy Endpoint'} />
-        <CopyButton text={configSnippet} label={m?.copyConfig ?? 'Copy Config'} />
       </div>
+
+      {/* Quick Setup — agent-specific config snippet */}
+      {agents.length > 0 && (
+        <div className="pl-11 pt-2 space-y-2.5">
+          <div className="flex items-center gap-2">
+            <span className="text-xs text-muted-foreground font-medium">
+              ── {m?.quickSetup ?? 'Quick Setup'} ──
+            </span>
+          </div>
+
+          <div className="flex items-center gap-2">
+            <span className="text-xs text-muted-foreground shrink-0">{m?.configureFor ?? 'Configure for'}</span>
+            <select
+              value={selectedAgent}
+              onChange={e => setSelectedAgent(e.target.value)}
+              className="text-xs px-2 py-1 rounded-md border border-border bg-background text-foreground outline-none focus-visible:ring-1 focus-visible:ring-ring"
+            >
+              {agents.map(a => (
+                <option key={a.key} value={a.key}>
+                  {a.name}{a.installed ? ` ✓` : a.present ? ` ·` : ''}
+                </option>
+              ))}
+            </select>
+          </div>
+
+          {snippetResult && (
+            <>
+              <div className="flex items-center gap-2">
+                <span className="text-xs text-muted-foreground shrink-0">{m?.configPath ?? 'Config path'}</span>
+                <span className="text-xs font-mono text-foreground">{snippetResult.path}</span>
+              </div>
+
+              <pre className="text-xs font-mono bg-muted/50 border border-border rounded-lg p-3 overflow-x-auto whitespace-pre">
+                {snippetResult.snippet}
+              </pre>
+
+              <CopyButton text={snippetResult.snippet} label={m?.copyConfig ?? 'Copy Config'} />
+            </>
+          )}
+        </div>
+      )}
     </div>
   );
 }
@@ -633,7 +732,7 @@ export function McpTab({ t }: McpTabProps) {
     <div className="space-y-6">
       {/* MCP Server Status — prominent card */}
       <div className="rounded-xl border p-4" style={{ borderColor: 'var(--border)', background: 'var(--card)' }}>
-        <ServerStatus status={mcpStatus} t={t} />
+        <ServerStatus status={mcpStatus} agents={agents} t={t} />
       </div>
 
       {/* Agent Install — collapsible */}

package/app/lib/i18n.ts

@@ -253,6 +253,9 @@ export const messages = {
         skillLangZh: '中文',
         selectDetected: 'Select Detected',
         clearSelection: 'Clear',
+        quickSetup: 'Quick Setup',
+        configureFor: 'Configure for',
+        configPath: 'Config path',
       },
       save: 'Save',
       saved: 'Saved',
@@ -320,6 +323,7 @@ export const messages = {
       aiProviderHint: 'Choose your preferred AI service.',
       aiSkip: 'Skip — configure later',
       apiKey: 'API Key',
+      apiKeyExisting: 'Existing key configured. Leave blank to keep it.',
       model: 'Model',
       baseUrl: 'Base URL',
       baseUrlHint: 'Optional. For proxies or OpenAI-compatible APIs.',
@@ -418,6 +422,55 @@ export const messages = {
       welcomeLinkAskAI: 'Ask AI',
       welcomeLinkMCP: 'MCP Settings',
     },
+    guide: {
+      title: 'Get Started with MindOS',
+      showGuide: 'Show getting started guide',
+      close: 'Close',
+      skip: 'Skip',
+      kb: {
+        title: 'Explore your knowledge base',
+        cta: 'Start',
+        fullDesc: 'Your knowledge base has 6 areas — try clicking one:',
+        dirs: {
+          profile: 'Who you are, preferences, goals',
+          notes: 'Daily capture: ideas, meetings, todos',
+          connections: 'Your network of people',
+          workflows: 'Reusable process SOPs',
+          resources: 'Structured data: product lists, tool lists',
+          projects: 'Project plans and progress',
+        },
+        instructionHint: 'Click INSTRUCTION.md to see how AI agents behave.',
+        emptyDesc: 'Your knowledge base has 3 core files:',
+        emptyFiles: {
+          instruction: 'INSTRUCTION.md — Rules that all AI agents follow',
+          readme: 'README.md — Directory index and navigation',
+          config: 'CONFIG.json — Machine-readable preferences',
+        },
+        emptyHint: 'Create your own folder structure anytime.',
+        progress: (n: number) => `Browsed ${n}/1 file`,
+        done: 'Done',
+      },
+      ai: {
+        title: 'Chat with AI',
+        cta: 'Start',
+        prompt: 'Read my knowledge base and help me write a self-introduction into Profile.',
+        promptEmpty: 'Help me design a knowledge base folder structure that fits my needs',
+      },
+      sync: {
+        title: 'Set up sync',
+        optional: 'Optional',
+        cta: 'Configure',
+      },
+      done: {
+        title: "You're all set!",
+        titleFinal: "You've mastered MindOS essentials!",
+        steps: [
+          { hint: 'Next: try saving an article →', prompt: 'Help me save the key points from this article into MindOS.' },
+          { hint: 'Next: try using your KB in another Agent →', prompt: 'Help me start coding based on the plan in MindOS.' },
+          { hint: 'Next: try turning experience into a reusable SOP →', prompt: 'Help me distill this conversation into a reusable workflow in MindOS.' },
+        ],
+      },
+    },
   },
   zh: {
     common: {
@@ -671,6 +724,9 @@ export const messages = {
         skillLangZh: '中文',
         selectDetected: '选择已检测',
         clearSelection: '清除',
+        quickSetup: '快速配置',
+        configureFor: '配置目标',
+        configPath: '配置路径',
       },
       save: '保存',
       saved: '已保存',
@@ -738,6 +794,7 @@ export const messages = {
       aiProviderHint: '选择你偏好的 AI 服务。',
       aiSkip: '跳过 — 稍后配置',
       apiKey: 'API 密钥',
+      apiKeyExisting: '已配置密钥。留空即保持不变。',
       model: '模型',
       baseUrl: '接口地址',
       baseUrlHint: '可选。用于代理或 OpenAI 兼容 API。',
@@ -837,6 +894,55 @@ export const messages = {
       welcomeLinkAskAI: '问 AI',
       welcomeLinkMCP: 'MCP 设置',
     },
+    guide: {
+      title: '开始使用 MindOS',
+      showGuide: '显示新手引导',
+      close: '关闭',
+      skip: '跳过',
+      kb: {
+        title: '探索你的知识库',
+        cta: '开始',
+        fullDesc: '你的知识库有 6 个区域，试试点开看看：',
+        dirs: {
+          profile: '你是谁、偏好、目标',
+          notes: '日常捕捉：想法、会议、待办',
+          connections: '你的人脉关系网',
+          workflows: '可复用的工作流程 SOP',
+          resources: '结构化数据：产品库、工具库',
+          projects: '项目计划和进展',
+        },
+        instructionHint: '点击 INSTRUCTION.md 看看 AI 的行为规则。',
+        emptyDesc: '你的知识库有 3 个核心文件：',
+        emptyFiles: {
+          instruction: 'INSTRUCTION.md — 所有 AI Agent 遵循的规则',
+          readme: 'README.md — 目录索引和导航',
+          config: 'CONFIG.json — 机器可读的配置偏好',
+        },
+        emptyHint: '你可以随时创建自己的目录结构。',
+        progress: (n: number) => `已浏览 ${n}/1 个文件`,
+        done: '完成',
+      },
+      ai: {
+        title: '和 AI 对话',
+        cta: '开始',
+        prompt: '读一下我的知识库，帮我把自我介绍写进 Profile。',
+        promptEmpty: '帮我设计一个适合我的知识库目录结构',
+      },
+      sync: {
+        title: '配置同步',
+        optional: '可选',
+        cta: '设置',
+      },
+      done: {
+        title: '你已准备好使用 MindOS',
+        titleFinal: '你已掌握 MindOS 核心用法',
+        steps: [
+          { hint: '下一步：试试把一篇文章存进来 →', prompt: '帮我把这篇文章的要点整理到 MindOS 里。' },
+          { hint: '下一步：试试在另一个 Agent 里调用知识库 →', prompt: '帮我按 MindOS 里的方案开始写代码。' },
+          { hint: '下一步：试试把经验沉淀为 SOP →', prompt: '帮我把这次对话的经验沉淀到 MindOS，形成可复用的工作流。' },
+        ],
+      },
+    },
   },
 } as const;
 

package/app/lib/mcp-agents.ts

@@ -13,6 +13,10 @@ export interface AgentDef {
   global: string;
   key: string;
   preferredTransport: 'stdio' | 'http';
+  /** Config file format: 'json' (default) or 'toml'. */
+  format?: 'json' | 'toml';
+  /** For agents whose global config nests under a parent key (e.g. VS Code: mcp.servers). */
+  globalNestedKey?: string;
   /** CLI binary name for presence detection (e.g. 'claude'). Optional. */
   presenceCli?: string;
   /** Data directories for presence detection. Any one existing → present. */
@@ -174,6 +178,31 @@ export const MCP_AGENTS: Record<string, AgentDef> = {
       '~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/',
     ],
   },
+  'vscode': {
+    name: 'VS Code',
+    project: '.vscode/mcp.json',
+    global: process.platform === 'darwin'
+      ? '~/Library/Application Support/Code/User/settings.json'
+      : '~/.config/Code/User/settings.json',
+    key: 'servers',
+    globalNestedKey: 'mcp.servers',
+    preferredTransport: 'stdio',
+    presenceDirs: [
+      '~/Library/Application Support/Code/',
+      '~/.config/Code/',
+    ],
+    presenceCli: 'code',
+  },
+  'codex': {
+    name: 'Codex',
+    project: null,
+    global: '~/.codex/config.toml',
+    key: 'mcp_servers',
+    format: 'toml',
+    preferredTransport: 'stdio',
+    presenceCli: 'codex',
+    presenceDirs: ['~/.codex/'],
+  },
 };
 
 /* ── MindOS MCP Install Detection ──────────────────────────────────────── */

package/bin/cli.js

@@ -325,7 +325,13 @@ const commands = {
     const mcpSdk = resolve(ROOT, 'mcp', 'node_modules', '@modelcontextprotocol', 'sdk', 'package.json');
     if (!existsSync(mcpSdk)) {
       console.log(yellow('Installing MCP dependencies (first run)...\n'));
-      run('npm install --prefer-offline --no-workspaces', resolve(ROOT, 'mcp'));
+      const mcpCwd = resolve(ROOT, 'mcp');
+      try {
+        execSync('npm install --prefer-offline --no-workspaces', { cwd: mcpCwd, stdio: 'inherit' });
+      } catch {
+        console.log(yellow('Offline install failed, retrying online...\n'));
+        run('npm install --no-workspaces', mcpCwd);
+      }
     }
     // Map config env vars to what the MCP server expects
     const mcpPort = process.env.MINDOS_MCP_PORT || '8781';

package/bin/lib/build.js

@@ -105,7 +105,12 @@ export function ensureAppDeps() {
     ? 'Updating app dependencies (package-lock.json changed)...\n'
     : 'Installing app dependencies (first run)...\n';
   console.log(yellow(label));
-  run('npm install --prefer-offline --no-workspaces', resolve(ROOT, 'app'));
+  try {
+    execSync('npm install --prefer-offline --no-workspaces', { cwd: resolve(ROOT, 'app'), stdio: 'inherit' });
+  } catch {
+    console.log(yellow('Offline install failed, retrying online...\n'));
+    run('npm install --no-workspaces', resolve(ROOT, 'app'));
+  }
 
   // Verify critical deps — npm tar extraction can silently fail (ENOENT race)
   if (!verifyDeps()) {

package/bin/lib/mcp-spawn.js

@@ -11,7 +11,19 @@ export function spawnMcp(verbose = false) {
   const mcpSdk = resolve(ROOT, 'mcp', 'node_modules', '@modelcontextprotocol', 'sdk', 'package.json');
   if (!existsSync(mcpSdk)) {
     console.log(yellow('Installing MCP dependencies (first run)...\n'));
-    execSync('npm install --prefer-offline --no-workspaces', { cwd: resolve(ROOT, 'mcp'), stdio: 'inherit' });
+    const mcpCwd = resolve(ROOT, 'mcp');
+    try {
+      execSync('npm install --prefer-offline --no-workspaces', { cwd: mcpCwd, stdio: 'inherit' });
+    } catch {
+      console.log(yellow('Offline install failed, retrying online...\n'));
+      try {
+        execSync('npm install --no-workspaces', { cwd: mcpCwd, stdio: 'inherit' });
+      } catch (err) {
+        console.error(red('Failed to install MCP dependencies.'));
+        console.error(`  Try manually: cd ${mcpCwd} && npm install\n`);
+        process.exit(1);
+      }
+    }
   }
   const env = {
     ...process.env,

package/mcp/package.json

@@ -7,7 +7,7 @@
     "start": "npx tsx src/index.ts"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.6.1",
+    "@modelcontextprotocol/sdk": "^1.25.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {

package/package.json

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