@chandshantanu/agentbuilder-mcp-server 0.2.0

package/GETTING_STARTED.md

@@ -0,0 +1,435 @@
+# Getting Started with AgentBuilder MCP Server
+
+**Quick Start Guide** for integrating workflow management with Claude Code
+
+---
+
+## 🎯 What is This?
+
+The **AgentBuilder MCP Server** is a bridge that lets you use Claude Code to create and manage workflows in your AgentBuilder platform through natural language commands.
+
+**Instead of manually coding workflows**, you can now say things like:
+
+> "Create a workflow that sends an email when a webhook is triggered"
+
+And Claude will build it for you!
+
+---
+
+## ⚡ Quick Setup (5 minutes)
+
+### 1. Run the Setup Script
+
+```bash
+cd agentbuilder-mcp-server
+./setup.sh
+```
+
+This will:
+- ✅ Install dependencies
+- ✅ Build the TypeScript project
+- ✅ Create `.env` configuration file
+- ✅ Show you the configuration to add to Claude Code
+
+### 2. Configure Claude Code
+
+Copy the configuration shown by the setup script and add it to:
+
+**File**: `~/.claude/settings.local.json`
+
+```json
+{
+  "mcpServers": {
+    "agentbuilder": {
+      "command": "node",
+      "args": ["/Users/shantanuchandra/code/agentbuilder/agentbuilder-mcp-server/dist/index.js"],
+      "env": {
+        "AGENTBUILDER_API_URL": "http://localhost:8000"
+      }
+    }
+  }
+}
+```
+
+### 3. Restart Claude Code
+
+```bash
+# Exit current session
+exit
+
+# Start new session
+claude code
+```
+
+### 4. Verify Installation
+
+In Claude Code, ask:
+
+```
+List the available agentbuilder MCP tools
+```
+
+**Expected Output**: You should see 10 tools listed:
+- `set_auth_token`
+- `create_workflow`
+- `list_workflows`
+- `get_workflow`
+- `update_workflow`
+- `execute_workflow`
+- `get_execution_status`
+- `list_executions`
+- `delete_workflow`
+- `validate_workflow`
+
+---
+
+## 🔑 Getting Your Authentication Token
+
+Before you can create workflows, you need to authenticate:
+
+### Step 1: Login to Frontend
+
+```bash
+# Make sure frontend is running
+cd frontend
+npm run dev
+
+# Open browser
+open http://localhost:5173
+```
+
+### Step 2: Get JWT Token
+
+1. Login as any user (e.g., `seller@agentbuilder.test` / `Seller123!@#`)
+2. Open Browser DevTools (F12 or Cmd+Option+I)
+3. Go to **Application** tab
+4. Navigate to **Local Storage** → `http://localhost:5173`
+5. Find key that starts with `supabase.auth.token`
+6. Copy the **entire JSON value**
+7. Extract the `access_token` field value
+
+### Step 3: Set Token in Claude Code
+
+In Claude Code:
+
+```
+Set my agentbuilder auth token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
+```
+
+(Use your actual token from Step 2)
+
+**Response**:
+> ✅ Authentication token set successfully. You can now use workflow tools.
+
+---
+
+## 🎮 Your First Workflow
+
+Now let's create your first workflow!
+
+### Example 1: Simple Email Notification
+
+In Claude Code, say:
+
+```
+Create a workflow using agentbuilder that:
+- Name: "Welcome Email"
+- Triggers on webhook
+- Sends a welcome email
+- Logs the action
+```
+
+**Claude will:**
+1. Use `create_workflow` tool
+2. Build the node structure
+3. Connect nodes with edges
+4. Return the created workflow with ID
+
+**You'll see output like:**
+```json
+{
+  "success": true,
+  "data": {
+    "workflow_id": "67abc123def...",
+    "name": "Welcome Email",
+    "status": "draft",
+    "nodes": [...],
+    "edges": [...]
+  }
+}
+```
+
+### Example 2: List Your Workflows
+
+```
+Show me all my workflows using agentbuilder
+```
+
+**Claude will call** `list_workflows` and show you all workflows in a formatted table.
+
+### Example 3: Execute a Workflow
+
+```
+Execute workflow "67abc123def" with this input:
+{
+  "email": "user@example.com",
+  "name": "John Doe"
+}
+```
+
+**Claude will:**
+1. Call `execute_workflow`
+2. Return execution ID
+3. You can then check status with: "What's the status of that execution?"
+
+---
+
+## 🏗️ Complex Workflow Example
+
+Let's build something more sophisticated:
+
+```
+Create a customer onboarding workflow in agentbuilder with these requirements:
+
+Name: "Customer Onboarding v1"
+Description: "Complete onboarding flow for new customers"
+
+Steps:
+1. Webhook trigger receives customer signup data
+2. Validate email format using regex
+3. Check if email already exists in database
+4. If new customer:
+   a. Create user account in database
+   b. Send welcome email with activation link
+   c. Add to "New Customers" mailing list in HubSpot
+   d. Schedule follow-up email for 3 days later
+5. If existing customer:
+   a. Update last_login timestamp
+   b. Send "Welcome Back" email
+6. Log all actions to audit log
+7. On any error:
+   a. Log error details
+   b. Send alert to admin@company.com
+   c. Create support ticket in Zendesk
+
+Make sure to include:
+- Proper error handling on each node
+- Retry logic for external API calls
+- Conditional branching for new vs existing customers
+- Parallel execution where possible (email + mailing list)
+
+Category: automation
+```
+
+**Claude will:**
+- Analyze the requirements
+- Design the workflow structure
+- Create appropriate nodes for each step
+- Add conditional logic nodes
+- Set up error handling
+- Connect everything with proper edges
+- Create the workflow via MCP
+
+**Result**: A production-ready workflow with 15+ nodes, conditional logic, error handling, and parallel execution!
+
+---
+
+## 📊 Common Use Cases
+
+### 1. Data Processing Pipeline
+
+```
+Build a CSV data processing workflow:
+- Upload CSV file
+- Validate columns
+- Clean data (remove duplicates, fix formats)
+- Enrich with external API data
+- Save to database
+- Generate summary report
+- Email report to stakeholders
+```
+
+### 2. Monitoring & Alerts
+
+```
+Create a system monitoring workflow that:
+- Runs every 5 minutes (cron trigger)
+- Checks API health endpoints
+- Tests database connectivity
+- Monitors disk space
+- If any check fails, send Slack alert
+- Log all results to MongoDB
+```
+
+### 3. Content Publishing
+
+```
+Build a content publishing workflow:
+- Trigger: New blog post drafted in CMS
+- Check for plagiarism using API
+- Generate SEO metadata
+- Optimize images
+- Schedule social media posts
+- Publish to website
+- Notify marketing team
+```
+
+### 4. E-commerce Order Processing
+
+```
+Create an order fulfillment workflow:
+- Trigger: New order received
+- Validate payment status
+- Check inventory levels
+- If in stock:
+  - Reserve items
+  - Generate packing slip
+  - Send to warehouse API
+  - Update inventory
+  - Send confirmation email to customer
+- If out of stock:
+  - Add to backorder queue
+  - Send delay notification
+  - Alert procurement team
+```
+
+---
+
+## 🔧 Advanced Features
+
+### Workflow Validation
+
+Before creating a complex workflow, validate it:
+
+```
+Validate this workflow structure:
+{
+  "nodes": [...],
+  "edges": [...]
+}
+```
+
+### Workflow Updates
+
+Modify existing workflows:
+
+```
+Update workflow "67abc123" to add a new email node after the validation step
+```
+
+### Execution Monitoring
+
+Track workflow executions:
+
+```
+Show me all failed executions from the last 24 hours
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### "Auth token required" Error
+
+**Solution**: Set your token again (tokens expire after ~1 hour)
+
+```
+Set my agentbuilder auth token: <new_token>
+```
+
+### "Workflow validation failed" Error
+
+**Check**:
+- All nodes have unique IDs
+- Edges connect existing nodes
+- No circular dependencies
+- At least one TRIGGER node exists
+
+### "Backend connection refused" Error
+
+**Solution**: Make sure backend is running
+
+```bash
+cd backend
+source venv/bin/activate
+uvicorn app.main:app --reload --port 8000
+```
+
+### Tools Not Showing in Claude Code
+
+**Solution**:
+1. Check settings file: `cat ~/.claude/settings.local.json`
+2. Verify path to `dist/index.js` is correct
+3. Rebuild MCP server: `npm run build`
+4. Restart Claude Code
+
+---
+
+## 📚 Learn More
+
+- **Full Documentation**: See [README.md](README.md)
+- **API Reference**: See [AgentBuilder API Docs](../docs/api/)
+- **MCP Protocol**: https://modelcontextprotocol.io/
+- **Claude Code**: https://claude.ai/code
+
+---
+
+## 🎯 Next Steps
+
+Now that you have the MCP server running, try:
+
+1. **Create 5 different workflows** to get familiar with the tool
+2. **Execute workflows** and monitor their status
+3. **Build a complex multi-step workflow** for a real use case
+4. **Integrate with your existing systems** (APIs, databases, etc.)
+5. **Automate repetitive tasks** in your development workflow
+
+---
+
+## 💡 Pro Tips
+
+### Tip 1: Use Natural Language
+
+Don't worry about exact syntax - Claude understands context:
+
+✅ Good: "Create a workflow that sends emails when users sign up"
+❌ Over-specific: "Use create_workflow tool with nodes array containing..."
+
+### Tip 2: Iterate Quickly
+
+Build workflows incrementally:
+
+```
+1. Create simple workflow
+2. Test it
+3. Add more complexity
+4. Test again
+5. Repeat
+```
+
+### Tip 3: Save Workflow IDs
+
+Keep track of important workflow IDs in a note:
+
+```markdown
+# My Workflows
+
+- Welcome Email: 67abc123def
+- Order Processing: 67xyz789ghi
+- Daily Report: 67mnp456jkl
+```
+
+### Tip 4: Use Descriptive Names
+
+Name workflows clearly:
+
+✅ Good: "Customer Onboarding - Email + CRM"
+❌ Bad: "Workflow 1"
+
+---
+
+## 🚀 You're Ready!
+
+You now have a powerful workflow automation system at your fingertips. Start building!
+
+**Happy automating!** 🎉