@chandshantanu/agentbuilder-mcp-server 0.2.0

package/LOCAL_DEVELOPMENT_TESTING_GUIDE.md

@@ -0,0 +1,358 @@
+# MCP Server - Local Development Testing Guide
+
+## ✅ Connection Test Results
+
+**Date**: 2026-01-09
+**Status**: All Systems Operational
+
+### Test Summary
+
+| Component | Status | Details |
+|-----------|--------|---------|
+| Backend API | ✅ Running | Port 8000, responding to requests |
+| MongoDB | ✅ Connected | Docker container running |
+| API Documentation | ✅ Accessible | http://127.0.0.1:8000/docs |
+| MCP OAuth Endpoints | ✅ Available | Returns 403 (auth required, as expected) |
+| MCP Server | ✅ Built | TypeScript compiled to dist/index.js |
+
+---
+
+## 🚀 Quick Start Testing
+
+### 1. Verify Backend is Running
+
+```bash
+curl http://127.0.0.1:8000/api/v1/health
+# Should return: {"status":"healthy",...}
+```
+
+### 2. Run Connection Test
+
+```bash
+cd /Users/shantanuchandra/code/agentbuilder/agentbuilder-mcp-server
+node test-connection.js
+```
+
+Expected output:
+```
+✅ Backend is reachable
+✅ API documentation accessible
+✅ Database is connected (auth required, as expected)
+✅ MCP OAuth endpoints available (403 = auth required)
+```
+
+### 3. Test MCP Server Directly
+
+```bash
+# The MCP server runs on stdio (standard input/output)
+node dist/index.js
+# Should output: "AgentBuilder MCP Server running on stdio"
+# Press Ctrl+C to exit
+```
+
+---
+
+## 🔧 Claude Code Configuration
+
+### Step 1: Create Claude Desktop Config Directory
+
+```bash
+mkdir -p ~/Library/Application\ Support/Claude
+```
+
+### Step 2: Configure MCP Server
+
+Edit (or create) `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "agentbuilder": {
+      "command": "node",
+      "args": [
+        "/Users/shantanuchandra/code/agentbuilder/agentbuilder-mcp-server/dist/index.js"
+      ],
+      "env": {
+        "AGENTBUILDER_API_URL": "http://127.0.0.1:8000"
+      }
+    }
+  }
+}
+```
+
+**Note**: A template is available at `claude_desktop_config.example.json`
+
+### Step 3: Restart Claude Desktop
+
+After saving the configuration:
+1. Quit Claude Desktop completely
+2. Restart Claude Desktop
+3. The MCP server will load automatically
+
+---
+
+## 🧪 Testing with Claude Code
+
+### Option 1: Dev/Test Mode (Quick Testing)
+
+1. **Get a test JWT token**:
+   ```bash
+   # Login to your local frontend (http://localhost:5173)
+   # Open browser DevTools → Network tab
+   # Copy the Authorization header from any API request
+   # Example: "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
+   ```
+
+2. **In Claude Code, run**:
+   ```
+   User: Use the set_auth_token tool with token "eyJhbGc..."
+
+   Claude: ✅ Auth token set (dev/test mode)
+   ```
+
+3. **Test workflow creation**:
+   ```
+   User: Create a workflow called "Test Workflow" with a single start node
+
+   Claude: [Creates workflow via AgentBuilder API]
+   ✅ Workflow created successfully!
+   ```
+
+### Option 2: Production OAuth Mode (Recommended)
+
+**Prerequisites**:
+- Frontend running on http://localhost:5173
+- Backend running on http://127.0.0.1:8000
+
+1. **Create MCP Connection in Dashboard**:
+   ```bash
+   # 1. Open frontend
+   open http://localhost:5173/settings/mcp
+
+   # 2. Click "Connect MCP" button
+   # 3. Complete OAuth flow
+   # 4. Copy connection ID (format: mcp_conn_abc123xyz)
+   ```
+
+2. **In Claude Code, connect**:
+   ```
+   User: Connect to AgentBuilder using connection ID mcp_conn_abc123xyz
+
+   Claude: ✅ Successfully connected to AgentBuilder workspace: "default"
+
+   Connection Status: active
+   Connection ID: mcp_conn_abc123xyz
+
+   You can now create workflows, and they will be saved to this workspace.
+   ```
+
+3. **Create workflows**:
+   ```
+   User: Create a workflow that sends a welcome email to new users
+
+   Claude: [Creates workflow with email node]
+   ✅ Workflow created in workspace: default
+   ```
+
+---
+
+## 📊 Available MCP Tools
+
+When the MCP server is configured in Claude Code, the following tools become available:
+
+### Core Tools
+
+| Tool | Description | Example |
+|------|-------------|---------|
+| `set_connection` | Connect with OAuth connection ID (PRODUCTION) | `Connect using mcp_conn_123` |
+| `set_auth_token` | Set JWT token (DEV/TEST ONLY) | `Use set_auth_token with token "eyJ..."` |
+| `list_workflows` | List user's workflows | `Show my workflows` |
+| `get_workflow` | Get workflow details | `Get workflow with ID wf_123` |
+| `create_workflow` | Create new workflow | `Create a workflow to send emails` |
+| `update_workflow` | Update existing workflow | `Update workflow wf_123` |
+| `delete_workflow` | Delete workflow | `Delete workflow wf_123` |
+
+---
+
+## 🔍 Troubleshooting
+
+### MCP Server Not Loading in Claude Code
+
+**Check**:
+1. Config file path is correct
+2. Absolute path to `dist/index.js` is correct
+3. Node.js is installed (`node --version`)
+4. MCP server builds successfully (`npm run build`)
+
+**View logs**:
+```bash
+# macOS
+tail -f ~/Library/Logs/Claude/mcp*.log
+
+# Check for errors in Claude Desktop console
+```
+
+### Backend Connection Fails
+
+**Check**:
+```bash
+# 1. Backend is running
+curl http://127.0.0.1:8000/api/v1/health
+
+# 2. MongoDB is running
+docker ps | grep mongo
+
+# 3. Check backend logs
+tail -f /tmp/backend.log
+```
+
+**Restart backend**:
+```bash
+cd /Users/shantanuchandra/code/agentbuilder/backend
+source venv/bin/activate
+python -m uvicorn app.main:app --reload --port 8000
+```
+
+### Authentication Errors
+
+**Test token validity**:
+```bash
+# Get token from frontend DevTools
+TOKEN="your_jwt_token_here"
+
+curl -H "Authorization: Bearer $TOKEN" \
+  http://127.0.0.1:8000/api/v1/workflows
+
+# Should return 200 with workflows or 401 if token invalid
+```
+
+### MCP OAuth Endpoints Not Found
+
+**Verify router is loaded**:
+```bash
+# Check backend logs for MCP OAuth router registration
+grep -i "mcp.*oauth" /tmp/backend.log
+
+# Test endpoint directly
+curl http://127.0.0.1:8000/api/v1/mcp/connections
+# Should return 401 or 403 (not 404)
+```
+
+---
+
+## 🌐 Environment Switching
+
+### Local Development → Production
+
+1. **Update .env**:
+   ```bash
+   # Change from:
+   AGENTBUILDER_API_URL=http://127.0.0.1:8000
+
+   # To:
+   AGENTBUILDER_API_URL=https://api.agentbuilder.com
+   ```
+
+2. **Update Claude Desktop config**:
+   ```json
+   {
+     "mcpServers": {
+       "agentbuilder": {
+         "command": "node",
+         "args": ["/absolute/path/to/dist/index.js"],
+         "env": {
+           "AGENTBUILDER_API_URL": "https://api.agentbuilder.com"
+         }
+       }
+     }
+   }
+   ```
+
+3. **Restart Claude Desktop**
+
+4. **Use production OAuth**:
+   - Create connection in production dashboard
+   - Use `set_connection` with production connection ID
+
+---
+
+## 📝 Development Workflow
+
+### Making Changes to MCP Server
+
+1. **Edit TypeScript source**:
+   ```bash
+   vim src/index.ts
+   ```
+
+2. **Rebuild**:
+   ```bash
+   npm run build
+   ```
+
+3. **Restart Claude Desktop** to load new version
+
+4. **Test changes** in Claude Code
+
+### Testing API Changes
+
+1. **Update backend code**:
+   ```bash
+   # Backend auto-reloads with --reload flag
+   # Make changes in backend/app/**
+   ```
+
+2. **Test with curl**:
+   ```bash
+   curl -X POST http://127.0.0.1:8000/api/v1/mcp/oauth/initiate \
+     -H "Authorization: Bearer $TOKEN" \
+     -H "Content-Type: application/json" \
+     -d '{"workspace_name": "test"}'
+   ```
+
+3. **Test with MCP server** in Claude Code
+
+---
+
+## 🎯 Current Test Status
+
+### ✅ Working
+- [x] Backend API running on port 8000
+- [x] MongoDB connection established
+- [x] MCP OAuth endpoints registered
+- [x] MCP server builds successfully
+- [x] TypeScript compilation working
+- [x] Environment configuration (.env)
+- [x] Request interceptor (X-MCP-Connection-ID header)
+- [x] Dev/test mode (set_auth_token)
+- [x] Production OAuth mode (set_connection)
+
+### ⚠️ Needs Testing
+- [ ] Complete OAuth flow in local development
+- [ ] Workflow creation via MCP
+- [ ] Token auto-refresh
+- [ ] Connection revocation
+- [ ] Workspace isolation
+- [ ] Rate limiting
+
+### 🔄 Next Steps
+1. Start frontend: `cd frontend && npm run dev`
+2. Create MCP connection via dashboard
+3. Test OAuth flow end-to-end
+4. Create workflows via Claude Code
+5. Verify workspace isolation
+
+---
+
+## 📚 Additional Resources
+
+- **MCP Server README**: [README.md](./README.md)
+- **Getting Started Guide**: [GETTING_STARTED.md](./GETTING_STARTED.md)
+- **Backend API Docs**: http://127.0.0.1:8000/docs
+- **Project Documentation**: `/Users/shantanuchandra/code/agentbuilder/docs/`
+
+---
+
+**Last Updated**: 2026-01-09
+**Tested By**: Claude Code Integration Test
+**Environment**: Local Development (macOS)