@useconductor/conductor 1.0.0

package/src/mcp/README.md

@@ -0,0 +1,20 @@
+# src/mcp
+
+Model Context Protocol server implementation. Exposes plugin tools to AI agents via stdio or HTTP/SSE transport.
+
+## Contents
+
+- `server.ts` - MCP server with circuit breaker, retry, audit logging, metrics, and Zod validation
+- `tools/` - Tool definitions and handlers
+
+## Architecture
+
+The MCP server wraps every plugin tool with:
+
+1. **Circuit breaker** — opens after repeated failures
+2. **Retry with exponential backoff**
+3. **Audit logging** — tamper-evident SHA-256 chained log
+4. **Metrics** — in-memory call counts and latency per tool
+5. **Zod validation** — validates inputs before handler invocation
+
+Transport: `StdioServerTransport` for AI agent integration; HTTP/SSE for the dashboard.

package/src/mcp/server.ts

@@ -0,0 +1,475 @@
+/**
+ * Conductor MCP Server — The AI Tool Hub
+ *
+ * A world-class MCP server that exposes every Conductor plugin as an MCP tool.
+ * Any AI agent (Claude Code, Cursor, Cline, Aider, etc.) connects once and
+ * gets access to 100+ tools across GitHub, Docker, databases, file ops, and more.
+ *
+ * Architecture:
+ *   - StdioServerTransport for direct AI agent integration
+ *   - HTTP/SSE transport for web dashboards and remote agents
+ *   - Auto-discovery of all enabled plugins
+ *   - Zod-validated input schemas
+ *   - Circuit breakers per tool (prevents cascading failures)
+ *   - Automatic retries with exponential backoff
+ *   - Audit logging (tamper-evident, SHA-256 chained)
+ *   - Health check system with per-plugin status
+ *   - Tool call metrics and latency tracking
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ListPromptsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { createRequire } from 'module';
+
+import type { Conductor } from '../core/conductor.js';
+import { PluginManager } from '../plugins/manager.js';
+import { validateTools } from '../plugins/validation.js';
+import { CircuitBreaker, CircuitOpenError } from '../core/circuit-breaker.js';
+import { withRetry } from '../core/retry.js';
+import { AuditLogger } from '../core/audit.js';
+import { HealthChecker } from '../core/health.js';
+import { WebhookManager } from '../core/webhooks.js';
+import { logger } from '../core/logger.js';
+import { enableZeroConfigMode } from '../core/zero-config.js';
+
+const _require = createRequire(import.meta.url);
+const { version } = _require('../../package.json') as { version: string };
+
+// ── Metrics ──────────────────────────────────────────────────────────────────
+
+interface ToolMetrics {
+  calls: number;
+  errors: number;
+  lastCallAt?: string;
+  avgLatencyMs: number;
+}
+
+const metrics: Map<string, ToolMetrics> = new Map();
+
+function recordCall(name: string, success: boolean, latencyMs: number): void {
+  const existing = metrics.get(name) ?? { calls: 0, errors: 0, avgLatencyMs: 0 };
+  const n = existing.calls + 1;
+  metrics.set(name, {
+    calls: n,
+    errors: existing.errors + (success ? 0 : 1),
+    lastCallAt: new Date().toISOString(),
+    avgLatencyMs: existing.avgLatencyMs + (latencyMs - existing.avgLatencyMs) / n,
+  });
+}
+
+// ── Tool Registry ────────────────────────────────────────────────────────────
+
+interface RegisteredTool {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+  handler: (args: Record<string, unknown>) => Promise<unknown>;
+  plugin: string;
+  requiresApproval: boolean;
+}
+
+async function buildToolRegistry(conductor: Conductor, pluginManager: PluginManager): Promise<RegisteredTool[]> {
+  const tools: RegisteredTool[] = [];
+
+  // Built-in conductor tools
+  tools.push({
+    name: 'conductor_status',
+    description: 'Get the current status of Conductor including enabled plugins and AI provider',
+    plugin: 'conductor',
+    requiresApproval: false,
+    inputSchema: { type: 'object', properties: {} },
+    handler: async () => {
+      const config = conductor.getConfig();
+      return {
+        version,
+        user: config.get('user.name') || 'not set',
+        ai_provider: config.get('ai.provider') || 'none',
+        plugins_enabled: config.get<string[]>('plugins.enabled') || [],
+        total_tools: tools.length,
+      };
+    },
+  });
+
+  tools.push({
+    name: 'conductor_tools_list',
+    description: 'List all available MCP tools grouped by plugin. Use this to discover what tools are available.',
+    plugin: 'conductor',
+    requiresApproval: false,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        plugin: { type: 'string', description: 'Filter by plugin name' },
+      },
+    },
+    handler: async (args: { plugin?: string }) => {
+      const byPlugin: Record<string, string[]> = {};
+      for (const t of tools) {
+        if (args.plugin && t.plugin !== args.plugin) continue;
+        (byPlugin[t.plugin] ??= []).push(t.name);
+      }
+      return { plugins: byPlugin, total: tools.length };
+    },
+  });
+
+  tools.push({
+    name: 'conductor_health',
+    description: 'Get detailed health report for all Conductor subsystems',
+    plugin: 'conductor',
+    requiresApproval: false,
+    inputSchema: { type: 'object', properties: {} },
+    handler: async () => {
+      return await globalHealthChecker.detailed(version);
+    },
+  });
+
+  tools.push({
+    name: 'conductor_audit_query',
+    description: 'Query the audit log for recent events. Supports filtering by actor, action, resource, result.',
+    plugin: 'conductor',
+    requiresApproval: false,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        actor: { type: 'string', description: 'Filter by actor' },
+        action: { type: 'string', description: 'Filter by action type' },
+        resource: { type: 'string', description: 'Filter by resource' },
+        result: { type: 'string', enum: ['success', 'failure', 'denied', 'timeout'], description: 'Filter by result' },
+        limit: { type: 'number', description: 'Max entries to return', default: 50 },
+      },
+    },
+    handler: async (args: { actor?: string; action?: string; resource?: string; result?: string; limit?: number }) => {
+      return globalAuditLogger.query({ ...args, limit: args.limit ?? 50 });
+    },
+  });
+
+  tools.push({
+    name: 'conductor_metrics',
+    description: 'Get tool call metrics (calls, errors, avg latency)',
+    plugin: 'conductor',
+    requiresApproval: false,
+    inputSchema: { type: 'object', properties: {} },
+    handler: async () => {
+      const result: Record<string, ToolMetrics> = {};
+      for (const [name, m] of metrics) result[name] = m;
+      return { metrics: result };
+    },
+  });
+
+  tools.push({
+    name: 'conductor_webhooks_list',
+    description: 'List all webhook subscriptions',
+    plugin: 'conductor',
+    requiresApproval: false,
+    inputSchema: { type: 'object', properties: {} },
+    handler: async () => {
+      const subs = globalWebhookManager.list();
+      return {
+        subscriptions: subs.map((s) => ({
+          id: s.id,
+          url: s.url,
+          events: s.events,
+          active: s.active,
+          failures: s.consecutiveFailures,
+        })),
+      };
+    },
+  });
+
+  // Plugin tools (with Zod validation)
+  const pluginTools = await pluginManager.getEnabledTools();
+  const validatedTools = validateTools(pluginTools);
+  for (const pt of validatedTools) {
+    tools.push({
+      name: pt.name,
+      description: pt.description,
+      inputSchema: pt.inputSchema,
+      handler: pt.handler,
+      plugin: 'plugin',
+      requiresApproval: pt.requiresApproval ?? false,
+    });
+  }
+
+  return tools;
+}
+
+// ── Global Infrastructure ────────────────────────────────────────────────────
+
+let globalAuditLogger: AuditLogger;
+let globalHealthChecker: HealthChecker;
+let globalWebhookManager: WebhookManager;
+const circuitBreakers: Map<string, CircuitBreaker> = new Map();
+
+/**
+ * Initialize global infrastructure (audit, health, webhooks).
+ * Called once when the MCP server starts.
+ */
+async function initInfrastructure(conductor: Conductor): Promise<void> {
+  const configDir = conductor.getConfig().getConfigDir();
+
+  // Audit logger
+  globalAuditLogger = new AuditLogger(configDir);
+
+  // Health checker
+  globalHealthChecker = new HealthChecker();
+
+  // Register health checks for each plugin
+  const pluginManager = new PluginManager(conductor);
+  await pluginManager.loadBuiltins();
+  for (const plugin of pluginManager.listPlugins()) {
+    globalHealthChecker.register(`plugin:${plugin.name}`, async () => ({
+      name: plugin.name,
+      status: plugin.enabled ? 'ok' : 'down',
+      message: plugin.enabled ? `${plugin.description}` : 'Plugin disabled',
+    }));
+  }
+
+  // Webhook manager
+  globalWebhookManager = new WebhookManager(configDir);
+  await globalWebhookManager.load();
+  globalHealthChecker.setWebhookCount(globalWebhookManager.list().filter((s) => s.active).length);
+
+  // Graceful shutdown
+  process.on('SIGINT', async () => {
+    await globalAuditLogger.close();
+    process.exit(0);
+  });
+  process.on('SIGTERM', async () => {
+    await globalAuditLogger.close();
+    process.exit(0);
+  });
+}
+
+// ── Server ───────────────────────────────────────────────────────────────────
+
+export interface MCPServerOptions {
+  /** Transport mode. stdio for AI agents, http for web dashboards. */
+  transport?: 'stdio' | 'http';
+  /** HTTP port when transport is http. */
+  port?: number;
+}
+
+export async function startMCPServer(conductor: Conductor, options: MCPServerOptions = {}): Promise<void> {
+  // Enable zero-config mode (20+ tools work without API keys)
+  await enableZeroConfigMode(conductor);
+
+  // Initialize infrastructure
+  await initInfrastructure(conductor);
+
+  const pluginManager = new PluginManager(conductor);
+  const tools = await buildToolRegistry(conductor, pluginManager);
+
+  // Create circuit breakers for each tool
+  for (const tool of tools) {
+    circuitBreakers.set(tool.name, new CircuitBreaker());
+    globalHealthChecker.registerCircuitBreaker(tool.name, circuitBreakers.get(tool.name)!);
+  }
+
+  // ── Startup summary ──────────────────────────────────────────────────────
+  const statuses = await pluginManager.getStatusSummary();
+  const ready = statuses.filter((s) => s.status === 'ready');
+  const notConfigured = statuses.filter((s) => s.status === 'not_configured');
+  const failed = statuses.filter((s) => s.status === 'init_failed');
+
+  process.stderr.write(`\n[conductor] v${version} — MCP server starting\n`);
+  process.stderr.write(`[conductor] ─────────────────────────────────────\n`);
+
+  for (const s of ready) {
+    process.stderr.write(`[conductor] ✓ ${s.name.padEnd(20)} ${s.toolCount} tool${s.toolCount !== 1 ? 's' : ''}\n`);
+  }
+
+  for (const s of notConfigured) {
+    process.stderr.write(`[conductor] ⚠ ${s.name.padEnd(20)} not configured\n`);
+    process.stderr.write(`[conductor]   → ${s.setupCommand}\n`);
+  }
+
+  for (const s of failed) {
+    process.stderr.write(`[conductor] ✗ ${s.name.padEnd(20)} init failed — ${s.error}\n`);
+    process.stderr.write(`[conductor]   → conductor doctor ${s.name}\n`);
+  }
+
+  process.stderr.write(`[conductor] ─────────────────────────────────────\n`);
+  process.stderr.write(`[conductor] ${tools.length} tools ready`);
+  if (notConfigured.length > 0)
+    process.stderr.write(` · ${notConfigured.length} need setup (run conductor plugins setup <name>)`);
+  if (failed.length > 0) process.stderr.write(` · ${failed.length} failed (run conductor doctor)`);
+  process.stderr.write(`\n\n`);
+
+  const server = new Server(
+    { name: 'conductor', version },
+    {
+      capabilities: {
+        tools: {},
+        resources: {},
+        prompts: {},
+      },
+    },
+  );
+
+  // ── tools/list ───────────────────────────────────────────────────────────
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => ({
+      name: t.name,
+      description: t.description,
+      inputSchema: t.inputSchema as Record<string, unknown>,
+    })),
+  }));
+
+  // ── tools/call ───────────────────────────────────────────────────────────
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+    const tool = tools.find((t) => t.name === name);
+
+    if (!tool) {
+      return {
+        content: [
+          { type: 'text' as const, text: `Unknown tool: ${name}. Run conductor_tools_list to see available tools.` },
+        ],
+        isError: true,
+      };
+    }
+
+    const start = Date.now();
+
+    try {
+      process.stderr.write(`[MCP] → ${name}\n`);
+
+      // Get or create circuit breaker for this tool
+      let breaker = circuitBreakers.get(name);
+      if (!breaker) {
+        breaker = new CircuitBreaker();
+        circuitBreakers.set(name, breaker);
+        globalHealthChecker.registerCircuitBreaker(name, breaker);
+      }
+
+      // Execute through circuit breaker + retry
+      const result = await breaker.execute(async () =>
+        withRetry(async () => tool.handler(args), { maxAttempts: 3, baseDelay: 500, maxDelay: 10000 }),
+      );
+
+      const latency = Date.now() - start;
+      recordCall(name, true, latency);
+      globalHealthChecker.recordToolCall(true, latency);
+
+      // Audit log
+      await globalAuditLogger.toolCall('mcp', name, args, 'success', { latency_ms: latency });
+
+      // Emit webhook event
+      await globalWebhookManager.emit({
+        type: 'tool_called',
+        resource: name,
+        data: { latency_ms: latency, success: true },
+      });
+
+      const text = typeof result === 'string' ? result : JSON.stringify(result, null, 2);
+      process.stderr.write(`[MCP] ← ${name} (${latency}ms)\n`);
+
+      return {
+        content: [{ type: 'text' as const, text }],
+      };
+    } catch (err: unknown) {
+      const latency = Date.now() - start;
+      recordCall(name, false, latency);
+      globalHealthChecker.recordToolCall(false, latency);
+
+      const message = err instanceof Error ? err.message : String(err);
+      const isCircuitOpen = err instanceof CircuitOpenError;
+      const result = isCircuitOpen ? 'denied' : 'failure';
+
+      // Audit log
+      await globalAuditLogger.toolCall('mcp', name, args, result as 'success' | 'failure' | 'denied' | 'timeout', {
+        latency_ms: latency,
+        error: message,
+        circuit_open: isCircuitOpen,
+      });
+
+      // Emit webhook event
+      await globalWebhookManager.emit({
+        type: 'tool_failed',
+        resource: name,
+        data: { latency_ms: latency, error: message, circuit_open: isCircuitOpen },
+      });
+
+      logger.warn({ tool: name, error: message, latency_ms: latency, circuit_open: isCircuitOpen }, 'Tool call failed');
+
+      process.stderr.write(`[MCP] ✗ ${name}: ${message} (${latency}ms)\n`);
+
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: isCircuitOpen
+              ? `Service unavailable: ${name} is temporarily disabled due to repeated failures. Try again later.`
+              : `Error: ${message}`,
+          },
+        ],
+        isError: true,
+      };
+    }
+  });
+
+  // ── resources/list ───────────────────────────────────────────────────────
+  server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+    resources: [],
+  }));
+
+  // ── prompts/list ─────────────────────────────────────────────────────────
+  server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+    prompts: [],
+  }));
+
+  // ── Transport ────────────────────────────────────────────────────────────
+  const transportMode = options.transport ?? 'stdio';
+
+  if (transportMode === 'http') {
+    const { SSEServerTransport } = await import('@modelcontextprotocol/sdk/server/sse.js');
+    const express = (await import('express')).default;
+    const rateLimit = (await import('express-rate-limit')).default;
+    const app = express();
+    const port = options.port ?? 3000;
+
+    // Rate limiting
+    app.use(rateLimit({ windowMs: 60_000, max: 1000, standardHeaders: true, legacyHeaders: false }));
+
+    // Health endpoints
+    app.get('/health', async (_req, res) => {
+      const report = await globalHealthChecker.detailed(version);
+      res.status(report.status === 'down' ? 503 : 200).json(report);
+    });
+
+    app.get('/health/ready', async (_req, res) => {
+      const ready = await globalHealthChecker.ready();
+      res.status(ready.ready ? 200 : 503).json(ready);
+    });
+
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let sseTransport: any = null;
+
+    app.get('/sse', async (_req, res) => {
+      sseTransport = new SSEServerTransport('/messages', res);
+      await server.connect(sseTransport);
+      process.stderr.write(`[MCP] SSE client connected\n`);
+    });
+
+    app.post('/messages', async (req, res) => {
+      if (sseTransport) {
+        await sseTransport.handlePostMessage(req, res);
+      } else {
+        res.status(503).json({ error: 'No SSE connection established' });
+      }
+    });
+
+    app.listen(port, () => {
+      process.stderr.write(`[MCP] HTTP server listening on port ${port}\n`);
+    });
+  } else {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write('[MCP] Connected via stdio\n');
+  }
+}

