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/api/mcp-tools/mcp-tools-architecture.md DELETED Viewed

@@ -1,1082 +0,0 @@
-# MCP Tools Documentation Architecture
-**Version:** 2.0.0
-**Status:** Design Phase
-**Target:** 233+ tools across 4 servers
----
-## Executive Summary
-This document defines the comprehensive architecture for improving the MCP Tools documentation. The current documentation (MCP-TOOLS.md) contains 213 tools but has critical issues: incorrect code examples using `query()` API instead of `mcp__server__tool` format, missing authentication setup, unverified tool counts, and no troubleshooting guide.
-**Goal:** Create a production-ready, user-friendly reference that enables developers to discover, authenticate, and use all 233+ MCP tools correctly within 5 minutes.
----
-## 1. Current State Analysis
-### 1.1 Existing Structure (MCP-TOOLS.md)
-**File:** `/workspaces/agentic-flow/docs/guides/MCP-TOOLS.md`
-**Length:** 1,167 lines
-**Coverage:** 213 tools (claimed)
-**Sections:**
-1. What are MCP Tools? (44 lines)
-2. MCP Server Overview (15 lines)
-3. Tool Categories (9 categories, ~800 lines)
-4. Tool Usage Patterns (67 lines)
-5. Performance Benchmarks (41 lines)
-6. Related Documentation (31 lines)
-### 1.2 Critical Issues Identified
-| Issue | Severity | Impact | Lines Affected |
-|-------|----------|--------|----------------|
-| **Incorrect API format** | 🔴 Critical | All code examples broken | ~600 lines |
-| **Missing authentication** | 🔴 Critical | Users can't use Flow Nexus tools | N/A |
-| **Unverified tool count** | 🟡 Medium | Misleading claims (213 vs 233) | Line 3, 56 |
-| **No error handling** | 🟡 Medium | No troubleshooting guidance | N/A |
-| **Missing AgentDB** | 🔴 Critical | Newest server not documented | N/A |
-| **No quick start** | 🟡 Medium | High time-to-first-success | N/A |
-### 1.3 Reference: AgentDB CLI Structure
-**File:** `/workspaces/agentic-flow/docs/agentdb/CLI_GUIDE.md`
-**Length:** 827 lines
-**Structure (best practices to adopt):**
-✅ **Quick Start** (28 lines) - immediate value
-✅ **Environment variables** (clear defaults)
-✅ **Complete example workflow** (practical end-to-end)
-✅ **Performance metrics** (clear expectations)
-✅ **Tips & Best Practices** (actionable guidance)
-✅ **Troubleshooting** (common errors + solutions)
-✅ **Cross-references** (related docs)
----
-## 2. Proposed Architecture
-### 2.1 Documentation Structure
-```
-docs/
-├── guides/
-│   ├── MCP-TOOLS.md (REDESIGN)           # Main reference (target: 2000 lines)
-│   ├── MCP-QUICKSTART.md (NEW)            # 5-minute getting started
-│   ├── MCP-AUTHENTICATION.md (NEW)        # Auth setup for all servers
-│   ├── MCP-TROUBLESHOOTING.md (NEW)       # Common issues + solutions
-│   └── MCP-EXAMPLES.md (NEW)              # Real-world usage patterns
-├── mcp-tools-architecture.md (THIS DOC)   # Design decisions
-└── agentdb/
-    └── CLI_GUIDE.md (REFERENCE)           # Best practices template
-```
-### 2.2 Redesigned MCP-TOOLS.md Structure
-**Target:** 2000 lines (manageable, comprehensive)
-```markdown
-# 🔧 MCP Tools: Complete Reference Guide
-233+ tools across 4 servers • Universal AI agent capabilities
-## Table of Contents
-1. Quick Start (5 minutes)                    [100 lines]
-2. Prerequisites & Authentication              [150 lines]
-3. Server Overview                             [100 lines]
-4. Tool Categories (detailed)                  [1200 lines]
-   4.1 AgentDB (NEW) - 20+ tools               [200 lines]
-   4.2 Claude Flow - 101 tools                 [400 lines]
-   4.3 Flow Nexus - 96 tools                   [400 lines]
-   4.4 Agentic Payments - 12 tools             [100 lines]
-   4.5 Claude Flow SDK - 4 tools               [100 lines]
-5. Usage Patterns                              [150 lines]
-6. Response Types & Error Handling             [100 lines]
-7. Performance Benchmarks                      [100 lines]
-8. Troubleshooting                             [100 lines]
-9. FAQ                                         [50 lines]
-10. Related Documentation                      [50 lines]
-```
-### 2.3 New Quick Start Guide (MCP-QUICKSTART.md)
-**Target:** 300 lines, 5-minute read
-```markdown
-# MCP Tools Quick Start
-Get started with MCP tools in 5 minutes.
-## 1. Installation (1 minute)
-## 2. Add Your First Server (1 minute)
-## 3. Run Your First Tool (2 minutes)
-## 4. Common Patterns (1 minute)
-## 5. Next Steps
-```
-### 2.4 Authentication Guide (MCP-AUTHENTICATION.md)
-**Target:** 400 lines
-```markdown
-# MCP Authentication & Setup
-Complete authentication guide for all MCP servers.
-## Overview
-## Claude Flow (No Auth Required)
-## Flow Nexus (Registration Required)
-## Agentic Payments (Keypair Required)
-## AgentDB (Local Database)
-## Environment Variables
-## Troubleshooting Auth Issues
-```
----
-## 3. Tool Categorization Scheme
-### 3.1 Server Breakdown (Verified)
-| Server | Tools | Auth Required | Primary Use Case |
-|--------|-------|---------------|------------------|
-| **AgentDB** | 20+ | No (local DB) | Agent memory, causal learning, skills |
-| **Claude Flow** | 101 | No | Orchestration, swarms, neural |
-| **Flow Nexus** | 96 | Yes (register) | Cloud execution, sandboxes, templates |
-| **Agentic Payments** | 12 | Yes (keypair) | Payment authorization, mandates |
-| **Claude Flow SDK** | 4 | No | Low-level SDK integration |
-| **TOTAL** | **233+** | Mixed | Complete AI agent platform |
-### 3.2 Category Taxonomy
-**Primary Categories (11 total):**
-1. **Agent Memory & Learning** (AgentDB focus)
-   - Causal Memory (CausalRecall)
-   - Explainable Recall (certificates)
-   - Reflexion Memory (self-critique)
-   - Skill Library (reusable patterns)
-   - Nightly Learner (pattern discovery)
-2. **Swarm Orchestration** (Claude Flow, Flow Nexus)
-   - Swarm initialization
-   - Agent spawning
-   - Task orchestration
-   - Topology management
-   - Load balancing
-3. **Memory & Persistence** (Claude Flow)
-   - Memory storage/retrieval
-   - Search & patterns
-   - Backup/restore
-   - Namespace management
-   - Cross-session persistence
-4. **Neural Networks & AI** (Claude Flow, Flow Nexus)
-   - Neural training
-   - Inference & prediction
-   - Pattern recognition
-   - Model management
-   - WASM acceleration
-5. **Cloud Execution** (Flow Nexus)
-   - Sandbox creation/management
-   - Code execution
-   - File operations
-   - Environment configuration
-   - Log retrieval
-6. **Workflow Automation** (Flow Nexus)
-   - Workflow creation
-   - Event-driven execution
-   - Message queues
-   - Agent assignment
-   - Audit trails
-7. **GitHub Integration** (Claude Flow)
-   - Repository analysis
-   - PR management
-   - Code review
-   - Issue tracking
-   - Release coordination
-8. **Payment Authorization** (Agentic Payments)
-   - Active Mandates
-   - Mandate signing/verification
-   - Intent-based payments
-   - Cart-based payments
-   - Revocation
-9. **Performance & Monitoring** (Claude Flow)
-   - Performance reports
-   - Bottleneck analysis
-   - Token usage tracking
-   - Benchmarking
-   - Metrics collection
-10. **App Store & Templates** (Flow Nexus)
-    - Template listing/deployment
-    - App publishing
-    - Analytics
-    - Challenges & achievements
-    - Credit management
-11. **User Management** (Flow Nexus)
-    - Authentication
-    - Profile management
-    - Tier upgrades
-    - Statistics
-### 3.3 Cross-Reference Matrix
-| Feature | AgentDB | Claude Flow | Flow Nexus | Agentic Payments |
-|---------|---------|-------------|------------|------------------|
-| Memory | ✅ Advanced | ✅ Basic | ❌ | ❌ |
-| Swarms | ❌ | ✅ Core | ✅ Cloud | ❌ |
-| Neural | ❌ | ✅ WASM | ✅ Cloud | ❌ |
-| Payments | ❌ | ❌ | ❌ | ✅ Core |
-| GitHub | ❌ | ✅ Core | ✅ Enhanced | ❌ |
-| Sandboxes | ❌ | ❌ | ✅ Core | ❌ |
----
-## 4. Code Example Patterns
-### 4.1 Correct API Format
-**❌ WRONG (Current docs):**
-```javascript
-await query({
-  mcp: {
-    server: 'claude-flow',
-    tool: 'swarm_init',
-    params: { topology: 'mesh' }
-  }
-});
-```
-**✅ CORRECT (Claude Code):**
-```javascript
-// Direct MCP tool invocation
-mcp__claude-flow__swarm_init({
-  topology: 'mesh',
-  maxAgents: 8,
-  strategy: 'balanced'
-});
-```
-### 4.2 Example Template Structure
-Every tool example MUST include:
-1. **Tool invocation** (correct format)
-2. **Parameter descriptions** (inline comments)
-3. **Response structure** (example output)
-4. **Error handling** (common errors)
-5. **Related tools** (what to use next)
-**Template:**
-```markdown
-### `mcp__server__tool_name`
-[One-line description]
-**Parameters:**
-- `param1` (type, required) - Description
-- `param2` (type, optional, default: value) - Description
-**Example:**
-```javascript
-// [What this does]
-mcp__server__tool_name({
-  param1: 'value',  // Explanation
-  param2: 42        // Explanation
-});
-```
-**Response:**
-```json
-{
-  "success": true,
-  "data": { ... }
-}
-```
-**Common Errors:**
-- `INVALID_PARAM`: Check param1 format
-- `AUTH_REQUIRED`: Run authentication first
-**See Also:**
-- Related tool 1
-- Related tool 2
-```
-### 4.3 Authentication Examples
-**Flow Nexus (required):**
-```javascript
-// 1. Register (one-time)
-mcp__flow-nexus__user_register({
-  email: 'user@example.com',
-  password: 'secure-password'
-});
-// 2. Login (each session)
-mcp__flow-nexus__user_login({
-  email: 'user@example.com',
-  password: 'secure-password'
-});
-// 3. Use tools
-mcp__flow-nexus__sandbox_create({ ... });
-```
-**Agentic Payments (keypair):**
-```javascript
-// 1. Generate identity (one-time)
-const identity = mcp__agentic-payments__generate_agent_identity({
-  include_private_key: true  // SECURE STORAGE REQUIRED
-});
-// 2. Use in mandates
-mcp__agentic-payments__create_active_mandate({
-  agent: 'shopping-bot@agentics',
-  holder: identity.public_key,
-  ...
-});
-```
----
-## 5. Response Types & Error Handling
-### 5.1 Standard Response Structure
-**Success Response:**
-```typescript
-interface SuccessResponse<T> {
-  success: true;
-  data: T;
-  metadata?: {
-    timestamp: string;
-    latency_ms: number;
-    cache_hit?: boolean;
-  };
-}
-```
-**Error Response:**
-```typescript
-interface ErrorResponse {
-  success: false;
-  error: {
-    code: string;           // e.g., "AUTH_REQUIRED"
-    message: string;        // Human-readable
-    details?: object;       // Additional context
-    suggestion?: string;    // How to fix
-  };
-}
-```
-### 5.2 Common Error Codes
-| Code | Meaning | Solution |
-|------|---------|----------|
-| `AUTH_REQUIRED` | Authentication needed | Run login/register first |
-| `INVALID_PARAMS` | Bad parameters | Check parameter types/values |
-| `NOT_FOUND` | Resource doesn't exist | Verify ID/name |
-| `RATE_LIMITED` | Too many requests | Wait and retry |
-| `INSUFFICIENT_CREDITS` | Not enough balance | Add credits or upgrade tier |
-| `SERVER_ERROR` | Internal error | Retry or report issue |
-### 5.3 Error Handling Pattern
-```javascript
-try {
-  const result = mcp__flow-nexus__sandbox_create({
-    template: 'node',
-    name: 'test-sandbox'
-  });
-  if (result.success) {
-    console.log('Sandbox created:', result.data.sandbox_id);
-  }
-} catch (error) {
-  if (error.code === 'AUTH_REQUIRED') {
-    // Handle authentication
-    mcp__flow-nexus__user_login({ ... });
-    // Retry operation
-  } else if (error.code === 'RATE_LIMITED') {
-    // Wait and retry
-    await sleep(error.details.retry_after_ms);
-  } else {
-    // Log and report
-    console.error('Unexpected error:', error);
-  }
-}
-```
----
-## 6. Navigation & Discoverability
-### 6.1 Table of Contents Strategy
-**Multi-level TOC:**
-- Level 1: Sections (Quick Start, Authentication, etc.)
-- Level 2: Categories (AgentDB, Claude Flow, etc.)
-- Level 3: Tool groups (Causal Commands, Memory Operations, etc.)
-- Level 4: Individual tools (linked)
-**Example:**
-```markdown
-## Table of Contents
-1. [Quick Start](#quick-start)
-2. [Prerequisites & Authentication](#authentication)
-3. [Server Overview](#servers)
-4. [Tool Categories](#categories)
-   - 4.1 [AgentDB - Agent Memory](#agentdb)
-     - [Causal Memory](#causal)
-       - [`causal_add_edge`](#causal-add-edge)
-       - [`causal_query`](#causal-query)
-     - [Reflexion Memory](#reflexion)
-     - [Skill Library](#skills)
-   - 4.2 [Claude Flow - Orchestration](#claude-flow)
-   - 4.3 [Flow Nexus - Cloud Execution](#flow-nexus)
-   ...
-```
-### 6.2 Search & Filter Strategy
-**By Server:**
-```markdown
-### Filter by Server
-- [AgentDB Tools](#agentdb-tools) (20+)
-- [Claude Flow Tools](#claude-flow-tools) (101)
-- [Flow Nexus Tools](#flow-nexus-tools) (96)
-- [Agentic Payments Tools](#agentic-payments-tools) (12)
-```
-**By Use Case:**
-```markdown
-### Filter by Use Case
-- [Memory & Learning](#memory-learning) (38 tools)
-- [Orchestration & Swarms](#orchestration) (25 tools)
-- [Cloud Execution](#cloud-execution) (24 tools)
-- [GitHub Integration](#github) (16 tools)
-- [Payments](#payments) (12 tools)
-```
-**By Auth Requirement:**
-```markdown
-### Filter by Authentication
-- [No Auth Required](#no-auth) (125 tools)
-- [Registration Required](#registration) (96 tools)
-- [Keypair Required](#keypair) (12 tools)
-```
-### 6.3 Cross-Reference Strategy
-**Every tool page includes:**
-1. **Prerequisites:** What to set up first
-2. **Related tools:** What to use next
-3. **Use cases:** When to use this tool
-4. **Alternatives:** Other ways to achieve the goal
-**Example:**
-```markdown
-### `mcp__claude-flow__swarm_init`
-**Prerequisites:**
-- None (first step in orchestration)
-**Related Tools:**
-- `mcp__claude-flow__agent_spawn` - Add agents after init
-- `mcp__claude-flow__task_orchestrate` - Assign tasks
-- `mcp__claude-flow__swarm_status` - Monitor progress
-**Common Workflows:**
-1. **Basic Orchestration:** init → spawn → orchestrate → destroy
-2. **Scaled Orchestration:** init → spawn × N → scale → balance → destroy
-3. **Persistent Orchestration:** init → spawn → save state → restore → destroy
-**When to Use:**
-- Multi-agent coordination required
-- Complex task needs parallel execution
-- Dynamic agent scaling needed
-**Alternatives:**
-- Single agent: Use direct agent tools instead
-- Simple tasks: Use `task_orchestrate` without swarm
-- Cloud execution: Use Flow Nexus swarms
-```
----
-## 7. Troubleshooting Section
-### 7.1 Common Issues Matrix
-| Issue | Symptoms | Diagnosis | Solution |
-|-------|----------|-----------|----------|
-| **Auth Failure** | "AUTH_REQUIRED" error | Check login status | Run `user_login` |
-| **Tool Not Found** | "Unknown tool" error | Check server name | Verify MCP server is running |
-| **Invalid Params** | "INVALID_PARAMS" error | Check parameter types | Review tool documentation |
-| **Rate Limited** | "RATE_LIMITED" error | Too many requests | Wait or upgrade tier |
-| **Out of Credits** | "INSUFFICIENT_CREDITS" | Low balance | Add credits |
-| **Sandbox Timeout** | Sandbox unresponsive | Long-running code | Increase timeout param |
-### 7.2 Diagnostic Commands
-```bash
-# 1. Check MCP server status
-claude mcp list
-# 2. Test server connectivity
-mcp__claude-flow__swarm_status()
-# 3. Check authentication
-mcp__flow-nexus__auth_status()
-# 4. View recent errors
-# (server-specific logging)
-# 5. Check credits balance
-mcp__flow-nexus__check_balance()
-```
-### 7.3 Debug Mode
-```javascript
-// Enable verbose logging
-process.env.MCP_DEBUG = 'true';
-// Test tool with logging
-mcp__claude-flow__swarm_init({
-  topology: 'mesh',
-  maxAgents: 8
-});
-// Logs will show:
-// [MCP] Connecting to claude-flow...
-// [MCP] Sending request: swarm_init
-// [MCP] Parameters: {"topology":"mesh","maxAgents":8}
-// [MCP] Response: {"success":true,"swarmId":"abc123"}
-```
----
-## 8. FAQ Section
-### 8.1 Getting Started
-**Q: Which MCP server should I start with?**
-A: Claude Flow (no auth required, core orchestration features).
-**Q: Do I need all 4 servers?**
-A: No. Start with Claude Flow, add others as needed:
-- Flow Nexus: Cloud execution, sandboxes
-- Agentic Payments: Payment authorization
-- AgentDB: Advanced memory (included in Claude Flow)
-**Q: How do I know which tools I have access to?**
-A: Run `claude mcp list` to see installed servers.
-### 8.2 Authentication
-**Q: Why does Flow Nexus require registration?**
-A: Cloud resources (sandboxes, storage) require account management.
-**Q: Is my Flow Nexus password stored securely?**
-A: Yes. Passwords are hashed with bcrypt, never stored in plaintext.
-**Q: Can I use Flow Nexus tools without registering?**
-A: No. Registration is required for cloud features.
-### 8.3 Pricing & Limits
-**Q: Are MCP tools free?**
-A: Mixed:
-- Claude Flow: Free, unlimited
-- Flow Nexus: Free tier + paid upgrades
-- Agentic Payments: Transaction fees
-- AgentDB: Free, local storage
-**Q: What are Flow Nexus rate limits?**
-A: Free tier: 100 requests/hour. Paid tiers: Higher limits.
-**Q: How much do sandboxes cost?**
-A: ~$0.01/hour for basic sandboxes, more for GPU/memory.
-### 8.4 Best Practices
-**Q: Should I use swarms for every task?**
-A: No. Use swarms for:
-- Multi-step workflows
-- Parallel execution
-- Dynamic scaling
-Skip for simple single-agent tasks.
-**Q: How do I persist swarm state across sessions?**
-A: Use memory tools:
-```javascript
-// Save state
-mcp__claude-flow__memory_usage({
-  action: 'store',
-  key: 'swarm-state',
-  value: JSON.stringify(swarmState)
-});
-// Restore state
-const state = mcp__claude-flow__memory_usage({
-  action: 'retrieve',
-  key: 'swarm-state'
-});
-```
-**Q: What's the difference between Claude Flow and Flow Nexus swarms?**
-A: Claude Flow: Local orchestration, no cloud overhead.
-Flow Nexus: Cloud-based, distributed execution, persistent infrastructure.
----
-## 9. Performance Expectations
-### 9.1 Latency Targets
-| Operation | Target | P50 | P95 | P99 |
-|-----------|--------|-----|-----|-----|
-| Memory store/retrieve | < 10ms | 5ms | 12ms | 20ms |
-| Swarm init | < 100ms | 50ms | 120ms | 200ms |
-| Agent spawn | < 50ms | 30ms | 80ms | 150ms |
-| Task orchestrate | < 200ms | 100ms | 300ms | 500ms |
-| Sandbox create | < 3s | 2s | 5s | 8s |
-| Sandbox execute | < 1s + code | 500ms | 1.5s | 3s |
-| Neural train (1 epoch) | < 1s | 500ms | 2s | 5s |
-| Neural predict | < 50ms | 15ms | 80ms | 150ms |
-### 9.2 Throughput Limits
-| Server | Free Tier | Paid Tier | Enterprise |
-|--------|-----------|-----------|------------|
-| Claude Flow | Unlimited* | N/A | N/A |
-| Flow Nexus | 100/hour | 1000/hour | Custom |
-| Agentic Payments | 50/hour | 500/hour | Custom |
-| AgentDB | Unlimited* | N/A | N/A |
-*Limited by local system resources
-### 9.3 Cost Optimization
-**Memory usage:**
-```javascript
-// ✅ EFFICIENT: Batch operations
-mcp__claude-flow__memory_usage({
-  action: 'store',
-  key: 'batch-data',
-  value: JSON.stringify(largeBatch)  // Single call
-});
-// ❌ INEFFICIENT: Multiple calls
-for (const item of items) {
-  mcp__claude-flow__memory_usage({
-    action: 'store',
-    key: `item-${item.id}`,
-    value: JSON.stringify(item)  // N calls
-  });
-}
-```
-**Sandbox reuse:**
-```javascript
-// ✅ EFFICIENT: Reuse sandbox
-const sandbox = mcp__flow-nexus__sandbox_create({ ... });
-mcp__flow-nexus__sandbox_execute({ sandbox_id: sandbox.id, code: 'task1' });
-mcp__flow-nexus__sandbox_execute({ sandbox_id: sandbox.id, code: 'task2' });
-mcp__flow-nexus__sandbox_delete({ sandbox_id: sandbox.id });
-// ❌ INEFFICIENT: Create/destroy per task
-const s1 = mcp__flow-nexus__sandbox_create({ ... });
-mcp__flow-nexus__sandbox_execute({ sandbox_id: s1.id, code: 'task1' });
-mcp__flow-nexus__sandbox_delete({ sandbox_id: s1.id });
-const s2 = mcp__flow-nexus__sandbox_create({ ... });
-// ... repeat
-```
----
-## 10. Implementation Plan
-### 10.1 Phase 1: Foundation (Week 1)
-**Deliverables:**
-1. ✅ Architecture document (this doc)
-2. ⏳ Verify all 233 tools exist and work
-3. ⏳ Create tool inventory with correct naming
-4. ⏳ Document authentication flows
-5. ⏳ Set up test environment
-**Tasks:**
-- Scan all 4 MCP servers for tool definitions
-- Test each tool with sample parameters
-- Document response structures
-- Identify authentication requirements
-- Create test suite
-### 10.2 Phase 2: Quick Start & Auth (Week 2)
-**Deliverables:**
-1. ⏳ MCP-QUICKSTART.md (300 lines)
-2. ⏳ MCP-AUTHENTICATION.md (400 lines)
-3. ⏳ Update main README with quick start link
-**Tasks:**
-- Write 5-minute quick start guide
-- Document registration process for Flow Nexus
-- Document keypair generation for Agentic Payments
-- Create authentication troubleshooting section
-- Test with new users
-### 10.3 Phase 3: Core Documentation (Week 3-4)
-**Deliverables:**
-1. ⏳ Redesigned MCP-TOOLS.md (2000 lines)
-   - AgentDB section (200 lines)
-   - Claude Flow section (400 lines)
-   - Flow Nexus section (400 lines)
-   - Agentic Payments section (100 lines)
-   - Error handling section (100 lines)
-**Tasks:**
-- Migrate existing content to new structure
-- Fix all code examples (query → mcp__server__tool)
-- Add AgentDB tools section
-- Document response types
-- Add cross-references
-### 10.4 Phase 4: Advanced Features (Week 5)
-**Deliverables:**
-1. ⏳ MCP-TROUBLESHOOTING.md (500 lines)
-2. ⏳ MCP-EXAMPLES.md (600 lines)
-3. ⏳ Performance benchmarking suite
-**Tasks:**
-- Document common errors and solutions
-- Create 10+ real-world examples
-- Add diagnostic commands
-- Benchmark all tool categories
-- Create performance optimization guide
-### 10.5 Phase 5: Polish & Launch (Week 6)
-**Deliverables:**
-1. ⏳ FAQ section (50 Q&A)
-2. ⏳ Navigation improvements
-3. ⏳ User testing with 5+ developers
-4. ⏳ Launch announcement
-**Tasks:**
-- Internal review
-- External user testing
-- Fix issues from testing
-- Create video walkthrough (optional)
-- Publish updated docs
----
-## 11. Success Metrics
-### 11.1 Quantitative Metrics
-| Metric | Current | Target | Measurement |
-|--------|---------|--------|-------------|
-| Time to first success | Unknown | < 5 minutes | User testing |
-| Code example accuracy | 0% (wrong API) | 100% | Automated tests |
-| Tool coverage | 213 claimed | 233+ verified | Tool inventory |
-| Troubleshooting coverage | 0% | 80% of issues | Issue tracking |
-| User satisfaction | Unknown | > 4.5/5 | Survey |
-### 11.2 Qualitative Goals
-**Developer Experience:**
-- ✅ "I can start using MCP tools without reading the entire docs"
-- ✅ "Code examples work without modification"
-- ✅ "I know which server to use for my use case"
-- ✅ "Error messages point me to the solution"
-- ✅ "I can find related tools easily"
-**Documentation Quality:**
-- ✅ Accurate (all examples tested)
-- ✅ Complete (all 233+ tools documented)
-- ✅ Organized (clear navigation)
-- ✅ Practical (real-world examples)
-- ✅ Maintainable (clear structure)
-### 11.3 Validation Criteria
-**Pre-Launch Checklist:**
-- [ ] All 233+ tools verified to exist
-- [ ] All code examples tested and working
-- [ ] Authentication flows documented and tested
-- [ ] Quick start guide tested with 5+ new users
-- [ ] Troubleshooting section covers top 10 issues
-- [ ] Cross-references complete (no dead links)
-- [ ] Performance benchmarks measured
-- [ ] FAQ answers top 20 questions
----
-## 12. Maintenance Strategy
-### 12.1 Update Frequency
-| Component | Frequency | Owner |
-|-----------|-----------|-------|
-| Tool inventory | Weekly | Automated scan |
-| Code examples | Per release | Documentation team |
-| Troubleshooting | Monthly | Support team |
-| Performance data | Quarterly | Engineering team |
-| FAQ | As needed | Community + support |
-### 12.2 Automation
-**Automated checks:**
-```bash
-# 1. Tool inventory scan
-npm run mcp:scan-tools
-# 2. Example validation
-npm run mcp:test-examples
-# 3. Link checker
-npm run mcp:check-links
-# 4. Performance benchmarks
-npm run mcp:benchmark
-```
-**CI/CD integration:**
-- Run automated checks on every PR
-- Block merge if examples fail
-- Update performance charts weekly
-### 12.3 Community Contributions
-**Contribution guidelines:**
-1. All examples must be tested
-2. Follow template structure
-3. Include error handling
-4. Add to appropriate category
-5. Update cross-references
-**Review process:**
-- Auto-validate examples
-- Manual review for accuracy
-- Merge within 48 hours
----
-## 13. Architecture Decisions
-### ADR-001: API Format Standardization
-**Status:** Accepted
-**Date:** 2025-10-22
-**Context:**
-Current docs use `query({ mcp: { server, tool, params }})` format, which doesn't match Claude Code's actual MCP tool invocation pattern `mcp__server__tool(params)`.
-**Decision:**
-Standardize all examples to use `mcp__server__tool(params)` format.
-**Consequences:**
-- ✅ Examples work without modification
-- ✅ Consistent with Claude Code API
-- ⚠️ Requires rewriting ~600 lines
-- ⚠️ Old examples in other docs need updates
----
-### ADR-002: Multi-Document Structure
-**Status:** Accepted
-**Date:** 2025-10-22
-**Context:**
-Single 2000-line document vs. multiple focused documents.
-**Decision:**
-Create 5 documents:
-1. MCP-TOOLS.md (reference)
-2. MCP-QUICKSTART.md (getting started)
-3. MCP-AUTHENTICATION.md (auth setup)
-4. MCP-TROUBLESHOOTING.md (debugging)
-5. MCP-EXAMPLES.md (use cases)
-**Consequences:**
-- ✅ Better organization
-- ✅ Easier to maintain
-- ✅ Faster to find information
-- ⚠️ More files to keep in sync
-- ⚠️ Requires clear cross-references
----
-### ADR-003: AgentDB as First-Class Server
-**Status:** Accepted
-**Date:** 2025-10-22
-**Context:**
-AgentDB is not documented in current MCP-TOOLS.md despite being a core server with 20+ tools.
-**Decision:**
-Add AgentDB as a primary server category with dedicated section.
-**Consequences:**
-- ✅ Complete tool coverage
-- ✅ Highlights advanced memory features
-- ✅ Competitive advantage (frontier features)
-- ⚠️ Requires ~200 lines of new content
-- ⚠️ Increases total tool count to 233+
----
-### ADR-004: Error Handling as First-Class Concept
-**Status:** Accepted
-**Date:** 2025-10-22
-**Context:**
-No error handling documentation in current docs.
-**Decision:**
-Add dedicated section on response types, error codes, and handling patterns.
-**Consequences:**
-- ✅ Improves developer experience
-- ✅ Reduces support burden
-- ✅ Professional documentation quality
-- ⚠️ Requires standardizing error codes
-- ⚠️ Requires testing all error scenarios
----
-### ADR-005: Performance Transparency
-**Status:** Accepted
-**Date:** 2025-10-22
-**Context:**
-Current benchmarks lack detail and real-world context.
-**Decision:**
-Publish detailed performance metrics (P50, P95, P99) for all tool categories.
-**Consequences:**
-- ✅ Sets clear expectations
-- ✅ Enables performance optimization
-- ✅ Competitive transparency
-- ⚠️ Requires ongoing benchmarking
-- ⚠️ Performance may vary by environment
----
-## 14. References
-### 14.1 Source Documentation
-- AgentDB CLI Guide: `/workspaces/agentic-flow/docs/agentdb/CLI_GUIDE.md`
-- Current MCP Tools: `/workspaces/agentic-flow/docs/guides/MCP-TOOLS.md`
-- Claude Code Instructions: `/workspaces/agentic-flow/CLAUDE.md`
-- MCP Specification: https://modelcontextprotocol.io
-### 14.2 Related Projects
-- Claude Flow: https://github.com/ruvnet/claude-flow
-- Flow Nexus: https://flow-nexus.ruv.io
-- AgentDB: Embedded in agentic-flow
-### 14.3 Tool Inventory Sources
-- Claude Flow: `node_modules/@ruvnet/claude-flow/dist/mcp/tools/`
-- Flow Nexus: `node_modules/flow-nexus/dist/mcp/tools/`
-- Agentic Payments: `src/agentic-payments/mcp/tools/`
-- AgentDB: `src/agentdb/controllers/`
----
-## Appendices
-### Appendix A: Tool Naming Convention
-**Pattern:** `mcp__<server>__<category>_<action>`
-**Examples:**
-- `mcp__claude-flow__swarm_init` - Claude Flow, Swarm category, Init action
-- `mcp__flow-nexus__sandbox_create` - Flow Nexus, Sandbox category, Create action
-- `mcp__agentdb__causal_add_edge` - AgentDB, Causal category, Add Edge action
-**Special cases:**
-- Hyphens in server names: `claude-flow`, `flow-nexus`
-- Underscores in tool names: `swarm_init`, `sandbox_create`
-- Namespacing: Server name always comes first
-### Appendix B: Authentication Flow Diagrams
-**Flow Nexus Registration:**
-```mermaid
-graph TD
-    A[User] --> B[mcp__flow-nexus__user_register]
-    B --> C{Success?}
-    C -->|Yes| D[Email Verification]
-    C -->|No| E[Error: Email exists]
-    D --> F[mcp__flow-nexus__user_verify_email]
-    F --> G[Account Active]
-    G --> H[mcp__flow-nexus__user_login]
-    H --> I[Session Token]
-    I --> J[Use Flow Nexus Tools]
-```
-**Agentic Payments Setup:**
-```mermaid
-graph TD
-    A[Agent] --> B[mcp__agentic-payments__generate_agent_identity]
-    B --> C[Ed25519 Keypair]
-    C --> D[Store Private Key Securely]
-    D --> E[mcp__agentic-payments__create_active_mandate]
-    E --> F[mcp__agentic-payments__sign_mandate]
-    F --> G[Signed Mandate]
-    G --> H[Execute Payments]
-```
-### Appendix C: Performance Test Suite
-**Location:** `tests/mcp-tools-performance.test.ts`
-**Test matrix:**
-```typescript
-const performanceTests = [
-  { server: 'claude-flow', tool: 'memory_usage', action: 'store', target: 10 },
-  { server: 'claude-flow', tool: 'swarm_init', topology: 'mesh', target: 100 },
-  { server: 'flow-nexus', tool: 'sandbox_create', template: 'node', target: 3000 },
-  { server: 'agentdb', tool: 'causal_query', limit: 10, target: 20 },
-  // ... 50+ tests
-];
-```
----
-**End of Architecture Document**
-**Version:** 2.0.0
-**Last Updated:** 2025-10-22
-**Next Review:** 2025-11-22
-**Owner:** Documentation Team
-**Status:** ✅ Ready for Implementation