@chandshantanu/agentbuilder-mcp-server 0.2.0

package/README.md

@@ -0,0 +1,978 @@
+# AgentBuilder MCP Server
+
+**Version**: 0.1.0
+**License**: MIT
+
+A Model Context Protocol (MCP) server that enables Claude Code to create and manage workflows in the AgentBuilder platform with **production-ready OAuth 2.0 workspace authentication**.
+
+---
+
+## 🎯 Features
+
+This MCP server provides Claude Code with the following capabilities:
+
+### **🆕 Agent Creation & Management (NEW!)**
+- ✅ **Create Agents** - Create new agents from scratch with complete configuration
+- ✅ **Set Wizard Configuration** - Define user onboarding wizards with OAuth, credentials, and platform config
+- ✅ **Set Agent Graph** - Define LangGraph workflows with nodes and edges
+- ✅ **Validate Agents** - Pre-publish validation of agent configuration
+- ✅ **Publish Agents** - Publish agents to marketplace
+- ✅ **Update Agents** - Modify agent metadata and configuration
+
+📖 **See [AGENT_CREATION_GUIDE.md](AGENT_CREATION_GUIDE.md) for complete documentation**
+
+### Workflow Management
+- ✅ **Create Workflows** - Build new workflows with nodes and edges
+- ✅ **List Workflows** - View all your workflows
+- ✅ **Get Workflow Details** - Retrieve specific workflow information
+- ✅ **Update Workflows** - Modify existing workflows
+- ✅ **Execute Workflows** - Run workflows with input data
+- ✅ **Monitor Executions** - Check execution status and results
+- ✅ **Delete Workflows** - Remove workflows
+- ✅ **Validate Workflows** - Check workflow structure before saving
+
+### Agent Operations
+- ✅ **List Agents** - Browse marketplace agents with filtering
+- ✅ **Get Agent Details** - View agent information
+- ✅ **Execute Agents** - Run pre-built agents
+- ✅ **Deploy Agents** - Deploy agents to Kubernetes
+
+### Dashboard Configuration
+- ✅ **Create Dashboards** - Configure agent-specific dashboards
+- ✅ **Add Widgets** - Add analytics, stats, and custom widgets
+- ✅ **Configure Pages** - Set up landing, configuration, and dashboard pages
+
+### Authentication & Security
+- ✅ **OAuth 2.0 Production Auth** - Secure workspace-scoped connections
+- ✅ **Multi-Tenant Isolation** - Each connection tied to specific user + workspace
+- ✅ **Automatic Token Refresh** - Tokens auto-refresh with 5-minute buffer
+- ✅ **Encrypted Storage** - AES-256-GCM encrypted token storage
+- ✅ **Dev/Test Mode** - Direct token auth for local development
+
+---
+
+## 📋 Prerequisites
+
+- **Node.js** 18.0.0 or higher
+- **AgentBuilder Backend** running (local or production)
+- **Claude Code CLI** installed
+- **AgentBuilder Account** with workspace access
+
+---
+
+## 🚀 Installation
+
+### Step 1: Install Dependencies
+
+```bash
+cd agentbuilder-mcp-server
+npm install
+```
+
+### Step 2: Build the Server
+
+```bash
+npm run build
+```
+
+### Step 3: Configure Environment
+
+```bash
+# Copy example env file
+cp .env.example .env
+
+# Edit .env with your configuration
+nano .env
+```
+
+**`.env` Configuration:**
+```bash
+# AgentBuilder API Base URL
+AGENTBUILDER_API_URL=http://localhost:8000
+# Or for production:
+# AGENTBUILDER_API_URL=https://api.agentbuilder.com
+```
+
+---
+
+## 🔐 Authentication Setup
+
+### 🌟 **Production OAuth 2.0** (Recommended)
+
+OAuth 2.0 provides secure, workspace-scoped authentication for production use.
+
+#### Step 1: Create MCP Connection in Dashboard
+
+1. **Login to AgentBuilder Dashboard**:
+   ```
+   https://app.agentbuilder.com
+   # Or local: http://localhost:5173
+   ```
+
+2. **Navigate to MCP Settings**:
+   - Go to **Settings** → **MCP Connections**
+   - Click **"Connect MCP"** button
+
+3. **Complete OAuth Flow**:
+   - You'll be redirected to Supabase OAuth
+   - Authenticate and grant permissions
+   - Select target workspace for this connection
+
+4. **Copy Connection ID**:
+   - After successful OAuth, you'll see a connection ID
+   - Format: `mcp_conn_abc123xyz`
+   - **Copy this ID** - you'll need it for Claude Code
+
+#### Step 2: Configure in Claude Code
+
+Once you have your connection ID, you'll use it in Claude Code.
+
+---
+
+### 🧪 **Dev/Test Mode** (Local Development)
+
+For local development, you can use direct JWT token authentication.
+
+#### Get JWT Token from Supabase
+
+```bash
+# Method 1: From Browser DevTools
+1. Login to frontend (http://localhost:5173)
+2. Open DevTools (F12)
+3. Go to Application → Local Storage
+4. Find supabase.auth.token
+5. Copy the access_token value
+
+# Method 2: From API (if you have credentials)
+curl -X POST http://localhost:8000/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email":"your@email.com","password":"password"}'
+```
+
+---
+
+## 🔧 Configuration for Claude Code
+
+### Step 1: Add to Claude Code MCP Settings
+
+Edit your Claude Code settings file:
+
+**Location**: `~/.claude/settings.local.json`
+
+**Add this configuration:**
+
+```json
+{
+  "mcpServers": {
+    "agentbuilder": {
+      "command": "node",
+      "args": ["/Users/shantanuchandra/code/agentbuilder/agentbuilder-mcp-server/dist/index.js"],
+      "env": {
+        "AGENTBUILDER_API_URL": "http://localhost:8000"
+      }
+    }
+  }
+}
+```
+
+**Adjust the path** to match where you cloned the repository.
+
+### Step 2: Restart Claude Code
+
+```bash
+# Restart Claude Code to load the new MCP server
+claude code
+```
+
+### Step 3: Verify Connection
+
+In Claude Code, ask:
+
+```
+List the available MCP tools
+```
+
+You should see tools like:
+- `agentbuilder:set_auth_token`
+- `agentbuilder:create_workflow`
+- `agentbuilder:list_workflows`
+- etc.
+
+---
+
+## 🎮 Usage Examples
+
+### 1. Authenticate with OAuth 2.0 (Production)
+
+**Recommended for production use with workspace isolation.**
+
+**In Claude Code:**
+
+```
+Connect to my AgentBuilder workspace using connection ID mcp_conn_abc123xyz
+```
+
+Claude will call:
+```typescript
+set_connection({ connection_id: "mcp_conn_abc123xyz" })
+```
+
+**Response:**
+```
+✅ Successfully connected to AgentBuilder workspace: "My Production Workspace"
+
+Connection Status: active
+Connection ID: mcp_conn_abc123xyz
+
+You can now create workflows, and they will be saved to this workspace.
+```
+
+---
+
+### 1b. Authenticate with Token (Dev/Test)
+
+**For local development only. Use OAuth for production.**
+
+**In Claude Code:**
+
+```
+Use the agentbuilder MCP server to set my auth token: <your_jwt_token_here>
+```
+
+Claude will call:
+```typescript
+set_auth_token({ token: "your_jwt_token" })
+```
+
+**Note:** This method is deprecated for production. Shows warning message.
+
+---
+
+### 2. Create a Simple Workflow
+
+```
+Create a workflow called "Email Notification" that:
+1. Triggers on webhook
+2. Sends an email notification
+3. Logs the result
+
+Use the agentbuilder MCP server.
+```
+
+Claude will call:
+```typescript
+create_workflow({
+  name: "Email Notification",
+  description: "Send email notifications on webhook trigger",
+  nodes: [
+    {
+      id: "trigger-1",
+      type: "TRIGGER",
+      data: { trigger_type: "webhook" }
+    },
+    {
+      id: "email-1",
+      type: "EMAIL_SEND",
+      data: {
+        to: "user@example.com",
+        subject: "Notification",
+        body: "Event triggered"
+      }
+    },
+    {
+      id: "log-1",
+      type: "LOG",
+      data: { level: "info" }
+    }
+  ],
+  edges: [
+    { source: "trigger-1", target: "email-1" },
+    { source: "email-1", target: "log-1" }
+  ],
+  category: "automation"
+})
+```
+
+---
+
+### 3. List Your Workflows
+
+```
+Show me all my active workflows using the agentbuilder MCP server
+```
+
+Claude will call:
+```typescript
+list_workflows({ status: "active" })
+```
+
+---
+
+### 4. Execute a Workflow
+
+```
+Execute workflow ID "67abc123" with the input:
+{
+  "email": "test@example.com",
+  "name": "Test User"
+}
+```
+
+Claude will call:
+```typescript
+execute_workflow({
+  workflow_id: "67abc123",
+  input: {
+    email: "test@example.com",
+    name: "Test User"
+  }
+})
+```
+
+---
+
+### 5. Check Execution Status
+
+```
+What's the status of execution "exec_xyz789"?
+```
+
+Claude will call:
+```typescript
+get_execution_status({ execution_id: "exec_xyz789" })
+```
+
+---
+
+### 6. Complex Workflow Creation
+
+```
+Create a customer onboarding workflow with the following steps:
+1. Webhook trigger receives customer data
+2. Validate email format
+3. Check if customer exists in database
+4. If new customer:
+   - Create account
+   - Send welcome email
+   - Add to mailing list
+5. If existing customer:
+   - Update profile
+   - Send "welcome back" email
+6. Log all actions
+```
+
+Claude will intelligently structure this into a workflow with conditional nodes, proper edges, and error handling.
+
+---
+
+## 🛠️ Available Tools
+
+### Authentication
+
+#### `set_connection` (Production - Recommended)
+Connect to AgentBuilder workspace using OAuth 2.0 connection ID.
+
+**Parameters:**
+- `connection_id` (string, required): MCP connection ID from dashboard (format: `mcp_conn_xxx`)
+
+**Example:**
+```typescript
+set_connection({ connection_id: "mcp_conn_abc123xyz" })
+```
+
+**Response:**
+```json
+{
+  "content": [{
+    "type": "text",
+    "text": "✅ Successfully connected to AgentBuilder workspace: \"Production Workspace\"\n\nConnection Status: active\nConnection ID: mcp_conn_abc123xyz\n\nYou can now create workflows, and they will be saved to this workspace."
+  }]
+}
+```
+
+**Features:**
+- ✅ Workspace-scoped access (workflows saved to specific workspace)
+- ✅ Automatic token refresh (no manual token management)
+- ✅ Multi-tenant isolation
+- ✅ Secure encrypted token storage
+
+---
+
+#### `set_auth_token` (Dev/Test Only - Deprecated)
+Set the JWT authentication token for API requests.
+
+**⚠️ Deprecated:** Use `set_connection` for production. This method is for dev/test only.
+
+**Parameters:**
+- `token` (string, required): Supabase JWT token
+
+**Example:**
+```typescript
+set_auth_token({ token: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." })
+```
+
+---
+
+### Workflow Management
+
+#### `create_workflow`
+Create a new workflow.
+
+**Parameters:**
+- `name` (string, required): Workflow name
+- `description` (string): Workflow description
+- `nodes` (array): Array of workflow nodes
+- `edges` (array): Array of connections between nodes
+- `category` (string): Workflow category (automation, data_processing, etc.)
+
+**Example:**
+```typescript
+create_workflow({
+  name: "Data Processing Pipeline",
+  description: "Process CSV data and send results",
+  nodes: [...],
+  edges: [...],
+  category: "data_processing"
+})
+```
+
+#### `list_workflows`
+List workflows for the authenticated user.
+
+**Parameters:**
+- `limit` (number): Number of results (default: 20)
+- `offset` (number): Pagination offset (default: 0)
+- `status` (string): Filter by status (draft, active, archived)
+
+**Example:**
+```typescript
+list_workflows({ limit: 10, status: "active" })
+```
+
+#### `get_workflow`
+Get details of a specific workflow.
+
+**Parameters:**
+- `workflow_id` (string, required): Workflow ID
+
+**Example:**
+```typescript
+get_workflow({ workflow_id: "67abc123" })
+```
+
+#### `update_workflow`
+Update an existing workflow.
+
+**Parameters:**
+- `workflow_id` (string, required): Workflow ID
+- `updates` (object, required): Fields to update
+
+**Example:**
+```typescript
+update_workflow({
+  workflow_id: "67abc123",
+  updates: {
+    name: "Updated Workflow Name",
+    status: "active"
+  }
+})
+```
+
+#### `delete_workflow`
+Delete a workflow.
+
+**Parameters:**
+- `workflow_id` (string, required): Workflow ID to delete
+
+**Example:**
+```typescript
+delete_workflow({ workflow_id: "67abc123" })
+```
+
+#### `validate_workflow`
+Validate workflow structure.
+
+**Parameters:**
+- `workflow` (object, required): Workflow object to validate
+
+**Example:**
+```typescript
+validate_workflow({
+  workflow: {
+    nodes: [...],
+    edges: [...]
+  }
+})
+```
+
+---
+
+### Workflow Execution
+
+#### `execute_workflow`
+Execute a workflow.
+
+**Parameters:**
+- `workflow_id` (string, required): Workflow ID
+- `input` (object): Input data for execution
+
+**Example:**
+```typescript
+execute_workflow({
+  workflow_id: "67abc123",
+  input: { user_id: "123", action: "process" }
+})
+```
+
+#### `get_execution_status`
+Get execution status and results.
+
+**Parameters:**
+- `execution_id` (string, required): Execution ID
+
+**Example:**
+```typescript
+get_execution_status({ execution_id: "exec_xyz789" })
+```
+
+#### `list_executions`
+List workflow executions.
+
+**Parameters:**
+- `workflow_id` (string): Filter by workflow ID (optional)
+
+**Example:**
+```typescript
+list_executions({ workflow_id: "67abc123" })
+```
+
+---
+
+## 🔍 Troubleshooting
+
+### OAuth Connection Issues
+
+#### Issue: Connection ID Invalid
+
+**Symptoms:**
+- Error: "Failed to connect with connection ID"
+- "Connection not found or inactive"
+
+**Solution:**
+```bash
+# 1. Verify connection ID format
+# Correct: mcp_conn_abc123xyz
+# Incorrect: abc123 (missing prefix)
+
+# 2. Check connection status in dashboard
+# Go to Settings → MCP Connections
+# Ensure connection is "active" (not expired/revoked)
+
+# 3. Create new connection if needed
+# Click "Connect MCP" in dashboard
+# Complete OAuth flow
+# Copy new connection ID
+```
+
+---
+
+#### Issue: Connection Expired
+
+**Symptoms:**
+- "Connection has expired"
+- "Token refresh failed"
+
+**Solution:**
+```bash
+# OAuth connections have automatic refresh, but if the connection has been
+# inactive for >30 days, it may expire.
+
+# Solution: Create new connection
+1. Go to dashboard → Settings → MCP Connections
+2. Revoke old connection
+3. Click "Connect MCP" to create new connection
+4. Use new connection ID in Claude Code
+```
+
+---
+
+#### Issue: Wrong Workspace
+
+**Symptoms:**
+- Workflows not appearing in expected workspace
+- "Access denied to workspace"
+
+**Solution:**
+```bash
+# Each MCP connection is tied to a specific workspace
+
+# To use different workspace:
+1. Create new MCP connection in dashboard
+2. Select correct workspace during OAuth flow
+3. Use new connection ID in Claude Code
+
+# To check current connection's workspace:
+# In Claude Code: "What workspace am I connected to?"
+```
+
+---
+
+### Issue: MCP Server Not Found
+
+**Symptoms:**
+- Claude Code doesn't show agentbuilder tools
+- Error: "MCP server not found"
+
+**Solution:**
+```bash
+# Check settings file
+cat ~/.claude/settings.local.json
+
+# Verify path to dist/index.js is correct
+ls -la /Users/shantanuchandra/code/agentbuilder/agentbuilder-mcp-server/dist/index.js
+
+# Rebuild server
+cd agentbuilder-mcp-server
+npm run build
+
+# Restart Claude Code
+```
+
+---
+
+### Issue: Authentication Failed
+
+**Symptoms:**
+- API calls return 401 Unauthorized
+- "Authentication token required" errors
+
+**Solution:**
+```bash
+# Get fresh JWT token:
+# 1. Login to frontend (http://localhost:5173)
+# 2. Open browser DevTools (F12)
+# 3. Go to Application → Local Storage
+# 4. Find supabase.auth.token
+# 5. Copy the access_token value
+
+# Then set token in Claude Code:
+# "Set my agentbuilder auth token: <copied_token>"
+```
+
+---
+
+### Issue: Backend Not Running
+
+**Symptoms:**
+- Connection refused errors
+- "Cannot connect to http://localhost:8000"
+
+**Solution:**
+```bash
+# Start backend
+cd backend
+source venv/bin/activate
+uvicorn app.main:app --reload --port 8000
+
+# Verify backend is running
+curl http://localhost:8000/api/v1/health
+# Expected: {"status": "healthy"}
+```
+
+---
+
+### Issue: TypeScript Compilation Errors
+
+**Symptoms:**
+- Build fails with type errors
+- "Cannot find module" errors
+
+**Solution:**
+```bash
+# Clean and reinstall
+rm -rf node_modules dist package-lock.json
+npm install
+npm run build
+
+# If still failing, check Node.js version
+node --version  # Should be 18.0.0+
+```
+
+---
+
+## 📊 Architecture
+
+### OAuth 2.0 Flow
+
+```
+┌──────────────────┐
+│   User Browser   │
+│   (Dashboard)    │
+└────────┬─────────┘
+         │ 1. Click "Connect MCP"
+         ↓
+┌──────────────────────────────┐
+│  AgentBuilder Backend        │
+│  POST /api/v1/mcp/oauth/init │
+└────────┬─────────────────────┘
+         │ 2. Generate state token
+         │    Return authorization URL
+         ↓
+┌──────────────────┐
+│  Supabase OAuth  │
+│  (Auth Flow)     │
+└────────┬─────────┘
+         │ 3. User authenticates
+         │    Grants permissions
+         ↓
+┌──────────────────────────────┐
+│  AgentBuilder Backend        │
+│  GET /api/v1/mcp/oauth/callback
+│  - Validate state            │
+│  - Exchange code for tokens  │
+│  - Encrypt tokens (AES-256)  │
+│  - Store in mcp_connections  │
+│  - Return connection_id      │
+└────────┬─────────────────────┘
+         │ 4. connection_id: mcp_conn_xxx
+         ↓
+┌──────────────────┐
+│   User Browser   │
+│   (Shows ID)     │
+└──────────────────┘
+```
+
+### MCP Request Flow
+
+```
+┌─────────────────┐
+│   Claude Code   │
+│   (User CLI)    │
+└────────┬────────┘
+         │ MCP Protocol (stdio)
+         │ Tool: set_connection(connection_id)
+         ↓
+┌─────────────────────────────────────┐
+│  AgentBuilder MCP Server            │
+│  - Validates connection ID          │
+│  - Adds X-MCP-Connection-ID header  │
+│  - Tool handlers                    │
+└────────┬────────────────────────────┘
+         │ HTTP/REST API
+         │ Header: X-MCP-Connection-ID
+         ↓
+┌─────────────────────────────────────┐
+│  AgentBuilder Backend               │
+│  (FastAPI on port 8000)             │
+│  Middleware:                        │
+│  1. Validate connection exists      │
+│  2. Check token expiry (auto-refresh)
+│  3. Verify workspace ownership      │
+│  4. Check RBAC permissions          │
+│  5. Inject workspace context        │
+└────────┬────────────────────────────┘
+         │ MongoDB
+         ↓
+┌─────────────────────────────────────┐
+│  MongoDB Database                   │
+│  - mcp_connections (encrypted tokens)│
+│  - workflows (with source tracking) │
+│  - executions collection            │
+└─────────────────────────────────────┘
+```
+
+---
+
+## 🧪 Testing
+
+### Manual Testing
+
+```bash
+# 1. Build and install
+npm run build
+
+# 2. Test directly (with auth token)
+export AGENTBUILDER_AUTH_TOKEN="your_token_here"
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js
+```
+
+### Integration Testing with Claude Code
+
+```bash
+# Start Claude Code
+claude code
+
+# In Claude Code, run test commands:
+# "List available agentbuilder MCP tools"
+# "Create a test workflow named 'Test Workflow'"
+# "List all workflows"
+```
+
+---
+
+## 🚀 Development
+
+### Local Development
+
+```bash
+# Run in watch mode
+npm run watch
+
+# In another terminal, test changes
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node dist/index.js
+```
+
+### Adding New Tools
+
+1. **Add tool definition** in `getTools()` method
+2. **Add handler** in `setupHandlers()` switch statement
+3. **Implement handler method** (e.g., `handleNewTool()`)
+4. **Rebuild and test**
+
+**Example:**
+
+```typescript
+// 1. Add tool definition
+{
+  name: 'duplicate_workflow',
+  description: 'Duplicate an existing workflow',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      workflow_id: { type: 'string' },
+      new_name: { type: 'string' }
+    },
+    required: ['workflow_id', 'new_name']
+  }
+}
+
+// 2. Add to switch statement
+case 'duplicate_workflow':
+  return await this.handleDuplicateWorkflow(args);
+
+// 3. Implement handler
+private async handleDuplicateWorkflow(args: any) {
+  // Get original workflow
+  const original = await this.client.getWorkflow(args.workflow_id);
+
+  // Create duplicate with new name
+  const duplicate = await this.client.createWorkflow({
+    ...original.data,
+    name: args.new_name
+  });
+
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify(duplicate, null, 2)
+    }]
+  };
+}
+```
+
+---
+
+## 📝 Examples
+
+### Example 1: Complete Onboarding Workflow
+
+```
+Create a complete customer onboarding workflow using agentbuilder that:
+
+1. Triggers when webhook receives new signup
+2. Validates email and phone number
+3. Creates user account in database
+4. Sends welcome email with verification link
+5. Adds user to "New Customers" mailing list
+6. Schedules follow-up email for 3 days later
+7. Logs all steps for auditing
+8. On any error, sends alert to admin
+
+Make it production-ready with proper error handling.
+```
+
+### Example 2: Data Processing Pipeline
+
+```
+Build a data processing workflow in agentbuilder that:
+
+1. Triggers on CSV file upload
+2. Validates CSV format
+3. Cleans data (remove duplicates, fix formatting)
+4. Enriches data with external API calls
+5. Saves processed data to database
+6. Generates summary report
+7. Emails report to stakeholder
+8. Archives original file
+
+Include retry logic for API calls and proper error notifications.
+```
+
+### Example 3: Monitoring Workflow
+
+```
+Create a monitoring workflow that:
+
+1. Runs every 5 minutes (cron trigger)
+2. Checks website uptime
+3. Tests API endpoints
+4. Monitors database connections
+5. If any checks fail:
+   - Send Slack alert
+   - Create incident ticket
+   - Trigger automated recovery if possible
+6. Log all check results
+```
+
+---
+
+## 🔒 Security Best Practices
+
+### 1. Don't Commit Tokens
+
+```bash
+# Never commit .env files
+echo ".env" >> .gitignore
+```
+
+### 2. Rotate Tokens Regularly
+
+```bash
+# Get new token from Supabase every session
+# Set expiration time in Supabase settings
+```
+
+### 3. Use Environment Variables
+
+```bash
+# Set token via environment, not hardcoded
+export AGENTBUILDER_AUTH_TOKEN="token_here"
+```
+
+---
+
+## 🆘 Support
+
+**Issues?** Report at: https://github.com/agentbuilder/agentbuilder/issues
+
+**Documentation**: See main [AgentBuilder Docs](../docs/README.md)
+
+**Questions?** Contact: support@agentbuilder.com
+
+---
+
+## 📄 License
+
+MIT License - See [LICENSE](LICENSE) file for details
+
+---
+
+## 🙏 Acknowledgments
+
+- Built with [Model Context Protocol](https://modelcontextprotocol.io/) SDK
+- Integrates with [AgentBuilder Platform](../README.md)
+- Powered by [Claude Code](https://claude.ai/code)
+
+---
+
+**Happy workflow building!** 🚀