tasq/node_modules/agentic-flow/docs/integrations/fastmcp-poc-integration.md

FastMCP POC Integration Guide

Overview

The FastMCP POC provides a minimal stdio-based MCP server with 2 basic tools (memory_store, memory_retrieve) to validate the fastmcp framework integration with agentic-flow.

Architecture

agentic-flow/
├── src/mcp/fastmcp/
│   ├── servers/
│   │   └── poc-stdio.ts      # POC server (stdio transport)
│   ├── tools/
│   │   └── memory/
│   │       ├── store.ts      # Memory store tool
│   │       └── retrieve.ts   # Memory retrieve tool
│   ├── types/
│   │   └── index.ts          # TypeScript definitions
│   └── config/
│       └── mcp-config.json   # MCP client configuration

Installation

Already installed as part of agentic-flow:

npm install  # fastmcp & zod included
npm run build

Usage

Option 1: Direct CLI Test

# Run test script
npm run test:fastmcp

# Or manually:
npm run mcp:fastmcp-poc

Option 2: Claude Code Integration

Add to Claude Code's MCP settings (~/.config/claude/mcp.json):

{
  "mcpServers": {
    "fastmcp-poc": {
      "command": "node",
      "args": ["/workspaces/flow-cloud/docker/claude-agent-sdk/dist/mcp/fastmcp/servers/poc-stdio.js"],
      "env": {}
    }
  }
}

Option 3: NPX Integration

# From package root
npx agentic-flow mcp:fastmcp-poc

Available Tools

1. memory_store

Store a value in persistent memory via claude-flow.

Parameters:

• key (string, required): Memory key
• value (string, required): Value to store
• namespace (string, optional): Memory namespace (default: "default")
• ttl (number, optional): Time-to-live in seconds

Example:

{
  "name": "memory_store",
  "arguments": {
    "key": "test-key",
    "value": "test-value",
    "namespace": "poc-test",
    "ttl": 3600
  }
}

Returns:

{
  "success": true,
  "key": "test-key",
  "namespace": "poc-test",
  "size": 10,
  "ttl": 3600,
  "timestamp": "2025-10-03T20:41:00.000Z",
  "message": "Memory stored successfully"
}

2. memory_retrieve

Retrieve a value from persistent memory.

Parameters:

• key (string, required): Memory key
• namespace (string, optional): Memory namespace (default: "default")

Example:

{
  "name": "memory_retrieve",
  "arguments": {
    "key": "test-key",
    "namespace": "poc-test"
  }
}

Returns:

{
  "success": true,
  "key": "test-key",
  "namespace": "poc-test",
  "value": "test-value",
  "timestamp": "2025-10-03T20:42:00.000Z"
}

Testing

Automated Test

npm run test:fastmcp

Manual Test with MCP Protocol

# Test memory_store
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"memory_store","arguments":{"key":"test","value":"hello","namespace":"poc"}}}' | npm run mcp:fastmcp-poc

# Test memory_retrieve
echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"memory_retrieve","arguments":{"key":"test","namespace":"poc"}}}' | npm run mcp:fastmcp-poc

Integration Status

✅ Phase 0 Complete - POC with stdio transport

• Created POC server with 2 tools
• Implemented stdio transport
• Tools use claude-flow backend via execSync
• TypeScript compilation successful
• Test scripts created
• MCP configuration provided

🔄 Phase 1 Pending - In-process migration (claude-flow-sdk)

• Migrate 6 claude-flow-sdk tools to fastmcp
• Remove execSync, use direct imports
• Validate all tools work in stdio

Known Limitations

1. Backend Dependency: Currently calls npx claude-flow@alpha via execSync

   • Phase 1 will replace with direct imports for in-process execution

2. Progress Reporting: Removed temporarily (fastmcp API investigation needed)

   • Context.onProgress not available in current fastmcp API

3. Error Handling: Basic throw-based errors

   • Will be enhanced with structured error types in Phase 1

Next Steps (Phase 1)

1. Migrate claude-flow-sdk tools (6 tools):

   • memory_store, memory_retrieve, memory_search
   • swarm_init, agent_spawn, task_orchestrate

2. Replace execSync with direct imports:

   // Before (Phase 0):
   const result = execSync(`npx claude-flow@alpha memory store ...`);
   
   // After (Phase 1):
   import { MemoryManager } from '../../memory/manager.js';
   const memory = new MemoryManager();
   const result = await memory.store(key, value, namespace, ttl);
   

3. Add progress reporting when fastmcp API clarified

4. Implement comprehensive error types

Resources

• FastMCP Implementation Plan: docs/mcp/fastmcp-implementation-plan.md
• POC Server: src/mcp/fastmcp/servers/poc-stdio.ts
• Tool Definitions: src/mcp/fastmcp/tools/memory/
• Test Script: scripts/test-fastmcp-poc.sh
• MCP Config: src/mcp/fastmcp/config/mcp-config.json