agent-relay 1.6.0 → 2.0.4

package/packages/mcp/dist/install-cli.js

@@ -0,0 +1,157 @@
+/**
+ * CLI wrapper for MCP installation
+ *
+ * Provides user-friendly interface for installing MCP server
+ * configuration in supported AI editors.
+ */
+import { install, uninstall, detectInstalledEditors, listSupportedEditors, isInstalledFor, } from './install.js';
+/**
+ * Format install result for display
+ */
+function formatResult(result, action) {
+    const icon = result.success ? '\u2713' : '\u2717';
+    const actionWord = action === 'install' ? 'configured' : 'removed';
+    const createdNote = result.created ? ' (created)' : '';
+    if (result.success) {
+        return `  ${icon} ${result.editor} ${actionWord}${createdNote}`;
+    }
+    else {
+        return `  ${icon} ${result.editor}: ${result.error}`;
+    }
+}
+/**
+ * Show installation status for all editors
+ */
+function showStatus(projectDir) {
+    const supported = listSupportedEditors();
+    const detected = detectInstalledEditors();
+    console.log('MCP Installation Status');
+    console.log('');
+    console.log('Editor               Detected    Installed');
+    console.log('-------------------------------------------');
+    for (const { key, name } of supported) {
+        const isDetected = detected.includes(key);
+        const isInstalled = isInstalledFor(key, { projectDir });
+        const detectedStr = isDetected ? '\u2713' : '-';
+        const installedStr = isInstalled ? '\u2713' : '-';
+        // Pad name to 20 chars
+        const paddedName = name.padEnd(20);
+        console.log(`${paddedName} ${detectedStr.padEnd(12)}${installedStr}`);
+    }
+}
+/**
+ * Show list of supported editors
+ */
+function showList() {
+    const supported = listSupportedEditors();
+    const detected = detectInstalledEditors();
+    console.log('Supported Editors:');
+    console.log('');
+    for (const { key, name } of supported) {
+        const isDetected = detected.includes(key);
+        const status = isDetected ? '(detected)' : '';
+        console.log(`  ${key.padEnd(15)} ${name} ${status}`);
+    }
+    console.log('');
+    console.log('Usage:');
+    console.log('  npx @agent-relay/mcp install --editor <key>');
+}
+/**
+ * Run the install command with CLI options
+ */
+export function runInstall(options = {}) {
+    // Handle --list
+    if (options.list) {
+        showList();
+        return;
+    }
+    // Handle --status
+    if (options.status) {
+        showStatus(process.cwd());
+        return;
+    }
+    const installOptions = {
+        editor: options.editor,
+        global: options.global,
+        projectDir: options.global ? undefined : process.cwd(),
+        dryRun: options.dryRun,
+    };
+    // Handle --uninstall
+    if (options.uninstall) {
+        if (!options.quiet) {
+            console.log('Uninstalling Agent Relay MCP server...');
+            if (options.dryRun) {
+                console.log('(dry run - no changes will be made)');
+            }
+            console.log('');
+        }
+        const results = uninstall(installOptions);
+        printResults(results, 'uninstall', options.quiet);
+        return;
+    }
+    // Normal install
+    if (!options.quiet) {
+        console.log('Installing Agent Relay MCP server...');
+        if (options.dryRun) {
+            console.log('(dry run - no changes will be made)');
+        }
+        console.log('');
+    }
+    const results = install(installOptions);
+    printResults(results, 'install', options.quiet);
+}
+/**
+ * Print results and exit with appropriate code
+ */
+function printResults(results, action, quiet) {
+    const successful = results.filter(r => r.success);
+    const failed = results.filter(r => !r.success);
+    if (!quiet) {
+        for (const result of results) {
+            console.log(formatResult(result, action));
+        }
+        console.log('');
+    }
+    // Handle no editors detected case
+    if (results.length === 1 && results[0].editor === 'none') {
+        console.log('No supported editors detected.');
+        console.log('');
+        console.log('Supported editors: claude, claude-code, cursor, vscode, windsurf, zed');
+        console.log('');
+        console.log('Specify manually with: npx @agent-relay/mcp install --editor <name>');
+        process.exit(1);
+    }
+    // Summary
+    if (!quiet) {
+        if (failed.length === 0) {
+            const actionWord = action === 'install' ? 'Installation' : 'Removal';
+            console.log(`${actionWord} complete!`);
+            if (action === 'install') {
+                console.log('');
+                console.log('The relay tools will be available when you start your editor.');
+                console.log('Make sure the relay daemon is running: agent-relay up');
+            }
+        }
+        else {
+            console.log(`Completed with ${failed.length} error(s).`);
+        }
+    }
+    // Exit with error if any failures
+    if (failed.length > 0) {
+        process.exit(1);
+    }
+}
+/**
+ * Validate editor argument
+ */
+export function validateEditor(editor) {
+    const supported = listSupportedEditors();
+    return supported.some(e => e.key === editor);
+}
+/**
+ * Get list of valid editor keys for CLI help
+ */
+export function getValidEditors() {
+    return listSupportedEditors().map(e => e.key);
+}
+//# sourceMappingURL=install-cli.js.map

