agentic-flow 1.1.14 → 1.2.1

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/releases/RELEASE-v1.2.0.md

@@ -0,0 +1,339 @@
+# Release Notes - agentic-flow v1.2.0
+
+**Release Date:** 2025-10-06
+**Version:** 1.2.0
+**Major Feature:** MCP CLI for User-Friendly Server Configuration
+
+---
+
+## 🚀 What's New
+
+### MCP CLI Manager - Add Custom Servers Without Code Editing!
+
+**The Problem:** Previously, adding custom MCP servers required editing TypeScript code and rebuilding the project.
+
+**The Solution:** New CLI commands let end users add custom MCP servers without any code editing, similar to Claude Desktop's approach.
+
+### New Commands
+
+```bash
+# Add MCP server (Claude Desktop style JSON config)
+npx agentic-flow mcp add weather '{"command":"npx","args":["-y","weather-mcp"],"env":{"API_KEY":"xxx"}}'
+
+# Add MCP server (simple flag-based config)
+npx agentic-flow mcp add github --npm @modelcontextprotocol/server-github --env "GITHUB_TOKEN=ghp_xxx"
+
+# Add local MCP server
+npx agentic-flow mcp add my-tools --local /path/to/server.js
+
+# List configured servers
+npx agentic-flow mcp list
+
+# Enable/disable servers
+npx agentic-flow mcp enable weather
+npx agentic-flow mcp disable weather
+
+# Remove server
+npx agentic-flow mcp remove weather
+
+# Update configuration
+npx agentic-flow mcp update weather --env "API_KEY=new-key"
+```
+
+### Key Benefits
+
+- ✅ **No Code Editing** - Add servers via CLI commands
+- ✅ **No TypeScript Required** - Suitable for non-developers
+- ✅ **No Rebuilding** - Changes take effect immediately
+- ✅ **Claude Desktop Compatible** - Same JSON config format
+- ✅ **Automatic Loading** - Servers load automatically in all agents
+- ✅ **Persistent Storage** - Configuration stored in `~/.agentic-flow/mcp-config.json`
+- ✅ **100% Backward Compatible** - No breaking changes
+
+---
+
+## 📚 Documentation
+
+### User Guides
+- **[ADDING-MCP-SERVERS-CLI.md](./guides/ADDING-MCP-SERVERS-CLI.md)** (516 lines)
+  - Complete end-user guide for CLI commands
+  - Step-by-step examples
+  - Popular MCP servers list
+  - Troubleshooting section
+
+- **[ADDING-MCP-SERVERS.md](./guides/ADDING-MCP-SERVERS.md)** (570 lines)
+  - Developer integration guide
+  - Code examples for in-SDK and external servers
+  - Best practices
+
+### Validation Reports
+- **[MCP-CLI-VALIDATION-REPORT.md](./mcp-validation/MCP-CLI-VALIDATION-REPORT.md)**
+  - Complete validation results
+  - Live agent test with strange-loops MCP
+  - 100% test pass rate (8/8 tests)
+
+- **[IMPLEMENTATION-SUMMARY.md](./mcp-validation/IMPLEMENTATION-SUMMARY.md)**
+  - Technical implementation details
+  - Before/after comparison
+  - Security considerations
+
+- **[strange-loops-test.md](./mcp-validation/strange-loops-test.md)**
+  - Live agent test output
+  - Proof of integration working
+
+---
+
+## 🔧 Technical Details
+
+### New Files
+
+**Implementation:**
+- `src/cli/mcp-manager.ts` (617 lines)
+  - Complete CLI tool with 8 commands
+  - JSON and flag-based config support
+  - Configuration management
+
+**Documentation:**
+- `docs/guides/ADDING-MCP-SERVERS-CLI.md`
+- `docs/guides/ADDING-MCP-SERVERS.md`
+- `docs/mcp-validation/MCP-CLI-VALIDATION-REPORT.md`
+- `docs/mcp-validation/IMPLEMENTATION-SUMMARY.md`
+- `docs/mcp-validation/strange-loops-test.md`
+- `docs/NPM-PUBLISH-GUIDE-v1.2.0.md`
+
+### Modified Files
+
+**Agent Integration:**
+- `src/agents/claudeAgent.ts` (lines 171-203)
+  - Auto-load user-configured MCP servers
+  - Read from `~/.agentic-flow/mcp-config.json`
+  - Merge with built-in servers
+
+**Documentation:**
+- Root `README.md` - Added "Add Custom MCP Servers" section
+- NPM `README.md` - Added "Add Custom MCP Servers" section
+
+### Configuration Format
+
+```json
+{
+  "servers": {
+    "server-name": {
+      "enabled": true,
+      "type": "npm" | "local",
+      "package": "npm-package@version",
+      "command": "npx" | "node" | "python3" | "docker",
+      "args": ["arg1", "arg2"],
+      "env": {
+        "API_KEY": "value"
+      },
+      "description": "Server description"
+    }
+  }
+}
+```
+
+---
+
+## ✅ Validation Results
+
+### Live Agent Test
+
+**Test:** Added strange-loops MCP server and ran agent
+
+**Command:**
+```bash
+npx agentic-flow mcp add strange-loops '{"command":"npx","args":["-y","strange-loops","mcp","start"]}'
+npx agentic-flow --agent researcher --task "List all MCP tools"
+```
+
+**Result:** ✅ SUCCESS
+- Agent loaded strange-loops MCP server
+- Detected all 9 tools from the server
+- Tools immediately available to agent
+
+**Console Output:**
+```
+[agentic-flow] Loaded MCP server: strange-loops
+```
+
+**Tools Detected:**
+1. `mcp__strange-loops__system_info`
+2. `mcp__strange-loops__benchmark_run`
+3. `mcp__strange-loops__nano_swarm_create`
+4. `mcp__strange-loops__nano_swarm_run`
+5. `mcp__strange-loops__quantum_container_create`
+6. `mcp__strange-loops__quantum_superposition`
+7. `mcp__strange-loops__quantum_measure`
+8. `mcp__strange-loops__temporal_predictor_create`
+9. `mcp__strange-loops__temporal_predict`
+
+### Test Results Summary
+
+| Test | Status | Evidence |
+|------|--------|----------|
+| TypeScript Build | ✅ PASS | Compilation successful |
+| CLI Commands | ✅ PASS | All commands working |
+| JSON Config | ✅ PASS | Claude Desktop format supported |
+| Flag Config | ✅ PASS | Flag-based format supported |
+| Config Persistence | ✅ PASS | Stored in ~/.agentic-flow/ |
+| Agent Integration | ✅ PASS | Auto-load working |
+| Tool Discovery | ✅ PASS | All tools detected |
+| Backward Compatibility | ✅ PASS | No breaking changes |
+
+**Overall:** ✅ **100% PASS RATE (8/8 tests)**
+
+---
+
+## 🎯 Use Cases
+
+### Add GitHub MCP Server
+```bash
+# Add official GitHub MCP
+npx agentic-flow mcp add github \
+  --npm @modelcontextprotocol/server-github \
+  --env "GITHUB_TOKEN=ghp_your_token"
+
+# Use it with agent
+npx agentic-flow --agent coder --task "Create issue on repo owner/repo"
+```
+
+### Add Weather MCP Server
+```bash
+# Add weather MCP
+npx agentic-flow mcp add weather \
+  --npm weather-mcp \
+  --env "WEATHER_API_KEY=your_key"
+
+# Use it
+npx agentic-flow --agent researcher --task "Get weather forecast for San Francisco"
+```
+
+### Add Local Development Server
+```bash
+# Add local MCP server
+npx agentic-flow mcp add dev-tools \
+  --local /home/user/projects/my-mcp/server.js
+
+# Use it
+npx agentic-flow --agent coder --task "Use my custom tools"
+```
+
+---
+
+## 🚫 Breaking Changes
+
+**None.** This is a purely additive feature.
+
+- Existing environment variable approach still works
+- Existing code-based MCP registration still works
+- User-configured servers load alongside built-in servers
+- No changes to existing APIs
+
+---
+
+## 🔮 Future Enhancements (v1.2.1+)
+
+### Planned Commands (Not in v1.2.0)
+
+**1. Test Command**
+```bash
+npx agentic-flow mcp test weather
+# Will test if server starts and responds correctly
+```
+
+**2. Info Command**
+```bash
+npx agentic-flow mcp info weather
+# Will show detailed server information
+```
+
+**3. Tools Command**
+```bash
+npx agentic-flow mcp tools weather
+# Will list all tools from specific server
+```
+
+**4. Export/Import**
+```bash
+npx agentic-flow mcp export > config.json
+npx agentic-flow mcp import < config.json
+# Share configurations with team
+```
+
+### Other Future Features
+- Shell completion (bash/zsh)
+- API key encryption in config
+- Server signature verification
+- Automatic server updates
+- Usage statistics
+
+---
+
+## 📦 Installation
+
+### Global Install
+```bash
+npm install -g agentic-flow@1.2.0
+```
+
+### Use with npx (No Install)
+```bash
+npx agentic-flow@1.2.0 mcp add my-server --npm my-mcp-package
+```
+
+### Upgrade from Previous Version
+```bash
+npm update -g agentic-flow
+```
+
+---
+
+## 🔗 Links
+
+**GitHub:**
+- Pull Request: https://github.com/ruvnet/agentic-flow/pull/4
+- Repository: https://github.com/ruvnet/agentic-flow
+- Issues: https://github.com/ruvnet/agentic-flow/issues
+
+**NPM:**
+- Package: https://www.npmjs.com/package/agentic-flow
+- Version: https://www.npmjs.com/package/agentic-flow/v/1.2.0
+
+**Documentation:**
+- User Guide: https://github.com/ruvnet/agentic-flow/blob/main/agentic-flow/docs/guides/ADDING-MCP-SERVERS-CLI.md
+- Developer Guide: https://github.com/ruvnet/agentic-flow/blob/main/agentic-flow/docs/guides/ADDING-MCP-SERVERS.md
+
+---
+
+## 👏 Credits
+
+**Built by:** [@ruvnet](https://github.com/ruvnet)
+**Implemented with:** [Claude Code](https://claude.com/claude-code)
+**Based on:** [Claude Agent SDK](https://docs.claude.com/en/api/agent-sdk) by Anthropic
+
+---
+
+## 📋 Quick Reference
+
+| Task | Command |
+|------|---------|
+| Add NPM server | `npx agentic-flow mcp add NAME --npm PACKAGE` |
+| Add local server | `npx agentic-flow mcp add NAME --local PATH` |
+| Add with JSON | `npx agentic-flow mcp add NAME '{"command":...}'` |
+| List servers | `npx agentic-flow mcp list` |
+| Enable server | `npx agentic-flow mcp enable NAME` |
+| Disable server | `npx agentic-flow mcp disable NAME` |
+| Remove server | `npx agentic-flow mcp remove NAME` |
+
+**Config File:** `~/.agentic-flow/mcp-config.json`
+
+---
+
+**Release Status:** ✅ READY FOR PRODUCTION
+
+**Validation:** ✅ 100% TEST PASS RATE
+
+**Documentation:** ✅ COMPLETE
+
+**Ready to Publish:** ✅ YES