@dobbyai/mcp-external 1.0.0

package/README.md

@@ -0,0 +1,527 @@
+# Dobby MCP Server
+
+> Connect to Dobby AI Platform from Claude Desktop, Cursor, Windsurf, VS Code, and any MCP-compatible client.
+
+## 🚀 Quick Start
+
+### Option 1: Interactive Setup (Recommended)
+
+```bash
+npx @dobbyai/mcp-external --setup
+```
+
+This will guide you through connecting Dobby to your preferred AI tools.
+
+### Option 2: Manual Setup
+
+1. Get your API credentials from [Dobby Dashboard](https://app.dobby.ai/settings/api)
+2. Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "dobby": {
+      "command": "npx",
+      "args": ["-y", "@dobbyai/mcp-external"],
+      "env": {
+        "DOBBY_API_URL": "https://app.dobby.ai",
+        "DOBBY_API_KEY": "your-api-key",
+        "DOBBY_TENANT_ID": "your-tenant-id"
+      }
+    }
+  }
+}
+```
+
+## 📱 Supported Clients
+
+| Client | Status | Setup Command |
+|--------|--------|---------------|
+| Claude Desktop | ✅ Full Support | `npx @dobbyai/mcp-external --setup` |
+| Cursor | ✅ Full Support | `npx @dobbyai/mcp-external --setup` |
+| Windsurf | ✅ Full Support | `npx @dobbyai/mcp-external --setup` |
+| VS Code (Cline) | ✅ Full Support | Manual config |
+| VS Code (Continue) | ✅ Full Support | Manual config |
+| Any MCP Client | ✅ STDIO Mode | Manual config |
+
+---
+
+## 🔧 Available Tools (12 Tools)
+
+### Task Management (6 tools)
+
+| Tool | Description | Example |
+|------|-------------|---------|
+| `create_task` | Create a new task for AI agents | `create_task(title: "Add dark mode", priority: "high")` |
+| `list_tasks` | List tasks with filters | `list_tasks(status: "pending", limit: 10)` |
+| `get_task` | Get detailed task information | `get_task(task_id: "task-abc123")` |
+| `update_task` | Update task status or priority | `update_task(task_id: "...", status: "in_progress")` |
+| `get_task_timeline` | Get activity history for a task | `get_task_timeline(task_id: "...")` |
+| `cancel_task` | Cancel a running task | `cancel_task(task_id: "...")` |
+
+### Conversation (2 tools)
+
+| Tool | Description | Example |
+|------|-------------|---------|
+| `get_messages` | Get conversation for a task | `get_messages(task_id: "...", limit: 20)` |
+| `send_message` | Send a message to task conversation | `send_message(task_id: "...", content: "Please add tests")` |
+
+### Approvals - Human-in-the-Loop (4 tools)
+
+| Tool | Description | Example |
+|------|-------------|---------|
+| `get_pending_approvals` | List approvals waiting for you | `get_pending_approvals()` |
+| `approve_task` | Approve a pending request (auto-merges PR) | `approve_task(approval_id: "...", note: "LGTM")` |
+| `reject_task` | Reject with feedback (agent retries automatically) | `reject_task(approval_id: "...", reason: "Need tests")` |
+| `request_changes` | Request specific modifications | `request_changes(approval_id: "...", changes: "...")` |
+
+---
+
+## 🔄 Approval Flow
+
+The Dobby MCP Server supports a complete Human-in-the-Loop workflow:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    APPROVAL WORKFLOW                             │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  1. Agent completes work → Creates PR → Requests approval        │
+│                                                                  │
+│  2. User receives notification via get_pending_approvals         │
+│                                                                  │
+│  3. User reviews and decides:                                    │
+│                                                                  │
+│     ┌─────────────────┐     ┌─────────────────┐                 │
+│     │  approve_task   │     │   reject_task   │                 │
+│     │                 │     │                 │                 │
+│     │  ✅ Auto-merge  │     │  🔁 Auto-retry  │                 │
+│     │     PR          │     │  with feedback  │                 │
+│     └────────┬────────┘     └────────┬────────┘                 │
+│              │                       │                           │
+│              ▼                       ▼                           │
+│     ┌─────────────────┐     ┌─────────────────┐                 │
+│     │ Task Completed  │     │ Agent Addresses │                 │
+│     │ 🎉              │     │ Feedback & ...  │──► Back to 1    │
+│     └─────────────────┘     └─────────────────┘                 │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### Approve Flow
+1. User calls `approve_task(approval_id, note?)`
+2. Agent automatically merges the PR
+3. Task status changes to `completed`
+4. User gets confirmation via `get_task_timeline`
+
+### Reject Flow (with automatic retry)
+1. User calls `reject_task(approval_id, reason)`
+2. Agent receives feedback
+3. Agent re-analyzes and addresses the feedback
+4. Agent creates new implementation
+5. New approval is requested
+6. User reviews again
+
+---
+
+## 📊 Task Timeline
+
+Track every action on a task with `get_task_timeline`:
+
+```
+📊 Timeline for Task task-abc123
+
+🆕 task created (User)
+   2/2/2026, 10:00:00 AM
+
+📋 plan created (DevCoordinator)
+   2/2/2026, 10:00:05 AM
+
+▶️ subtask started (dobby-frontend-agent)
+   2/2/2026, 10:00:10 AM
+
+🎨 frontend code generated (FrontendDeveloper)
+   2/2/2026, 10:01:30 AM
+
+📝 pr created (FrontendDeveloper)
+   PR #42
+   2/2/2026, 10:01:45 AM
+
+⏳ approval requested (DevCoordinator)
+   2/2/2026, 10:01:50 AM
+
+✅ approval approved (User)
+   2/2/2026, 10:05:00 AM
+
+🚀 agent continuation triggered (system)
+   2/2/2026, 10:05:01 AM
+
+🔀 pr merged (DevCoordinator)
+   PR #42
+   2/2/2026, 10:05:10 AM
+
+🎉 continuation after approval completed (DevCoordinator)
+   2/2/2026, 10:05:15 AM
+```
+
+---
+
+## 📚 Resources
+
+Access data directly via MCP resources:
+
+```
+tasks://list              # All tasks
+tasks://pending           # Pending tasks
+tasks://in-progress       # In-progress tasks
+tasks://completed         # Completed tasks
+tasks://{task_id}         # Specific task details
+tasks://{task_id}/messages # Task conversation
+approvals://pending       # Pending approvals
+```
+
+---
+
+## 💬 Prompts (Slash Commands)
+
+| Command | Description |
+|---------|-------------|
+| `/create-feature` | Guided feature creation |
+| `/fix-bug` | Create bug fix task |
+| `/check-approvals` | Review pending approvals |
+| `/task-status` | Get task status summary |
+| `/review-pr` | Review a task's PR |
+
+---
+
+## 🖥️ Client-Specific Setup
+
+### Claude Desktop
+
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+**Linux:** `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "dobby": {
+      "command": "npx",
+      "args": ["-y", "@dobbyai/mcp-external"],
+      "env": {
+        "DOBBY_API_URL": "https://app.dobby.ai",
+        "DOBBY_API_KEY": "dk_your_api_key",
+        "DOBBY_TENANT_ID": "your-tenant-id"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Settings → MCP → Add Server:
+
+```json
+{
+  "dobby": {
+    "command": "npx",
+    "args": ["-y", "@dobbyai/mcp-external"],
+    "env": {
+      "DOBBY_API_URL": "https://app.dobby.ai",
+      "DOBBY_API_KEY": "dk_your_api_key",
+      "DOBBY_TENANT_ID": "your-tenant-id"
+    }
+  }
+}
+```
+
+### Windsurf
+
+File: `~/.codeium/windsurf/mcp_config.json`
+
+```json
+{
+  "mcpServers": {
+    "dobby": {
+      "command": "npx",
+      "args": ["-y", "@dobbyai/mcp-external"],
+      "env": {
+        "DOBBY_API_URL": "https://app.dobby.ai",
+        "DOBBY_API_KEY": "dk_your_api_key",
+        "DOBBY_TENANT_ID": "your-tenant-id"
+      }
+    }
+  }
+}
+```
+
+### VS Code with Cline
+
+Command Palette → "Cline: Open MCP Settings" → Add:
+
+```json
+{
+  "mcpServers": {
+    "dobby": {
+      "command": "npx",
+      "args": ["-y", "@dobbyai/mcp-external"],
+      "env": {
+        "DOBBY_API_URL": "https://app.dobby.ai",
+        "DOBBY_API_KEY": "dk_your_api_key",
+        "DOBBY_TENANT_ID": "your-tenant-id"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 🔐 Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `DOBBY_API_URL` | Yes | Dobby API URL (default: https://app.dobby.ai) |
+| `DOBBY_API_KEY` | Yes | Your Dobby API key |
+| `DOBBY_TENANT_ID` | Yes | Your workspace/tenant ID |
+| `DOBBY_USER_ID` | No | User ID for messages |
+| `DOBBY_USER_NAME` | No | Display name for messages |
+
+---
+
+## 📖 Usage Examples
+
+### Create a Feature Task
+
+```
+You: Create a task to add dark mode to the settings page
+
+Claude: [Uses create_task tool]
+        ✅ Task created: task-abc123
+        Title: Add dark mode to settings page
+        Priority: medium
+
+        The AI agents will start working on it soon.
+```
+
+### Check Approvals
+
+```
+You: Check my pending approvals
+
+Claude: [Uses get_pending_approvals]
+
+        🔔 You have 2 pending approvals:
+
+        1. 📝 PR CREATE - Add user authentication
+           ID: approval-xyz789
+           Waiting: 5 minutes
+
+        2. 🔀 PR MERGE - Fix login bug
+           ID: approval-abc456
+           Waiting: 1 hour
+
+        Which one would you like to review?
+```
+
+### Approve a PR (Auto-Merge)
+
+```
+You: Approve approval-xyz789 with note "looks good"
+
+Claude: [Uses approve_task]
+        ✅ **Approved!** approval-xyz789
+
+        Note: "looks good"
+
+        🔀 The agent is now merging the PR automatically.
+        Use `get_task_timeline` to track progress.
+```
+
+### Reject with Feedback (Auto-Retry)
+
+```
+You: Reject approval-abc456 because it needs unit tests
+
+Claude: [Uses reject_task]
+        ❌ **Rejected!** approval-abc456
+
+        💬 Feedback: "needs unit tests"
+
+        🔁 The agent is now retrying and will address your feedback.
+        Use `get_task_timeline` to track progress.
+```
+
+### Cancel Running Task
+
+```
+You: Cancel task-def789, it's taking too long
+
+Claude: [Uses cancel_task]
+        🛑 Task task-def789 execution cancelled successfully.
+
+        The task status has been reverted to pending.
+```
+
+### View Task Timeline
+
+```
+You: Show me the timeline for task-abc123
+
+Claude: [Uses get_task_timeline]
+
+        📊 Timeline for Task task-abc123
+
+        🆕 **task created** (User)
+           2/2/2026, 10:00:00 AM
+
+        📋 **plan created** (DevCoordinator)
+           2/2/2026, 10:00:05 AM
+
+        🎨 **frontend code generated** (FrontendDeveloper)
+           2/2/2026, 10:01:30 AM
+
+        📝 **pr created** PR #42
+           2/2/2026, 10:01:45 AM
+
+        ✅ **approval approved**
+           2/2/2026, 10:05:00 AM
+
+        🔀 **pr merged** PR #42
+           2/2/2026, 10:05:10 AM
+```
+
+---
+
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     MCP Client                                   │
+│         (Claude Desktop, Cursor, Windsurf, etc.)                │
+└──────────────────────────┬──────────────────────────────────────┘
+                           │ MCP Protocol (STDIO)
+                           ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                   Dobby MCP Server                               │
+│  ┌─────────────────────────────────────────────────────────────┐│
+│  │ Tools           │ Resources       │ Prompts                 ││
+│  │ - create_task   │ - tasks://      │ - /create-feature       ││
+│  │ - list_tasks    │ - approvals://  │ - /fix-bug              ││
+│  │ - get_task      │                 │ - /check-approvals      ││
+│  │ - update_task   │                 │ - /task-status          ││
+│  │ - get_timeline  │                 │ - /review-pr            ││
+│  │ - cancel_task   │                 │                         ││
+│  │ - get_messages  │                 │                         ││
+│  │ - send_message  │                 │                         ││
+│  │ - get_pending   │                 │                         ││
+│  │ - approve_task  │                 │                         ││
+│  │ - reject_task   │                 │                         ││
+│  │ - req_changes   │                 │                         ││
+│  └─────────────────────────────────────────────────────────────┘│
+│                              │                                   │
+│                    DobbyClient (API)                             │
+└──────────────────────────────┬──────────────────────────────────┘
+                               │ HTTPS
+                               ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Dobby API (Next.js)                          │
+│  /api/dobby/tasks        - Task CRUD                             │
+│  /api/dobby/tasks/[id]/execute - Execute/Cancel task            │
+│  /api/dobby/tasks/[id]/conversation - Messages                  │
+│  /api/dobby/approvals    - Approval workflow                    │
+└──────────────────────────────┬──────────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                  Dobby Python API (FastAPI)                     │
+│  POST /api/v1/tasks/{id}/execute   - Start agent execution      │
+│  POST /api/v1/tasks/{id}/cancel    - Cancel execution           │
+│  GET  /api/v1/runs/{id}/status     - Get run status             │
+└──────────────────────────────┬──────────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    AI Agents (Dobby)                            │
+│  ┌──────────────┐                                               │
+│  │ Chief Agent  │ ─► Analyzes tasks, routes to coordinators     │
+│  └──────┬───────┘                                               │
+│         │                                                        │
+│  ┌──────▼───────┐                                               │
+│  │ DevCoordinator│ ─► Manages development workflow              │
+│  └──────┬───────┘                                               │
+│         │                                                        │
+│  ┌──────▼───────────────────────────────────────┐              │
+│  │ Workers                                       │              │
+│  │ - FrontendDeveloper (React, TypeScript)      │              │
+│  │ - BackendDeveloper (Python, FastAPI)         │              │
+│  │ - TestWriter (Unit tests)                    │              │
+│  │ - CodeReviewer (PR review)                   │              │
+│  │ - DevOpsWorker (CI/CD, PR merge)             │              │
+│  └───────────────────────────────────────────────┘              │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 🛠️ Development
+
+```bash
+# Clone the repo
+git clone https://github.com/gil-dataopsvalley/repo-dobby.git
+cd repo-dobby/mcp/external
+
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+
+# Build
+npm run build
+
+# Run tests
+npm test
+```
+
+### Local Testing
+
+```bash
+# Set environment variables
+export DOBBY_API_URL=http://localhost:3000
+export DOBBY_API_KEY=dev-key
+export DOBBY_TENANT_ID=your-tenant-id
+
+# Run the server
+npm run dev
+```
+
+---
+
+## 📝 Changelog
+
+### v1.2.0 (2026-02-02)
+- **NEW:** `get_task_timeline` tool - View all activity on a task
+- **NEW:** `cancel_task` tool - Stop running task executions
+- **IMPROVED:** `approve_task` now triggers automatic PR merge
+- **IMPROVED:** `reject_task` now triggers automatic agent retry with feedback
+- **IMPROVED:** Better response messages with action hints
+
+### v1.1.0 (2026-01-31)
+- Added VS Code support (Cline, Continue)
+- Added Windsurf connector
+- Fixed approval endpoint compatibility
+
+### v1.0.0 (2026-01-29)
+- Initial release
+- 10 tools for task management, messaging, and approvals
+- 7 resources for direct data access
+- 5 slash command prompts
+- Support for Claude Desktop and Cursor
+
+---
+
+## 📄 License
+
+MIT © Dobby AI Platform

package/dist/connectors/claude-desktop.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Claude Desktop Connector
+ *
+ * Generates and installs configuration for Claude Desktop.
+ */
+export interface ClaudeDesktopConfig {
+    mcpServers: {
+        dobby: {
+            command: string;
+            args: string[];
+            env: {
+                DOBBY_API_URL: string;
+                DOBBY_API_KEY: string;
+                DOBBY_TENANT_ID: string;
+            };
+        };
+    };
+}
+export declare function generateClaudeDesktopConfig(credentials: {
+    apiUrl: string;
+    apiKey: string;
+    tenantId: string;
+}): ClaudeDesktopConfig;
+export declare function installClaudeDesktopConfig(newConfig: ClaudeDesktopConfig): Promise<boolean>;
+export declare function readClaudeDesktopConfig(): any | null;
+//# sourceMappingURL=claude-desktop.d.ts.map

package/dist/connectors/claude-desktop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claude-desktop.d.ts","sourceRoot":"","sources":["../../src/connectors/claude-desktop.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA0CH,MAAM,WAAW,mBAAmB;IAClC,UAAU,EAAE;QACV,KAAK,EAAE;YACL,OAAO,EAAE,MAAM,CAAC;YAChB,IAAI,EAAE,MAAM,EAAE,CAAC;YACf,GAAG,EAAE;gBACH,aAAa,EAAE,MAAM,CAAC;gBACtB,aAAa,EAAE,MAAM,CAAC;gBACtB,eAAe,EAAE,MAAM,CAAC;aACzB,CAAC;SACH,CAAC;KACH,CAAC;CACH;AAED,wBAAgB,2BAA2B,CAAC,WAAW,EAAE;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,mBAAmB,CActB;AAMD,wBAAsB,0BAA0B,CAC9C,SAAS,EAAE,mBAAmB,GAC7B,OAAO,CAAC,OAAO,CAAC,CAkClB;AAMD,wBAAgB,uBAAuB,IAAI,GAAG,GAAG,IAAI,CAYpD"}

package/dist/connectors/claude-desktop.js

@@ -0,0 +1,133 @@
+/**
+ * Claude Desktop Connector
+ *
+ * Generates and installs configuration for Claude Desktop.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+// ============================================
+// Config Paths
+// ============================================
+function getConfigPath() {
+    const platform = os.platform();
+    if (platform === 'darwin') {
+        return path.join(os.homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+    }
+    else if (platform === 'win32') {
+        return path.join(process.env.APPDATA || '', 'Claude', 'claude_desktop_config.json');
+    }
+    else {
+        // Linux
+        return path.join(os.homedir(), '.config', 'Claude', 'claude_desktop_config.json');
+    }
+}
+export function generateClaudeDesktopConfig(credentials) {
+    return {
+        mcpServers: {
+            dobby: {
+                command: 'npx',
+                args: ['-y', '@dobbyai/mcp-external'],
+                env: {
+                    DOBBY_API_URL: credentials.apiUrl,
+                    DOBBY_API_KEY: credentials.apiKey,
+                    DOBBY_TENANT_ID: credentials.tenantId,
+                },
+            },
+        },
+    };
+}
+// ============================================
+// Config Installation
+// ============================================
+export async function installClaudeDesktopConfig(newConfig) {
+    try {
+        const configPath = getConfigPath();
+        const configDir = path.dirname(configPath);
+        // Create directory if it doesn't exist
+        if (!fs.existsSync(configDir)) {
+            fs.mkdirSync(configDir, { recursive: true });
+        }
+        // Read existing config or create empty
+        let existingConfig = {};
+        if (fs.existsSync(configPath)) {
+            const content = fs.readFileSync(configPath, 'utf-8');
+            existingConfig = JSON.parse(content);
+        }
+        // Merge configs
+        const mergedConfig = {
+            ...existingConfig,
+            mcpServers: {
+                ...existingConfig.mcpServers,
+                ...newConfig.mcpServers,
+            },
+        };
+        // Write config
+        fs.writeFileSync(configPath, JSON.stringify(mergedConfig, null, 2));
+        return true;
+    }
+    catch (error) {
+        console.error('Failed to install Claude Desktop config:', error);
+        return false;
+    }
+}
+// ============================================
+// Config Reading
+// ============================================
+export function readClaudeDesktopConfig() {
+    try {
+        const configPath = getConfigPath();
+        if (!fs.existsSync(configPath)) {
+            return null;
+        }
+        const content = fs.readFileSync(configPath, 'utf-8');
+        return JSON.parse(content);
+    }
+    catch (error) {
+        return null;
+    }
+}
+// ============================================
+// CLI Entry Point
+// ============================================
+// CLI Entry - ESM compatible
+const isMain = process.argv[1]?.includes('claude-desktop');
+if (isMain) {
+    const args = process.argv.slice(2);
+    if (args.includes('--setup')) {
+        const apiUrl = process.env.DOBBY_API_URL || 'https://app.dobby.ai';
+        const apiKey = process.env.DOBBY_API_KEY;
+        const tenantId = process.env.DOBBY_TENANT_ID;
+        if (!apiKey || !tenantId) {
+            console.error('Error: DOBBY_API_KEY and DOBBY_TENANT_ID are required');
+            process.exit(1);
+        }
+        const config = generateClaudeDesktopConfig({ apiUrl, apiKey, tenantId });
+        const success = await installClaudeDesktopConfig(config);
+        if (success) {
+            console.log('✅ Claude Desktop configured for Dobby');
+            console.log('   Restart Claude Desktop to apply changes.');
+        }
+        else {
+            console.error('❌ Failed to configure Claude Desktop');
+            console.log('   Add this config manually:');
+            console.log(JSON.stringify(config, null, 2));
+        }
+    }
+    else if (args.includes('--show')) {
+        const config = generateClaudeDesktopConfig({
+            apiUrl: process.env.DOBBY_API_URL || 'https://app.dobby.ai',
+            apiKey: process.env.DOBBY_API_KEY || '<YOUR_API_KEY>',
+            tenantId: process.env.DOBBY_TENANT_ID || '<YOUR_TENANT_ID>',
+        });
+        console.log(JSON.stringify(config, null, 2));
+    }
+    else {
+        console.log('Claude Desktop Connector for Dobby');
+        console.log('');
+        console.log('Usage:');
+        console.log('  --setup   Install config (requires DOBBY_API_KEY, DOBBY_TENANT_ID)');
+        console.log('  --show    Show config template');
+    }
+}
+//# sourceMappingURL=claude-desktop.js.map