@useconductor/conductor 1.0.0

package/docs/getting-started.md

@@ -0,0 +1,100 @@
+# Getting Started
+
+Install Conductor and connect your first AI agent in under 60 seconds.
+
+## Prerequisites
+
+- **Node.js 18+** (20+ recommended)
+- **npm, pnpm, or yarn**
+
+## Install
+
+```bash
+npm install -g @conductor/cli
+```
+
+## Quick Start
+
+### Step 1: Start the MCP Server
+
+```bash
+conductor mcp start
+```
+
+That's it. The server starts with 20+ tools that work without any configuration:
+- File system (read, write, list, search)
+- Shell (safe commands only)
+- Git (status, diff, log)
+- Calculator (math, conversions, dates)
+- Weather, crypto, network tools, and more
+
+### Step 2: Connect Your AI Agent
+
+**Claude Desktop:**
+```bash
+conductor mcp setup
+```
+Then restart Claude Desktop.
+
+**Claude Code:**
+Add to your `~/.claude/settings.json`:
+```json
+{
+  "mcpServers": {
+    "conductor": {
+      "command": "conductor",
+      "args": ["mcp", "start"]
+    }
+  }
+}
+```
+
+**Cursor:**
+Settings → MCP → Add Server → Command: `conductor`, Args: `mcp start`
+
+**Cline:**
+Settings → MCP Servers → Add → Command: `conductor`, Args: `mcp start`
+
+### Step 3: Test It
+
+Ask your AI agent:
+- "What files are in the current directory?"
+- "What's the weather in Tokyo?"
+- "Calculate sqrt(144) + 2^8"
+- "Show me the git status"
+
+### Step 4: Enable More Plugins
+
+```bash
+# Enable GitHub integration
+conductor plugins enable github
+conductor config set github.token ghp_your_token
+
+# Enable Docker integration
+conductor plugins enable docker
+
+# Enable database integration
+conductor plugins enable database
+conductor config set database.postgres_url postgresql://user:pass@host:5432/db
+```
+
+## Verify Everything Works
+
+```bash
+# Run the doctor command
+conductor doctor
+
+# Check health
+conductor health
+
+# List all available tools
+conductor plugins list
+```
+
+## Next Steps
+
+- [Configuration Guide](./configuration.md) — all settings explained
+- [Plugin Development](./plugins.md) — build your own plugins
+- [Webhook System](./webhooks.md) — event-driven integrations
+- [Security](./security.md) — audit logs, RBAC, encryption
+- [API Reference](./api.md) — every tool documented

package/docs/plugins.md

