@useconductor/conductor 1.0.0 → 1.0.1

package/README.md

@@ -1,16 +1,43 @@
 # Conductor
 
-**The AI Tool Hub.** One MCP server. 100+ tools. Every AI agent.
+**One MCP server. Tools for every AI agent.**
 
-[![CI](https://github.com/conductor/conductor/actions/workflows/ci.yml/badge.svg)](https://github.com/conductor/conductor/actions/workflows/ci.yml)
-[![npm](https://img.shields.io/npm/v/@conductor/cli)](https://www.npmjs.com/package/@conductor/cli)
-[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![CI](https://github.com/useconductor/conductor/actions/workflows/ci.yml/badge.svg)](https://github.com/useconductor/conductor/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@useconductor/conductor)](https://www.npmjs.com/package/@useconductor/conductor)
+[![Node](https://img.shields.io/badge/node-%3E%3D20.12-brightgreen)](https://nodejs.org)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue)](./LICENSE)
 
-## One Connection. Every Tool.
+Conductor is a single [Model Context Protocol](https://modelcontextprotocol.io) server that gives any AI agent — Claude, Cursor, Cline, Copilot, and more — access to your tools through one connection. Install once, configure once, use everywhere.
 
-Conductor is the single MCP server that gives **any AI agent** access to 100+ real-world tools. No more configuring 10 different MCP servers. No more managing 10 different auth flows. One line of config, everything works.
+```bash
+npm install -g @useconductor/conductor
+conductor init
+```
+
+---
+
+## Why Conductor
+
+Running one MCP server per tool means one process, one config, and one potential failure per integration. Conductor collapses all of that into a single server with a consistent security layer and one config block in your AI client.
+
+- **Single process** — GitHub, Docker, shell, databases, and more through one connection
+- **Encrypted credential storage** — secrets encrypted with a machine-derived AES-256-GCM key, never in plain config files
+- **Circuit breakers + retry** on every tool call — failures don't cascade
+- **SHA-256 chained audit log** — every action recorded, tamper-evident
+- **One config block** in your AI client
+
+---
+
+## Quick start
+
+```bash
+npm install -g @useconductor/conductor
+conductor init
+```
+
+### Claude Desktop
 
-Add this to your AI agent's MCP config:
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 
 ```json
 {
@@ -23,157 +50,299 @@ Add this to your AI agent's MCP config:
 }
 ```
 
-Now **Claude Code**, **Cursor**, **Cline**, **Aider**, and every other MCP-compatible AI agent instantly gets access to:
+Or skip the manual editing: `conductor mcp setup`
 
-| Category | Tools |
-|----------|-------|
-| **GitHub** | repos, issues, PRs, stars, trending, actions |
-| **Docker** | containers, images, volumes, networks, stats, run |
-| **Databases** | PostgreSQL, MySQL, MongoDB, Redis queries |
-| **File System** | read, write, list, search, grep |
-| **Shell** | safe command execution with approval workflow |
-| **Git** | status, diff, log, branch operations |
-| **Calculator** | math expressions, unit conversions, date math |
-| **Web** | search, scrape, URL tools, translate |
-| **System** | info, network, crypto, hash, colors |
-| **Google** | Gmail, Calendar, Drive |
-| **Productivity** | Notion, Todoist, Slack, notes, cron |
-| **And more** | Vercel, n8n, weather, timezone, memory |
+### Cursor / Windsurf / Cline / Continue
 
-## Install
+Same config block — drop it into `.cursor/mcp.json`, `.codeium/windsurf/mcp_config.json`, or your client's MCP config file.
+
+### No global install
+
+```json
+{
+  "mcpServers": {
+    "conductor": {
+      "command": "npx",
+      "args": ["-y", "@useconductor/conductor", "mcp", "start"]
+    }
+  }
+}
+```
+
+---
+
+## Plugins
+
+### Core (fully tested, production-ready)
+
+| Plugin | What it does | Setup |
+|---|---|---|
+| `shell` | Safe shell execution, file read/write/search | Enabled by default |
+| `github` | Repos, issues, PRs, code search (23 tools) | Optional `GITHUB_TOKEN` for private repos |
+| `docker` | Containers, images, volumes, networks (16 tools) | Docker daemon running |
+| `database` | PostgreSQL, MySQL, MongoDB, Redis queries | Connection URL |
+| `slack` | Messages, channels, search, DMs | `conductor slack setup` |
+
+### Zero-config utilities (no setup required)
+
+| Plugin | What it does |
+|---|---|
+| `calculator` | Math expressions, unit conversions, date arithmetic |
+| `colors` | Convert hex/RGB/HSL, generate palettes, WCAG contrast |
+| `hash` | SHA-256/MD5/SHA-512, base64, UUID, passwords |
+| `text-tools` | JSON format, word count, regex test, case transform |
+| `timezone` | Current time in any city, timezone conversion |
+| `weather` | Current conditions and forecast by city (Open-Meteo, no key required) |
+| `network` | Ping, DNS lookup, port check, IP info |
+| `url-tools` | Expand short links, check status, inspect headers |
+| `system` | CPU, memory, disk usage |
+| `notes` | Local markdown notes |
+| `memory` | Persistent key-value memory across sessions |
+| `cron` | Schedule recurring tasks |
+| `fun` | Jokes, trivia, quotes |
+
+### Additional (needs setup)
+
+| Plugin | Setup |
+|---|---|
+| `gmail`, `gcal`, `gdrive` | `conductor google` |
+| `notion` | API key |
+| `linear` | API key |
+| `jira` | Domain + API token |
+| `stripe` | Secret key |
+| `vercel` | API token |
+| `n8n` | Base URL + API key |
+| `spotify` | Client ID + secret |
+| `x` | API credentials |
+| `homekit` | Homebridge base URL |
+| `todoist` | API token |
+| `github-actions` | `GITHUB_TOKEN` |
+
+---
+
+## CLI reference
+
+### Setup
 
 ```bash
-npm install -g @conductor/cli
+conductor init                        # First-run wizard
+conductor mcp setup                   # Auto-configure Claude Desktop / Cursor
+conductor mcp start                   # Start MCP server (stdio)
+conductor mcp status                  # Show MCP server status
+conductor doctor                      # Diagnose common issues
+conductor health                      # System health report
+conductor health --json               # Machine-readable health output
 ```
 
-## Quick Start
+### Plugins
 
 ```bash
-# Start the MCP server
-conductor mcp start
+conductor plugins list                # List all plugins (enabled/disabled)
+conductor plugins enable <name>       # Enable a plugin
+conductor plugins disable <name>      # Disable a plugin
+conductor onboard                     # Interactive TUI plugin picker
+conductor install <plugin>            # Install from marketplace
+conductor marketplace                 # Browse marketplace
+conductor marketplace info <plugin>   # Plugin details
+conductor plugins create <name>       # Scaffold a new plugin with tests
+```
+
+### Authentication
 
-# Enable plugins
-conductor plugins enable github
-conductor plugins enable docker
-conductor plugins enable shell
+```bash
+conductor google                      # Browser-based Google OAuth (Gmail, Calendar, Drive)
+conductor slack setup                 # Configure Slack bot token
+conductor slack start                 # Start the Slack bot
+conductor telegram setup              # Configure Telegram bot token
+conductor telegram start              # Start the Telegram bot
+conductor ai setup                    # Configure AI provider
+conductor ai test                     # Test current AI provider
+```
 
-# Configure credentials
-conductor config set github.token ghp_your_token_here
+### Configuration
 
-# Check status
-conductor plugins list
+```bash
+conductor config list                 # Show all config keys and values
+conductor config get <key>            # Get a specific key (e.g. ai.provider)
+conductor config set <key> <value>    # Set a key (JSON or string)
+conductor config path                 # Print config file path
+conductor config export               # Dump config as JSON
+conductor config validate             # Check config structure
+conductor config reset                # Reset to defaults
+```
+
+### Audit log
+
+```bash
+conductor audit list                  # List recent entries
+conductor audit list --actor user1    # Filter by actor
+conductor audit list --result failure # Filter by result
+conductor audit verify                # Verify SHA-256 chain integrity
+conductor audit tail                  # Stream in real time
+conductor audit stats                 # Summary statistics
+conductor audit export -o out.json    # Export to file
+conductor audit rotate                # Manually rotate log file
 ```
 
-## Works With Every AI Agent
+### Circuit breakers
+
+```bash
+conductor circuit list                # Show state of all circuit breakers
+conductor circuit reset <tool>        # Reset a specific circuit to closed
+```
 
-Conductor connects to any MCP-compatible client:
+---
 
-- **Claude Desktop** — `conductor mcp setup`
-- **Claude Code** — add to `claude.json` MCP config
-- **Cursor** — add to Cursor MCP settings
-- **Cline** — add to Cline MCP servers
-- **Aider** — configure as external tool
-- **Any MCP client** — stdio or HTTP transport
+## Security model
+
+Every tool call passes through this stack:
+
+```
+Request
+  → Zod input validation
+  → Circuit breaker              (opens after 5 failures, recovers in 30s)
+  → Retry with exponential backoff
+  → Handler
+  → Audit log entry              (SHA-256 chained, append-only)
+  → Metrics
+```
+
+**Credentials** are encrypted with AES-256-GCM using a key derived from the machine's hardware ID (IOPlatformUUID on macOS, `/etc/machine-id` on Linux). They are stored in `~/.conductor/keychain/` as encrypted files — not in `config.json`, and never in plaintext.
+
+**Shell commands** go through a strict allowlist (~50 standard dev tools). No `eval()`, no arbitrary execution.
+
+**Audit log** at `~/.conductor/audit/audit.log` is JSONL with a SHA-256 chain. Each entry hashes the previous entry's hash + its own content. Verify integrity anytime with `conductor audit verify`.
+
+**Rate limiting** on all HTTP endpoints via `express-rate-limit`.
+
+---
 
 ## Architecture
 
 ```
-┌─────────────────────────────────────────────────┐
-│              AI Agent (any MCP client)          │
-│  Claude Code  │  Cursor  │  Cline  │  Aider     │
-└──────────────────────┬──────────────────────────┘
-                       │ MCP Protocol (stdio/HTTP)
-                       ▼
-┌─────────────────────────────────────────────────┐
-│              Conductor MCP Server               │
-│                                                 │
-│  ┌──────────┐  ┌──────────┐  ┌───────────────┐ │
-│  │  GitHub   │  │  Docker   │  │  Databases    │ │
-│  │  Plugin   │  │  Plugin   │  │   Plugin      │ │
-│  └──────────┘  └──────────┘  └───────────────┘ │
-│  ┌──────────┐  ┌──────────┐  ┌───────────────┐ │
-│  │   Shell   │  │    Git    │  │  Calculator   │ │
-│  │  Plugin   │  │  Plugin   │  │   Plugin      │ │
-│  └──────────┘  └──────────┘  └───────────────┘ │
-│  ┌──────────┐  ┌──────────┐  ┌───────────────┐ │
-│  │  Google   │  │  Slack    │  │  + 90 more    │ │
-│  │  Plugin   │  │  Plugin   │  │   plugins     │ │
-│  └──────────┘  └──────────┘  └───────────────┘ │
-│                                                 │
-│  Encrypted Keychain │ Zod Validation │ Metrics  │
-└─────────────────────────────────────────────────┘
-```
-
-## Security
-
-- **Encrypted keychain** — AES-256-GCM with machine-bound key derivation
-- **Zod validation** — every plugin input is validated before execution
-- **Safe shell** — whitelist-based command filtering, no `eval()`, no `exec()`
-- **Plugin sandboxing** — plugins run with minimal permissions
-- **Approval workflow** — dangerous operations require explicit user approval
-- **Rate limiting** — all endpoints protected against abuse
-
-## Plugin System
-
-Build your own plugins. Drop a `.js` file in `~/.conductor/plugins/` and it's available via MCP.
+src/
+├── cli/            Commander CLI
+│   └── commands/   init, mcp, plugins, audit, config, circuit, auth, ...
+├── core/           Conductor orchestrator, config, database, audit, retry, circuit-breaker
+├── mcp/            MCP server — stdio + HTTP/SSE transports
+├── plugins/        Plugin manager, validation, 35 builtin plugins
+│   └── builtin/    shell, github, docker, database, slack, calculator, ...
+├── ai/             Multi-provider AI (Claude, OpenAI, Gemini, Ollama)
+├── bot/            Telegram + Slack bot runtimes
+├── dashboard/      Express web dashboard + REST API
+└── security/       Credential storage, auth
+```
+
+Config storage at `~/.conductor/`:
+
+| Path | Contents |
+|---|---|
+| `config.json` | Non-secret settings |
+| `conductor.db` | SQLite activity log and history |
+| `audit/audit.log` | Tamper-evident audit chain (JSONL) |
+| `keychain/` | AES-256-GCM encrypted credentials |
+| `plugins/` | External plugin `.js` files |
+
+---
+
+## Writing plugins
 
 ```typescript
-import { Plugin, PluginTool } from '@conductor/cli';
+import type { Plugin, PluginTool } from '@useconductor/sdk';
 
-export class MyPlugin implements Plugin {
+class MyPlugin implements Plugin {
   name = 'my-plugin';
-  description = 'My awesome plugin';
+  description = 'Does something useful';
   version = '1.0.0';
 
-  async initialize() {}
-  isConfigured() { return true; }
+  async initialize(): Promise<void> {}
+  isConfigured(): boolean { return true; }
 
   getTools(): PluginTool[] {
-    return [{
-      name: 'my_tool',
-      description: 'Does something awesome',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          input: { type: 'string', description: 'Your input' },
+    return [
+      {
+        name: 'my_tool',
+        description: 'Explain what this does in one sentence',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            query: { type: 'string', description: 'The query to process' },
+          },
+          required: ['query'],
+        },
+        handler: async ({ query }) => {
+          return { result: `Processed: ${query}` };
         },
-        required: ['input'],
-      },
-      handler: async (input: { input: string }) => {
-        return { result: `You said: ${input.input}` };
       },
-    }];
+    ];
   }
 }
+
+export default new MyPlugin();
 ```
 
-## Development
+Place compiled output at `~/.conductor/plugins/my-plugin.js`. Scaffold with tests:
 
 ```bash
-git clone https://github.com/conductor/conductor.git
+conductor plugins create my-plugin
+```
+
+For plugins needing credentials, add a `configSchema` with `secret: true` fields — they get encrypted and stored automatically.
+
+---
+
+## Programmatic use
+
+```typescript
+import { ConductorClient } from '@useconductor/sdk';
+
+// stdio (local)
+const client = new ConductorClient({ transport: 'stdio' });
+await client.connect();
+const result = await client.callText('calc_math', { expression: 'sqrt(144) + 8' });
+console.log(result); // "20"
+await client.disconnect();
+
+// HTTP/SSE (remote)
+const remote = new ConductorClient({
+  transport: 'http',
+  url: 'http://your-conductor-host:3000',
+});
+```
+
+---
+
+## Supported clients
+
+- [Claude Desktop](https://claude.ai/download)
+- [Cursor](https://cursor.com)
+- [Cline (VS Code)](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev)
+- [Windsurf](https://codeium.com/windsurf)
+- [Continue.dev](https://continue.dev)
+- [Zed](https://zed.dev)
+- [Aider](https://aider.chat)
+- [Roo Code](https://roocode.com)
+- VS Code (GitHub Copilot)
+- Any client supporting MCP stdio transport
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/useconductor/conductor
 cd conductor
 npm install
-npm run build
-npm run dev          # Watch mode
-npm test             # Run tests
-npm run test:coverage # With coverage
-npm run lint         # ESLint
-npm run format       # Prettier
-```
-
-## CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `conductor mcp start` | Start MCP server (stdio) |
-| `conductor mcp setup` | Configure for Claude Desktop |
-| `conductor mcp status` | Show MCP status |
-| `conductor plugins list` | List all plugins |
-| `conductor plugins enable <name>` | Enable a plugin |
-| `conductor plugins disable <name>` | Disable a plugin |
-| `conductor ai setup` | Configure AI providers |
-| `conductor ai test` | Test AI provider |
+npm run dev        # Watch mode
+npm test           # Run tests (Vitest)
+npm run typecheck  # Type check
+npm run lint       # ESLint
+```
+
+Requirements: Node >= 20.12, npm >= 9.
+
+---
 
 ## License
 
-Apache-2.0
+Apache 2.0 — see [LICENSE](./LICENSE)

package/dist/cli/commands/audit.d.ts

@@ -0,0 +1,40 @@
+/**
+ * conductor audit — query and verify the tamper-evident audit log.
+ *
+ * Commands:
+ *   conductor audit list   — filter and display log entries
+ *   conductor audit verify — verify SHA-256 chain integrity
+ *   conductor audit tail   — stream the log in real time
+ *   conductor audit export — export entries to JSON or NDJSON
+ *   conductor audit stats  — show summary statistics
+ *   conductor audit rotate — manually rotate the current log file
+ */
+import type { Conductor } from '../../core/conductor.js';
+export declare function auditList(conductor: Conductor, opts: {
+    actor?: string;
+    action?: string;
+    tool?: string;
+    result?: string;
+    since?: string;
+    until?: string;
+    limit?: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function auditVerify(conductor: Conductor, opts: {
+    json?: boolean;
+}): Promise<void>;
+export declare function auditTail(conductor: Conductor, opts: {
+    json?: boolean;
+    lines?: string;
+}): Promise<void>;
+export declare function auditExport(conductor: Conductor, opts: {
+    output?: string;
+    format?: string;
+    since?: string;
+    until?: string;
+}): Promise<void>;
+export declare function auditStats(conductor: Conductor, opts: {
+    json?: boolean;
+}): Promise<void>;
+export declare function auditRotate(conductor: Conductor): Promise<void>;
+//# sourceMappingURL=audit.d.ts.map

package/dist/cli/commands/audit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/audit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAQH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AA8CzD,wBAAsB,SAAS,CAC7B,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE;IACJ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB,GACA,OAAO,CAAC,IAAI,CAAC,CAiCf;AAID,wBAAsB,WAAW,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB/F;AAID,wBAAsB,SAAS,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAwE7G;AAID,wBAAsB,WAAW,CAC/B,SAAS,EAAE,SAAS,EACpB,IAAI,EAAE;IACJ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,GACA,OAAO,CAAC,IAAI,CAAC,CAsBf;AAID,wBAAsB,UAAU,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAkD9F;AAID,wBAAsB,WAAW,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAerE"}