agentic-flow 1.2.0 → 1.2.1

package/dist/cli-proxy.js

@@ -65,6 +65,26 @@ class AgenticFlowCLI {
             await handleAgentCommand(agentArgs);
             process.exit(0);
         }
+        if (options.mode === 'mcp-manager') {
+            // Handle MCP manager commands (add, list, remove, etc.)
+            const { spawn } = await import('child_process');
+            const { resolve, dirname } = await import('path');
+            const { fileURLToPath } = await import('url');
+            const __filename = fileURLToPath(import.meta.url);
+            const __dirname = dirname(__filename);
+            const mcpManagerPath = resolve(__dirname, './cli/mcp-manager.js');
+            // Pass all args after 'mcp' to mcp-manager
+            const mcpArgs = process.argv.slice(3); // Skip 'node', 'cli-proxy.js', 'mcp'
+            const proc = spawn('node', [mcpManagerPath, ...mcpArgs], {
+                stdio: 'inherit'
+            });
+            proc.on('exit', (code) => {
+                process.exit(code || 0);
+            });
+            process.on('SIGINT', () => proc.kill('SIGINT'));
+            process.on('SIGTERM', () => proc.kill('SIGTERM'));
+            return;
+        }
         if (options.mode === 'proxy') {
             // Run standalone proxy server for Claude Code/Cursor
             await this.runStandaloneProxy();
@@ -110,7 +130,8 @@ class AgenticFlowCLI {
                 agent: options.agent,
                 task: options.task,
                 priority: options.optimizePriority || 'balanced',
-                maxCostPerTask: options.maxCost
+                maxCostPerTask: options.maxCost,
+                requiresTools: true // Agents have MCP tools available, so require tool support
             });
             // Display recommendation
             ModelOptimizer.displayRecommendation(recommendation);

package/dist/utils/.claude-flow/metrics/agent-metrics.json

@@ -0,0 +1 @@
+{}

package/dist/utils/.claude-flow/metrics/performance.json

@@ -0,0 +1,9 @@
+{
+  "startTime": 1759762633186,
+  "totalTasks": 1,
+  "successfulTasks": 1,
+  "failedTasks": 0,
+  "totalAgents": 0,
+  "activeAgents": 0,
+  "neuralEvents": 0
+}

package/dist/utils/.claude-flow/metrics/task-metrics.json

@@ -0,0 +1,10 @@
+[
+  {
+    "id": "cmd-hooks-1759762633317",
+    "type": "hooks",
+    "success": true,
+    "duration": 6.094114000000047,
+    "timestamp": 1759762633323,
+    "metadata": {}
+  }
+]

package/dist/utils/cli.js

@@ -16,8 +16,16 @@ export function parseArgs() {
     }
     // Check for MCP command
     if (args[0] === 'mcp') {
+        const mcpSubcommand = args[1];
+        // MCP Manager commands (CLI configuration)
+        const managerCommands = ['add', 'list', 'remove', 'enable', 'disable', 'update', 'test', 'info', 'export', 'import'];
+        if (managerCommands.includes(mcpSubcommand)) {
+            options.mode = 'mcp-manager';
+            return options;
+        }
+        // MCP Server commands (start/stop server)
         options.mode = 'mcp';
-        options.mcpCommand = args[1] || 'start'; // default to start
+        options.mcpCommand = mcpSubcommand || 'start'; // default to start
         options.mcpServer = args[2] || 'all'; // default to all servers
         return options;
     }

package/dist/utils/modelOptimizer.js

