agentic-flow 1.9.0 → 1.9.1

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

@@ -1,642 +0,0 @@
-# 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).