@@ -0,0 +1,306 @@
+# Conductor Plugin Reference
+
+All built-in plugins live in `src/plugins/builtin/`. Each plugin implements the `Plugin` interface.
+
+## 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>;
+}
+```
+
+---
+
+## Utility Plugins (no credentials required)
+
+### calculator
+Math expression evaluator, unit converter, date calculator.
+
+**Tools**: `calculate`, `convert_unit`, `date_calc`
+
+### colors
+Color format conversion, contrast checking, palette generation.
+
+**Tools**: `colors_convert`, `colors_contrast`, `colors_palette`
+
+### hash
+Hashing, base64 encoding/decoding.
+
+**Tools**: `hash_text`, `base64_encode`, `base64_decode`
+
+### text-tools
+JSON formatter, word counter, text transformers.
+
+**Tools**: `format_json`, `word_count`, `text_transform`
+
+### timezone
+Timezone conversion and lookup.
+
+**Tools**: `timezone_convert`, `timezone_list`
+
+### crypto
+Cryptocurrency prices and search.
+
+**Tools**: `crypto_price`, `crypto_search`
+
+### network
+DNS lookup, IP geolocation, reverse DNS.
+
+**Tools**: `dns_lookup`, `ip_info`, `reverse_dns`
+
+### url-tools
+URL expansion, QR code generation, URL parsing.
+
+**Tools**: `expand_url`, `url_parse`
+
+### fun
+Random jokes and facts.
+
+**Tools**: `random_joke`, `random_fact`
+
+### notes
+Local markdown note management.
+
+**Tools**: `notes_create`, `notes_list`, `notes_read`, `notes_update`, `notes_delete`, `notes_search`
+
+### cron
+Cron expression parser and scheduler.
+
+**Tools**: `cron_parse`, `cron_next`
+
+### system
+System stats, process management, clipboard.
+
+**Tools**: `system_info`, `list_processes`, `kill_process`, `clipboard_read`, `clipboard_write`
+
+### translate
+Text translation using LibreTranslate.
+
+**Tools**: `translate_text`, `detect_language`
+
+---
+
+## Google Plugins
+
+All Google plugins require Google OAuth. Connect via: `conductor auth google`
+
+**Keychain**: `google / access_token`, `google / refresh_token`
+
+### gmail
+Read, send, archive emails and manage labels.
+
+**Tools**: `gmail_list`, `gmail_read`, `gmail_send`, `gmail_reply`, `gmail_archive`, `gmail_labels`, `gmail_search`
+
+**getContext()**: Returns unread message count.
+
+### gcal
+Create, read, update, delete calendar events.
+
+**Tools**: `gcal_list_calendars`, `gcal_list_events`, `gcal_create_event`, `gcal_update_event`, `gcal_delete_event`, `gcal_find_free_time`
+
+**getContext()**: Returns today's event summaries.
+
+### gdrive
+Browse, read, create, upload files in Google Drive.
+
+**Tools**: `gdrive_list`, `gdrive_read`, `gdrive_create`, `gdrive_upload`, `gdrive_search`
+
+---
+
+## Developer Plugins
+
+### github
+GitHub repositories, issues, stars, user info.
+
+**Required credential**: `github / token` (PAT with `repo` and `workflow` scopes)
+
+**Tools**: `github_user`, `github_repo`, `github_repos`, `github_search_repos`, `github_issues`, `github_create_issue`, `github_close_issue`, `github_prs`, `github_create_pr`, `github_merge_pr`, `github_stars`
+
+### github-actions
+Trigger and monitor GitHub Actions workflows.
+
+**Required credential**: `github / token`
+
+**Tools**: `github_actions_list`, `github_actions_run`, `github_actions_status`
+
+### vercel
+Deploy and manage Vercel projects and deployments.
+
+**Required credential**: `vercel / token`
+
+**Tools**: `vercel_list_projects`, `vercel_deployments`, `vercel_deploy`, `vercel_logs`
+
+### n8n
+Trigger and manage n8n automation workflows.
+
+**Required credentials**: `n8n / api_key`, `n8n / base_url`
+
+**Tools**: `n8n_list_workflows`, `n8n_trigger_workflow`, `n8n_get_execution`
+
+---
+
+## Service Plugins
+
+### notion
+Read, search, and create Notion pages and databases.
+
+**Required credential**: `notion / api_key` (Internal Integration Token)
+
+**Setup**: Visit https://www.notion.so/my-integrations, create integration, copy token.
+
+**Tools**: `notion_search`, `notion_get_page`, `notion_create_page`, `notion_query_database`, `notion_append_block`
+
+### spotify
+Control Spotify playback and search music.
+
+**Required credentials**: `spotify / client_id`, `spotify / client_secret`, `spotify / access_token`
+
+**Tools**: `spotify_search`, `spotify_play`, `spotify_pause`, `spotify_next`, `spotify_current`, `spotify_queue`
+
+### weather
+Current weather and forecasts.
+
+**Required credential**: `weather / api_key` (OpenWeatherMap API key)
+
+**Tools**: `weather_current`, `weather_forecast`
+
+### todoist
+Manage Todoist tasks, projects, and comments.
+
+**Required credential**: `todoist / api_token`
+
+**Setup**: Go to https://app.todoist.com/app/settings/integrations/developer, copy API token.
+
+**Tools**:
+- `todoist_list_tasks` — List tasks with optional filters
+- `todoist_create_task` — Create a task with natural-language due date
+- `todoist_complete_task` — Mark a task as complete
+- `todoist_update_task` — Update task content, due date, priority
+- `todoist_delete_task` — Permanently delete a task (requiresApproval)
+- `todoist_get_projects` — List all projects
+- `todoist_search_tasks` — Search with Todoist filter syntax
+- `todoist_add_comment` — Add a comment to a task
+
+**getContext()**: Returns overdue and today's task counts.
+
+### x (Twitter)
+Post tweets and manage X/Twitter account.
+
+**Required credential**: `x / api_key`
+
+**Tools**: `x_post`, `x_read_timeline`, `x_search`
+
+---
+
+## Messaging Plugins
+
+### slack
+Send messages and manage Slack channels and threads.
+
+**Required credential**: `slack / bot_token` (Bot User OAuth Token)
+
+**Tools**: `slack_send_message`, `slack_list_channels`, `slack_read_channel`, `slack_reply_thread`
+
+---
+
+## Smart Home
+
+### homekit
+Control HomeKit accessories via the homebridge REST API.
+
+**Required credentials**: `homekit / base_url`, `homekit / username`, `homekit / password`
+
+**Tools**: `homekit_list`, `homekit_get`, `homekit_set`
+
+---
+
+## Infrastructure Plugins
+
+### docker
+Docker container, image, volume, and network management.
+
+**No credentials required** — uses the local Docker CLI.
+
+**Tools**:
+- `docker_containers` — List containers (use `--all` for stopped)
+- `docker_container_logs` — Get container logs
+- `docker_container_action` — start/stop/restart/pause/kill/remove
+- `docker_images` — List images
+- `docker_pull` — Pull an image
+- `docker_run` — Run a container (requiresApproval)
+- `docker_volumes` — List volumes
+- `docker_networks` — List networks
+- `docker_stats` — Resource usage stats
+
+### database
+Query PostgreSQL, MySQL, MongoDB, and Redis databases.
+
+**Required credentials** (stored encrypted in keychain):
+- `database / postgres_url` — `postgresql://user:pass@host:5432/db`
+- `database / mysql_url` — `mysql://user:pass@host:3306/db`
+- `database / mongo_url` — `mongodb://user:pass@host:27017/db`
+- `database / redis_url` — `redis://:pass@host:6379/0`
+
+**Tools**:
+- `db_postgres_query` — Read-only SELECT query
+- `db_mysql_query` — Read-only SELECT query
+- `db_mongo_find` — Query a collection
+- `db_redis_command` — Execute a Redis command
+- `db_list_connections` — List configured connections
+
+### shell
+Safe shell command execution with approval workflow and path validation.
+
+**No credentials required.**
+
+**Tools**:
+- `shell_run` — Run a whitelisted command (requiresApproval)
+- `shell_read_file` — Read file contents
+- `shell_write_file` — Write content to file (requiresApproval)
+- `shell_list_dir` — List directory contents
+- `shell_search_files` — Search files by glob pattern
+- `shell_search_content` — Search file contents with grep
+
+**Safety features:**
+- Whitelist-based command filtering (no arbitrary commands)
+- Path traversal protection
+- Dangerous pattern detection (fork bombs, rm -rf /, etc.)
+- 10MB output limit, 120s timeout
+
+---
+
+## AI
+
+### lumen
+Agentic AI coding assistant. Writes code, runs shell commands, manages git.
+
+**Required**: Ollama running locally with the `lumen` model.
+
+**Tools** (all with `requiresApproval: true` for shell-executing tools):
+- `lumen_ask` — Ask Lumen to complete any coding task
+- `lumen_shell` — Run a shell task
+- `lumen_write_file` — Generate and write a file
+- `lumen_fix_bug` — Investigate and fix a bug
+- `lumen_git_commit` — Stage and commit changes
+- `lumen_git_push` — Push to origin
+- `lumen_git_status` — Show git status
+- `lumen_ping` — Check if Lumen is available
+
+---
+
+## System Plugins
+
+### memory
+Long-term memory storage and recall using SQLite.
+
+**Tools**: `memory_recall`, `memory_store`, `memory_forget`, `memory_list`, `search_past_conversations`
+
+Note: `search_past_conversations` is scoped to the current user's conversation history.

