fix(web): use daemon MCP install info in agent guide

Author: YOMXXX

apps/web/src/components/UseEverywhereModal.tsx

@@ -18,6 +18,7 @@ import { modalOverlay, modalContent } from '../motion';
 import type { Dict } from '../i18n/types';
 import {
   buildAgentGuideMarkdown,
+  type AgentGuideMcpInstallInfo,
   type AgentGuideOptions,
 } from './use-everywhere/agent-guide';
 import {
@@ -147,14 +148,41 @@ export function UseEverywhereGuidePanel({
   const [activeId, setActiveId] = useState<GuideSection['id']>('overview');
   const [guideCopy, setGuideCopy] = useState<CopyState>('idle');
   const [snippetCopy, setSnippetCopy] = useState<{ key: string; state: CopyState } | null>(null);
+  const [mcpInstallInfo, setMcpInstallInfo] = useState<AgentGuideMcpInstallInfo | null>(null);
   const guideSections = useMemo(() => localizeGuideSections(t), [t]);
 
+  useEffect(() => {
+    let cancelled = false;
+    fetch('/api/mcp/install-info')
+      .then(async (res) => {
+        if (!res.ok) throw new Error(`daemon ${res.status}`);
+        return (await res.json()) as AgentGuideMcpInstallInfo;
+      })
+      .then((data) => {
+        if (cancelled) return;
+        if (
+          typeof data.command === 'string' &&
+          Array.isArray(data.args) &&
+          data.args.every((arg) => typeof arg === 'string')
+        ) {
+          setMcpInstallInfo(data);
+        }
+      })
+      .catch(() => {
+        if (!cancelled) setMcpInstallInfo(null);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
   const guideOptions: AgentGuideOptions = useMemo(() => {
     const opts: AgentGuideOptions = {};
     if (daemonUrl) opts.daemonUrl = daemonUrl;
     if (versionHint) opts.versionHint = versionHint;
+    if (mcpInstallInfo) opts.mcpInstallInfo = mcpInstallInfo;
     return opts;
-  }, [daemonUrl, versionHint]);
+  }, [daemonUrl, mcpInstallInfo, versionHint]);
 
   const fullGuide = useMemo(
     () => buildAgentGuideMarkdown(guideOptions),

apps/web/src/components/use-everywhere/agent-guide.ts

@@ -14,6 +14,12 @@ import { GUIDE_SECTIONS, type CodeSnippet, type GuideSection } from './sections'
 export interface AgentGuideOptions {
   /** Live daemon URL detected at modal-open time. Defaults to the documented port. */
   daemonUrl?: string;
+  /**
+   * Launch spec returned by `/api/mcp/install-info`. When present, MCP
+   * snippets use this absolute command/args/env tuple instead of assuming
+   * an `od` binary exists on PATH.
+   */
+  mcpInstallInfo?: AgentGuideMcpInstallInfo | null;
   /**
    * Optional `od` binary path / hint. When provided we mention it in the
    * setup checklist so the agent knows whether to run `od …` directly or
@@ -24,10 +30,18 @@ export interface AgentGuideOptions {
   versionHint?: string;
 }
 
+export interface AgentGuideMcpInstallInfo {
+  command: string;
+  args: string[];
+  env?: Record<string, string>;
+}
+
 const DEFAULT_DAEMON_URL = 'http://127.0.0.1:7456';
 
 export function buildAgentGuideMarkdown(options: AgentGuideOptions = {}): string {
   const daemonUrl = (options.daemonUrl ?? DEFAULT_DAEMON_URL).replace(/\/$/, '');
+  const installInfo = normalizeMcpInstallInfo(options.mcpInstallInfo);
+  const cliCommand = installInfo ? renderCliCommandPrefix(installInfo) : null;
   const lines: string[] = [];
 
   lines.push('# Open Design — agent setup guide');
@@ -56,12 +70,23 @@ export function buildAgentGuideMarkdown(options: AgentGuideOptions = {}): string
   lines.push('');
   lines.push('   If it 404s or times out, ask the user to run `pnpm tools-dev` (dev) or open the Open Design app (packaged).');
   lines.push('');
-  lines.push('2. Detect available agent CLIs and confirm `od` is on PATH:');
+  if (installInfo) {
+    lines.push('2. Use this daemon-reported MCP server config. Do not replace it with a bare `od` command:');
+    lines.push('');
+    lines.push('   ```json');
+    lines.push(indent(buildMcpServerConfigSnippet(installInfo), '   '));
+    lines.push('   ```');
+    lines.push('');
+    lines.push(`   This config came from \`${daemonUrl}/api/mcp/install-info\` and preserves the absolute command, args, and env needed by packaged installs.`);
+  } else {
+    lines.push('2. Detect available agent CLIs and confirm `od` is on PATH:');
+    lines.push('');
+    lines.push('   ```bash');
+    lines.push('   od doctor');
+    lines.push('   od status --json');
+    lines.push('   ```');
+  }
   lines.push('');
-  lines.push('   ```bash');
-  lines.push('   od doctor');
-  lines.push('   od status --json');
-  lines.push('   ```');
   if (options.cliHint) {
     lines.push('');
     lines.push(`   The user reported \`od\` at: \`${options.cliHint}\``);
@@ -83,12 +108,12 @@ export function buildAgentGuideMarkdown(options: AgentGuideOptions = {}): string
   lines.push('');
   lines.push('   ```bash');
   lines.push(`   curl -s ${daemonUrl}/api/skills | jq '.skills | length'`);
-  lines.push('   od skills list --json');
+  lines.push(`   ${cliCommand ?? 'od'} skills list --json`);
   lines.push('   ```');
   lines.push('');
 
   for (const section of GUIDE_SECTIONS) {
-    lines.push(...renderSection(section, daemonUrl));
+    lines.push(...renderSection(section, daemonUrl, installInfo, cliCommand));
   }
 
   lines.push('## Reference URLs');
@@ -109,7 +134,12 @@ export function buildAgentGuideMarkdown(options: AgentGuideOptions = {}): string
   return lines.join('\n');
 }
 
-function renderSection(section: GuideSection, daemonUrl: string): string[] {
+function renderSection(
+  section: GuideSection,
+  daemonUrl: string,
+  installInfo: AgentGuideMcpInstallInfo | null,
+  cliCommand: string | null,
+): string[] {
   const lines: string[] = [];
   lines.push(`## ${substituteDaemonUrl(section.heading, daemonUrl)}`);
   lines.push('');
@@ -122,7 +152,7 @@ function renderSection(section: GuideSection, daemonUrl: string): string[] {
     lines.push('');
   }
   for (const snippet of section.snippets) {
-    lines.push(...renderSnippet(snippet, daemonUrl));
+    lines.push(...renderSnippet(snippet, daemonUrl, installInfo, cliCommand));
   }
   if (section.footer) {
     lines.push(`> ${substituteDaemonUrl(section.footer, daemonUrl)}`);
@@ -131,17 +161,97 @@ function renderSection(section: GuideSection, daemonUrl: string): string[] {
   return lines;
 }
 
-function renderSnippet(snippet: CodeSnippet, daemonUrl: string): string[] {
+function renderSnippet(
+  snippet: CodeSnippet,
+  daemonUrl: string,
+  installInfo: AgentGuideMcpInstallInfo | null,
+  cliCommand: string | null,
+): string[] {
   const lines: string[] = [];
   lines.push(`### ${substituteDaemonUrl(snippet.label, daemonUrl)}`);
   lines.push('');
   lines.push('```' + snippet.language);
-  lines.push(substituteDaemonUrl(snippet.body, daemonUrl));
+  lines.push(renderSnippetBody(snippet, daemonUrl, installInfo, cliCommand));
   lines.push('```');
   lines.push('');
   return lines;
 }
 
+function renderSnippetBody(
+  snippet: CodeSnippet,
+  daemonUrl: string,
+  installInfo: AgentGuideMcpInstallInfo | null,
+  cliCommand: string | null,
+): string {
+  if (
+    installInfo &&
+    snippet.language === 'json' &&
+    snippet.body.includes('"mcpServers"') &&
+    snippet.body.includes('"command": "od"')
+  ) {
+    return buildMcpServerConfigSnippet(installInfo);
+  }
+  const withUrl = substituteDaemonUrl(snippet.body, daemonUrl);
+  if (!cliCommand) return withUrl;
+  return withUrl
+    .replace(/^od(?=\s)/gm, cliCommand)
+    .replace(/\$\(od(?=\s)/g, `$(${cliCommand}`);
+}
+
 function substituteDaemonUrl(body: string, daemonUrl: string): string {
   return body.replace(/http:\/\/127\.0\.0\.1:7456/g, daemonUrl);
 }
+
+function buildMcpServerConfigSnippet(info: AgentGuideMcpInstallInfo): string {
+  const env = info.env && Object.keys(info.env).length > 0 ? info.env : undefined;
+  return JSON.stringify(
+    {
+      mcpServers: {
+        'open-design': {
+          command: info.command,
+          args: info.args,
+          ...(env ? { env } : {}),
+        },
+      },
+    },
+    null,
+    2,
+  );
+}
+
+function normalizeMcpInstallInfo(
+  info: AgentGuideMcpInstallInfo | null | undefined,
+): AgentGuideMcpInstallInfo | null {
+  if (!info || typeof info.command !== 'string' || info.command.length === 0) return null;
+  if (!Array.isArray(info.args) || !info.args.every((arg) => typeof arg === 'string')) return null;
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(info.env ?? {})) {
+    if (typeof value === 'string') env[key] = value;
+  }
+  return {
+    command: info.command,
+    args: info.args,
+    ...(Object.keys(env).length > 0 ? { env } : {}),
+  };
+}
+
+function renderCliCommandPrefix(info: AgentGuideMcpInstallInfo): string {
+  const mcpArgIndex = info.args.indexOf('mcp');
+  const cliArgs = mcpArgIndex >= 0 ? info.args.slice(0, mcpArgIndex) : info.args;
+  const envPrefix = Object.entries(info.env ?? {})
+    .filter(([key]) => /^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+    .map(([key, value]) => `${key}=${shellQuote(value)}`);
+  return [...envPrefix, info.command, ...cliArgs].map((part, index) => {
+    if (index < envPrefix.length) return part;
+    return shellQuote(part);
+  }).join(' ');
+}
+
+function shellQuote(value: string): string {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value)) return value;
+  return `"${value.replace(/(["$`])/g, '\\$1')}"`;
+}
+
+function indent(body: string, prefix: string): string {
+  return body.split('\n').map((line) => `${prefix}${line}`).join('\n');
+}

apps/web/tests/components/use-everywhere-agent-guide.test.ts

@@ -74,4 +74,29 @@ describe('buildAgentGuideMarkdown', () => {
     expect(md).toContain('- Daemon: `http://example.test:5555`');
     expect(md).toContain('- MCP install info: `http://example.test:5555/api/mcp/install-info`');
   });
+
+  it('uses daemon install-info for the MCP config instead of assuming od is on PATH', () => {
+    const md = buildAgentGuideMarkdown({
+      daemonUrl: 'http://127.0.0.1:7456',
+      mcpInstallInfo: {
+        command: 'C:\\Program Files\\Open Design\\Open Design.exe',
+        args: [
+          'C:\\Program Files\\Open Design\\resources\\app\\apps\\daemon\\dist\\cli.js',
+          'mcp',
+        ],
+        env: {
+          ELECTRON_RUN_AS_NODE: '1',
+          OD_DATA_DIR: 'C:\\Users\\Ada\\AppData\\Roaming\\Open Design',
+        },
+      },
+    });
+
+    expect(md).toContain('"command": "C:\\\\Program Files\\\\Open Design\\\\Open Design.exe"');
+    expect(md).toContain(
+      '"C:\\\\Program Files\\\\Open Design\\\\resources\\\\app\\\\apps\\\\daemon\\\\dist\\\\cli.js"',
+    );
+    expect(md).toContain('"ELECTRON_RUN_AS_NODE": "1"');
+    expect(md).toContain('"OD_DATA_DIR": "C:\\\\Users\\\\Ada\\\\AppData\\\\Roaming\\\\Open Design"');
+    expect(md).not.toContain('"command": "od"');
+  });
 });

apps/web/tests/components/use-everywhere-copy-guide.test.tsx

@@ -0,0 +1,62 @@
+// @vitest-environment jsdom
+
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { UseEverywhereGuidePanel } from '../../src/components/UseEverywhereModal';
+
+const originalFetch = globalThis.fetch;
+const originalClipboard = Object.getOwnPropertyDescriptor(navigator, 'clipboard');
+
+describe('UseEverywhereGuidePanel copy guide', () => {
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    if (originalClipboard) {
+      Object.defineProperty(navigator, 'clipboard', originalClipboard);
+    }
+    vi.restoreAllMocks();
+  });
+
+  it('copies the daemon install-info launch spec into the agent guide', async () => {
+    const writeText = vi.fn().mockResolvedValue(undefined);
+    Object.defineProperty(navigator, 'clipboard', {
+      configurable: true,
+      value: { writeText },
+    });
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      json: async () => ({
+        command: 'C:\\Program Files\\Open Design\\Open Design.exe',
+        args: [
+          'C:\\Program Files\\Open Design\\resources\\app\\apps\\daemon\\dist\\cli.js',
+          'mcp',
+        ],
+        env: {
+          ELECTRON_RUN_AS_NODE: '1',
+          OD_DATA_DIR: 'C:\\Users\\Ada\\AppData\\Roaming\\Open Design',
+        },
+        daemonUrl: 'http://127.0.0.1:7456',
+        platform: 'win32',
+        cliExists: true,
+        nodeExists: true,
+        buildHint: null,
+      }),
+    } satisfies Partial<Response>) as typeof fetch;
+
+    render(<UseEverywhereGuidePanel daemonUrl="http://127.0.0.1:7456" />);
+
+    await waitFor(() =>
+      expect(globalThis.fetch).toHaveBeenCalledWith('/api/mcp/install-info'),
+    );
+    fireEvent.click(screen.getByTestId('use-everywhere-copy-guide'));
+
+    await waitFor(() => expect(writeText).toHaveBeenCalledTimes(1));
+    const copied = writeText.mock.calls[0]?.[0] as string;
+    expect(copied).toContain('"command": "C:\\\\Program Files\\\\Open Design\\\\Open Design.exe"');
+    expect(copied).toContain(
+      '"C:\\\\Program Files\\\\Open Design\\\\resources\\\\app\\\\apps\\\\daemon\\\\dist\\\\cli.js"',
+    );
+    expect(copied).toContain('"ELECTRON_RUN_AS_NODE": "1"');
+    expect(copied).not.toContain('"command": "od"');
+  });
+});