package/packages/mcp/dist/install.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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)
+ */
+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';
+    /** 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[];
+}
+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>;
+}
+/**
+ * Default MCP server configuration
+ */
+export declare function getDefaultServerConfig(): McpServerConfig;
+/**
+ * Detect which editors are installed by checking for their config directories
+ */
+export declare function detectInstalledEditors(): string[];
+/**
+ * Get editor configuration by key
+ */
+export declare function getEditorConfig(editorKey: string): EditorConfig | undefined;
+/**
+ * List all supported editors
+ */
+export declare function listSupportedEditors(): Array<{
+    key: string;
+    name: string;
+}>;
+/**
+ * Install MCP server configuration for a specific editor
+ */
+export declare function installForEditor(editorKey: string, options?: InstallOptions): InstallResult;
+/**
+ * Uninstall MCP server configuration from an editor
+ */
+export declare function uninstallFromEditor(editorKey: string, options?: {
+    global?: boolean;
+    projectDir?: string;
+}): InstallResult;
+/**
+ * Check if agent-relay MCP server is installed for an editor
+ */
+export declare function isInstalledFor(editorKey: string, options?: {
+    global?: boolean;
+    projectDir?: string;
+}): boolean;
+/**
+ * Install MCP server for all detected editors (or specified editors)
+ */
+export declare function install(options?: InstallOptions): InstallResult[];
+/**
+ * Uninstall MCP server from all detected editors (or specified editors)
+ */
+export declare function uninstall(options?: InstallOptions): InstallResult[];
+//# sourceMappingURL=install.d.ts.map

package/packages/mcp/dist/install.js

