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,43 @@ 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 mcpInstallInfoRequestRef = useRef<Promise<AgentGuideMcpInstallInfo | null> | null>(null);
   const guideSections = useMemo(() => localizeGuideSections(t), [t]);
 
+  function loadMcpInstallInfo(): Promise<AgentGuideMcpInstallInfo | null> {
+    if (!mcpInstallInfoRequestRef.current) {
+      mcpInstallInfoRequestRef.current = fetch('/api/mcp/install-info')
+        .then(async (res) => {
+          if (!res.ok) throw new Error(`daemon ${res.status}`);
+          const data = (await res.json()) as unknown;
+          if (isAgentGuideMcpInstallInfo(data)) return data;
+          return null;
+        })
+        .catch(() => null);
+    }
+    return mcpInstallInfoRequestRef.current;
+  }
+
+  useEffect(() => {
+    let cancelled = false;
+    loadMcpInstallInfo()
+      .then((data) => {
+        if (cancelled) return;
+        setMcpInstallInfo(data);
+      });
+    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),
@@ -177,7 +207,14 @@ export function UseEverywhereGuidePanel({
   }, [activeId, guideSections]);
 
   async function onCopyGuide() {
-    const state = await copyText(fullGuide);
+    const installInfo = mcpInstallInfo ?? await loadMcpInstallInfo();
+    if (installInfo && installInfo !== mcpInstallInfo) {
+      setMcpInstallInfo(installInfo);
+    }
+    const guide = installInfo
+      ? buildAgentGuideMarkdown({ ...guideOptions, mcpInstallInfo: installInfo })
+      : fullGuide;
+    const state = await copyText(guide);
     setGuideCopy(state);
     if (state !== 'idle') {
       window.setTimeout(() => setGuideCopy('idle'), COPY_RESET_MS);
@@ -283,6 +320,16 @@ export function UseEverywhereGuidePanel({
   );
 }
 
+function isAgentGuideMcpInstallInfo(data: unknown): data is AgentGuideMcpInstallInfo {
+  if (!data || typeof data !== 'object') return false;
+  const candidate = data as Partial<AgentGuideMcpInstallInfo>;
+  return (
+    typeof candidate.command === 'string' &&
+    Array.isArray(candidate.args) &&
+    candidate.args.every((arg) => typeof arg === 'string')
+  );
+}
+
 async function copyText(text: string): Promise<CopyState> {
   if (typeof navigator === 'undefined' || !navigator.clipboard) {
     return 'failed';

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"');
+  });
 });