package/src/mcp/tools/README.md

@@ -0,0 +1,11 @@
+# src/mcp/tools
+
+MCP tool definitions and handlers that bridge the protocol layer to plugin implementations.
+
+## Contents
+
+- `misc.ts` - Miscellaneous tools not tied to a specific plugin
+
+## Architecture
+
+This directory contains tool definitions that are registered with the MCP server. Most tools are provided by plugins in `src/plugins/`, but cross-cutting or standalone tools live here. Each tool is wrapped with circuit breaker, retry, audit logging, and Zod validation by the MCP server.

package/src/mcp/tools/misc.ts

@@ -0,0 +1,61 @@
+import { PluginManager } from '../../plugins/manager.js';
+import { Conductor } from '../../core/conductor.js';
+
+export interface MCPTool {
+  name: string;
+  description: string;
+  inputSchema: Record<string, any>;
+  handler: (input: any) => Promise<any>;
+}
+
+/** Get built-in tools that are always available. */
+export function getBuiltinTools(conductor: Conductor): MCPTool[] {
+  return [
+    {
+      name: 'conductor_status',
+      description: 'Get the current status of Conductor',
+      inputSchema: { type: 'object', properties: {} },
+      handler: async () => {
+        const config = conductor.getConfig();
+        return {
+          user: config.get('user.name') || 'not set',
+          ai_provider: config.get('ai.provider') || 'none',
+          plugins_enabled: config.get<string[]>('plugins.enabled') || [],
+        };
+      },
+    },
+    {
+      name: 'conductor_recent_activity',
+      description: 'Get recent activity from Conductor',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          limit: { type: 'number', description: 'Number of entries', default: 10 },
+        },
+      },
+      handler: async (input: { limit?: number }) => {
+        return await conductor.getRecentActivity(input.limit || 10);
+      },
+    },
+  ];
+}
+
+/** Get tools from enabled plugins only (not all registered plugins). */
+export async function getPluginTools(pluginManager: PluginManager): Promise<MCPTool[]> {
+  // Only returns tools from plugins that are both enabled AND initialized
+  const pluginTools = await pluginManager.getEnabledTools();
+
+  return pluginTools.map((tool) => ({
+    name: tool.name,
+    description: tool.description,
+    inputSchema: tool.inputSchema,
+    handler: tool.handler,
+  }));
+}
+
+/** Get all available MCP tools (builtin + enabled plugins). */
+export async function getAllTools(conductor: Conductor, pluginManager: PluginManager): Promise<MCPTool[]> {
+  const builtin = getBuiltinTools(conductor);
+  const pluginTools = await getPluginTools(pluginManager);
+  return [...builtin, ...pluginTools];
+}

