npm - agentic-flow - Versions diffs - 1.9.0 → 1.9.2 - Mend

agentic-flow 1.9.0 → 1.9.2

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/agentic-flow/docs/guides/ADDING-MCP-SERVERS-CLI.md DELETED Viewed

@@ -1,515 +0,0 @@
-# Adding MCP Servers via CLI (End User Guide)
-**For end users who want to add custom MCP servers without editing code.**
----
-## Quick Start
-```bash
-# Add an MCP server from NPM
-npx agentic-flow mcp add my-mcp-server --npm
-# Add a local MCP server
-npx agentic-flow mcp add my-local-server --command "node /path/to/server.js"
-# Add with environment variables
-npx agentic-flow mcp add weather-api --npm weather-mcp --env "WEATHER_API_KEY=xxx"
-# List configured MCP servers
-npx agentic-flow mcp list
-# Remove an MCP server
-npx agentic-flow mcp remove my-mcp-server
-# Enable/disable MCP server
-npx agentic-flow mcp enable my-mcp-server
-npx agentic-flow mcp disable my-mcp-server
-```
----
-## Configuration File
-MCP servers are stored in `~/.agentic-flow/mcp-config.json`:
-```json
-{
-  "servers": {
-    "my-custom-server": {
-      "enabled": true,
-      "type": "npm",
-      "package": "my-mcp-package@latest",
-      "command": "my-mcp",
-      "args": ["start"],
-      "env": {
-        "MY_API_KEY": "xxx"
-      },
-      "description": "My custom MCP server"
-    },
-    "local-tools": {
-      "enabled": true,
-      "type": "local",
-      "command": "node",
-      "args": ["/home/user/my-mcp/index.js"],
-      "env": {},
-      "description": "Local development MCP server"
-    }
-  }
-}
-```
----
-## CLI Commands
-### 1. Add MCP Server
-#### From NPM Package
-```bash
-# Basic NPM package
-npx agentic-flow mcp add weather-api --npm weather-mcp
-# With version
-npx agentic-flow mcp add weather-api --npm weather-mcp@1.2.3
-# With custom command
-npx agentic-flow mcp add weather-api --npm weather-mcp --command mcp-server
-# With environment variables
-npx agentic-flow mcp add weather-api \
-  --npm weather-mcp \
-  --env "WEATHER_API_KEY=your-key-here" \
-  --env "WEATHER_REGION=us-west"
-# With description
-npx agentic-flow mcp add weather-api \
-  --npm weather-mcp \
-  --desc "Weather data MCP server"
-```
-#### From Local Path
-```bash
-# Local executable
-npx agentic-flow mcp add my-tools --local /home/user/my-mcp/server.js
-# With node
-npx agentic-flow mcp add my-tools \
-  --command "node" \
-  --args "/home/user/my-mcp/server.js"
-# With Python
-npx agentic-flow mcp add python-tools \
-  --command "python3" \
-  --args "/home/user/mcp-server.py"
-# With custom arguments
-npx agentic-flow mcp add advanced-tools \
-  --command "node" \
-  --args "/path/to/server.js --port 8080 --debug"
-```
-#### With Docker
-```bash
-# Docker container
-npx agentic-flow mcp add docker-mcp \
-  --command "docker" \
-  --args "run -i --rm my-mcp-image"
-```
-### 2. List MCP Servers
-```bash
-# List all configured servers
-npx agentic-flow mcp list
-# Output:
-# Configured MCP Servers:
-#
-# ✅ weather-api (enabled)
-#    Type: npm
-#    Package: weather-mcp@latest
-#    Description: Weather data MCP server
-#
-# ✅ my-tools (enabled)
-#    Type: local
-#    Command: node /home/user/my-mcp/server.js
-#
-# ❌ old-server (disabled)
-#    Type: npm
-#    Package: old-mcp@1.0.0
-# List only enabled
-npx agentic-flow mcp list --enabled
-# Show full config
-npx agentic-flow mcp list --verbose
-```
-### 3. Enable/Disable MCP Server
-```bash
-# Enable server
-npx agentic-flow mcp enable weather-api
-# Disable server
-npx agentic-flow mcp disable weather-api
-# Enable all
-npx agentic-flow mcp enable --all
-# Disable all
-npx agentic-flow mcp disable --all
-```
-### 4. Remove MCP Server
-```bash
-# Remove server
-npx agentic-flow mcp remove weather-api
-# Remove with confirmation
-npx agentic-flow mcp remove weather-api --confirm
-# Remove all disabled servers
-npx agentic-flow mcp remove --disabled
-```
-### 5. Update MCP Server
-```bash
-# Update NPM package version
-npx agentic-flow mcp update weather-api --version 2.0.0
-# Update environment variables
-npx agentic-flow mcp update weather-api \
-  --env "WEATHER_API_KEY=new-key"
-# Update command
-npx agentic-flow mcp update my-tools \
-  --command "node" \
-  --args "/new/path/server.js"
-```
-### 6. Test MCP Server
-```bash
-# Test if server responds
-npx agentic-flow mcp test weather-api
-# Output:
-# Testing MCP server: weather-api
-# ✅ Server started successfully
-# ✅ Responds to tools/list
-# ✅ Found 5 tools:
-#    - get_weather
-#    - get_forecast
-#    - get_alerts
-#    - get_historical
-#    - search_location
-# ✅ Server is working correctly
-# Test with verbose output
-npx agentic-flow mcp test weather-api --verbose
-```
-### 7. Info/Docs
-```bash
-# Show server info
-npx agentic-flow mcp info weather-api
-# Output:
-# MCP Server: weather-api
-# Status: ✅ Enabled
-# Type: npm
-# Package: weather-mcp@1.2.3
-# Command: npx -y weather-mcp start
-# Environment:
-#   WEATHER_API_KEY: ***key***
-#   WEATHER_REGION: us-west
-# Tools: 5 tools available
-# Description: Weather data MCP server
-# Show all tools from server
-npx agentic-flow mcp tools weather-api
-# Output:
-# Tools from weather-api:
-# 1. get_weather - Get current weather for location
-# 2. get_forecast - Get weather forecast
-# 3. get_alerts - Get weather alerts
-# 4. get_historical - Get historical weather data
-# 5. search_location - Search for location by name
-```
----
-## Usage in Agents
-Once configured, MCP servers are automatically available to all agents:
-```bash
-# MCP servers load automatically
-npx agentic-flow --agent researcher \
-  --task "Get weather for San Francisco using get_weather tool"
-# All configured and enabled servers are available
-# No need to specify which MCP server to use
-```
----
-## Configuration via Environment Variables
-You can also configure MCP servers via environment variables (temporary):
-```bash
-# Add MCP server for this session only
-export AGENTIC_FLOW_MCP_WEATHER='{"type":"npm","package":"weather-mcp","env":{"API_KEY":"xxx"}}'
-# Use it
-npx agentic-flow --agent researcher --task "Get weather data"
-```
----
-## Popular MCP Servers
-Here are some popular MCP servers you can add:
-### Official Anthropic Servers
-```bash
-# Filesystem MCP
-npx agentic-flow mcp add filesystem \
-  --npm @modelcontextprotocol/server-filesystem \
-  --args "/path/to/allowed/directory"
-# GitHub MCP
-npx agentic-flow mcp add github \
-  --npm @modelcontextprotocol/server-github \
-  --env "GITHUB_TOKEN=your-token"
-# Google Drive MCP
-npx agentic-flow mcp add gdrive \
-  --npm @modelcontextprotocol/server-gdrive \
-  --env "GDRIVE_CREDENTIALS=/path/to/creds.json"
-# Brave Search MCP
-npx agentic-flow mcp add brave-search \
-  --npm @modelcontextprotocol/server-brave-search \
-  --env "BRAVE_API_KEY=your-key"
-```
-### Community Servers
-```bash
-# Database MCP (PostgreSQL, MySQL)
-npx agentic-flow mcp add database \
-  --npm mcp-database \
-  --env "DATABASE_URL=postgresql://localhost/mydb"
-# Slack MCP
-npx agentic-flow mcp add slack \
-  --npm mcp-slack \
-  --env "SLACK_TOKEN=xoxb-your-token"
-# Email MCP (IMAP/SMTP)
-npx agentic-flow mcp add email \
-  --npm mcp-email \
-  --env "EMAIL_HOST=imap.gmail.com" \
-  --env "EMAIL_USER=user@gmail.com" \
-  --env "EMAIL_PASS=app-password"
-# Notion MCP
-npx agentic-flow mcp add notion \
-  --npm @notionhq/mcp-server \
-  --env "NOTION_TOKEN=secret_xxx"
-```
----
-## Advanced Usage
-### Custom Configuration File Path
-```bash
-# Use custom config file
-export AGENTIC_FLOW_MCP_CONFIG=/path/to/custom-mcp-config.json
-npx agentic-flow mcp list
-```
-### Multiple Profiles
-```bash
-# Development profile
-export AGENTIC_FLOW_MCP_CONFIG=~/.agentic-flow/mcp-dev.json
-npx agentic-flow mcp add local-tools --local /dev/tools/server.js
-# Production profile
-export AGENTIC_FLOW_MCP_CONFIG=~/.agentic-flow/mcp-prod.json
-npx agentic-flow mcp add prod-tools --npm production-mcp
-```
-### Import/Export Configuration
-```bash
-# Export configuration
-npx agentic-flow mcp export > my-mcp-config.json
-# Import configuration
-npx agentic-flow mcp import < my-mcp-config.json
-# Share with team
-cat my-mcp-config.json | pbcopy  # macOS
-```
----
-## Troubleshooting
-### Server Not Working
-```bash
-# 1. Test server
-npx agentic-flow mcp test my-server
-# 2. Check if enabled
-npx agentic-flow mcp list
-# 3. Check logs
-npx agentic-flow --agent coder --task "test" --verbose
-# Look for: "Loading MCP server: my-server"
-# 4. Test manually
-npx my-mcp-package start
-```
-### Environment Variables Not Set
-```bash
-# Check current config
-npx agentic-flow mcp info my-server
-# Update env vars
-npx agentic-flow mcp update my-server \
-  --env "API_KEY=correct-key"
-```
-### NPM Package Not Found
-```bash
-# Test NPM package
-npx my-mcp-package --help
-# Update package name
-npx agentic-flow mcp update my-server \
-  --npm correct-package-name
-```
----
-## Security Best Practices
-1. **Don't Commit API Keys**
-   ```bash
-   # Use environment variables
-   npx agentic-flow mcp add weather \
-     --npm weather-mcp \
-     --env "API_KEY=$WEATHER_API_KEY"
-   ```
-2. **Validate Sources**
-   ```bash
-   # Check NPM package first
-   npm view weather-mcp
-   # Review package code
-   npm view weather-mcp repository
-   ```
-3. **Use Version Pinning**
-   ```bash
-   # Pin to specific version
-   npx agentic-flow mcp add weather \
-     --npm weather-mcp@1.2.3  # Not @latest
-   ```
-4. **Review Permissions**
-   ```bash
-   # Check what tools are available
-   npx agentic-flow mcp tools my-server
-   # Disable if not needed
-   npx agentic-flow mcp disable my-server
-   ```
----
-## Example Workflow
-```bash
-# 1. Install agentic-flow
-npm install -g agentic-flow
-# 2. Add weather MCP server
-npx agentic-flow mcp add weather \
-  --npm weather-mcp \
-  --env "WEATHER_API_KEY=your-key" \
-  --desc "Real-time weather data"
-# 3. Test it
-npx agentic-flow mcp test weather
-# 4. Use it
-npx agentic-flow --agent researcher \
-  --task "Get current weather and 7-day forecast for Tokyo"
-# 5. Check what it can do
-npx agentic-flow mcp tools weather
-# 6. Update if needed
-npx agentic-flow mcp update weather --version 2.0.0
-# 7. Share config with team
-npx agentic-flow mcp export > team-mcp-config.json
-```
----
-## Summary
-**Quick Reference Card:**
-| Task | Command |
-|------|---------|
-| Add NPM server | `npx agentic-flow mcp add NAME --npm PACKAGE` |
-| Add local server | `npx agentic-flow mcp add NAME --local PATH` |
-| List servers | `npx agentic-flow mcp list` |
-| Test server | `npx agentic-flow mcp test NAME` |
-| Enable/disable | `npx agentic-flow mcp enable/disable NAME` |
-| Update config | `npx agentic-flow mcp update NAME --env "KEY=val"` |
-| Remove server | `npx agentic-flow mcp remove NAME` |
-| Show tools | `npx agentic-flow mcp tools NAME` |
-**Config File:** `~/.agentic-flow/mcp-config.json`
-**All enabled MCP servers automatically available to agents!**
----
-## Implementation Status
-**🚧 COMING SOON - This feature is not yet implemented.**
-The CLI commands documented above will be available in **agentic-flow v1.2.0**.
-**Current Workaround:** Use environment variables as documented in the [main guide](./ADDING-MCP-SERVERS.md).
-**Track Progress:** https://github.com/ruvnet/agentic-flow/issues
----
-**Want this feature sooner?** Contribute! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.