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

package/agentic-flow/docs/guides/ADDING-MCP-SERVERS-CLI.md

@@ -0,0 +1,515 @@
+# 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.