npm - agentic-flow - Versions diffs - 1.9.0 → 1.9.1 - Mend

agentic-flow 1.9.0 → 1.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1223) hide show

package/docs/guides/MCP-AUTHENTICATION.md DELETED Viewed

@@ -1,2017 +0,0 @@
-# MCP Authentication & Setup Guide
-**Complete authentication guide for all MCP servers**
-Version: 2.0.0 | Last Updated: 2025-10-22
----
-## Table of Contents
-1. [Overview](#overview)
-2. [Authentication Matrix](#authentication-matrix)
-3. [AgentDB Setup](#agentdb-setup)
-4. [Claude Flow Setup](#claude-flow-setup)
-5. [Flow Nexus Authentication](#flow-nexus-authentication)
-6. [Agentic Payments Authentication](#agentic-payments-authentication)
-7. [Environment Configuration](#environment-configuration)
-8. [MCP Server Registration](#mcp-server-registration)
-9. [Verification & Testing](#verification--testing)
-10. [Security Best Practices](#security-best-practices)
-11. [Troubleshooting Authentication Errors](#troubleshooting-authentication-errors)
----
-## Overview
-MCP (Model Context Protocol) servers provide 233+ tools for AI agent orchestration. Each server has different authentication requirements:
-| Server | Auth Required | Auth Type | Setup Time |
-|--------|---------------|-----------|------------|
-| **AgentDB** | ❌ No | Local database | < 1 minute |
-| **Claude Flow** | ❌ No | Local orchestration | < 1 minute |
-| **Flow Nexus** | ✅ Yes | Email/password registration | 2-3 minutes |
-| **Agentic Payments** | ✅ Yes | Ed25519 keypair | < 1 minute |
-**Total Setup Time:** 5-7 minutes for all servers
----
-## Authentication Matrix
-### Quick Reference
-```
-┌─────────────────┬─────────────┬──────────────┬─────────────────────┐
-│ Server          │ Auth Needed │ Storage      │ Key Management      │
-├─────────────────┼─────────────┼──────────────┼─────────────────────┤
-│ AgentDB         │ No          │ Local SQLite │ None                │
-│ Claude Flow     │ No          │ Local        │ None                │
-│ Flow Nexus      │ Yes         │ Cloud        │ Session token       │
-│ Agentic Payments│ Yes         │ None         │ Ed25519 private key │
-└─────────────────┴─────────────┴──────────────┴─────────────────────┘
-```
-### Authentication Flow
-```mermaid
-graph TD
-    A[Start] --> B{Need AgentDB?}
-    B -->|Yes| C[Install AgentDB - No Auth]
-    B -->|No| D{Need Claude Flow?}
-    C --> D
-    D -->|Yes| E[Install Claude Flow - No Auth]
-    D -->|No| F{Need Flow Nexus?}
-    E --> F
-    F -->|Yes| G[Register & Login Flow Nexus]
-    F -->|No| H{Need Agentic Payments?}
-    G --> H
-    H -->|Yes| I[Generate Ed25519 Keypair]
-    H -->|No| J[All Set!]
-    I --> J
-```
----
-## AgentDB Setup
-AgentDB provides state-of-the-art agent memory with no authentication required.
-### Features
-- **20+ memory tools**
-- **Causal Memory Graph** - Track cause-effect relationships
-- **Explainable Recall** - Certificate-based explanations
-- **Reflexion Memory** - Self-critique and improvement
-- **Skill Library** - Reusable agent patterns
-- **Nightly Learner** - Pattern discovery
-### Installation
-```bash
-# Install AgentDB MCP server
-claude mcp add agentdb npx agentdb mcp
-# Verify installation
-claude mcp list
-```
-### Configuration
-No authentication required. AgentDB stores data locally in SQLite.
-**Default Database Location:**
-```
-/workspaces/agentic-flow/.swarm/memory.db
-```
-### Environment Variables (Optional)
-```bash
-# Custom database path
-AGENTDB_PATH=/path/to/custom/memory.db
-# Enable debug logging
-AGENTDB_DEBUG=true
-# Set default vector dimensions
-AGENTDB_VECTOR_DIM=1536
-```
-### Example Usage
-```javascript
-// No authentication needed - works immediately
-mcp__agentdb__causal_add_edge({
-  cause: "user_request",
-  effect: "api_call",
-  strength: 0.9,
-  metadata: {
-    timestamp: new Date().toISOString()
-  }
-});
-// Query causal relationships
-const results = mcp__agentdb__causal_query({
-  node_id: "api_call",
-  direction: "incoming",
-  limit: 10
-});
-```
-### Verification
-```bash
-# Test AgentDB connectivity
-npx agentdb test
-# Check database status
-npx agentdb status
-# View memory statistics
-npx agentdb stats
-```
----
-## Claude Flow Setup
-Claude Flow provides local orchestration with 101 tools and no authentication.
-### Features
-- **Swarm orchestration** - Multi-agent coordination
-- **Memory management** - Persistent agent memory
-- **Neural networks** - WASM-accelerated AI
-- **GitHub integration** - Repository automation
-- **Performance monitoring** - Real-time metrics
-### Installation
-```bash
-# Install Claude Flow MCP server
-claude mcp add claude-flow npx claude-flow@alpha mcp start
-# Verify installation
-claude mcp list
-```
-### Configuration
-No authentication required. All operations run locally.
-### Environment Variables (Optional)
-```bash
-# Enable hooks for automation
-CLAUDE_FLOW_HOOKS_ENABLED=true
-# Custom memory path
-CLAUDE_FLOW_MEMORY_PATH=/path/to/memory
-# Enable neural features
-CLAUDE_FLOW_NEURAL_ENABLED=true
-# Set swarm defaults
-CLAUDE_FLOW_MAX_AGENTS=10
-CLAUDE_FLOW_DEFAULT_TOPOLOGY=mesh
-```
-### Example Usage
-```javascript
-// No authentication needed
-mcp__claude-flow__swarm_init({
-  topology: 'mesh',
-  maxAgents: 8,
-  strategy: 'balanced'
-});
-// Spawn agents
-mcp__claude-flow__agent_spawn({
-  type: 'coder',
-  name: 'backend-agent',
-  capabilities: ['nodejs', 'express', 'postgres']
-});
-// Store memory
-mcp__claude-flow__memory_usage({
-  action: 'store',
-  key: 'swarm/config',
-  namespace: 'default',
-  value: JSON.stringify({ initialized: true })
-});
-```
-### Verification
-```bash
-# Test Claude Flow connectivity
-npx claude-flow@alpha test
-# Check swarm status
-npx claude-flow@alpha swarm status
-# View hooks configuration
-npx claude-flow@alpha hooks list
-```
----
-## Flow Nexus Authentication
-Flow Nexus requires registration for cloud-based features (96 tools).
-### Features
-- **E2B Sandboxes** - Isolated code execution
-- **Cloud workflows** - Event-driven automation
-- **Template marketplace** - Pre-built solutions
-- **Neural training** - Distributed AI
-- **Real-time streaming** - Live execution monitoring
-- **Storage & databases** - Cloud persistence
-### Registration Process
-#### Method 1: CLI Registration (Recommended)
-```bash
-# Register new account
-npx flow-nexus@latest register
-# Follow prompts:
-# Email: your-email@example.com
-# Password: [secure-password]
-# Full Name: Your Name (optional)
-```
-#### Method 2: MCP Tool Registration
-```javascript
-// Register via MCP tool
-mcp__flow-nexus__user_register({
-  email: 'your-email@example.com',
-  password: 'YourSecureP@ssw0rd!',
-  full_name: 'Your Name'  // Optional
-});
-// Response:
-// {
-//   success: true,
-//   message: 'Registration successful. Please verify your email.',
-//   user_id: 'usr_abc123def456'
-// }
-```
-#### Email Verification
-```bash
-# Check your email for verification link
-# Or use verification token:
-npx flow-nexus@latest verify-email --token YOUR_TOKEN
-```
-```javascript
-// Via MCP tool
-mcp__flow-nexus__user_verify_email({
-  token: 'verify_token_from_email'
-});
-```
-### Login Process
-#### Method 1: CLI Login
-```bash
-# Login to existing account
-npx flow-nexus@latest login
-# Follow prompts:
-# Email: your-email@example.com
-# Password: [your-password]
-```
-#### Method 2: MCP Tool Login
-```javascript
-// Login via MCP tool
-mcp__flow-nexus__user_login({
-  email: 'your-email@example.com',
-  password: 'YourSecureP@ssw0rd!'
-});
-// Response:
-// {
-//   success: true,
-//   session_token: 'sess_abc123def456',
-//   user_id: 'usr_abc123def456',
-//   tier: 'free',
-//   expires_at: '2025-10-23T14:00:00Z'
-// }
-```
-### Session Management
-```javascript
-// Check authentication status
-mcp__flow-nexus__auth_status({
-  detailed: true
-});
-// Response:
-// {
-//   authenticated: true,
-//   user_id: 'usr_abc123def456',
-//   email: 'your-email@example.com',
-//   tier: 'free',
-//   credits_remaining: 100,
-//   session_expires: '2025-10-23T14:00:00Z'
-// }
-// Logout
-mcp__flow-nexus__user_logout();
-```
-### MCP Server Registration with Auth
-```bash
-# Add Flow Nexus MCP server
-claude mcp add flow-nexus npx flow-nexus@latest mcp start
-# Server automatically uses cached session token
-```
-### Password Reset
-```bash
-# Request password reset
-npx flow-nexus@latest reset-password --email your-email@example.com
-```
-```javascript
-// Via MCP tool
-mcp__flow-nexus__user_reset_password({
-  email: 'your-email@example.com'
-});
-// Check email for reset token, then:
-mcp__flow-nexus__user_update_password({
-  token: 'reset_token_from_email',
-  new_password: 'NewSecureP@ssw0rd!'
-});
-```
-### Example Usage (After Authentication)
-```javascript
-// Create sandbox (requires authentication)
-const sandbox = mcp__flow-nexus__sandbox_create({
-  template: 'node',
-  name: 'my-sandbox',
-  env_vars: {
-    NODE_ENV: 'development'
-  }
-});
-// Execute code in sandbox
-mcp__flow-nexus__sandbox_execute({
-  sandbox_id: sandbox.data.sandbox_id,
-  code: 'console.log("Hello from sandbox!");'
-});
-// Create workflow
-mcp__flow-nexus__workflow_create({
-  name: 'data-pipeline',
-  steps: [
-    { action: 'fetch-data', agent: 'researcher' },
-    { action: 'process-data', agent: 'analyst' },
-    { action: 'store-results', agent: 'coordinator' }
-  ]
-});
-```
-### Tier Upgrades
-```javascript
-// Check current tier
-mcp__flow-nexus__user_profile({
-  user_id: 'usr_abc123def456'
-});
-// Upgrade to Pro tier
-mcp__flow-nexus__user_upgrade({
-  user_id: 'usr_abc123def456',
-  tier: 'pro'  // Options: 'pro', 'enterprise'
-});
-```
-### Verification
-```bash
-# Test Flow Nexus authentication
-npx flow-nexus@latest test-auth
-# Check balance
-npx flow-nexus@latest balance
-# View profile
-npx flow-nexus@latest profile
-```
----
-## Agentic Payments Authentication
-Agentic Payments uses Ed25519 cryptographic keypairs for autonomous agent payment authorization.
-### Features
-- **Active Mandates** - Time-limited payment authorization
-- **Intent-based payments** - High-level purchase approval
-- **Cart-based payments** - Specific item approval
-- **Multi-agent consensus** - Byzantine fault-tolerant verification
-- **Revocation** - Cancel mandates anytime
-### Keypair Generation
-#### Method 1: MCP Tool (Recommended for Production)
-```javascript
-// Generate agent identity with Ed25519 keypair
-const identity = mcp__agentic-payments__generate_agent_identity({
-  include_private_key: true  // ⚠️ SECURE STORAGE REQUIRED
-});
-// Response:
-// {
-//   success: true,
-//   agent_id: 'agent_abc123def456',
-//   public_key: 'ed25519_public_key_base64_encoded',
-//   private_key: 'ed25519_private_key_base64_encoded',  // Store securely!
-//   created_at: '2025-10-22T14:00:00Z'
-// }
-```
-#### Method 2: CLI Generation
-```bash
-# Generate keypair via CLI
-npx agentic-payments generate-keypair --output ./keypair.json
-# Output file structure:
-# {
-#   "agent_id": "agent_abc123def456",
-#   "public_key": "ed25519_public_key_base64",
-#   "private_key": "ed25519_private_key_base64"
-# }
-```
-### Secure Key Storage
-**❌ NEVER DO THIS:**
-```javascript
-// NEVER hardcode private keys
-const PRIVATE_KEY = 'ed25519_private_key_base64';  // INSECURE!
-// NEVER commit keys to git
-// NEVER log private keys
-console.log(identity.private_key);  // INSECURE!
-```
-**✅ SECURE STORAGE OPTIONS:**
-#### Option 1: Environment Variables (Development)
-```bash
-# Store in .env file (add .env to .gitignore)
-AGENTIC_PAYMENTS_AGENT_ID=agent_abc123def456
-AGENTIC_PAYMENTS_PUBLIC_KEY=ed25519_public_key_base64
-AGENTIC_PAYMENTS_PRIVATE_KEY=ed25519_private_key_base64
-```
-```javascript
-// Load from environment
-const AGENT_ID = process.env.AGENTIC_PAYMENTS_AGENT_ID;
-const PRIVATE_KEY = process.env.AGENTIC_PAYMENTS_PRIVATE_KEY;
-const PUBLIC_KEY = process.env.AGENTIC_PAYMENTS_PUBLIC_KEY;
-```
-#### Option 2: Encrypted Key Store (Production)
-```javascript
-import { encrypt, decrypt } from './encryption';
-// Encrypt private key with user password
-const encryptedKey = encrypt(identity.private_key, userPassword);
-// Store encrypted key in database
-await db.store('agent_private_keys', {
-  agent_id: identity.agent_id,
-  encrypted_private_key: encryptedKey,
-  public_key: identity.public_key
-});
-// Decrypt when needed
-const privateKey = decrypt(encryptedKey, userPassword);
-```
-#### Option 3: Hardware Security Module (Enterprise)
-```javascript
-// Use HSM for key storage (recommended for production)
-import { HSM } from './hsm-provider';
-const hsm = new HSM({
-  endpoint: process.env.HSM_ENDPOINT,
-  credentials: process.env.HSM_CREDENTIALS
-});
-// Store key in HSM
-await hsm.storeKey(identity.private_key, 'agent_payment_key');
-// Sign mandates using HSM (key never leaves secure hardware)
-const signature = await hsm.sign('agent_payment_key', mandateData);
-```
-### Creating Payment Mandates
-```javascript
-// 1. Create Active Mandate
-const mandate = mcp__agentic-payments__create_active_mandate({
-  agent: 'shopping-bot@agentics',
-  holder: PUBLIC_KEY,  // Your agent's public key
-  amount: 12000,  // $120.00 in cents
-  currency: 'USD',
-  period: 'monthly',
-  kind: 'intent',
-  expires_at: '2025-11-22T00:00:00Z',
-  merchant_allow: ['amazon.com', 'ebay.com'],
-  merchant_block: ['gambling-site.com']
-});
-// 2. Sign mandate with private key
-const signedMandate = mcp__agentic-payments__sign_mandate({
-  mandate: mandate.data,
-  private_key: PRIVATE_KEY  // From secure storage
-});
-// 3. Verify signature (optional)
-const verification = mcp__agentic-payments__verify_mandate({
-  signed_mandate: signedMandate.data,
-  check_guards: true  // Check expiration, revocation
-});
-```
-### Intent-Based Payments
-```javascript
-// High-level purchase authorization
-const intentMandate = mcp__agentic-payments__create_intent_mandate({
-  merchant_id: 'merchant_abc123',
-  customer_id: 'customer_def456',
-  intent: 'Purchase laptop for development work',
-  max_amount: 2000,  // $2000 maximum
-  currency: 'USD',
-  expires_at: Math.floor(Date.now() / 1000) + 86400  // 24 hours
-});
-```
-### Cart-Based Payments
-```javascript
-// Specific item approval
-const cartMandate = mcp__agentic-payments__create_cart_mandate({
-  merchant_id: 'merchant_abc123',
-  customer_id: 'customer_def456',
-  items: [
-    { id: 'item_1', name: 'Laptop', quantity: 1, unit_price: 150000 },
-    { id: 'item_2', name: 'Mouse', quantity: 2, unit_price: 2500 }
-  ],
-  currency: 'USD'
-});
-```
-### Mandate Revocation
-```javascript
-// Revoke a mandate
-mcp__agentic-payments__revoke_mandate({
-  mandate_id: 'mandate_abc123def456',
-  reason: 'User requested cancellation'
-});
-// List all revoked mandates
-const revocations = mcp__agentic-payments__list_revocations();
-```
-### Multi-Agent Consensus
-```javascript
-// Verify payment with Byzantine fault-tolerant consensus
-const consensus = mcp__agentic-payments__verify_consensus({
-  message: 'payment_request_data_base64',
-  signature: 'signature_base64',
-  public_key: 'agent_public_key_base64',
-  agent_public_keys: [
-    'agent1_public_key',
-    'agent2_public_key',
-    'agent3_public_key',
-    'agent4_public_key'
-  ],
-  consensus_threshold: 0.67  // 67% agreement required
-});
-```
-### Example Workflow
-```javascript
-// Complete payment authorization workflow
-async function authorizeAgentPayment() {
-  // 1. Generate agent identity (one-time)
-  const identity = mcp__agentic-payments__generate_agent_identity({
-    include_private_key: true
-  });
-  // 2. Store keys securely
-  await storeKeys(identity);
-  // 3. Create mandate
-  const mandate = mcp__agentic-payments__create_active_mandate({
-    agent: 'shopping-bot@agentics',
-    holder: identity.public_key,
-    amount: 10000,  // $100
-    currency: 'USD',
-    period: 'single',
-    kind: 'intent',
-    expires_at: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString()
-  });
-  // 4. Sign mandate
-  const signed = mcp__agentic-payments__sign_mandate({
-    mandate: mandate.data,
-    private_key: identity.private_key
-  });
-  // 5. Verify before use
-  const verified = mcp__agentic-payments__verify_mandate({
-    signed_mandate: signed.data,
-    check_guards: true
-  });
-  if (verified.success && verified.data.valid) {
-    console.log('Payment authorization ready:', signed.data.mandate_id);
-    return signed.data;
-  } else {
-    throw new Error('Mandate verification failed');
-  }
-}
-```
-### Verification
-```bash
-# Test keypair generation
-npx agentic-payments test-keypair
-# Verify signature
-npx agentic-payments verify-signature \
-  --message "test message" \
-  --signature "signature_base64" \
-  --public-key "public_key_base64"
-```
----
-## Environment Configuration
-### Complete .env File Template
-```bash
-# ============================================
-# MCP Authentication Configuration
-# ============================================
-# -----------------
-# AgentDB (No Auth)
-# -----------------
-AGENTDB_PATH=/workspaces/agentic-flow/.swarm/memory.db
-AGENTDB_DEBUG=false
-AGENTDB_VECTOR_DIM=1536
-# ---------------------
-# Claude Flow (No Auth)
-# ---------------------
-CLAUDE_FLOW_HOOKS_ENABLED=true
-CLAUDE_FLOW_MEMORY_PATH=/workspaces/agentic-flow/.swarm
-CLAUDE_FLOW_NEURAL_ENABLED=true
-CLAUDE_FLOW_MAX_AGENTS=10
-CLAUDE_FLOW_DEFAULT_TOPOLOGY=mesh
-# --------------------------
-# Flow Nexus (Auth Required)
-# --------------------------
-# Register at: npx flow-nexus@latest register
-FLOW_NEXUS_EMAIL=your-email@example.com
-FLOW_NEXUS_SESSION_TOKEN=sess_abc123def456  # Auto-populated after login
-FLOW_NEXUS_USER_ID=usr_abc123def456  # Auto-populated after login
-# --------------------------------------
-# Agentic Payments (Keypair Required)
-# --------------------------------------
-# Generate with: mcp__agentic-payments__generate_agent_identity()
-AGENTIC_PAYMENTS_AGENT_ID=agent_abc123def456
-AGENTIC_PAYMENTS_PUBLIC_KEY=ed25519_public_key_base64_encoded
-AGENTIC_PAYMENTS_PRIVATE_KEY=ed25519_private_key_base64_encoded  # SECURE!
-# -----------------
-# Security Settings
-# -----------------
-# Encryption key for local key storage (generate with: openssl rand -hex 32)
-ENCRYPTION_KEY=your_32_byte_hex_encryption_key_here
-# Session timeout (in seconds)
-SESSION_TIMEOUT=3600
-# Enable debug logging (NEVER in production)
-MCP_DEBUG=false
-```
-### .env.example Template
-```bash
-# Copy this to .env and fill in your values
-# NEVER commit .env to git!
-# AgentDB
-AGENTDB_PATH=.swarm/memory.db
-# Claude Flow
-CLAUDE_FLOW_HOOKS_ENABLED=true
-# Flow Nexus (register first)
-FLOW_NEXUS_EMAIL=your-email@example.com
-# Agentic Payments (generate keypair first)
-AGENTIC_PAYMENTS_AGENT_ID=
-AGENTIC_PAYMENTS_PUBLIC_KEY=
-AGENTIC_PAYMENTS_PRIVATE_KEY=  # SECURE STORAGE REQUIRED
-# Security
-ENCRYPTION_KEY=  # Generate with: openssl rand -hex 32
-```
-### .gitignore Configuration
-```bash
-# Add to .gitignore to prevent committing secrets
-.env
-.env.local
-.env.*.local
-*.key
-*.pem
-keypair.json
-*-private-key.txt
-.swarm/*.db
-.swarm/*.db-journal
-```
-### Loading Environment Variables
-```javascript
-// Load environment variables
-import dotenv from 'dotenv';
-dotenv.config();
-// Validate required variables
-function validateEnvironment() {
-  const required = [
-    // Flow Nexus (if using)
-    'FLOW_NEXUS_EMAIL',
-    // Agentic Payments (if using)
-    'AGENTIC_PAYMENTS_AGENT_ID',
-    'AGENTIC_PAYMENTS_PUBLIC_KEY',
-    'AGENTIC_PAYMENTS_PRIVATE_KEY'
-  ];
-  const missing = required.filter(key => !process.env[key]);
-  if (missing.length > 0) {
-    console.error('Missing environment variables:', missing);
-    process.exit(1);
-  }
-}
-// Call on startup
-validateEnvironment();
-```
----
-## MCP Server Registration
-### Complete Registration Workflow
-#### Step 1: Install MCP Servers
-```bash
-# Install all MCP servers at once
-claude mcp add agentdb npx agentdb mcp && \
-claude mcp add claude-flow npx claude-flow@alpha mcp start && \
-claude mcp add flow-nexus npx flow-nexus@latest mcp start
-# Or install individually as needed
-```
-#### Step 2: Verify Installation
-```bash
-# List all installed MCP servers
-claude mcp list
-# Expected output:
-# ┌──────────────┬────────────────────────────────────┬────────┐
-# │ Name         │ Command                            │ Status │
-# ├──────────────┼────────────────────────────────────┼────────┤
-# │ agentdb      │ npx agentdb mcp                    │ Active │
-# │ claude-flow  │ npx claude-flow@alpha mcp start    │ Active │
-# │ flow-nexus   │ npx flow-nexus@latest mcp start    │ Active │
-# └──────────────┴────────────────────────────────────┴────────┘
-```
-#### Step 3: Test Connectivity
-```bash
-# Test each server
-npx agentdb test
-npx claude-flow@alpha test
-npx flow-nexus@latest test-auth  # Requires login
-```
-#### Step 4: Claude Code Configuration
-Claude Code automatically discovers MCP servers. Verify in Claude Code:
-```javascript
-// Test each server with a simple operation
-mcp__agentdb__test();  // Should return success
-mcp__claude-flow__swarm_status();  // Should return empty swarm list
-mcp__flow-nexus__auth_status();  // Should show auth status
-```
-### Server Management
-```bash
-# View server logs
-claude mcp logs agentdb
-claude mcp logs claude-flow
-claude mcp logs flow-nexus
-# Restart a server
-claude mcp restart flow-nexus
-# Remove a server
-claude mcp remove flow-nexus
-# Update server version
-claude mcp update claude-flow
-```
-### Custom MCP Configuration
-Create `.claude-mcp.json` in your project root:
-```json
-{
-  "mcpServers": {
-    "agentdb": {
-      "command": "npx",
-      "args": ["agentdb", "mcp"],
-      "env": {
-        "AGENTDB_PATH": ".swarm/memory.db",
-        "AGENTDB_DEBUG": "false"
-      }
-    },
-    "claude-flow": {
-      "command": "npx",
-      "args": ["claude-flow@alpha", "mcp", "start"],
-      "env": {
-        "CLAUDE_FLOW_HOOKS_ENABLED": "true",
-        "CLAUDE_FLOW_MAX_AGENTS": "10"
-      }
-    },
-    "flow-nexus": {
-      "command": "npx",
-      "args": ["flow-nexus@latest", "mcp", "start"],
-      "env": {
-        "FLOW_NEXUS_EMAIL": "${FLOW_NEXUS_EMAIL}",
-        "FLOW_NEXUS_SESSION_TOKEN": "${FLOW_NEXUS_SESSION_TOKEN}"
-      }
-    }
-  }
-}
-```
----
-## Verification & Testing
-### Complete Test Suite
-```bash
-# Create test script
-cat > test-mcp-auth.sh << 'EOF'
-#!/bin/bash
-echo "🔧 Testing MCP Server Authentication"
-echo "======================================"
-echo ""
-# 1. AgentDB (No Auth)
-echo "1️⃣ Testing AgentDB..."
-npx agentdb test
-if [ $? -eq 0 ]; then
-  echo "✅ AgentDB: PASSED (no auth required)"
-else
-  echo "❌ AgentDB: FAILED"
-fi
-echo ""
-# 2. Claude Flow (No Auth)
-echo "2️⃣ Testing Claude Flow..."
-npx claude-flow@alpha test
-if [ $? -eq 0 ]; then
-  echo "✅ Claude Flow: PASSED (no auth required)"
-else
-  echo "❌ Claude Flow: FAILED"
-fi
-echo ""
-# 3. Flow Nexus (Auth Required)
-echo "3️⃣ Testing Flow Nexus..."
-npx flow-nexus@latest test-auth
-if [ $? -eq 0 ]; then
-  echo "✅ Flow Nexus: PASSED (authenticated)"
-else
-  echo "❌ Flow Nexus: FAILED (login required)"
-  echo "   Run: npx flow-nexus@latest login"
-fi
-echo ""
-# 4. Agentic Payments (Keypair Required)
-echo "4️⃣ Testing Agentic Payments..."
-if [ -n "$AGENTIC_PAYMENTS_PUBLIC_KEY" ]; then
-  echo "✅ Agentic Payments: Keypair configured"
-else
-  echo "⚠️  Agentic Payments: Keypair not configured"
-  echo "   Generate with: mcp__agentic-payments__generate_agent_identity()"
-fi
-echo ""
-echo "======================================"
-echo "✅ Test Complete"
-EOF
-chmod +x test-mcp-auth.sh
-./test-mcp-auth.sh
-```
-### Individual Server Tests
-#### AgentDB Test
-```javascript
-// Test causal memory
-const testAgentDB = async () => {
-  try {
-    // Add causal edge
-    await mcp__agentdb__causal_add_edge({
-      cause: 'test_event_1',
-      effect: 'test_event_2',
-      strength: 0.8
-    });
-    // Query relationships
-    const results = await mcp__agentdb__causal_query({
-      node_id: 'test_event_2',
-      direction: 'incoming'
-    });
-    console.log('✅ AgentDB: Connected and working');
-    return true;
-  } catch (error) {
-    console.error('❌ AgentDB: Failed', error);
-    return false;
-  }
-};
-```
-#### Claude Flow Test
-```javascript
-// Test swarm orchestration
-const testClaudeFlow = async () => {
-  try {
-    // Initialize swarm
-    const swarm = await mcp__claude-flow__swarm_init({
-      topology: 'mesh',
-      maxAgents: 5
-    });
-    // Check status
-    const status = await mcp__claude-flow__swarm_status();
-    console.log('✅ Claude Flow: Connected and working');
-    return true;
-  } catch (error) {
-    console.error('❌ Claude Flow: Failed', error);
-    return false;
-  }
-};
-```
-#### Flow Nexus Test
-```javascript
-// Test cloud services
-const testFlowNexus = async () => {
-  try {
-    // Check auth status
-    const auth = await mcp__flow-nexus__auth_status({
-      detailed: true
-    });
-    if (!auth.authenticated) {
-      console.error('❌ Flow Nexus: Not authenticated');
-      console.log('   Run: npx flow-nexus@latest login');
-      return false;
-    }
-    // Test sandbox creation
-    const sandbox = await mcp__flow-nexus__sandbox_create({
-      template: 'node',
-      name: 'test-sandbox'
-    });
-    // Clean up
-    await mcp__flow-nexus__sandbox_delete({
-      sandbox_id: sandbox.data.sandbox_id
-    });
-    console.log('✅ Flow Nexus: Connected and authenticated');
-    return true;
-  } catch (error) {
-    console.error('❌ Flow Nexus: Failed', error);
-    return false;
-  }
-};
-```
-#### Agentic Payments Test
-```javascript
-// Test payment authorization
-const testAgenticPayments = async () => {
-  try {
-    // Generate test keypair
-    const identity = await mcp__agentic-payments__generate_agent_identity({
-      include_private_key: true
-    });
-    // Create test mandate
-    const mandate = await mcp__agentic-payments__create_active_mandate({
-      agent: 'test-agent@test',
-      holder: identity.public_key,
-      amount: 1000,
-      currency: 'USD',
-      period: 'single',
-      kind: 'intent',
-      expires_at: new Date(Date.now() + 86400000).toISOString()
-    });
-    // Sign mandate
-    const signed = await mcp__agentic-payments__sign_mandate({
-      mandate: mandate.data,
-      private_key: identity.private_key
-    });
-    // Verify signature
-    const verified = await mcp__agentic-payments__verify_mandate({
-      signed_mandate: signed.data
-    });
-    if (verified.data.valid) {
-      console.log('✅ Agentic Payments: Connected and working');
-      return true;
-    } else {
-      console.error('❌ Agentic Payments: Signature verification failed');
-      return false;
-    }
-  } catch (error) {
-    console.error('❌ Agentic Payments: Failed', error);
-    return false;
-  }
-};
-```
-### Comprehensive Test
-```javascript
-// Run all tests
-async function runAllTests() {
-  console.log('🔧 Testing MCP Server Authentication');
-  console.log('======================================\n');
-  const results = {
-    agentdb: await testAgentDB(),
-    claudeFlow: await testClaudeFlow(),
-    flowNexus: await testFlowNexus(),
-    agenticPayments: await testAgenticPayments()
-  };
-  console.log('\n======================================');
-  console.log('📊 Test Results:');
-  console.log(`   AgentDB: ${results.agentdb ? '✅' : '❌'}`);
-  console.log(`   Claude Flow: ${results.claudeFlow ? '✅' : '❌'}`);
-  console.log(`   Flow Nexus: ${results.flowNexus ? '✅' : '❌'}`);
-  console.log(`   Agentic Payments: ${results.agenticPayments ? '✅' : '❌'}`);
-  const allPassed = Object.values(results).every(r => r);
-  console.log(`\n${allPassed ? '✅ All tests passed!' : '⚠️  Some tests failed'}`);
-  return allPassed;
-}
-// Execute tests
-runAllTests();
-```
----
-## Security Best Practices
-### General Security Principles
-#### 1. Never Hardcode Secrets
-```javascript
-// ❌ WRONG: Hardcoded credentials
-const PASSWORD = 'mypassword123';
-const PRIVATE_KEY = 'ed25519_key_here';
-// ✅ CORRECT: Use environment variables
-const PASSWORD = process.env.FLOW_NEXUS_PASSWORD;
-const PRIVATE_KEY = process.env.AGENTIC_PAYMENTS_PRIVATE_KEY;
-```
-#### 2. Use .gitignore
-```bash
-# Always add to .gitignore
-.env
-.env.*
-*.key
-*.pem
-keypair.json
-*-private-key*
-.swarm/*.db
-```
-#### 3. Rotate Credentials Regularly
-```javascript
-// Set expiration for credentials
-const CREDENTIAL_EXPIRY_DAYS = 90;
-async function checkCredentialAge() {
-  const lastRotation = await getLastRotationDate();
-  const daysSince = Math.floor((Date.now() - lastRotation) / 86400000);
-  if (daysSince > CREDENTIAL_EXPIRY_DAYS) {
-    console.warn('⚠️  Credentials are old. Consider rotating.');
-    // Notify admin or auto-rotate
-  }
-}
-```
-#### 4. Use Strong Passwords
-```javascript
-// Password requirements
-const PASSWORD_REQUIREMENTS = {
-  minLength: 12,
-  requireUppercase: true,
-  requireLowercase: true,
-  requireNumbers: true,
-  requireSpecialChars: true
-};
-function validatePassword(password) {
-  if (password.length < PASSWORD_REQUIREMENTS.minLength) {
-    return { valid: false, error: 'Password too short' };
-  }
-  if (!/[A-Z]/.test(password)) {
-    return { valid: false, error: 'Missing uppercase letter' };
-  }
-  if (!/[a-z]/.test(password)) {
-    return { valid: false, error: 'Missing lowercase letter' };
-  }
-  if (!/[0-9]/.test(password)) {
-    return { valid: false, error: 'Missing number' };
-  }
-  if (!/[^A-Za-z0-9]/.test(password)) {
-    return { valid: false, error: 'Missing special character' };
-  }
-  return { valid: true };
-}
-```
-### Flow Nexus Security
-#### Secure Session Management
-```javascript
-// Store session token securely
-import { SecureStore } from './secure-store';
-async function storeFlowNexusSession(sessionToken) {
-  await SecureStore.set('flow_nexus_session', sessionToken, {
-    encrypt: true,
-    ttl: 3600  // 1 hour
-  });
-}
-async function getFlowNexusSession() {
-  return await SecureStore.get('flow_nexus_session');
-}
-// Clear session on logout
-async function logout() {
-  await mcp__flow-nexus__user_logout();
-  await SecureStore.delete('flow_nexus_session');
-}
-```
-#### Rate Limiting
-```javascript
-// Implement client-side rate limiting
-class RateLimiter {
-  constructor(maxRequests, windowMs) {
-    this.maxRequests = maxRequests;
-    this.windowMs = windowMs;
-    this.requests = [];
-  }
-  async checkLimit() {
-    const now = Date.now();
-    this.requests = this.requests.filter(t => now - t < this.windowMs);
-    if (this.requests.length >= this.maxRequests) {
-      const oldestRequest = this.requests[0];
-      const waitTime = this.windowMs - (now - oldestRequest);
-      throw new Error(`Rate limited. Wait ${waitTime}ms`);
-    }
-    this.requests.push(now);
-  }
-}
-const flowNexusLimiter = new RateLimiter(100, 3600000);  // 100/hour
-async function callFlowNexusTool(tool, params) {
-  await flowNexusLimiter.checkLimit();
-  return await tool(params);
-}
-```
-### Agentic Payments Security
-#### Private Key Protection
-```javascript
-// Encrypt private keys at rest
-import crypto from 'crypto';
-class KeyManager {
-  constructor(masterPassword) {
-    this.masterPassword = masterPassword;
-  }
-  encrypt(privateKey) {
-    const algorithm = 'aes-256-gcm';
-    const key = crypto.scryptSync(this.masterPassword, 'salt', 32);
-    const iv = crypto.randomBytes(16);
-    const cipher = crypto.createCipheriv(algorithm, key, iv);
-    let encrypted = cipher.update(privateKey, 'utf8', 'hex');
-    encrypted += cipher.final('hex');
-    const authTag = cipher.getAuthTag();
-    return {
-      encrypted,
-      iv: iv.toString('hex'),
-      authTag: authTag.toString('hex')
-    };
-  }
-  decrypt(encryptedData) {
-    const algorithm = 'aes-256-gcm';
-    const key = crypto.scryptSync(this.masterPassword, 'salt', 32);
-    const decipher = crypto.createDecipheriv(
-      algorithm,
-      key,
-      Buffer.from(encryptedData.iv, 'hex')
-    );
-    decipher.setAuthTag(Buffer.from(encryptedData.authTag, 'hex'));
-    let decrypted = decipher.update(encryptedData.encrypted, 'hex', 'utf8');
-    decrypted += decipher.final('utf8');
-    return decrypted;
-  }
-}
-// Usage
-const keyManager = new KeyManager(process.env.MASTER_PASSWORD);
-const encryptedKey = keyManager.encrypt(privateKey);
-// Store encryptedKey in database
-```
-#### Mandate Validation
-```javascript
-// Always validate mandates before signing
-function validateMandate(mandate) {
-  const now = Date.now();
-  const expiresAt = new Date(mandate.expires_at).getTime();
-  // Check expiration
-  if (expiresAt < now) {
-    throw new Error('Mandate already expired');
-  }
-  // Check amount
-  if (mandate.amount <= 0 || mandate.amount > 1000000) {  // $10k max
-    throw new Error('Invalid mandate amount');
-  }
-  // Check merchant restrictions
-  if (mandate.merchant_allow && mandate.merchant_allow.length === 0) {
-    throw new Error('Must specify allowed merchants');
-  }
-  // Warn if no time limit
-  const daysUntilExpiry = (expiresAt - now) / 86400000;
-  if (daysUntilExpiry > 90) {
-    console.warn('⚠️  Mandate expires in >90 days. Consider shorter period.');
-  }
-  return true;
-}
-// Use before signing
-const mandate = await mcp__agentic-payments__create_active_mandate({...});
-validateMandate(mandate.data);
-const signed = await mcp__agentic-payments__sign_mandate({
-  mandate: mandate.data,
-  private_key: privateKey
-});
-```
-#### Audit Logging
-```javascript
-// Log all payment operations
-class PaymentAuditLogger {
-  async log(action, data) {
-    const logEntry = {
-      timestamp: new Date().toISOString(),
-      action,
-      data: this.sanitize(data),
-      user_id: getCurrentUserId(),
-      ip_address: getClientIP()
-    };
-    await mcp__claude-flow__memory_usage({
-      action: 'store',
-      key: `audit/payment/${Date.now()}`,
-      namespace: 'security',
-      value: JSON.stringify(logEntry)
-    });
-  }
-  sanitize(data) {
-    // Remove sensitive fields
-    const sanitized = { ...data };
-    delete sanitized.private_key;
-    delete sanitized.password;
-    return sanitized;
-  }
-}
-const auditLogger = new PaymentAuditLogger();
-// Log all mandate operations
-await auditLogger.log('mandate_created', { mandate_id, amount, merchant });
-await auditLogger.log('mandate_signed', { mandate_id });
-await auditLogger.log('mandate_verified', { mandate_id, valid });
-```
-### Network Security
-#### HTTPS Only
-```javascript
-// Enforce HTTPS for all API calls
-function validateEndpoint(url) {
-  if (!url.startsWith('https://')) {
-    throw new Error('Only HTTPS endpoints allowed');
-  }
-}
-// Custom fetch wrapper
-async function secureFetch(url, options) {
-  validateEndpoint(url);
-  // Add security headers
-  const secureOptions = {
-    ...options,
-    headers: {
-      ...options.headers,
-      'X-Content-Type-Options': 'nosniff',
-      'X-Frame-Options': 'DENY',
-      'X-XSS-Protection': '1; mode=block'
-    }
-  };
-  return fetch(url, secureOptions);
-}
-```
-#### Certificate Pinning (Advanced)
-```javascript
-// Pin Flow Nexus TLS certificate
-import tls from 'tls';
-const PINNED_CERTIFICATES = {
-  'flow-nexus.ruv.io': [
-    'sha256/abc123...',  // Expected certificate hash
-    'sha256/def456...'   // Backup certificate hash
-  ]
-};
-function validateCertificate(hostname, cert) {
-  const hash = crypto.createHash('sha256')
-    .update(cert.raw)
-    .digest('base64');
-  const pinnedHashes = PINNED_CERTIFICATES[hostname];
-  if (!pinnedHashes || !pinnedHashes.includes(`sha256/${hash}`)) {
-    throw new Error('Certificate pinning validation failed');
-  }
-}
-```
----
-## Troubleshooting Authentication Errors
-### Common Issues & Solutions
-#### 1. "AUTH_REQUIRED" Error (Flow Nexus)
-**Symptoms:**
-```
-Error: AUTH_REQUIRED
-Message: Authentication required for this operation
-```
-**Diagnosis:**
-```bash
-# Check authentication status
-npx flow-nexus@latest test-auth
-# Or via MCP tool
-mcp__flow-nexus__auth_status({ detailed: true })
-```
-**Solutions:**
-**Solution A: Login Required**
-```bash
-# Login via CLI
-npx flow-nexus@latest login
-# Or via MCP tool
-mcp__flow-nexus__user_login({
-  email: 'your-email@example.com',
-  password: 'your-password'
-});
-```
-**Solution B: Session Expired**
-```bash
-# Re-login to get new session token
-npx flow-nexus@latest login
-# Verify session
-npx flow-nexus@latest profile
-```
-**Solution C: Invalid Credentials**
-```bash
-# Reset password
-npx flow-nexus@latest reset-password --email your-email@example.com
-# Check email for reset link
-# Set new password
-npx flow-nexus@latest update-password --token YOUR_TOKEN --password NEW_PASSWORD
-```
----
-#### 2. "INVALID_SIGNATURE" Error (Agentic Payments)
-**Symptoms:**
-```
-Error: INVALID_SIGNATURE
-Message: Ed25519 signature verification failed
-```
-**Diagnosis:**
-```javascript
-// Check keypair integrity
-const identity = mcp__agentic-payments__generate_agent_identity({
-  include_private_key: false  // Get public key only
-});
-console.log('Expected public key:', identity.public_key);
-console.log('Your public key:', process.env.AGENTIC_PAYMENTS_PUBLIC_KEY);
-// Test signing
-const testMandate = { test: 'data' };
-const signed = mcp__agentic-payments__sign_mandate({
-  mandate: testMandate,
-  private_key: process.env.AGENTIC_PAYMENTS_PRIVATE_KEY
-});
-const verified = mcp__agentic-payments__verify_mandate({
-  signed_mandate: signed.data
-});
-console.log('Signature valid:', verified.data.valid);
-```
-**Solutions:**
-**Solution A: Regenerate Keypair**
-```javascript
-// Generate new keypair
-const newIdentity = mcp__agentic-payments__generate_agent_identity({
-  include_private_key: true
-});
-// Update environment variables
-console.log('Update .env with:');
-console.log(`AGENTIC_PAYMENTS_AGENT_ID=${newIdentity.agent_id}`);
-console.log(`AGENTIC_PAYMENTS_PUBLIC_KEY=${newIdentity.public_key}`);
-console.log(`AGENTIC_PAYMENTS_PRIVATE_KEY=${newIdentity.private_key}`);
-```
-**Solution B: Check Key Encoding**
-```javascript
-// Verify base64 encoding
-function validateBase64(str) {
-  try {
-    return btoa(atob(str)) === str;
-  } catch (err) {
-    return false;
-  }
-}
-const publicKeyValid = validateBase64(process.env.AGENTIC_PAYMENTS_PUBLIC_KEY);
-const privateKeyValid = validateBase64(process.env.AGENTIC_PAYMENTS_PRIVATE_KEY);
-console.log('Public key valid:', publicKeyValid);
-console.log('Private key valid:', privateKeyValid);
-```
-**Solution C: Mandate Expired**
-```javascript
-// Check mandate expiration
-const mandate = { /* your mandate */ };
-const now = Date.now();
-const expiresAt = new Date(mandate.expires_at).getTime();
-if (expiresAt < now) {
-  console.error('Mandate expired. Create new mandate.');
-  // Create new mandate with future expiration
-}
-```
----
-#### 3. "MCP_SERVER_NOT_FOUND" Error
-**Symptoms:**
-```
-Error: MCP_SERVER_NOT_FOUND
-Message: MCP server 'flow-nexus' not found or not running
-```
-**Diagnosis:**
-```bash
-# List all MCP servers
-claude mcp list
-# Check if server is installed
-claude mcp status flow-nexus
-```
-**Solutions:**
-**Solution A: Install Server**
-```bash
-# Install missing server
-claude mcp add flow-nexus npx flow-nexus@latest mcp start
-# Verify installation
-claude mcp list
-```
-**Solution B: Restart Server**
-```bash
-# Restart server
-claude mcp restart flow-nexus
-# Check logs
-claude mcp logs flow-nexus
-```
-**Solution C: Fix Server Configuration**
-```bash
-# Remove and re-add server
-claude mcp remove flow-nexus
-claude mcp add flow-nexus npx flow-nexus@latest mcp start
-# Test connectivity
-npx flow-nexus@latest test
-```
----
-#### 4. "INSUFFICIENT_CREDITS" Error (Flow Nexus)
-**Symptoms:**
-```
-Error: INSUFFICIENT_CREDITS
-Message: Not enough credits to perform this operation
-```
-**Diagnosis:**
-```javascript
-// Check credit balance
-const balance = mcp__flow-nexus__check_balance();
-console.log('Current balance:', balance.data.credits);
-console.log('Current tier:', balance.data.tier);
-```
-**Solutions:**
-**Solution A: Add Credits**
-```javascript
-// Create payment link
-const payment = mcp__flow-nexus__create_payment_link({
-  amount: 50  // $50 USD
-});
-console.log('Payment URL:', payment.data.payment_url);
-// Visit URL to add credits
-```
-**Solution B: Upgrade Tier**
-```javascript
-// Upgrade to Pro tier (higher rate limits)
-mcp__flow-nexus__user_upgrade({
-  user_id: 'your_user_id',
-  tier: 'pro'
-});
-```
-**Solution C: Configure Auto-Refill**
-```javascript
-// Auto-refill when balance < $10
-mcp__flow-nexus__configure_auto_refill({
-  enabled: true,
-  threshold: 1000,  // 1000 credits = $10
-  amount: 2000      // Refill 2000 credits = $20
-});
-```
----
-#### 5. "RATE_LIMITED" Error
-**Symptoms:**
-```
-Error: RATE_LIMITED
-Message: Too many requests. Retry after 3600 seconds.
-```
-**Diagnosis:**
-```javascript
-// Check rate limits
-const stats = mcp__flow-nexus__usage_stats({
-  component: 'api'
-});
-console.log('Requests today:', stats.data.requests_today);
-console.log('Limit:', stats.data.rate_limit);
-console.log('Resets at:', stats.data.reset_at);
-```
-**Solutions:**
-**Solution A: Wait for Reset**
-```javascript
-// Calculate wait time
-const resetTime = new Date(stats.data.reset_at);
-const waitMs = resetTime - Date.now();
-const waitMinutes = Math.ceil(waitMs / 60000);
-console.log(`Wait ${waitMinutes} minutes for rate limit reset`);
-// Auto-retry after wait
-setTimeout(() => {
-  // Retry operation
-}, waitMs);
-```
-**Solution B: Upgrade Tier**
-```javascript
-// Pro tier has higher rate limits
-mcp__flow-nexus__user_upgrade({
-  user_id: 'your_user_id',
-  tier: 'pro'  // 10x higher rate limits
-});
-```
-**Solution C: Implement Backoff**
-```javascript
-// Exponential backoff retry
-async function retryWithBackoff(fn, maxRetries = 3) {
-  for (let i = 0; i < maxRetries; i++) {
-    try {
-      return await fn();
-    } catch (error) {
-      if (error.code === 'RATE_LIMITED' && i < maxRetries - 1) {
-        const waitMs = Math.pow(2, i) * 1000;  // 1s, 2s, 4s
-        console.log(`Rate limited. Waiting ${waitMs}ms...`);
-        await new Promise(resolve => setTimeout(resolve, waitMs));
-      } else {
-        throw error;
-      }
-    }
-  }
-}
-// Usage
-await retryWithBackoff(() => mcp__flow-nexus__sandbox_create({...}));
-```
----
-#### 6. "EMAIL_NOT_VERIFIED" Error (Flow Nexus)
-**Symptoms:**
-```
-Error: EMAIL_NOT_VERIFIED
-Message: Please verify your email address before using this service
-```
-**Diagnosis:**
-```javascript
-// Check verification status
-const profile = mcp__flow-nexus__user_profile({
-  user_id: 'your_user_id'
-});
-console.log('Email verified:', profile.data.email_verified);
-```
-**Solutions:**
-**Solution A: Check Email**
-```
-1. Check inbox for verification email from Flow Nexus
-2. Check spam/junk folder
-3. Click verification link in email
-```
-**Solution B: Resend Verification**
-```bash
-# Request new verification email
-npx flow-nexus@latest resend-verification --email your-email@example.com
-```
-**Solution C: Manual Verification**
-```javascript
-// Use verification token from email
-mcp__flow-nexus__user_verify_email({
-  token: 'verification_token_from_email'
-});
-```
----
-#### 7. Database Connection Errors (AgentDB)
-**Symptoms:**
-```
-Error: SQLITE_ERROR
-Message: unable to open database file
-```
-**Diagnosis:**
-```bash
-# Check database file
-ls -la .swarm/memory.db
-# Check permissions
-stat .swarm/memory.db
-# Test database
-npx agentdb status
-```
-**Solutions:**
-**Solution A: Create Database Directory**
-```bash
-# Create .swarm directory
-mkdir -p .swarm
-# Set permissions
-chmod 755 .swarm
-# Restart AgentDB
-claude mcp restart agentdb
-```
-**Solution B: Fix Permissions**
-```bash
-# Fix database permissions
-chmod 644 .swarm/memory.db
-# Fix directory permissions
-chmod 755 .swarm
-# Verify
-ls -la .swarm/
-```
-**Solution C: Reset Database**
-```bash
-# Backup existing database
-cp .swarm/memory.db .swarm/memory.db.backup
-# Remove corrupted database
-rm .swarm/memory.db
-# Restart AgentDB (will create new database)
-claude mcp restart agentdb
-# Test
-npx agentdb test
-```
----
-### Debug Mode
-Enable debug logging for detailed troubleshooting:
-```bash
-# Enable debug for all MCP servers
-export MCP_DEBUG=true
-# Or per-server
-export AGENTDB_DEBUG=true
-export CLAUDE_FLOW_DEBUG=true
-export FLOW_NEXUS_DEBUG=true
-# Run operation with logging
-mcp__flow-nexus__sandbox_create({...})
-# Logs will show:
-# [2025-10-22T14:00:00.000Z] MCP: Connecting to flow-nexus
-# [2025-10-22T14:00:00.100Z] MCP: Sending request: sandbox_create
-# [2025-10-22T14:00:00.200Z] MCP: Parameters: {"template":"node"}
-# [2025-10-22T14:00:02.000Z] MCP: Response received: {"success":true}
-```
-### Contact Support
-If issues persist:
-1. **Flow Nexus Support:** support@flow-nexus.ruv.io
-2. **GitHub Issues:** https://github.com/ruvnet/claude-flow/issues
-3. **Documentation:** https://github.com/ruvnet/claude-flow/docs
-Include in support request:
-- Error message and stack trace
-- MCP server versions (`claude mcp list`)
-- Debug logs (with secrets redacted)
-- Steps to reproduce
----
-## Quick Reference Card
-### Command Cheat Sheet
-```bash
-# ===== AgentDB =====
-claude mcp add agentdb npx agentdb mcp
-npx agentdb test
-npx agentdb status
-# ===== Claude Flow =====
-claude mcp add claude-flow npx claude-flow@alpha mcp start
-npx claude-flow@alpha test
-npx claude-flow@alpha swarm status
-# ===== Flow Nexus =====
-# Installation
-claude mcp add flow-nexus npx flow-nexus@latest mcp start
-# Registration
-npx flow-nexus@latest register
-npx flow-nexus@latest verify-email --token TOKEN
-# Login
-npx flow-nexus@latest login
-npx flow-nexus@latest profile
-# Management
-npx flow-nexus@latest balance
-npx flow-nexus@latest upgrade --tier pro
-# ===== Agentic Payments =====
-# Generate keypair
-mcp__agentic-payments__generate_agent_identity({ include_private_key: true })
-# Test signature
-npx agentic-payments test-keypair
-npx agentic-payments verify-signature
-# ===== General =====
-# List all servers
-claude mcp list
-# Test all servers
-./test-mcp-auth.sh
-# Check environment
-env | grep -E '(AGENTDB|CLAUDE_FLOW|FLOW_NEXUS|AGENTIC_PAYMENTS)'
-```
-### Authentication Summary
-| Server | Command | Result |
-|--------|---------|--------|
-| AgentDB | `claude mcp add agentdb npx agentdb mcp` | Ready to use |
-| Claude Flow | `claude mcp add claude-flow npx claude-flow@alpha mcp start` | Ready to use |
-| Flow Nexus | `npx flow-nexus@latest register && login` | Session token |
-| Agentic Payments | `mcp__agentic-payments__generate_agent_identity()` | Ed25519 keypair |
----
-**Document Complete** | Version 2.0.0 | Last Updated: 2025-10-22
-For complete MCP Tools documentation, see:
-- [MCP Tools Complete Reference](/workspaces/agentic-flow/docs/guides/MCP-TOOLS.md)
-- [MCP Tools Architecture](/workspaces/agentic-flow/docs/mcp-tools-architecture.md)
-- [AgentDB CLI Guide](/workspaces/agentic-flow/docs/agentdb/CLI_GUIDE.md)
-**Support:** https://github.com/ruvnet/claude-flow/issues