@@ -0,0 +1,398 @@
+/**
+ * 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';
+/**
+ * Get platform-specific config paths
+ */
+function getConfigPaths() {
+    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.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,
+        },
+    };
+}
+/**
+ * Default MCP server configuration
+ */
+export function getDefaultServerConfig() {
+    return {
+        command: 'npx',
+        args: ['@agent-relay/mcp', 'serve'],
+    };
+}
+/**
+ * Detect which editors are installed by checking for their config directories
+ */
+export function detectInstalledEditors() {
+    const editors = getConfigPaths();
+    const detected = [];
+    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) {
+    const editors = getConfigPaths();
+    return editors[editorKey];
+}
+/**
+ * List all supported editors
+ */
+export function listSupportedEditors() {
+    const editors = getConfigPaths();
+    return Object.entries(editors).map(([key, config]) => ({
+        key,
+        name: config.name,
+    }));
+}
+/**
+ * Strip JSON comments (for JSONC format)
+ */
+function stripJsonComments(content) {
+    // Remove single-line comments
+    let result = content.replace(/\/\/.*$/gm, '');
+    // Remove multi-line comments
+    result = result.replace(/\/\*[\s\S]*?\*\//g, '');
+    return result;
+}
+/**
+ * Read and parse config file, handling both JSON and JSONC
+ */
+function readConfigFile(configPath, format) {
+    if (!existsSync(configPath)) {
+        return {};
+    }
+    const content = readFileSync(configPath, 'utf-8');
+    const jsonContent = format === 'jsonc' ? stripJsonComments(content) : content;
+    try {
+        // Handle empty or whitespace-only files
+        const trimmed = jsonContent.trim();
+        if (!trimmed) {
+            return {};
+        }
+        return JSON.parse(trimmed);
+    }
+    catch {
+        // Invalid JSON, start fresh
+        return {};
+    }
+}
+/**
+ * Write config file with proper formatting
+ */
+function writeConfigFile(configPath, config) {
+    const configDir = dirname(configPath);
+    // Ensure directory exists
+    if (!existsSync(configDir)) {
+        mkdirSync(configDir, { recursive: true });
+    }
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+}
+/**
+ * Get the config path for local (project-specific) installation
+ */
+function getLocalConfigPath(editor, projectDir) {
+    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');
+        default:
+            return null;
+    }
+}
+/**
+ * Install MCP server configuration for a specific editor
+ */
+export function installForEditor(editorKey, options = {}) {
+    const editor = getEditorConfig(editorKey);
+    if (!editor) {
+        return {
+            editor: editorKey,
+            configPath: '',
+            success: false,
+            error: `Unknown editor: ${editorKey}`,
+            created: false,
+        };
+    }
+    // Determine config path (global vs local)
+    let configPath = editor.configPath;
+    if (!options.global && options.projectDir && editor.supportsLocal) {
+        const localPath = getLocalConfigPath(editor, options.projectDir);
+        if (localPath) {
+            configPath = localPath;
+        }
+    }
+    // Build server config
+    const serverConfig = {
+        command: options.command || 'npx',
+        args: options.args || ['@agent-relay/mcp', 'serve'],
+    };
+    // Note: We don't set RELAY_PROJECT for local installs because the MCP server
+    // will auto-discover the socket from the current working directory.
+    // This makes the config portable across machines.
+    if (options.dryRun) {
+        return {
+            editor: editor.name,
+            configPath,
+            success: true,
+            created: !existsSync(configPath),
+        };
+    }
+    try {
+        // Read existing config
+        const config = readConfigFile(configPath, editor.format);
+        const created = !existsSync(configPath);
+        // Initialize mcpServers if not present
+        const configKeyValue = config[editor.configKey];
+        if (!configKeyValue || typeof configKeyValue !== 'object') {
+            config[editor.configKey] = {};
+        }
+        // Add agent-relay server config
+        const mcpServers = config[editor.configKey];
+        mcpServers['agent-relay'] = serverConfig;
+        // Write updated config
+        writeConfigFile(configPath, config);
+        return {
+            editor: editor.name,
+            configPath,
+            success: true,
+            created,
+        };
+    }
+    catch (err) {
+        return {
+            editor: editor.name,
+            configPath,
+            success: false,
+            error: err instanceof Error ? err.message : String(err),
+            created: false,
+        };
+    }
+}
+/**
+ * Uninstall MCP server configuration from an editor
+ */
+export function uninstallFromEditor(editorKey, options = {}) {
+    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];
+        if (mcpServers && 'agent-relay' in mcpServers) {
+            delete mcpServers['agent-relay'];
+            writeConfigFile(configPath, config);
+        }
+        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, options = {}) {
+    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];
+        return mcpServers !== undefined && 'agent-relay' in mcpServers;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Install MCP server for all detected editors (or specified editors)
+ */
+export function install(options = {}) {
+    const results = [];
+    // 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;
+}
+/**
+ * Uninstall MCP server from all detected editors (or specified editors)
+ */
+export function uninstall(options = {}) {
+    const results = [];
+    const editors = options.editor
+        ? [options.editor]
+        : detectInstalledEditors();
+    for (const editorKey of editors) {
+        results.push(uninstallFromEditor(editorKey, {
+            global: options.global,
+            projectDir: options.projectDir,
+        }));
+    }
+    return results;
+}
+//# sourceMappingURL=install.js.map

package/packages/mcp/dist/prompts/index.d.ts

@@ -0,0 +1,2 @@
+export { protocolPrompt, getProtocolPrompt, PROTOCOL_DOCUMENTATION } from './protocol.js';
+//# sourceMappingURL=index.d.ts.map

package/packages/mcp/dist/prompts/index.js

@@ -0,0 +1,2 @@
+export { protocolPrompt, getProtocolPrompt, PROTOCOL_DOCUMENTATION } from './protocol.js';
+//# sourceMappingURL=index.js.map