package/docs-site/.vitepress/config.ts

@@ -0,0 +1,59 @@
+import { defineConfig } from 'vitepress'
+
+export default defineConfig({
+  title: 'Conductor',
+  description: 'The AI Tool Hub — One MCP server. 100+ tools. Every AI agent.',
+  themeConfig: {
+    logo: '/logo.svg',
+    nav: [
+      { text: 'Docs', link: '/getting-started' },
+      { text: 'API Reference', link: '/api' },
+      { text: 'Plugins', link: '/plugins' },
+      { text: 'SDKs', link: '/sdks' },
+      { text: 'Changelog', link: '/changelog' },
+    ],
+    sidebar: [
+      {
+        text: 'Getting Started',
+        items: [
+          { text: 'Quick Start', link: '/getting-started' },
+          { text: 'Configuration', link: '/configuration' },
+          { text: 'CLI Reference', link: '/cli' },
+        ],
+      },
+      {
+        text: 'Core',
+        items: [
+          { text: 'MCP Server', link: '/mcp' },
+          { text: 'Plugin Development', link: '/plugins' },
+          { text: 'Webhook System', link: '/webhooks' },
+          { text: 'Security & Audit', link: '/security' },
+        ],
+      },
+      {
+        text: 'SDKs',
+        items: [
+          { text: 'Overview', link: '/sdks' },
+          { text: 'TypeScript', link: '/sdks/typescript' },
+          { text: 'Python', link: '/sdks/python' },
+          { text: 'Go', link: '/sdks/go' },
+        ],
+      },
+      {
+        text: 'Reference',
+        items: [
+          { text: 'API Reference', link: '/api' },
+          { text: 'Changelog', link: '/changelog' },
+          { text: 'Contributing', link: '/contributing' },
+        ],
+      },
+    ],
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/conductor/conductor' },
+    ],
+    footer: {
+      message: 'Released under the Apache 2.0 License.',
+      copyright: 'Copyright © 2026 Conductor Team',
+    },
+  },
+})

