@sparkleideas/agentic-flow 2.0.2-alpha-patch.1

package/agentic-flow/docs/releases/NPM-PUBLISH-GUIDE-v1.2.0.md

@@ -0,0 +1,440 @@
+# NPM Publish Guide - agentic-flow v1.2.0
+
+**Release Date:** 2025-10-06
+**Version:** 1.2.0 (from 1.1.14)
+**Major Feature:** MCP CLI for user-friendly server configuration
+
+---
+
+## Pre-Publish Checklist
+
+### ✅ Code & Build
+- [x] TypeScript compilation successful
+- [x] All tests passing
+- [x] Build artifacts verified in `dist/`
+- [x] `dist/cli/mcp-manager.js` present and working
+- [x] CLI help displays correctly
+
+### ✅ Version & Documentation
+- [x] `package.json` version updated to 1.2.0
+- [x] Package description updated with v1.2.0 feature
+- [x] Root README.md updated
+- [x] NPM README.md updated
+- [x] User guide created (ADDING-MCP-SERVERS-CLI.md)
+- [x] Developer guide created (ADDING-MCP-SERVERS.md)
+- [x] Validation reports created
+
+### ✅ Git & GitHub
+- [x] All changes committed
+- [x] Pushed to remote branch
+- [x] Pull request created (#4)
+- [x] PR description comprehensive
+
+### ⏳ NPM Publish Preparation
+- [ ] Merge PR to main (or publish from feature branch)
+- [ ] NPM credentials configured
+- [ ] Ready to publish
+
+---
+
+## What's New in v1.2.0
+
+### 🚀 Major Feature: MCP CLI Manager
+
+**End users can now add custom MCP servers without editing code!**
+
+#### New Commands
+```bash
+# Add MCP server (Claude Desktop style)
+npx agentic-flow mcp add weather '{"command":"npx","args":["-y","weather-mcp"]}'
+
+# Add MCP server (simple flags)
+npx agentic-flow mcp add github --npm @modelcontextprotocol/server-github
+
+# List configured servers
+npx agentic-flow mcp list
+
+# Enable/disable servers
+npx agentic-flow mcp enable weather
+npx agentic-flow mcp disable weather
+```
+
+#### Key Benefits
+- ✅ No TypeScript knowledge required
+- ✅ No code editing required
+- ✅ No rebuilding required
+- ✅ Compatible with Claude Desktop JSON config
+- ✅ Configuration stored in `~/.agentic-flow/mcp-config.json`
+- ✅ Automatic loading in all agents
+
+### 🔧 Technical Improvements
+- New CLI tool: `src/cli/mcp-manager.ts` (617 lines)
+- Auto-load config in agents: `src/agents/claudeAgent.ts`
+- Comprehensive documentation (5 new docs)
+- Live validation with strange-loops MCP server
+
+### 📚 Documentation
+- User guide: `docs/guides/ADDING-MCP-SERVERS-CLI.md`
+- Developer guide: `docs/guides/ADDING-MCP-SERVERS.md`
+- Validation reports in `docs/mcp-validation/`
+- Updated README files
+
+---
+
+## NPM Publish Commands
+
+### Option 1: Publish from Feature Branch (Current State)
+
+**Current branch:** `feat/provider-optimization-and-mcp-integration`
+
+```bash
+# Make sure you're in the right directory
+cd /workspaces/agentic-flow/agentic-flow
+
+# Verify build artifacts
+ls -l dist/cli/mcp-manager.js
+
+# Verify version
+cat package.json | grep version
+
+# Check NPM login status
+npm whoami
+
+# Publish to NPM
+npm publish
+
+# Or publish as beta first
+npm publish --tag beta
+```
+
+### Option 2: Publish from Main Branch (After PR Merge)
+
+```bash
+# Merge PR first
+gh pr merge 4 --merge
+
+# Switch to main
+git checkout main
+git pull origin main
+
+# Verify everything
+npm run build
+npm test
+
+# Publish
+cd agentic-flow
+npm publish
+```
+
+### Option 3: Publish with Specific Tag
+
+```bash
+# Publish as beta
+npm publish --tag beta
+
+# Publish as latest (default)
+npm publish --tag latest
+
+# Publish as next
+npm publish --tag next
+```
+
+---
+
+## Post-Publish Steps
+
+### 1. Verify NPM Package
+```bash
+# Check package is live
+npm view agentic-flow
+
+# Check specific version
+npm view agentic-flow@1.2.0
+
+# Test installation
+npx agentic-flow@1.2.0 --version
+```
+
+### 2. Test New Feature
+```bash
+# Test MCP CLI
+npx agentic-flow@1.2.0 mcp --help
+
+# Add test server
+npx agentic-flow@1.2.0 mcp add test-server '{"command":"echo","args":["test"]}'
+
+# List servers
+npx agentic-flow@1.2.0 mcp list
+```
+
+### 3. Create GitHub Release
+
+**Via GitHub CLI:**
+```bash
+gh release create v1.2.0 \
+  --title "v1.2.0 - MCP CLI for User-Friendly Configuration" \
+  --notes "$(cat <<'EOF'
+# agentic-flow v1.2.0
+
+## 🚀 Major Feature: MCP CLI Manager
+
+End users can now add custom MCP servers without editing code!
+
+### New Commands
+
+```bash
+# Add MCP server (Claude Desktop style JSON config)
+npx agentic-flow mcp add weather '{"command":"npx","args":["-y","weather-mcp"]}'
+
+# Add MCP server (simple flags)
+npx agentic-flow mcp add github --npm @modelcontextprotocol/server-github
+
+# List configured servers
+npx agentic-flow mcp list
+```
+
+### Key Features
+
+✅ No code editing required
+✅ Compatible with Claude Desktop config format
+✅ Configuration stored in `~/.agentic-flow/mcp-config.json`
+✅ Automatic loading in all agents
+✅ 100% backward compatible
+
+### Documentation
+
+- **User Guide:** [ADDING-MCP-SERVERS-CLI.md](https://github.com/ruvnet/agentic-flow/blob/main/agentic-flow/docs/guides/ADDING-MCP-SERVERS-CLI.md)
+- **Developer Guide:** [ADDING-MCP-SERVERS.md](https://github.com/ruvnet/agentic-flow/blob/main/agentic-flow/docs/guides/ADDING-MCP-SERVERS.md)
+- **Validation Report:** [MCP-CLI-VALIDATION-REPORT.md](https://github.com/ruvnet/agentic-flow/blob/main/agentic-flow/docs/mcp-validation/MCP-CLI-VALIDATION-REPORT.md)
+
+### What's Changed
+
+- **New:** MCP CLI Manager (`src/cli/mcp-manager.ts`)
+- **Enhanced:** Agent integration with auto-load config
+- **Added:** Comprehensive documentation and validation
+- **Updated:** README files with MCP CLI examples
+
+### Breaking Changes
+
+None. Purely additive feature.
+
+### Installation
+
+```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
+```
+
+### Full Changelog
+
+See PR #4: https://github.com/ruvnet/agentic-flow/pull/4
+EOF
+)"
+```
+
+**Or via GitHub Web UI:**
+1. Go to https://github.com/ruvnet/agentic-flow/releases/new
+2. Tag: `v1.2.0`
+3. Title: `v1.2.0 - MCP CLI for User-Friendly Configuration`
+4. Copy release notes from above
+
+### 4. Announce Release
+
+**NPM Page:**
+- https://www.npmjs.com/package/agentic-flow
+
+**GitHub:**
+- https://github.com/ruvnet/agentic-flow
+
+**Social/Community:**
+- Tweet/post about new feature
+- Update project README badges
+- Notify users in Discord/Slack/forums
+
+---
+
+## Rollback Plan (If Issues Found)
+
+### Unpublish (within 72 hours)
+```bash
+# Unpublish specific version
+npm unpublish agentic-flow@1.2.0
+
+# Note: After 72 hours, can only deprecate
+```
+
+### Deprecate (after 72 hours)
+```bash
+# Mark version as deprecated
+npm deprecate agentic-flow@1.2.0 "Contains critical bug, use v1.2.1 instead"
+```
+
+### Quick Fix and Republish
+```bash
+# Fix issue
+# Update version to 1.2.1
+npm version patch  # Updates to 1.2.1
+
+# Rebuild and publish
+npm run build
+npm publish
+```
+
+---
+
+## Version History
+
+| Version | Date | Key Feature |
+|---------|------|-------------|
+| 1.2.0 | 2025-10-06 | MCP CLI for user-friendly configuration |
+| 1.1.14 | 2025-10-05 | Fixed OpenRouter proxy (80% success rate) |
+| 1.1.13 | 2025-10-04 | Context-aware OpenRouter proxy |
+| ... | ... | ... |
+
+---
+
+## Files Included in NPM Package
+
+### Source Files (dist/)
+- `dist/cli/mcp-manager.js` ✅ NEW
+- `dist/cli/agent-manager.js`
+- `dist/cli/claude-code-wrapper.js`
+- `dist/cli/config-wizard.js`
+- `dist/cli/mcp.js`
+- `dist/cli-proxy.js` (main entry point)
+- `dist/index.js`
+- All agent files, MCP servers, etc.
+
+### Documentation
+- `README.md` ✅ UPDATED
+- `docs/guides/ADDING-MCP-SERVERS-CLI.md` ✅ NEW
+- `docs/guides/ADDING-MCP-SERVERS.md` ✅ NEW
+- `docs/mcp-validation/` ✅ NEW
+- Other existing documentation
+
+### Configuration
+- `package.json` (version 1.2.0)
+- `tsconfig.json`
+- `.npmignore`
+
+---
+
+## Testing After Publish
+
+### 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 MCP CLI
+agentic-flow mcp --help
+
+# Add test server
+agentic-flow mcp add test '{"command":"echo","args":["hello"]}'
+
+# List servers
+agentic-flow mcp list
+
+# Test with agent
+agentic-flow --agent researcher --task "What is agentic-flow?"
+```
+
+### Integration Test
+```bash
+# Test with real MCP server
+agentic-flow mcp add strange-loops '{"command":"npx","args":["-y","strange-loops","mcp","start"]}'
+
+# Run agent that uses it
+agentic-flow --agent researcher --task "List all MCP tools from strange-loops"
+
+# Should see: [agentic-flow] Loaded MCP server: strange-loops
+```
+
+---
+
+## Monitoring Post-Release
+
+### NPM Stats
+- Check download counts: https://npm-stat.com/charts.html?package=agentic-flow
+- Monitor version distribution
+
+### GitHub
+- Watch for new issues related to MCP CLI
+- Monitor PR #4 comments
+- Check GitHub Discussions
+
+### User Feedback
+- Monitor support channels
+- Check for bug reports
+- Collect feature requests
+
+---
+
+## Known Issues / Limitations
+
+1. **Future Enhancements (v1.2.1+):**
+   - `mcp test` command not yet implemented
+   - `mcp info` command not yet implemented
+   - `mcp export/import` commands not yet implemented
+
+2. **Security Considerations:**
+   - API keys stored in plaintext in config file
+   - No signature verification for MCP servers
+   - Users should only add trusted MCP servers
+
+---
+
+## Support Resources
+
+**Documentation:**
+- User Guide: `docs/guides/ADDING-MCP-SERVERS-CLI.md`
+- Developer Guide: `docs/guides/ADDING-MCP-SERVERS.md`
+
+**Code:**
+- MCP Manager: `src/cli/mcp-manager.ts`
+- Agent Integration: `src/agents/claudeAgent.ts` (lines 171-203)
+
+**Validation:**
+- Test Results: `docs/mcp-validation/MCP-CLI-VALIDATION-REPORT.md`
+- Live Test: `docs/mcp-validation/strange-loops-test.md`
+
+**GitHub:**
+- Pull Request: https://github.com/ruvnet/agentic-flow/pull/4
+- Issues: https://github.com/ruvnet/agentic-flow/issues
+
+---
+
+## Ready to Publish!
+
+**Current Status:**
+- ✅ Code complete and tested
+- ✅ Build successful
+- ✅ Documentation complete
+- ✅ PR created
+- ✅ Version updated to 1.2.0
+- ⏳ Awaiting NPM publish command
+
+**Next Action:**
+```bash
+cd /workspaces/agentic-flow/agentic-flow
+npm publish
+```
+
+**Or publish as beta first:**
+```bash
+npm publish --tag beta
+```
+
+---
+
+**Prepared by:** Claude Code
+**Date:** 2025-10-06
+**Ready for Release:** ✅ YES