package/packages/mcp/dist/prompts/protocol.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Protocol Documentation Prompt
+ *
+ * Provides the full Agent Relay protocol documentation as an MCP prompt.
+ * This is included automatically when an agent connects.
+ */
+import type { Prompt } from '@modelcontextprotocol/sdk/types.js';
+export declare const protocolPrompt: Prompt;
+export declare const PROTOCOL_DOCUMENTATION = "\n# Agent Relay Protocol\n\nYou are connected to Agent Relay, a real-time messaging system for AI agent coordination.\n\n## Communication Patterns\n\n### Direct Messages\nSend a message to a specific agent by name:\n```\nrelay_send(to=\"Alice\", message=\"Can you review this PR?\")\n```\n\n### Channel Messages\nSend to a channel (prefix with #):\n```\nrelay_send(to=\"#engineering\", message=\"Build complete\")\n```\nChannel messages are visible to all agents subscribed to that channel.\n\n### Broadcast\nSend to all online agents:\n```\nrelay_send(to=\"*\", message=\"System maintenance in 5 minutes\")\n```\nUse sparingly - broadcasts interrupt all agents.\n\n### Threaded Conversations\nFor multi-turn conversations, use thread IDs:\n```\nrelay_send(to=\"Bob\", message=\"Starting task\", thread=\"task-123\")\nrelay_send(to=\"Bob\", message=\"Task update\", thread=\"task-123\")\n```\n\n### Await Response\nBlock and wait for a reply:\n```\nrelay_send(to=\"Worker\", message=\"Process this file\", await_response=true, timeout_ms=60000)\n```\n\n## Spawning Workers\n\nCreate worker agents to parallelize work:\n\n```\nrelay_spawn(\n  name=\"TestRunner\",\n  cli=\"claude\",\n  task=\"Run the test suite in src/tests/ and report any failures\"\n)\n```\n\nWorkers:\n- Run in separate processes\n- Have their own CLI instance\n- Can use relay to communicate back\n- Should be released when done\n\n### Worker Lifecycle\n1. Spawn worker with task\n2. Worker sends ACK when ready\n3. Worker sends progress updates\n4. Worker sends DONE when complete\n5. Lead releases worker\n\n### Release Workers\n```\nrelay_release(name=\"TestRunner\", reason=\"Tests completed\")\n```\n\n## Message Protocol\n\nWhen you receive messages, they follow this format:\n```\nRelay message from Alice [msg-id-123]: Content here\n```\n\nChannel messages include the channel:\n```\nRelay message from Alice [msg-id-456] [#general]: Hello team!\n```\n\n### ACK/DONE Protocol\nWhen assigned a task:\n1. Send ACK immediately: \"ACK: Starting work on X\"\n2. Send progress updates as needed\n3. Send DONE when complete: \"DONE: Completed X with result Y\"\n\nExample:\n```\n# When receiving a task\nrelay_send(to=\"Lead\", message=\"ACK: Starting test suite run\")\n\n# ... do work ...\n\nrelay_send(to=\"Lead\", message=\"DONE: All 42 tests passed\")\n```\n\n## Best Practices\n\n### For Lead Agents\n- Spawn workers for parallelizable tasks\n- Keep track of spawned workers\n- Release workers when done\n- Use channels for team announcements\n\n### For Worker Agents\n- ACK immediately when receiving tasks\n- Send progress updates for long tasks\n- Send DONE with results when complete\n- Ask clarifying questions if needed\n\n### Message Etiquette\n- Keep messages concise\n- Include relevant context\n- Use threads for related messages\n- Don't spam broadcasts\n\n## Checking Messages\n\nProactively check your inbox:\n```\nrelay_inbox()\nrelay_inbox(from=\"Lead\")\nrelay_inbox(channel=\"#urgent\")\n```\n\n## Seeing Who's Online\n\n```\nrelay_who()\n```\n\n## Error Handling\n\nIf relay returns an error:\n- \"Daemon not running\" - The relay daemon needs to be started\n- \"Agent not found\" - Target agent is offline\n- \"Channel not found\" - Channel doesn't exist\n- \"Timeout\" - No response within timeout period\n\n## Multi-Project Communication\n\nIn multi-project setups, specify project:\n```\nrelay_send(to=\"frontend:Designer\", message=\"Need UI mockup\")\n```\n\nSpecial targets:\n- `project:lead` - Lead agent of that project\n- `project:*` - Broadcast to project\n- `*:*` - Broadcast to all projects\n";
+export declare function getProtocolPrompt(): string;
+//# sourceMappingURL=protocol.d.ts.map