@sparkleideas/agentic-flow 2.0.2-alpha-patch.1

package/agentic-flow/docs/guides/ADDING-MCP-SERVERS.md

@@ -0,0 +1,642 @@
+# Adding Custom MCP Servers to Agentic Flow
+
+This guide shows you how to integrate custom MCP (Model Context Protocol) servers into agentic-flow.
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Integration Methods](#integration-methods)
+3. [Method 1: In-SDK MCP Server (Recommended)](#method-1-in-sdk-mcp-server-recommended)
+4. [Method 2: External MCP Server via Stdio](#method-2-external-mcp-server-via-stdio)
+5. [Method 3: External MCP Server via NPM Package](#method-3-external-mcp-server-via-npm-package)
+6. [Environment Variables](#environment-variables)
+7. [Testing Your MCP Server](#testing-your-mcp-server)
+8. [Troubleshooting](#troubleshooting)
+
+---
+
+## Overview
+
+Agentic Flow supports three ways to add custom MCP servers:
+
+| Method | Type | Performance | Use Case |
+|--------|------|-------------|----------|
+| **In-SDK** | In-process | Fastest (<1ms) | Custom tools, simple operations |
+| **Stdio** | Subprocess | Fast (10-50ms) | Local MCP servers, CLI tools |
+| **NPM Package** | Subprocess | Fast (10-50ms) | Published MCP packages |
+
+**Current MCP Servers in Agentic Flow:**
+
+1. **claude-flow-sdk** (In-SDK) - 6 tools
+2. **claude-flow** (NPM) - 101 tools
+3. **flow-nexus** (NPM) - 96 tools
+4. **agentic-payments** (NPM) - 10 tools
+
+---
+
+## Integration Methods
+
+### Method 1: In-SDK MCP Server (Recommended)
+
+**Best for:** Custom tools, simple operations, fastest performance
+
+In-SDK servers run directly in the agent process without spawning subprocesses.
+
+#### Step 1: Create MCP Server File
+
+Create `src/mcp/myCustomServer.ts`:
+
+```typescript
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+import { logger } from '../utils/logger.js';
+
+/**
+ * Create an in-SDK MCP server with custom tools
+ */
+export const myCustomServer = createSdkMcpServer({
+  name: 'my-custom-server',
+  version: '1.0.0',
+
+  tools: [
+    // Tool 1: Simple calculator
+    tool(
+      'calculate',
+      'Perform mathematical calculations',
+      {
+        operation: z.enum(['add', 'subtract', 'multiply', 'divide'])
+          .describe('Mathematical operation'),
+        a: z.number().describe('First number'),
+        b: z.number().describe('Second number')
+      },
+      async ({ operation, a, b }) => {
+        logger.info('Executing calculation', { operation, a, b });
+
+        let result: number;
+        switch (operation) {
+          case 'add': result = a + b; break;
+          case 'subtract': result = a - b; break;
+          case 'multiply': result = a * b; break;
+          case 'divide':
+            if (b === 0) throw new Error('Division by zero');
+            result = a / b;
+            break;
+        }
+
+        return {
+          operation,
+          inputs: { a, b },
+          result,
+          message: `${a} ${operation} ${b} = ${result}`
+        };
+      }
+    ),
+
+    // Tool 2: Data storage
+    tool(
+      'store_data',
+      'Store key-value data in memory',
+      {
+        key: z.string().describe('Storage key'),
+        value: z.string().describe('Value to store'),
+        namespace: z.string().optional().describe('Optional namespace')
+      },
+      async ({ key, value, namespace }) => {
+        // Your storage logic here
+        const fullKey = namespace ? `${namespace}:${key}` : key;
+
+        // Store in memory, database, or filesystem
+        logger.info('Storing data', { fullKey, value });
+
+        return {
+          success: true,
+          key: fullKey,
+          stored: value
+        };
+      }
+    ),
+
+    // Tool 3: API call wrapper
+    tool(
+      'fetch_data',
+      'Fetch data from external API',
+      {
+        url: z.string().url().describe('API endpoint URL'),
+        method: z.enum(['GET', 'POST']).default('GET').describe('HTTP method')
+      },
+      async ({ url, method }) => {
+        logger.info('Fetching data', { url, method });
+
+        try {
+          const response = await fetch(url, { method });
+          const data = await response.json();
+
+          return {
+            success: true,
+            status: response.status,
+            data
+          };
+        } catch (error: any) {
+          return {
+            success: false,
+            error: error.message
+          };
+        }
+      }
+    )
+  ]
+});
+```
+
+#### Step 2: Register in Claude Agent
+
+Edit `src/agents/claudeAgent.ts`:
+
+```typescript
+// Add import at top
+import { myCustomServer } from '../mcp/myCustomServer.js';
+
+// Inside claudeAgent function, around line 128:
+if (process.env.ENABLE_MY_CUSTOM_MCP === 'true') {
+  mcpServers['my-custom-server'] = myCustomServer;
+}
+```
+
+#### Step 3: Enable and Use
+
+```bash
+# Enable your custom MCP server
+export ENABLE_MY_CUSTOM_MCP=true
+
+# Run agent with your custom tools
+npx agentic-flow --agent coder --task "Calculate 42 + 58 using the calculate tool"
+```
+
+**Pros:**
+- ✅ Fastest performance (in-process, <1ms latency)
+- ✅ No subprocess overhead
+- ✅ Full TypeScript type safety
+- ✅ Easy to debug
+
+**Cons:**
+- ⚠️ Requires rebuild (`npm run build`)
+- ⚠️ Can't use external CLI tools directly
+
+---
+
+### Method 2: External MCP Server via Stdio
+
+**Best for:** Local MCP servers, custom CLI tools, existing MCP implementations
+
+External stdio servers run as subprocesses and communicate via standard input/output.
+
+#### Step 1: Create Standalone MCP Server
+
+Create `my-mcp-server/index.js`:
+
+```javascript
+#!/usr/bin/env node
+// Standalone MCP server using FastMCP or @modelcontextprotocol/sdk
+
+import { FastMCP } from 'fastmcp';
+
+const server = new FastMCP({
+  name: 'my-external-server',
+  version: '1.0.0'
+});
+
+// Add tools
+server.addTool({
+  name: 'custom_search',
+  description: 'Search custom database',
+  parameters: {
+    type: 'object',
+    properties: {
+      query: { type: 'string', description: 'Search query' },
+      limit: { type: 'number', description: 'Max results' }
+    },
+    required: ['query']
+  },
+  execute: async ({ query, limit = 10 }) => {
+    // Your search logic
+    return {
+      results: [
+        { id: 1, title: 'Result 1', score: 0.95 },
+        { id: 2, title: 'Result 2', score: 0.87 }
+      ],
+      count: 2
+    };
+  }
+});
+
+server.addTool({
+  name: 'send_notification',
+  description: 'Send notification via custom service',
+  parameters: {
+    type: 'object',
+    properties: {
+      message: { type: 'string' },
+      channel: { type: 'string', enum: ['email', 'slack', 'sms'] }
+    },
+    required: ['message', 'channel']
+  },
+  execute: async ({ message, channel }) => {
+    // Send notification
+    console.error(`Sending ${channel} notification: ${message}`);
+    return { success: true, channel, message };
+  }
+});
+
+// Start stdio transport
+server.listen({ transport: 'stdio' });
+```
+
+Make it executable:
+```bash
+chmod +x my-mcp-server/index.js
+```
+
+#### Step 2: Register in Claude Agent
+
+Edit `src/agents/claudeAgent.ts`:
+
+```typescript
+// Inside claudeAgent function, around line 169:
+if (process.env.ENABLE_MY_EXTERNAL_MCP === 'true') {
+  mcpServers['my-external-server'] = {
+    type: 'stdio',
+    command: 'node',
+    args: ['/path/to/my-mcp-server/index.js'],
+    env: {
+      ...process.env,
+      MY_SERVER_CONFIG: 'value'
+    }
+  };
+}
+```
+
+#### Step 3: Enable and Use
+
+```bash
+# Enable external MCP server
+export ENABLE_MY_EXTERNAL_MCP=true
+
+# Run agent
+npx agentic-flow --agent researcher --task "Search for 'AI trends' using custom_search"
+```
+
+**Pros:**
+- ✅ No rebuild required
+- ✅ Can use any language (Node, Python, Go, etc.)
+- ✅ Full access to CLI tools and system commands
+- ✅ Isolated process
+
+**Cons:**
+- ⚠️ Subprocess overhead (10-50ms startup)
+- ⚠️ Requires absolute path or PATH setup
+- ⚠️ More complex debugging
+
+---
+
+### Method 3: External MCP Server via NPM Package
+
+**Best for:** Published MCP packages, shared tools, community servers
+
+If your MCP server is published as an NPM package, integrate it like existing servers.
+
+#### Step 1: Publish MCP Package
+
+Create `package.json` for your MCP server:
+
+```json
+{
+  "name": "my-mcp-package",
+  "version": "1.0.0",
+  "bin": {
+    "my-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "scripts": {
+    "mcp": "node dist/index.js"
+  }
+}
+```
+
+Publish to NPM:
+```bash
+npm publish my-mcp-package
+```
+
+#### Step 2: Register in Claude Agent
+
+Edit `src/agents/claudeAgent.ts`:
+
+```typescript
+// Inside claudeAgent function, around line 169:
+if (process.env.ENABLE_MY_MCP_PACKAGE === 'true') {
+  mcpServers['my-mcp-package'] = {
+    type: 'stdio',
+    command: 'npx',
+    args: ['my-mcp-package@latest', 'mcp'],  // Or just 'my-mcp' if using bin
+    env: {
+      ...process.env,
+      MY_MCP_API_KEY: process.env.MY_MCP_API_KEY || ''
+    }
+  };
+}
+```
+
+#### Step 3: Enable and Use
+
+```bash
+# Enable MCP package
+export ENABLE_MY_MCP_PACKAGE=true
+export MY_MCP_API_KEY=your-api-key
+
+# Run agent (will auto-install via npx)
+npx agentic-flow --agent coder --task "Use tools from my-mcp-package"
+```
+
+**Pros:**
+- ✅ Easy distribution via NPM
+- ✅ Version management
+- ✅ Auto-installation via npx
+- ✅ Community sharing
+
+**Cons:**
+- ⚠️ Requires NPM publishing
+- ⚠️ Network dependency for first install
+- ⚠️ Subprocess overhead
+
+---
+
+## Environment Variables
+
+Create environment variables to enable/disable your MCP servers:
+
+```bash
+# In-SDK servers
+export ENABLE_CLAUDE_FLOW_SDK=true        # Built-in (6 tools)
+export ENABLE_MY_CUSTOM_MCP=true          # Your custom in-SDK server
+
+# External stdio servers
+export ENABLE_CLAUDE_FLOW_MCP=true        # claude-flow (101 tools)
+export ENABLE_FLOW_NEXUS_MCP=true         # flow-nexus (96 tools)
+export ENABLE_AGENTIC_PAYMENTS_MCP=true   # agentic-payments (10 tools)
+export ENABLE_MY_EXTERNAL_MCP=true        # Your external server
+export ENABLE_MY_MCP_PACKAGE=true         # Your NPM package
+```
+
+**Convention:**
+- In-SDK: `ENABLE_<NAME>_MCP=true`
+- External: `ENABLE_<NAME>_MCP=true`
+- Config: `<NAME>_API_KEY=xxx`, `<NAME>_CONFIG=xxx`
+
+---
+
+## Testing Your MCP Server
+
+### Test In-SDK Server
+
+```typescript
+// Create test file: src/mcp/__tests__/myCustomServer.test.ts
+import { myCustomServer } from '../myCustomServer.js';
+
+describe('MyCustomServer', () => {
+  it('should calculate correctly', async () => {
+    const tools = myCustomServer.tools;
+    const calculateTool = tools.find(t => t.name === 'calculate');
+
+    const result = await calculateTool?.execute({
+      operation: 'add',
+      a: 10,
+      b: 20
+    });
+
+    expect(result.result).toBe(30);
+  });
+});
+```
+
+### Test External Server
+
+```bash
+# Test standalone server
+echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node my-mcp-server/index.js
+
+# Test with agentic-flow
+export ENABLE_MY_EXTERNAL_MCP=true
+npx agentic-flow --agent coder --task "List all available tools"
+```
+
+### Integration Test
+
+```bash
+# Enable your server
+export ENABLE_MY_CUSTOM_MCP=true
+
+# Run with verbose logging
+npx agentic-flow --agent coder --task "Test my custom tools" --verbose
+
+# Check logs
+# Should see: "Registered MCP server: my-custom-server"
+```
+
+---
+
+## Code Reference: Existing Integrations
+
+### In-SDK Example: claude-flow-sdk
+
+**File:** `src/mcp/claudeFlowSdkServer.ts`
+
+```typescript
+export const claudeFlowSdkServer = createSdkMcpServer({
+  name: 'claude-flow-sdk',
+  version: '1.0.0',
+  tools: [
+    tool('memory_store', 'Store value in memory', {...}),
+    tool('memory_retrieve', 'Retrieve value from memory', {...}),
+    tool('swarm_init', 'Initialize swarm', {...}),
+    // ... 6 tools total
+  ]
+});
+```
+
+**Registration:** `src/agents/claudeAgent.ts:128-130`
+```typescript
+if (process.env.ENABLE_CLAUDE_FLOW_SDK === 'true') {
+  mcpServers['claude-flow-sdk'] = claudeFlowSdkServer;
+}
+```
+
+### External Example: claude-flow
+
+**Registration:** `src/agents/claudeAgent.ts:134-145`
+```typescript
+if (process.env.ENABLE_CLAUDE_FLOW_MCP === 'true') {
+  mcpServers['claude-flow'] = {
+    type: 'stdio',
+    command: 'npx',
+    args: ['claude-flow@alpha', 'mcp', 'start'],
+    env: {
+      ...process.env,
+      MCP_AUTO_START: 'true',
+      PROVIDER: provider
+    }
+  };
+}
+```
+
+### External Example: flow-nexus
+
+**Registration:** `src/agents/claudeAgent.ts:147-157`
+```typescript
+if (process.env.ENABLE_FLOW_NEXUS_MCP === 'true') {
+  mcpServers['flow-nexus'] = {
+    type: 'stdio',
+    command: 'npx',
+    args: ['flow-nexus@latest', 'mcp', 'start'],
+    env: {
+      ...process.env,
+      FLOW_NEXUS_AUTO_START: 'true'
+    }
+  };
+}
+```
+
+---
+
+## Troubleshooting
+
+### MCP Server Not Loading
+
+**Problem:** Agent doesn't see your MCP tools
+
+**Solutions:**
+```bash
+# 1. Check environment variable
+echo $ENABLE_MY_CUSTOM_MCP  # Should be "true"
+
+# 2. Rebuild if in-SDK
+npm run build
+
+# 3. Check logs
+npx agentic-flow --agent coder --task "test" --verbose
+# Should see: "Registered MCP server: my-custom-server"
+
+# 4. Test server directly
+node my-mcp-server/index.js  # For external servers
+```
+
+### Tools Not Executing
+
+**Problem:** Tools registered but don't execute
+
+**Solutions:**
+```bash
+# 1. Check tool name in task
+# Correct: "Use the calculate tool to add 5 and 10"
+# Wrong: "Calculate 5 + 10" (doesn't reference tool)
+
+# 2. Check Zod schema validation
+# Ensure parameters match schema exactly
+
+# 3. Add logging
+logger.info('Tool executed', { toolName, params, result });
+```
+
+### Subprocess Failures
+
+**Problem:** External MCP server crashes or times out
+
+**Solutions:**
+```bash
+# 1. Test server standalone
+node my-mcp-server/index.js
+# Type: {"jsonrpc":"2.0","method":"tools/list","id":1}
+
+# 2. Check command/args
+# Ensure absolute path or npx for NPM packages
+
+# 3. Increase timeout
+mcpServers['my-server'] = {
+  type: 'stdio',
+  command: 'node',
+  args: ['/path/to/server.js'],
+  timeout: 60000  // 60 seconds
+};
+```
+
+### Type Errors
+
+**Problem:** TypeScript errors with In-SDK tools
+
+**Solutions:**
+```typescript
+// Ensure correct imports
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { z } from 'zod';
+
+// Rebuild after changes
+npm run build
+
+// Check types
+npx tsc --noEmit
+```
+
+---
+
+## Best Practices
+
+1. **Start with In-SDK for Simple Tools**
+   - Faster development iteration
+   - Better type safety
+   - Easier debugging
+
+2. **Use External for Complex Operations**
+   - System commands
+   - Heavy computations
+   - External APIs
+
+3. **Use NPM Packages for Distribution**
+   - Share with community
+   - Version management
+   - Easy updates
+
+4. **Always Add Logging**
+   ```typescript
+   logger.info('Tool executed', { tool, params, result });
+   ```
+
+5. **Test Standalone First**
+   - Test MCP server independently
+   - Then integrate with agentic-flow
+
+6. **Document Your Tools**
+   - Clear descriptions
+   - Parameter documentation
+   - Example usage
+
+---
+
+## Summary
+
+**Quick Reference:**
+
+| Need | Method | Steps |
+|------|--------|-------|
+| Simple custom tool | In-SDK | 1. Create `src/mcp/myServer.ts`<br>2. Register in `claudeAgent.ts`<br>3. `npm run build` |
+| Local MCP server | Stdio | 1. Create standalone server<br>2. Register with command/args<br>3. Enable env var |
+| Published package | NPM | 1. Publish to NPM<br>2. Register with `npx` command<br>3. Enable env var |
+
+**Next Steps:**
+- See `src/mcp/claudeFlowSdkServer.ts` for in-SDK example
+- See `src/agents/claudeAgent.ts:134-169` for external examples
+- Read [MCP Specification](https://modelcontextprotocol.io) for protocol details
+
+---
+
+**Need help?** Open an issue on [GitHub](https://github.com/ruvnet/agentic-flow/issues) or check the [MCP docs](https://modelcontextprotocol.io).