package/src/plugins/README.md

@@ -0,0 +1,28 @@
+# src/plugins
+
+Plugin system for Conductor. Every capability is a plugin implementing the `Plugin` interface.
+
+## Contents
+
+- `manager.ts` - `PluginManager` that handles registration, lazy initialization, and lifecycle
+- `validation.ts` - Input validation for plugin tool calls
+- `builtin/` - Built-in plugins shipped with Conductor
+
+## Architecture
+
+Plugins implement the `Plugin` interface:
+
+```typescript
+interface Plugin {
+  name: string;
+  description: string;
+  version: string;
+  initialize(conductor: Conductor): Promise<void>;
+  isConfigured(): boolean;
+  getTools(): PluginTool[];
+  configSchema?: PluginConfigSchema;
+  getContext?(): Promise<string | null>;
+}
+```
+
+Plugins are **lazily initialized** — `PluginManager.getPlugin(name)` initializes on first call. Built-in plugins live in `builtin/`; external plugins are loaded from `~/.conductor/plugins/` as `.js` files.

package/src/plugins/builtin/README.md

@@ -0,0 +1,23 @@
+# src/plugins/builtin
+
+Built-in plugins shipped with Conductor. Each file implements a `Plugin` for a specific capability.
+
+## Contents
+
+- `index.ts` - Registry of all builtin plugins
+- `shell.ts` - Shell command execution with whitelist allowlist
+- `github.ts` / `github-actions.ts` - GitHub repository and CI/CD operations
+- `gcal.ts` / `gdrive.ts` / `gmail.ts` - Google Workspace integrations
+- `slack.ts` - Slack messaging and channel management
+- `linear.ts` / `notion.ts` / `todoist.ts` - Project management tools
+- `docker.ts` - Docker container management
+- `database.ts` - Database query operations
+- `calculator.ts` / `crypto.ts` / `hash.ts` - Math and crypto utilities
+- `text-tools.ts` / `url-tools.ts` / `translate.ts` - Text manipulation
+- `weather.ts` / `timezone.ts` / `system.ts` - System and info tools
+- `n8n.ts` / `vercel.ts` / `spotify.ts` / `x.ts` - Third-party service integrations
+- `cron.ts` / `memory.ts` / `notes.ts` / `fun.ts` / `colors.ts` / `network.ts` / `homekit.ts` / `lumen.ts` - Utility plugins
+
+## Architecture
+
+Each plugin is auto-registered via `index.ts` and lazily initialized by `PluginManager`. Plugins declare their tools via `getTools()` and can provide config schemas for `conductor config setup <plugin>`. Secret credentials use `secret: true` fields stored in the OS keychain.