package/docs-site/README.md

@@ -0,0 +1,12 @@
+# docs-site
+
+VitePress documentation site for Conductor.
+
+## Contents
+
+- `index.md` - Site landing page
+- `.vitepress/` - VitePress configuration
+
+## Architecture
+
+This is the source for the rendered documentation website, built with VitePress. The site provides a browsable, searchable version of the markdown docs in `docs/`. Run the dev server with the VitePress CLI to preview changes locally.

package/docs-site/index.md

@@ -0,0 +1,30 @@
+---
+layout: home
+hero:
+  name: "Conductor"
+  text: "The AI Tool Hub"
+  tagline: One MCP server. 100+ tools. Every AI agent.
+  actions:
+    - theme: brand
+      text: Get Started
+      link: /getting-started
+    - theme: alt
+      text: API Reference
+      link: /api
+    - theme: alt
+      text: GitHub
+      link: https://github.com/conductor/conductor
+features:
+  - icon: 🔌
+    title: One Connection
+    details: Add one line to your AI agent's config and get instant access to 100+ tools.
+  - icon: 🛡️
+    title: Stripe-Grade Reliability
+    details: Circuit breakers, automatic retries, audit logging, and health checks built in.
+  - icon: 🧩
+    title: Plugin SDK
+    details: Build custom tools in minutes with TypeScript, Zod validation, and testing utilities.
+  - icon: 🌐
+    title: 8 SDKs
+    details: TypeScript, Python, Go, Rust, Java, Ruby, PHP, C# — integrate from any language.
+---

package/eslint.config.js

@@ -0,0 +1,29 @@
+import tseslint from '@typescript-eslint/eslint-plugin';
+import tsparser from '@typescript-eslint/parser';
+import prettierConfig from 'eslint-config-prettier';
+
+export default [
+  {
+    ignores: ['dist/', 'node_modules/', 'coverage/', 'docs-site/', 'sdks/'],
+  },
+  {
+    files: ['src/**/*.ts'],
+    languageOptions: {
+      parser: tsparser,
+      parserOptions: {
+        ecmaVersion: 2022,
+        sourceType: 'module',
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tseslint,
+    },
+    rules: {
+      ...tseslint.configs.recommended.rules,
+      '@typescript-eslint/no-explicit-any': 'warn',
+      '@typescript-eslint/no-unused-vars': ['error', { argsIgnorePattern: '^_', varsIgnorePattern: '^_' }],
+      'no-console': 'off',
+    },
+  },
+  prettierConfig,
+];