@@ -16,6 +16,7 @@ const MODEL_DATABASE = {
         speed_score: 85,
         cost_score: 20,
         tier: 'flagship',
+        supports_tools: true,
         strengths: ['reasoning', 'coding', 'analysis', 'production'],
         weaknesses: ['cost'],
         bestFor: ['coder', 'reviewer', 'architecture', 'planner', 'production-validator']
@@ -30,6 +31,7 @@ const MODEL_DATABASE = {
         speed_score: 90,
         cost_score: 30,
         tier: 'flagship',
+        supports_tools: true,
         strengths: ['multimodal', 'speed', 'general-purpose', 'vision'],
         weaknesses: ['cost'],
         bestFor: ['researcher', 'analyst', 'multimodal-tasks']
@@ -44,6 +46,7 @@ const MODEL_DATABASE = {
         speed_score: 75,
         cost_score: 50,
         tier: 'flagship',
+        supports_tools: true,
         strengths: ['reasoning', 'large-context', 'math', 'analysis'],
         weaknesses: ['speed'],
         bestFor: ['planner', 'architecture', 'researcher', 'code-analyzer']
@@ -59,8 +62,9 @@ const MODEL_DATABASE = {
         speed_score: 80,
         cost_score: 100,
         tier: 'cost-effective',
+        supports_tools: false, // DeepSeek R1 does NOT support tool/function calling
         strengths: ['reasoning', 'coding', 'math', 'value', 'free'],
-        weaknesses: ['newer-model'],
+        weaknesses: ['newer-model', 'no-tool-use'],
         bestFor: ['coder', 'pseudocode', 'specification', 'refinement', 'tester']
     },
     'deepseek-chat-v3': {
@@ -73,6 +77,7 @@ const MODEL_DATABASE = {
         speed_score: 90,
         cost_score: 100,
         tier: 'cost-effective',
+        supports_tools: true,
         strengths: ['cost', 'speed', 'coding', 'development', 'free'],
         weaknesses: ['complex-reasoning'],
         bestFor: ['coder', 'reviewer', 'tester', 'backend-dev', 'cicd-engineer']
@@ -88,6 +93,7 @@ const MODEL_DATABASE = {
         speed_score: 98,
         cost_score: 98,
         tier: 'balanced',
+        supports_tools: true,
         strengths: ['speed', 'cost', 'interactive'],
         weaknesses: ['quality'],
         bestFor: ['researcher', 'planner', 'smart-agent']
@@ -102,6 +108,7 @@ const MODEL_DATABASE = {
         speed_score: 95,
         cost_score: 100,
         tier: 'balanced',
+        supports_tools: true,
         strengths: ['open-source', 'versatile', 'coding', 'free', 'fast'],
         weaknesses: ['smaller-model'],
         bestFor: ['coder', 'reviewer', 'base-template-generator', 'tester']
@@ -116,6 +123,7 @@ const MODEL_DATABASE = {
         speed_score: 85,
         cost_score: 90,
         tier: 'balanced',
+        supports_tools: true,
         strengths: ['multilingual', 'coding', 'reasoning'],
         weaknesses: ['english-optimized'],
         bestFor: ['researcher', 'coder', 'multilingual-tasks']
@@ -131,6 +139,7 @@ const MODEL_DATABASE = {
         speed_score: 95,
         cost_score: 99,
         tier: 'budget',
+        supports_tools: true,
         strengths: ['ultra-low-cost', 'speed'],
         weaknesses: ['quality', 'complex-tasks'],
         bestFor: ['simple-tasks', 'testing']
@@ -146,6 +155,7 @@ const MODEL_DATABASE = {
         speed_score: 30,
         cost_score: 100,
         tier: 'local',
+        supports_tools: false,
         strengths: ['privacy', 'offline', 'zero-cost'],
         weaknesses: ['quality', 'speed'],
         bestFor: ['privacy-tasks', 'offline-tasks']
@@ -197,8 +207,14 @@ export class ModelOptimizer {
         const taskComplexity = criteria.taskComplexity || this.inferComplexity(criteria.task);
         // Set default priority to balanced if not specified
         const priority = criteria.priority || 'balanced';
+        // Filter models that support tools if required
+        let availableModels = Object.entries(MODEL_DATABASE);
+        if (criteria.requiresTools) {
+            availableModels = availableModels.filter(([key, model]) => model.supports_tools !== false);
+            logger.info(`Filtered to ${availableModels.length} models with tool support`);
+        }
         // Score all models
-        const scoredModels = Object.entries(MODEL_DATABASE).map(([key, model]) => {
+        const scoredModels = availableModels.map(([key, model]) => {
             // Calculate overall score based on priority
             let overall_score;
             switch (priority) {

package/docs/.claude-flow/metrics/performance.json

@@ -1,5 +1,5 @@
 {
-  "startTime": 1759680310468,
+  "startTime": 1759762593440,
   "totalTasks": 1,
   "successfulTasks": 1,
   "failedTasks": 0,

package/docs/.claude-flow/metrics/task-metrics.json

@@ -1,10 +1,10 @@
 [
   {
-    "id": "cmd-hooks-1759680310618",
+    "id": "cmd-hooks-1759762593563",
     "type": "hooks",
     "success": true,
-    "duration": 8.211029999999994,
-    "timestamp": 1759680310627,
+    "duration": 24.05694200000005,
+    "timestamp": 1759762593587,
     "metadata": {}
   }
 ]

package/docs/INDEX.md

@@ -54,10 +54,35 @@ Multi-model router configuration and usage.
 - [Router Config Reference](router/ROUTER_CONFIG_REFERENCE.md) - Configuration options
 - [Top 20 Models Matrix](router/TOP20_MODELS_MATRIX.md) - Model comparison guide
 
-### ✅ [Validation & Testing](validation/)
-Test results and quality assurance reports.
+### ✅ [Testing & Validation](testing/)
+Current test results, validation reports, and quality assurance.
 
-- [Validation README](validation/README.md) - Overview and archived reports
+- [Testing Overview](testing/README.md) - Current testing documentation
+- [Agent System Validation](testing/AGENT-SYSTEM-VALIDATION.md) - Multi-agent testing
+- [Final Testing Summary](testing/FINAL-TESTING-SUMMARY.md) - Comprehensive coverage
+- [Regression Test Results](testing/REGRESSION-TEST-RESULTS.md) - Regression testing
+- [Streaming & MCP Validation](testing/STREAMING-AND-MCP-VALIDATION.md) - Integration tests
+
+### 🔍 [MCP Validation](mcp-validation/)
+Model Context Protocol implementation and validation.
+
+- [MCP Validation Overview](mcp-validation/README.md) - MCP testing documentation
+- [Implementation Summary](mcp-validation/IMPLEMENTATION-SUMMARY.md) - MCP implementation
+- [CLI Validation Report](mcp-validation/MCP-CLI-VALIDATION-REPORT.md) - CLI tool testing
+- [Strange Loops Test](mcp-validation/strange-loops-test.md) - Advanced patterns
+
+### 📦 [Releases](releases/)
+Version-specific release notes and publishing documentation.
+
+- [Release Overview](releases/README.md) - Release documentation index
+- [v1.2.0 Release](releases/RELEASE-v1.2.0.md) - Latest stable release
+- [v1.2.0 Publishing Guide](releases/NPM-PUBLISH-GUIDE-v1.2.0.md) - Publishing process
+- [v1.2.1 Hotfix](releases/HOTFIX-v1.2.1.md) - Critical fixes
+
+### 🗄️ [Validation Archive](validation/)
+Historical validation reports and test archives.
+
+- [Validation Archive](validation/README.md) - Archived test reports
 
 ### 📦 [Archived](archived/)
 Historical documentation, completed implementations, and validation reports.
@@ -103,13 +128,15 @@ Historical documentation, completed implementations, and validation reports.
 ### Path 2: Developers (1.5 hours)
 1. [Architecture Overview](architecture/EXECUTIVE_SUMMARY.md) - System design (20 min)
 2. [Implementation Examples](guides/IMPLEMENTATION_EXAMPLES.md) - Code patterns (40 min)
-3. [Integration Guides](integrations/) - External services (30 min)
+3. [Integration Guides](integrations/) - External services (20 min)
+4. [Testing Documentation](testing/) - Quality assurance (10 min)
 
 ### Path 3: System Architects (2 hours)
 1. [Research Summary](architecture/RESEARCH_SUMMARY.md) - Technical findings (30 min)
 2. [Multi-Model Router Plan](architecture/MULTI_MODEL_ROUTER_PLAN.md) - Router architecture (45 min)
-3. [Integration Status](architecture/INTEGRATION-STATUS.md) - Current state (30 min)
+3. [Integration Status](architecture/INTEGRATION-STATUS.md) - Current state (20 min)
 4. [Router Documentation](router/) - Configuration and usage (15 min)
+5. [MCP Validation](mcp-validation/) - Protocol implementation (10 min)
 
 ---
 
@@ -192,5 +219,15 @@ Historical reports, completed implementations, and superseded guides are in the
 
 ---
 
-**Documentation Status**: ✅ Organized and up-to-date
-**Last Updated**: October 5, 2025
+**Documentation Status**: ✅ Reorganized and up-to-date
+**Last Updated**: October 6, 2025
+
+## 📋 Recent Documentation Updates
+
+**v2.0 Reorganization (Oct 6, 2025)**:
+- Created dedicated `releases/` directory for version-specific documentation
+- Consolidated testing reports into `testing/` directory
+- Separated MCP validation into dedicated `mcp-validation/` section
+- Added comprehensive READMEs to all major sections
+- Archived historical v1.1.x releases for cleaner navigation
+- Improved documentation index with better categorization

package/docs/mcp-validation/README.md

@@ -0,0 +1,43 @@
+# MCP Validation Reports
+
+Model Context Protocol (MCP) implementation and validation documentation.
+
+## Validation Reports
+
+- [Implementation Summary](IMPLEMENTATION-SUMMARY.md) - MCP implementation details
+- [MCP CLI Validation Report](MCP-CLI-VALIDATION-REPORT.md) - Command-line tool validation
+- [Strange Loops Test](strange-loops-test.md) - Advanced MCP pattern testing
+
+## MCP Integration
+
+The agentic-flow system integrates with multiple MCP servers:
+
+### Primary MCP Server
+- **claude-flow** - Core coordination and orchestration
+- 70+ specialized tools for agent coordination
+- Neural pattern learning and memory management
+
+### Optional MCP Servers
+- **ruv-swarm** - Enhanced coordination topologies
+- **flow-nexus** - Cloud-based orchestration (requires authentication)
+
+## MCP Tools Categories
+
+1. **Swarm Coordination** - `swarm_init`, `agent_spawn`, `task_orchestrate`
+2. **Memory Management** - `memory_usage`, `memory_search`, `memory_persist`
+3. **Neural Learning** - `neural_train`, `neural_patterns`, `cognitive_analyze`
+4. **Performance** - `benchmark_run`, `bottleneck_analyze`, `performance_report`
+5. **GitHub Integration** - `github_repo_analyze`, `github_pr_manage`, `github_workflow_auto`
+
+## Validation Status
+
+✅ Core MCP functionality validated
+✅ CLI tools operational
+✅ Integration with Claude Code confirmed
+✅ Multi-provider support working
+
+## Related Documentation
+
+- [MCP Integration Guide](../guides/ADDING-MCP-SERVERS.md)
+- [MCP CLI Integration](../integrations/FASTMCP_CLI_INTEGRATION.md)
+- [Router MCP Support](../router/README.md)

package/docs/releases/HOTFIX-v1.2.1.md

@@ -0,0 +1,315 @@
+# Hotfix v1.2.1 - Critical Bug Fixes
+
+**Release Date:** 2025-10-06
+**Type:** Patch Release
+**Fixes:** 2 critical issues found in v1.2.0
+
+---
+
+## Issues Fixed
+
+### Issue #1: CLI Router Not Wired 🔴 CRITICAL - FIXED
+
+**Problem:** The main CLI didn't route `mcp` subcommands to `mcp-manager.js`
+
+**Symptoms:**
+```bash
+npx agentic-flow mcp add    # ❌ Started MCP server instead
+npx agentic-flow mcp list   # ❌ Started MCP server instead
+```
+
+**Root Cause:** The CLI parser detected `mcp` as a mode but didn't distinguish between MCP manager commands (add, list, remove) and MCP server commands (start, stop, status).
+
+**Fix Applied:**
+- Updated `src/utils/cli.ts` to detect MCP manager subcommands
+- Added new mode `'mcp-manager'` to CliOptions
+- Added routing in `src/cli-proxy.ts` to spawn mcp-manager.js for manager commands
+
+**Result:** ✅ FIXED
+```bash
+npx agentic-flow mcp list   # ✅ Now shows configured servers
+npx agentic-flow mcp add    # ✅ Now adds servers to config
+```
+
+**Test Output:**
+```
+$ node dist/cli-proxy.js mcp list
+Configured MCP Servers:
+
+✅ strange-loops (enabled)
+   Type: local
+   Command: npx -y strange-loops mcp start
+   Description: Strange Loops MCP server for testing
+```
+
+---
+
+### Issue #2: Model Optimization Filter 🟡 ENHANCEMENT - FIXED
+
+**Problem:** `--optimize` flag selected models without tool support (DeepSeek R1)
+
+**Symptoms:**
+```bash
+npx agentic-flow --agent coder --task "..." --optimize
+# Selected: DeepSeek R1 (doesn't support tool use)
+# Error: Tools not available
+```
+
+**Root Cause:** Model optimizer didn't filter by tool-use capability. All agents have MCP tools available, so models must support function calling.
+
+**Fix Applied:**
+1. Added `supports_tools` field to all models in MODEL_DATABASE
+2. Set `deepseek-r1: supports_tools: false` (confirmed no tool support)
+3. Added `requiresTools` parameter to OptimizationCriteria
+4. Added filtering logic in `ModelOptimizer.optimize()`
+5. Set `requiresTools: true` in cli-proxy.ts when optimizing
+
+**Result:** ✅ FIXED
+
+**Test Output:**
+```javascript
+// Test 1: WITH tool requirement (as used in CLI)
+ModelOptimizer.optimize({
+  agent: 'coder',
+  task: 'Simple hello world',
+  priority: 'cost',
+  requiresTools: true  // <-- Filters out DeepSeek R1
+});
+// Selected: DeepSeek Chat V3.1 (supports tools)
+
+// Test 2: WITHOUT tool requirement
+ModelOptimizer.optimize({
+  agent: 'coder',
+  task: 'Simple hello world',
+  priority: 'cost',
+  requiresTools: false
+});
+// Selected: DeepSeek R1 (cheapest, no tools needed)
+```
+
+---
+
+## Files Changed
+
+### src/utils/cli.ts
+**Changes:**
+- Added detection for MCP manager commands (add, list, remove, etc.)
+- Added new mode: `'mcp-manager'`
+- Router now distinguishes between MCP manager and MCP server commands
+
+```typescript
+// Check for MCP command
+if (args[0] === 'mcp') {
+  const mcpSubcommand = args[1];
+
+  // MCP Manager commands (CLI configuration)
+  const managerCommands = ['add', 'list', 'remove', 'enable', 'disable', 'update', 'test', 'info', 'export', 'import'];
+
+  if (managerCommands.includes(mcpSubcommand)) {
+    options.mode = 'mcp-manager';
+    return options;
+  }
+
+  // MCP Server commands (start/stop server)
+  options.mode = 'mcp';
+  options.mcpCommand = mcpSubcommand || 'start';
+  options.mcpServer = args[2] || 'all';
+  return options;
+}
+```
+
+### src/cli-proxy.ts
+**Changes:**
+- Added routing for `'mcp-manager'` mode
+- Spawns `mcp-manager.js` with proper args
+- Added `requiresTools: true` to model optimization
+
+```typescript
+if (options.mode === 'mcp-manager') {
+  // Handle MCP manager commands (add, list, remove, etc.)
+  const { spawn } = await import('child_process');
+  const { resolve, dirname } = await import('path');
+  const { fileURLToPath } = await import('url');
+
+  const __filename = fileURLToPath(import.meta.url);
+  const __dirname = dirname(__filename);
+  const mcpManagerPath = resolve(__dirname, './cli/mcp-manager.js');
+
+  // Pass all args after 'mcp' to mcp-manager
+  const mcpArgs = process.argv.slice(3);
+
+  const proc = spawn('node', [mcpManagerPath, ...mcpArgs], {
+    stdio: 'inherit'
+  });
+
+  proc.on('exit', (code) => {
+    process.exit(code || 0);
+  });
+
+  process.on('SIGINT', () => proc.kill('SIGINT'));
+  process.on('SIGTERM', () => proc.kill('SIGTERM'));
+  return;
+}
+```
+
+```typescript
+// Apply model optimization if requested
+if (options.optimize && options.agent && options.task) {
+  const recommendation = ModelOptimizer.optimize({
+    agent: options.agent,
+    task: options.task,
+    priority: options.optimizePriority || 'balanced',
+    maxCostPerTask: options.maxCost,
+    requiresTools: true // Agents have MCP tools available, so require tool support
+  });
+```
+
+### src/utils/modelOptimizer.ts
+**Changes:**
+- Added `requiresTools?: boolean` to OptimizationCriteria interface
+- Added `supports_tools` field to all models in MODEL_DATABASE
+- Added filtering logic to exclude models without tool support when required
+
+```typescript
+export interface OptimizationCriteria {
+  agent: string;
+  task: string;
+  priority?: 'quality' | 'balanced' | 'cost' | 'speed' | 'privacy';
+  maxCostPerTask?: number;
+  requiresReasoning?: boolean;
+  requiresMultimodal?: boolean;
+  requiresTools?: boolean; // NEW: Filter models that support tool/function calling
+  taskComplexity?: 'simple' | 'moderate' | 'complex' | 'expert';
+}
+```
+
+```typescript
+// Filter models that support tools if required
+let availableModels = Object.entries(MODEL_DATABASE);
+
+if (criteria.requiresTools) {
+  availableModels = availableModels.filter(([key, model]) => model.supports_tools !== false);
+  logger.info(`Filtered to ${availableModels.length} models with tool support`);
+}
+
+// Score all models
+const scoredModels = availableModels.map(([key, model]) => {
+  // ... scoring logic
+});
+```
+
+**Model Database Updates:**
+```typescript
+'deepseek-r1': {
+  // ...
+  supports_tools: false, // DeepSeek R1 does NOT support tool/function calling
+  weaknesses: ['newer-model', 'no-tool-use'],
+  // ...
+},
+'deepseek-chat-v3': {
+  // ...
+  supports_tools: true,
+  // ...
+},
+// All other models: supports_tools: true (except local ONNX)
+```
+
+---
+
+## Test Results
+
+### Test 1: MCP CLI Routing ✅ PASS
+```bash
+# Before (v1.2.0):
+$ npx agentic-flow mcp list
+Starting MCP server... (WRONG)
+
+# After (v1.2.1):
+$ npx agentic-flow mcp list
+Configured MCP Servers:
+✅ strange-loops (enabled)
+```
+
+### Test 2: Model Optimizer Tool Filtering ✅ PASS
+```javascript
+// WITH tool requirement (default for CLI)
+Selected: DeepSeek Chat V3.1 (supports tools) ✅
+
+// WITHOUT tool requirement
+Selected: DeepSeek R1 (no tools, cheaper) ✅
+```
+
+### Test 3: End-to-End Agent Execution ✅ PASS
+```bash
+$ npx agentic-flow --agent coder --task "Create calculator" --optimize
+Selected: Claude Sonnet 4.5 (supports tools) ✅
+Agent successfully used MCP tools ✅
+```
+
+---
+
+## Breaking Changes
+
+**None.** This is a patch release with bug fixes only.
+
+---
+
+## Upgrade Instructions
+
+### For Users
+```bash
+# Update globally
+npm install -g agentic-flow@1.2.1
+
+# Or use npx (always uses latest)
+npx agentic-flow mcp list
+```
+
+### Verify Fix
+```bash
+# Test MCP CLI routing
+npx agentic-flow mcp list
+
+# Test model optimization
+npx agentic-flow --agent coder --task "test" --optimize
+# Should NOT select DeepSeek R1
+```
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.2.1 | 2025-10-06 | **HOTFIX** - MCP CLI routing + model optimizer tool filtering |
+| 1.2.0 | 2025-10-06 | MCP CLI for user-friendly configuration |
+| 1.1.14 | 2025-10-05 | OpenRouter proxy fix (80% success rate) |
+
+---
+
+## Credits
+
+**Reported By:** Testing and validation
+**Fixed By:** Claude Code
+**Release Type:** Patch (Point Release)
+
+---
+
+## Summary
+
+✅ **Both Issues Fixed**
+- MCP CLI commands now route correctly
+- Model optimizer filters by tool support
+
+✅ **All Tests Pass**
+- MCP list/add commands work
+- Optimization selects tool-supporting models
+
+✅ **Ready for NPM Publish**
+- Version: 1.2.1
+- Type: Patch release
+- Breaking changes: None
+
+---
+
+**Status:** ✅ READY FOR RELEASE

package/docs/releases/PUBLISH-COMPLETE-v1.2.0.md

@@ -0,0 +1,308 @@
+# ✅ NPM Publish Complete - agentic-flow v1.2.0
+
+**Published:** 2025-10-06
+**Version:** 1.2.0
+**Package:** agentic-flow
+**Status:** ✅ LIVE ON NPM
+
+---
+
+## 🎉 Publication Successful!
+
+**NPM Package:** https://www.npmjs.com/package/agentic-flow/v/1.2.0
+
+**Install Command:**
+```bash
+npm install -g agentic-flow@1.2.0
+```
+
+**Or use with npx:**
+```bash
+npx agentic-flow@1.2.0 mcp add my-server --npm my-mcp-package
+```
+
+---
+
+## 📦 What Was Published
+
+### Package Details
+- **Name:** agentic-flow
+- **Version:** 1.2.0 (from 1.1.14)
+- **Description:** "Production-ready AI agent orchestration platform with 66 specialized agents, 213 MCP tools, and autonomous multi-agent swarms. Built by @ruvnet with Claude Agent SDK, neural networks, memory persistence, GitHub integration, and distributed consensus protocols. v1.2.0: NEW - Add custom MCP servers via CLI without code editing! Compatible with Claude Desktop config format."
+- **Main Entry:** dist/cli-proxy.js
+- **Binary:** agentic-flow → dist/cli-proxy.js
+
+### Key Files Included
+- ✅ `dist/cli/mcp-manager.js` - NEW MCP CLI tool
+- ✅ All agent definitions (66 agents)
+- ✅ All MCP tools and servers
+- ✅ Complete documentation
+- ✅ Build artifacts in dist/
+- ✅ Claude Code integration files
+
+### NPM Build Warnings (Non-Critical)
+```
+npm WARN publish npm auto-corrected some errors in your package.json when publishing.
+npm WARN publish "repository.url" was normalized to "git+https://github.com/ruvnet/agentic-flow.git"
+```
+**Note:** NPM automatically fixed the repository URL format. This is normal and non-breaking.
+
+---
+
+## 🚀 Major Feature: MCP CLI Manager
+
+### What Users Get
+
+**Add MCP Servers Without Code Editing:**
+```bash
+# Claude Desktop style JSON config
+npx agentic-flow mcp add weather '{"command":"npx","args":["-y","weather-mcp"]}'
+
+# Simple flag-based config
+npx agentic-flow mcp add github --npm @modelcontextprotocol/server-github
+
+# List servers
+npx agentic-flow mcp list
+
+# Use in agents (automatic)
+npx agentic-flow --agent researcher --task "Get weather for Tokyo"
+```
+
+### Key Benefits
+- ✅ No TypeScript knowledge required
+- ✅ No code editing required
+- ✅ No rebuilding required
+- ✅ Compatible with Claude Desktop config format
+- ✅ Configuration persisted in `~/.agentic-flow/mcp-config.json`
+- ✅ Automatic loading in all agents
+
+---
+
+## 📊 Publication Metrics
+
+### Package Size
+```
+npm notice 📦  agentic-flow@1.2.0
+npm notice === Tarball Details ===
+npm notice Total files: 476
+```
+
+### Files Breakdown
+- Agent definitions: 66 specialized agents
+- MCP tools: 213 tools from 4 servers
+- CLI tools: 5 CLI managers including new mcp-manager
+- Documentation: Comprehensive guides and validation reports
+- Build artifacts: Complete dist/ directory
+
+---
+
+## ✅ Post-Publish Verification
+
+### NPM Package Live
+```bash
+# Check package
+npm view agentic-flow
+
+# Output shows version 1.2.0 is live
+```
+
+### Quick Smoke Test
+```bash
+# Install globally
+npm install -g agentic-flow@1.2.0
+
+# Test version
+agentic-flow --version  # Should show 1.2.0
+
+# Test new MCP CLI
+agentic-flow mcp --help
+
+# Add test server
+agentic-flow mcp add test '{"command":"echo","args":["hello"]}'
+
+# List servers
+agentic-flow mcp list
+```
+
+---
+
+## 🔗 Links & Resources
+
+### NPM
+- **Package Page:** https://www.npmjs.com/package/agentic-flow
+- **Version 1.2.0:** https://www.npmjs.com/package/agentic-flow/v/1.2.0
+- **Downloads:** https://npm-stat.com/charts.html?package=agentic-flow
+
+### GitHub
+- **Repository:** https://github.com/ruvnet/agentic-flow
+- **Pull Request:** https://github.com/ruvnet/agentic-flow/pull/4
+- **Branch:** feat/provider-optimization-and-mcp-integration
+- **Commits:**
+  - c415477 - feat: Add MCP CLI for user-friendly server configuration
+  - 6379fcb - chore: Bump version to 1.2.0 and add NPM publish guide
+
+### Documentation
+- **User Guide:** [ADDING-MCP-SERVERS-CLI.md](./guides/ADDING-MCP-SERVERS-CLI.md)
+- **Developer Guide:** [ADDING-MCP-SERVERS.md](./guides/ADDING-MCP-SERVERS.md)
+- **Validation Report:** [MCP-CLI-VALIDATION-REPORT.md](./mcp-validation/MCP-CLI-VALIDATION-REPORT.md)
+- **Release Notes:** [RELEASE-v1.2.0.md](./RELEASE-v1.2.0.md)
+
+---
+
+## 📋 Next Steps
+
+### 1. Create GitHub Release
+
+**Recommended:** Create GitHub release for v1.2.0
+
+```bash
+gh release create v1.2.0 \
+  --title "v1.2.0 - MCP CLI for User-Friendly Configuration" \
+  --notes-file docs/RELEASE-v1.2.0.md
+```
+
+Or via GitHub web UI:
+- Go to: https://github.com/ruvnet/agentic-flow/releases/new
+- Tag: `v1.2.0`
+- Title: `v1.2.0 - MCP CLI for User-Friendly Configuration`
+- Description: Copy from RELEASE-v1.2.0.md
+
+### 2. Merge Pull Request
+
+**PR #4:** https://github.com/ruvnet/agentic-flow/pull/4
+
+```bash
+gh pr merge 4 --merge
+```
+
+Or merge via GitHub web UI
+
+### 3. Announce Release
+
+**Channels to notify:**
+- GitHub Discussions
+- Project README
+- Social media (Twitter, LinkedIn, etc.)
+- Community forums (Reddit, Discord, etc.)
+
+**Key Message Points:**
+- ✅ Add custom MCP servers without code editing
+- ✅ Compatible with Claude Desktop config format
+- ✅ User-friendly CLI commands
+- ✅ 100% backward compatible
+
+### 4. Monitor Package
+
+**NPM Stats:**
+- Watch download counts
+- Monitor version distribution
+- Track user feedback
+
+**GitHub:**
+- Watch for issues related to MCP CLI
+- Monitor PR comments
+- Check discussions
+
+---
+
+## 🎯 Success Metrics
+
+### Pre-Publish Checklist ✅
+- [x] TypeScript compilation successful
+- [x] All tests passing
+- [x] Build artifacts verified
+- [x] Version updated to 1.2.0
+- [x] Documentation complete
+- [x] PR created (#4)
+- [x] Changes committed and pushed
+- [x] NPM credentials configured
+
+### Publication ✅
+- [x] NPM publish successful
+- [x] Package version 1.2.0 live
+- [x] No critical warnings
+- [x] All files included
+
+### Post-Publish ⏳
+- [ ] GitHub release created
+- [ ] PR merged to main
+- [ ] Release announced
+- [ ] User feedback collected
+
+---
+
+## 📝 Version History
+
+| Version | Date | Key Feature | Status |
+|---------|------|-------------|--------|
+| 1.2.0 | 2025-10-06 | MCP CLI for configuration | ✅ Published |
+| 1.1.14 | 2025-10-05 | OpenRouter proxy fix | ✅ Published |
+| 1.1.13 | 2025-10-04 | Context-aware OpenRouter | ✅ Published |
+
+---
+
+## 🔐 Package Integrity
+
+### NPM Warnings
+```
+npm WARN publish npm auto-corrected some errors in your package.json
+npm WARN publish "repository.url" was normalized
+```
+
+**Resolution:** Non-critical. NPM auto-corrected repository URL format. No action needed.
+
+### Files Integrity
+- ✅ All source files included
+- ✅ Build artifacts present
+- ✅ Documentation complete
+- ✅ No sensitive data exposed
+
+---
+
+## 📞 Support
+
+### For Users
+- **Documentation:** docs/guides/ADDING-MCP-SERVERS-CLI.md
+- **Issues:** https://github.com/ruvnet/agentic-flow/issues
+- **Discussions:** https://github.com/ruvnet/agentic-flow/discussions
+
+### For Developers
+- **Developer Guide:** docs/guides/ADDING-MCP-SERVERS.md
+- **Implementation:** src/cli/mcp-manager.ts
+- **Validation:** docs/mcp-validation/
+
+---
+
+## 🎊 Summary
+
+**Status:** ✅ **PUBLISH COMPLETE**
+
+**What was accomplished:**
+1. ✅ Implemented MCP CLI manager (617 lines)
+2. ✅ Integrated auto-load in agents
+3. ✅ Created comprehensive documentation (5 guides)
+4. ✅ Validated with live agent test
+5. ✅ Updated package to v1.2.0
+6. ✅ Published to NPM successfully
+7. ✅ Created GitHub PR (#4)
+
+**What's live:**
+- NPM package: agentic-flow@1.2.0
+- GitHub branch: feat/provider-optimization-and-mcp-integration
+- Pull request: #4
+- Documentation: Complete and published
+
+**Next actions:**
+1. Create GitHub release for v1.2.0
+2. Merge PR #4 to main
+3. Announce release to users
+4. Monitor feedback and downloads
+
+---
+
+**Published by:** ruvnet
+**Implemented with:** Claude Code
+**Release Status:** ✅ COMPLETE AND LIVE
+**Package URL:** https://www.npmjs.com/package/agentic-flow/v/1.2.0
+
+🎉 **Congratulations! agentic-flow v1.2.0 is now live on NPM!**

package/docs/releases/README.md

@@ -0,0 +1,18 @@
+# Release Documentation
+
+Version-specific release notes, publish guides, and hotfix documentation.
+
+## Latest Releases
+
+- [v1.2.0 Release](RELEASE-v1.2.0.md) - Latest stable release
+- [v1.2.0 Publishing Guide](NPM-PUBLISH-GUIDE-v1.2.0.md) - How the release was published
+- [v1.2.0 Publish Complete](PUBLISH-COMPLETE-v1.2.0.md) - Publishing completion report
+- [v1.2.1 Hotfix](HOTFIX-v1.2.1.md) - Critical hotfix documentation
+
+## Archived Releases
+
+Historical release notes for v1.1.x can be found in the [archived/](../archived/) directory.
+
+## Release Process
+
+For information on how to publish new releases, see the [NPM Publishing Guide](../guides/NPM-PUBLISH.md).

package/docs/testing/README.md

@@ -0,0 +1,46 @@
+# Testing & Validation Documentation
+
+Comprehensive testing reports, validation summaries, and quality assurance documentation.
+
+## Current Test Reports
+
+- [Agent System Validation](AGENT-SYSTEM-VALIDATION.md) - Multi-agent system testing
+- [Final Testing Summary](FINAL-TESTING-SUMMARY.md) - Comprehensive test coverage report
+- [Regression Test Results](REGRESSION-TEST-RESULTS.md) - Regression testing outcomes
+- [Streaming and MCP Validation](STREAMING-AND-MCP-VALIDATION.md) - MCP integration tests
+
+## Test Categories
+
+### Agent System Tests
+- Multi-agent coordination
+- Swarm topology validation
+- Task orchestration
+- Memory and state management
+
+### Integration Tests
+- MCP server integration
+- Provider compatibility (Anthropic, OpenRouter, ONNX, Gemini)
+- Streaming functionality
+- Real-time coordination
+
+### Regression Tests
+- Backward compatibility
+- Performance benchmarks
+- API contract validation
+
+## Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run specific test suite
+npm test -- --grep "agent"
+
+# Run with coverage
+npm run test:coverage
+```
+
+## Historical Test Reports
+
+Older validation reports can be found in the [validation/](../validation/) and [archived/](../archived/) directories.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agentic-flow",
-  "version": "1.2.0",
-  "description": "Production-ready AI agent orchestration platform with 66 specialized agents, 213 MCP tools, and autonomous multi-agent swarms. Built by @ruvnet with Claude Agent SDK, neural networks, memory persistence, GitHub integration, and distributed consensus protocols. v1.2.0: NEW - Add custom MCP servers via CLI without code editing! Compatible with Claude Desktop config format.",
+  "version": "1.2.1",
+  "description": "Production-ready AI agent orchestration platform with 66 specialized agents, 213 MCP tools, and autonomous multi-agent swarms. Built by @ruvnet with Claude Agent SDK, neural networks, memory persistence, GitHub integration, and distributed consensus protocols. v1.2.1: Hotfix - Fixed CLI routing for MCP commands and model optimizer tool filtering.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {