441 lines
9.7 KiB
Markdown
441 lines
9.7 KiB
Markdown
# 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
|