agent-relay 2.3.13 → 2.4.0

package/packages/mcp/src/install.ts

@@ -1,820 +0,0 @@
-/**
- * MCP Installation System
- *
- * Auto-configures MCP server for different AI editors:
- * - Claude Desktop / Claude Code
- * - Cursor
- * - VS Code (with MCP extension)
- * - Windsurf
- * - Zed
- * - Gemini CLI
- * - OpenCode
- * - Droid (Factory)
- */
-
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { homedir, platform } from 'node:os';
-import { execSync } from 'node:child_process';
-import * as TOML from 'smol-toml';
-
-export interface EditorConfig {
-  /** Display name for the editor */
-  name: string;
-  /** Path to the config file */
-  configPath: string;
-  /** Key in config object for MCP servers */
-  configKey: string;
-  /** Config file format */
-  format: 'json' | 'jsonc' | 'toml';
-  /** Whether this editor supports project-local MCP configs */
-  supportsLocal?: boolean;
-}
-
-export interface InstallOptions {
-  /** Specific editor to install for (auto-detect if not specified) */
-  editor?: string;
-  /** Install globally vs project-local */
-  global?: boolean;
-  /** Project directory for local install */
-  projectDir?: string;
-  /** Dry run - print what would be done without making changes */
-  dryRun?: boolean;
-  /** Custom server command (defaults to npx) */
-  command?: string;
-  /** Custom server args */
-  args?: string[];
-  /** Custom config path - overrides auto-detected path */
-  configPath?: string;
-  /** Config format when using custom configPath (default: json) */
-  configFormat?: 'json' | 'jsonc' | 'toml';
-  /** Config key for MCP servers when using custom configPath (default: mcpServers) */
-  configKey?: string;
-  /** Environment variables to set when launching the MCP server */
-  env?: Record<string, string>;
-}
-
-export interface InstallResult {
-  editor: string;
-  configPath: string;
-  success: boolean;
-  error?: string;
-  /** Whether config was created vs updated */
-  created: boolean;
-}
-
-/**
- * MCP server configuration that gets added to editor configs
- */
-export interface McpServerConfig {
-  command: string;
-  args: string[];
-  env?: Record<string, string>;
-}
-
-/**
- * Get platform-specific config paths
- */
-function getConfigPaths(): Record<string, EditorConfig> {
-  const home = homedir();
-  const plat = platform();
-
-  // Platform-specific base paths
-  const appSupport =
-    plat === 'darwin'
-      ? join(home, 'Library', 'Application Support')
-      : plat === 'win32'
-        ? process.env.APPDATA || join(home, 'AppData', 'Roaming')
-        : join(home, '.config');
-
-  return {
-    claude: {
-      name: 'Claude Desktop',
-      configPath:
-        plat === 'darwin'
-          ? join(appSupport, 'Claude', 'claude_desktop_config.json')
-          : plat === 'win32'
-            ? join(appSupport, 'Claude', 'claude_desktop_config.json')
-            : join(home, '.config', 'claude', 'claude_desktop_config.json'),
-      configKey: 'mcpServers',
-      format: 'json',
-    },
-    'claude-code': {
-      name: 'Claude Code',
-      configPath: join(home, '.claude', 'settings.json'),
-      configKey: 'mcpServers',
-      format: 'json',
-      supportsLocal: true,
-    },
-    cursor: {
-      name: 'Cursor',
-      configPath: join(home, '.cursor', 'mcp.json'),
-      configKey: 'mcpServers',
-      format: 'json',
-      supportsLocal: true,
-    },
-    vscode: {
-      name: 'VS Code',
-      configPath: join(home, '.vscode', 'mcp.json'),
-      configKey: 'mcpServers',
-      format: 'jsonc',
-      supportsLocal: true,
-    },
-    windsurf: {
-      name: 'Windsurf',
-      configPath: join(home, '.windsurf', 'mcp.json'),
-      configKey: 'mcpServers',
-      format: 'json',
-      supportsLocal: true,
-    },
-    zed: {
-      name: 'Zed',
-      configPath: join(home, '.config', 'zed', 'settings.json'),
-      configKey: 'context_servers',
-      format: 'jsonc',
-    },
-    gemini: {
-      name: 'Gemini CLI',
-      configPath: join(home, '.gemini', 'settings.json'),
-      configKey: 'mcpServers',
-      format: 'json',
-      supportsLocal: true,
-    },
-    opencode: {
-      name: 'OpenCode',
-      configPath: join(home, '.config', 'opencode', 'opencode.json'),
-      configKey: 'mcp', // OpenCode uses "mcp" not "mcpServers"
-      format: 'json',
-      supportsLocal: true,
-    },
-    droid: {
-      name: 'Droid',
-      configPath: join(home, '.factory', 'mcp.json'),
-      configKey: 'mcpServers',
-      format: 'json',
-      supportsLocal: true,
-    },
-    codex: {
-      name: 'Codex',
-      configPath: join(home, '.codex', 'config.toml'),
-      configKey: 'mcp_servers', // TOML uses [mcp_servers.agent-relay] tables
-      format: 'toml',
-      supportsLocal: true,
-    },
-  };
-}
-
-/**
- * Default MCP server configuration
- */
-export function getDefaultServerConfig(): McpServerConfig {
-  return {
-    command: 'npx',
-    args: ['@agent-relay/mcp', 'serve'],
-  };
-}
-
-/**
- * Check if node is installed via nvm (Node Version Manager).
- * GUI apps (Claude, Cursor, VS Code) can't use nvm's shell function,
- * so we need to use absolute paths for nvm installations.
- */
-function isUsingNvm(): boolean {
-  try {
-    const nodePath = execSync('which node', { encoding: 'utf-8' }).trim();
-    return nodePath.includes('.nvm');
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Get absolute path to node binary
- */
-function getNodePath(): string | null {
-  try {
-    return execSync('which node', { encoding: 'utf-8' }).trim();
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Get path to globally installed @agent-relay/mcp bin.js
- * Returns null if not installed globally.
- */
-function getGlobalMcpBinPath(): string | null {
-  try {
-    // Get npm global prefix
-    const npmPrefix = execSync('npm prefix -g', { encoding: 'utf-8' }).trim();
-    const binPath = join(npmPrefix, 'lib', 'node_modules', '@agent-relay', 'mcp', 'dist', 'bin.js');
-    if (existsSync(binPath)) {
-      return binPath;
-    }
-  } catch {
-    // npm not available or failed
-  }
-  return null;
-}
-
-/**
- * Build MCP server configuration with proper paths.
- *
- * For nvm users: Uses absolute paths (recommended by MCP community)
- * For others: Uses npx (works when node is in standard PATH)
- *
- * See: https://github.com/modelcontextprotocol/servers/issues/64
- */
-function buildServerConfig(): McpServerConfig {
-  // If using nvm, we need absolute paths because GUI apps can't access nvm's shell function
-  if (isUsingNvm()) {
-    const nodePath = getNodePath();
-    const mcpBinPath = getGlobalMcpBinPath();
-
-    if (nodePath && mcpBinPath) {
-      // Best option: globally installed package with absolute paths
-      return {
-        command: nodePath,
-        args: [mcpBinPath, 'serve'],
-      };
-    }
-
-    // Package not installed globally - still try with absolute node path + npx
-    if (nodePath) {
-      const npxPath = join(dirname(nodePath), 'npx');
-      if (existsSync(npxPath)) {
-        return {
-          command: npxPath,
-          args: ['@agent-relay/mcp', 'serve'],
-        };
-      }
-    }
-  }
-
-  // Standard case: npx should work
-  return {
-    command: 'npx',
-    args: ['@agent-relay/mcp', 'serve'],
-  };
-}
-
-/**
- * Detect which editors are installed by checking for their config directories
- */
-export function detectInstalledEditors(): string[] {
-  const editors = getConfigPaths();
-  const detected: string[] = [];
-
-  for (const [key, config] of Object.entries(editors)) {
-    const configDir = dirname(config.configPath);
-    if (existsSync(configDir)) {
-      detected.push(key);
-    }
-  }
-
-  return detected;
-}
-
-/**
- * Get editor configuration by key
- */
-export function getEditorConfig(editorKey: string): EditorConfig | undefined {
-  const editors = getConfigPaths();
-  return editors[editorKey];
-}
-
-/**
- * List all supported editors
- */
-export function listSupportedEditors(): Array<{ key: string; name: string }> {
-  const editors = getConfigPaths();
-  return Object.entries(editors).map(([key, config]) => ({
-    key,
-    name: config.name,
-  }));
-}
-
-/**
- * Strip JSONC comments while preserving strings that contain // or /* sequences.
- * Uses a state machine to track whether we're inside a string literal.
- */
-function stripJsonComments(content: string): string {
-  let result = '';
-  let inString = false;
-  let inSingleLineComment = false;
-  let inMultiLineComment = false;
-  let i = 0;
-
-  while (i < content.length) {
-    const char = content[i];
-    const nextChar = content[i + 1];
-
-    // Handle string state (only when not in a comment)
-    if (!inSingleLineComment && !inMultiLineComment) {
-      if (char === '"' && (i === 0 || content[i - 1] !== '\\')) {
-        inString = !inString;
-        result += char;
-        i++;
-        continue;
-      }
-
-      // If in string, just copy the character
-      if (inString) {
-        result += char;
-        i++;
-        continue;
-      }
-
-      // Check for single-line comment start
-      if (char === '/' && nextChar === '/') {
-        inSingleLineComment = true;
-        i += 2;
-        continue;
-      }
-
-      // Check for multi-line comment start
-      if (char === '/' && nextChar === '*') {
-        inMultiLineComment = true;
-        i += 2;
-        continue;
-      }
-
-      // Not in any comment or string, copy the character
-      result += char;
-      i++;
-      continue;
-    }
-
-    // Handle single-line comment end
-    if (inSingleLineComment) {
-      if (char === '\n') {
-        inSingleLineComment = false;
-        result += char; // Preserve newline
-      }
-      i++;
-      continue;
-    }
-
-    // Handle multi-line comment end
-    if (inMultiLineComment) {
-      if (char === '*' && nextChar === '/') {
-        inMultiLineComment = false;
-        i += 2;
-        continue;
-      }
-      i++;
-      continue;
-    }
-
-    i++;
-  }
-
-  return result;
-}
-
-/**
- * Read and parse config file, handling JSON, JSONC, and TOML
- */
-function readConfigFile(
-  configPath: string,
-  format: 'json' | 'jsonc' | 'toml'
-): Record<string, unknown> {
-  if (!existsSync(configPath)) {
-    return {};
-  }
-
-  const content = readFileSync(configPath, 'utf-8');
-
-  try {
-    // Handle empty or whitespace-only files
-    const trimmed = content.trim();
-    if (!trimmed) {
-      return {};
-    }
-
-    if (format === 'toml') {
-      return TOML.parse(trimmed) as Record<string, unknown>;
-    }
-
-    const jsonContent = format === 'jsonc' ? stripJsonComments(content) : content;
-    return JSON.parse(jsonContent.trim()) as Record<string, unknown>;
-  } catch {
-    // Invalid config, start fresh
-    return {};
-  }
-}
-
-/**
- * Write config file with proper formatting
- */
-function writeConfigFile(
-  configPath: string,
-  config: Record<string, unknown>,
-  format: 'json' | 'jsonc' | 'toml' = 'json'
-): void {
-  const configDir = dirname(configPath);
-
-  // Ensure directory exists
-  if (!existsSync(configDir)) {
-    mkdirSync(configDir, { recursive: true });
-  }
-
-  if (format === 'toml') {
-    writeFileSync(configPath, TOML.stringify(config) + '\n');
-  } else {
-    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
-  }
-}
-
-/**
- * Get the config path for local (project-specific) installation
- */
-function getLocalConfigPath(
-  editor: EditorConfig,
-  projectDir: string
-): string | null {
-  if (!editor.supportsLocal) {
-    return null;
-  }
-
-  // Most editors use .vscode/mcp.json or similar in project root
-  switch (editor.name) {
-    case 'Claude Code':
-      return join(projectDir, '.mcp.json');
-    case 'Cursor':
-      return join(projectDir, '.cursor', 'mcp.json');
-    case 'VS Code':
-      return join(projectDir, '.vscode', 'mcp.json');
-    case 'Windsurf':
-      return join(projectDir, '.windsurf', 'mcp.json');
-    case 'Gemini CLI':
-      return join(projectDir, '.gemini', 'settings.json');
-    case 'OpenCode':
-      return join(projectDir, 'opencode.json');
-    case 'Droid':
-      return join(projectDir, '.factory', 'mcp.json');
-    case 'Codex':
-      return join(projectDir, 'codex.toml');
-    default:
-      return null;
-  }
-}
-
-/**
- * Install MCP server configuration for a specific editor
- */
-export function installForEditor(
-  editorKey: string,
-  options: InstallOptions = {}
-): InstallResult {
-  const editor = getEditorConfig(editorKey);
-
-  // Allow custom configPath even without known editor
-  if (!editor && !options.configPath) {
-    return {
-      editor: editorKey,
-      configPath: '',
-      success: false,
-      error: `Unknown editor: ${editorKey}`,
-      created: false,
-    };
-  }
-
-  // Determine config path, format, and key
-  // Custom configPath overrides everything (for programmatic installation)
-  let configPath: string;
-  let configFormat: 'json' | 'jsonc' | 'toml';
-  let configKey: string;
-
-  if (options.configPath) {
-    // Use custom path - for programmatic/auto installation
-    configPath = options.configPath;
-    configFormat = options.configFormat || 'json';
-    configKey = options.configKey || 'mcpServers';
-  } else if (editor) {
-    // Use editor's config
-    configPath = editor.configPath;
-    configFormat = editor.format;
-    configKey = editor.configKey;
-
-    // Check for local path override
-    if (!options.global && options.projectDir && editor.supportsLocal) {
-      const localPath = getLocalConfigPath(editor, options.projectDir);
-      if (localPath) {
-        configPath = localPath;
-      }
-    }
-  } else {
-    // Should not reach here due to early return above
-    return {
-      editor: editorKey,
-      configPath: '',
-      success: false,
-      error: `Unknown editor: ${editorKey}`,
-      created: false,
-    };
-  }
-
-  // Build server config - handles nvm users with absolute paths
-  const defaultConfig = buildServerConfig();
-  const serverConfig: McpServerConfig = {
-    command: options.command || defaultConfig.command,
-    args: options.args || [...defaultConfig.args],
-    env: options.env ? { ...options.env } : undefined,
-  };
-
-  // Set environment variables for project-local installs so the MCP server
-  // always targets the correct daemon socket, even when invoked from ~ or GUI
-  // apps. Do this only if values were not already provided explicitly.
-  const isProjectLocal = !options.global && options.projectDir;
-  if (isProjectLocal) {
-    const projectSocket = join(options.projectDir!, '.agent-relay', 'relay.sock');
-    serverConfig.env = {
-      ...(serverConfig.env || {}),
-      RELAY_SOCKET: serverConfig.env?.RELAY_SOCKET || projectSocket,
-      RELAY_PROJECT: serverConfig.env?.RELAY_PROJECT || options.projectDir!,
-      AGENT_RELAY_PROJECT: serverConfig.env?.AGENT_RELAY_PROJECT || options.projectDir!,
-    };
-  }
-
-  // For project-local installs with projectDir, add --project argument
-  // This allows the MCP server to find the correct socket even when
-  // invoked from a different working directory (e.g., by Claude Code)
-  if (isProjectLocal) {
-    // Add --project argument with absolute path to project directory
-    serverConfig.args = [...serverConfig.args, '--project', options.projectDir!];
-  }
-
-  if (options.dryRun) {
-    const editorName = editor?.name || editorKey || 'custom';
-    return {
-      editor: editorName,
-      configPath,
-      success: true,
-      created: !existsSync(configPath),
-    };
-  }
-
-  try {
-    // Read existing config
-    const config = readConfigFile(configPath, configFormat);
-    const created = !existsSync(configPath);
-
-    // Initialize mcpServers if not present
-    const configKeyValue = config[configKey];
-    if (!configKeyValue || typeof configKeyValue !== 'object') {
-      (config as Record<string, unknown>)[configKey] = {};
-    }
-
-    // Add agent-relay server config
-    const mcpServers = config[configKey] as Record<string, unknown>;
-
-    // OpenCode uses a different format: { type: "local", command: [...], environment: {...} }
-    if (editor?.name === 'OpenCode') {
-      const openCodeConfig: Record<string, unknown> = {
-        type: 'local',
-        command: [serverConfig.command, ...serverConfig.args],
-      };
-      if (serverConfig.env) {
-        openCodeConfig.environment = serverConfig.env;
-      }
-      mcpServers['agent-relay'] = openCodeConfig;
-    } else {
-      mcpServers['agent-relay'] = serverConfig;
-    }
-
-    // For Claude Code, also add permissions to auto-approve agent-relay tools
-    // Permissions go in settings.json, not .mcp.json
-    if (editor?.name === 'Claude Code') {
-      // Determine settings path based on where MCP config is being written
-      const projectDir = configPath.endsWith('.mcp.json')
-        ? dirname(configPath) // project-local: same dir as .mcp.json
-        : dirname(configPath); // global: ~/.claude/
-
-      const settingsPath = configPath.endsWith('.mcp.json')
-        ? join(projectDir, '.claude', 'settings.json') // project-local
-        : configPath; // global uses same file (settings.json)
-
-      // Read existing settings
-      const settings = configPath.endsWith('.mcp.json')
-        ? readConfigFile(settingsPath, 'json') // separate file for project-local
-        : config; // same config object for global
-
-      const permissions = (settings.permissions as Record<string, unknown>) || {};
-      const allowList = (permissions.allow as string[]) || [];
-
-      // Add agent-relay permission if not already present
-      if (!allowList.includes('mcp__agent-relay__*')) {
-        allowList.push('mcp__agent-relay__*');
-      }
-
-      permissions.allow = allowList;
-      settings.permissions = permissions;
-
-      // Write settings (separate file for project-local)
-      if (configPath.endsWith('.mcp.json')) {
-        writeConfigFile(settingsPath, settings, 'json');
-      }
-      // For global, permissions are added to same config object
-    }
-
-    // Write updated config
-    writeConfigFile(configPath, config, configFormat);
-
-    const editorName = editor?.name || editorKey || 'custom';
-    return {
-      editor: editorName,
-      configPath,
-      success: true,
-      created,
-    };
-  } catch (err) {
-    const editorName = editor?.name || editorKey || 'custom';
-    return {
-      editor: editorName,
-      configPath,
-      success: false,
-      error: err instanceof Error ? err.message : String(err),
-      created: false,
-    };
-  }
-}
-
-/**
- * Uninstall MCP server configuration from an editor
- */
-export function uninstallFromEditor(
-  editorKey: string,
-  options: { global?: boolean; projectDir?: string } = {}
-): InstallResult {
-  const editor = getEditorConfig(editorKey);
-
-  if (!editor) {
-    return {
-      editor: editorKey,
-      configPath: '',
-      success: false,
-      error: `Unknown editor: ${editorKey}`,
-      created: false,
-    };
-  }
-
-  // Determine config path
-  let configPath = editor.configPath;
-  if (!options.global && options.projectDir && editor.supportsLocal) {
-    const localPath = getLocalConfigPath(editor, options.projectDir);
-    if (localPath) {
-      configPath = localPath;
-    }
-  }
-
-  if (!existsSync(configPath)) {
-    return {
-      editor: editor.name,
-      configPath,
-      success: true,
-      created: false,
-    };
-  }
-
-  try {
-    const config = readConfigFile(configPath, editor.format);
-
-    const mcpServers = config[editor.configKey] as
-      | Record<string, unknown>
-      | undefined;
-    if (mcpServers && 'agent-relay' in mcpServers) {
-      delete mcpServers['agent-relay'];
-      writeConfigFile(configPath, config, editor.format);
-    }
-
-    return {
-      editor: editor.name,
-      configPath,
-      success: true,
-      created: false,
-    };
-  } catch (err) {
-    return {
-      editor: editor.name,
-      configPath,
-      success: false,
-      error: err instanceof Error ? err.message : String(err),
-      created: false,
-    };
-  }
-}
-
-/**
- * Check if agent-relay MCP server is installed for an editor
- */
-export function isInstalledFor(
-  editorKey: string,
-  options: { global?: boolean; projectDir?: string } = {}
-): boolean {
-  const editor = getEditorConfig(editorKey);
-  if (!editor) {
-    return false;
-  }
-
-  let configPath = editor.configPath;
-  if (!options.global && options.projectDir && editor.supportsLocal) {
-    const localPath = getLocalConfigPath(editor, options.projectDir);
-    if (localPath) {
-      configPath = localPath;
-    }
-  }
-
-  if (!existsSync(configPath)) {
-    return false;
-  }
-
-  try {
-    const config = readConfigFile(configPath, editor.format);
-    const mcpServers = config[editor.configKey] as
-      | Record<string, unknown>
-      | undefined;
-    return mcpServers !== undefined && 'agent-relay' in mcpServers;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Install MCP server for all detected editors (or specified editors)
- */
-export function install(options: InstallOptions = {}): InstallResult[] {
-  const results: InstallResult[] = [];
-
-  // Determine which editors to install for
-  const editors = options.editor
-    ? [options.editor]
-    : detectInstalledEditors();
-
-  if (editors.length === 0) {
-    return [
-      {
-        editor: 'none',
-        configPath: '',
-        success: false,
-        error: 'No supported editors detected',
-        created: false,
-      },
-    ];
-  }
-
-  for (const editorKey of editors) {
-    results.push(installForEditor(editorKey, options));
-  }
-
-  return results;
-}
-
-/**
- * Install MCP server configuration to a specific config file path.
- * This is a simpler API for programmatic/automated installation.
- *
- * @param configPath - Absolute path to config file
- * @param options - Optional settings for format, key, etc.
- */
-export function installMcpConfig(
-  configPath: string,
-  options: {
-    format?: 'json' | 'jsonc' | 'toml';
-    configKey?: string;
-    command?: string;
-    args?: string[];
-    env?: Record<string, string>;
-  } = {}
-): InstallResult {
-  return installForEditor('custom', {
-    configPath,
-    configFormat: options.format || 'json',
-    configKey: options.configKey || 'mcpServers',
-    command: options.command,
-    args: options.args,
-    env: options.env,
-  });
-}
-
-/**
- * Uninstall MCP server from all detected editors (or specified editors)
- */
-export function uninstall(options: InstallOptions = {}): InstallResult[] {
-  const results: InstallResult[] = [];
-
-  const editors = options.editor
-    ? [options.editor]
-    : detectInstalledEditors();
-
-  for (const editorKey of editors) {
-    results.push(
-      uninstallFromEditor(editorKey, {
-        global: options.global,
-        projectDir: options.projectDir,
-      })
-    );
-  }
-
-  return results;
-}