From d814037edc188e5564bf8c072e396cbf05400921 Mon Sep 17 00:00:00 2001 From: Doug Pearson Date: Thu, 19 Feb 2026 12:04:56 -0500 Subject: [PATCH] Improve docs formatting: add syntax highlighting and fix Markdown style --- docs/custom-servers.md | 40 ++++++++++++++++++++++++++++----- docs/docker-gateway.md | 40 +++++++++++++++++++++++++++++++-- docs/installation.md | 23 ++++++++++++++++--- docs/troubleshooting.md | 49 ++++++++++++++++++++++++++++++++++++++++- 4 files changed, 141 insertions(+), 11 deletions(-) diff --git a/docs/custom-servers.md b/docs/custom-servers.md index f2dc60c..2e7115c 100644 --- a/docs/custom-servers.md +++ b/docs/custom-servers.md @@ -5,6 +5,7 @@ Learn how to create your own MCP servers from scratch using NetworkChuck's MCP B ## Overview MCP servers are Docker containers that expose tools to AI assistants. You can build servers for: + - API integrations (weather, stocks, databases) - System tools (file management, network utilities) - Custom business logic @@ -15,6 +16,7 @@ MCP servers are Docker containers that expose tools to AI assistants. You can bu ### Step 1: Prepare Your Requirements Before using the prompt, gather: + 1. **Service name** - What will you call your server? 2. **API documentation** - Links to any APIs you'll use 3. **Tool list** - What specific functions do you need? @@ -31,6 +33,7 @@ Before using the prompt, gather: ### Step 3: Generate Your Server The AI will create 5 files: + - `Dockerfile` - Container configuration - `requirements.txt` - Python dependencies - `[name]_server.py` - Main server code @@ -39,8 +42,9 @@ The AI will create 5 files: ## Example: Weather MCP Server -### Input to the Prompt: -``` +### Input to the Prompt + +```text I want to build a weather MCP server that: - Gets current weather for any city - Gets 5-day forecast @@ -48,7 +52,8 @@ I want to build a weather MCP server that: - Uses the OpenWeatherMap API ``` -### Generated Structure: +### Generated Structure + ```python @mcp.tool() async def get_weather(city: str = "") -> str: @@ -60,39 +65,47 @@ async def get_weather(city: str = "") -> str: ## Building Process ### 1. Create Project Directory + ```bash mkdir weather-mcp-server cd weather-mcp-server ``` ### 2. Save Generated Files + Save all 5 files from the AI output ### 3. Build Docker Image + ```bash docker build -t weather-mcp-server . ``` ### 4. Add Secrets (if needed) + ```bash docker mcp secret set OPENWEATHER_API_KEY="your-key-here" ``` ### 5. Register in Catalog + Add to `~/.docker/mcp/catalogs/custom.yaml` ### 6. Update Registry + Add to `~/.docker/mcp/registry.yaml` ### 7. Configure Client + Update Claude/Cursor configuration ### 8. Test + Restart client and test your new tools! ## Server Architecture -``` +```text Client (Claude/Cursor) ↓ Docker MCP Gateway @@ -105,18 +118,21 @@ External APIs/Services ## Best Practices ### Code Structure + - One tool per function - Clear, single-line docstrings - Comprehensive error handling - Informative return messages ### Security + - Never hardcode credentials - Use Docker secrets for API keys - Validate all inputs - Run as non-root user ### Performance + - Add timeouts to API calls - Cache responses when appropriate - Use async operations @@ -125,6 +141,7 @@ External APIs/Services ## Common Patterns ### API Integration + ```python async with httpx.AsyncClient() as client: response = await client.get(url, headers=headers) @@ -133,6 +150,7 @@ async with httpx.AsyncClient() as client: ``` ### File Operations + ```python try: with open(filename, 'r') as f: @@ -143,6 +161,7 @@ except FileNotFoundError: ``` ### Command Execution + ```python result = subprocess.run( command, @@ -156,19 +175,25 @@ return result.stdout if result.returncode == 0 else result.stderr ## Advanced Topics ### Multi-Tool Servers + Combine related tools in one server: + - Database operations (create, read, update, delete) - Project management (tasks, projects, time tracking) - DevOps tools (deploy, monitor, scale) ### Stateful Operations + While MCP is stateless, you can: + - Use external databases - Write to files - Maintain sessions via IDs ### Complex Workflows + Chain tools together: + 1. Fetch data from API 2. Process/transform data 3. Store results @@ -177,6 +202,7 @@ Chain tools together: ## Debugging ### Local Testing + ```bash # Run server directly python your_server.py @@ -186,12 +212,14 @@ echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python your_server.py ``` ### Check Logs + ```bash # View container logs docker logs $(docker ps -a | grep your-server | awk '{print $1}') ``` ### Common Issues + - **Import errors**: Check requirements.txt - **Tool not found**: Verify @mcp.tool() decorator - **Auth failures**: Check secret names match @@ -199,12 +227,14 @@ docker logs $(docker ps -a | grep your-server | awk '{print $1}') ## Examples from the Video ### Toggl Timer Integration + - Start/stop timers - View time entries - Track projects - API authentication with tokens ### Kali Linux Tools + - Network scanning (nmap) - Web testing (nikto, dirb) - Security assessments @@ -224,4 +254,4 @@ docker logs $(docker ps -a | grep your-server | awk '{print $1}') 3. Implement multiple related tools 4. Share your creation with the community! -Remember: The MCP Builder Prompt does the heavy lifting - you just need to describe what you want! \ No newline at end of file +Remember: The MCP Builder Prompt does the heavy lifting - you just need to describe what you want! diff --git a/docs/docker-gateway.md b/docs/docker-gateway.md index cdade38..4fcc85c 100644 --- a/docs/docker-gateway.md +++ b/docs/docker-gateway.md @@ -13,7 +13,7 @@ The Docker MCP Gateway is a special MCP server that acts as a proxy/orchestrator ## Architecture Overview -``` +```text Claude/Cursor/LM Studio ↓ [Single Connection] @@ -28,18 +28,23 @@ The Docker MCP Gateway is a special MCP server that acts as a proxy/orchestrator ## Key Benefits ### 1. Simplified Configuration + **Without Gateway:** + - Configure each server individually - Manage multiple connections - Update each client separately **With Gateway:** + - One configuration entry - Single connection point - Centralized management ### 2. Dynamic Container Management + Containers run only when needed: + ```bash # Before tool use $ docker ps @@ -57,6 +62,7 @@ $ docker ps ``` ### 3. Centralized Secret Management + ```bash # Set secrets once, use everywhere docker mcp secret set API_KEY="abc123" @@ -68,20 +74,26 @@ os.environ.get("API_KEY") ## Transport Modes ### Standard I/O (Local) + Default mode for local clients: + ```bash docker mcp gateway run --transport stdio ``` + - Direct process communication - No network overhead - Maximum security - Perfect for desktop apps ### Server-Sent Events (Network) + For remote access and automation: + ```bash docker mcp gateway run --transport sse --port 8811 ``` + - HTTP/HTTPS transport - Access from anywhere - Integration with n8n, Make, Zapier @@ -90,7 +102,9 @@ docker mcp gateway run --transport sse --port 8811 ## Running the Gateway ### As Part of Docker Desktop + Automatically managed when MCP Toolkit is enabled: + ```json { "mcpServers": { @@ -112,7 +126,9 @@ Automatically managed when MCP Toolkit is enabled: ``` ### Standalone Container + Run independently for production: + ```bash # Pull the gateway image docker pull docker/mcp-gateway @@ -131,6 +147,7 @@ docker run -d \ ## Catalog System ### Structure + ```yaml version: 2 name: custom @@ -150,6 +167,7 @@ registry: ``` ### Multiple Catalogs + ```bash # Load multiple catalogs docker mcp gateway run \ @@ -161,6 +179,7 @@ docker mcp gateway run \ ## Registry Management The registry tracks installed servers: + ```yaml registry: dice: @@ -172,6 +191,7 @@ registry: ``` Manage via CLI: + ```bash # List registered servers docker mcp server list @@ -186,6 +206,7 @@ docker mcp server remove my-server ## Remote Access Setup ### Local Network Access + ```bash # Start gateway with network transport docker run -d \ @@ -201,6 +222,7 @@ http://192.168.1.100:8811 ``` ### n8n Integration + As shown in the video: 1. Start gateway with SSE transport @@ -210,6 +232,7 @@ As shown in the video: 5. Build automation workflows! ### Security Considerations + - Use HTTPS in production - Implement authentication - Restrict network access @@ -218,11 +241,13 @@ As shown in the video: ## Advanced Configuration ### Custom Port + ```bash docker mcp gateway run --transport sse --port 9000 ``` ### Custom Config Path + ```bash docker mcp gateway run \ --config=/custom/path/config.yaml \ @@ -230,6 +255,7 @@ docker mcp gateway run \ ``` ### Environment Variables + ```bash docker run -e DEBUG=true \ -e LOG_LEVEL=debug \ @@ -239,7 +265,9 @@ docker run -e DEBUG=true \ ## Performance Optimization ### Container Caching + First run pulls image, subsequent runs are instant: + ```bash # Pre-pull images for faster first run docker pull dice-mcp-server @@ -247,6 +275,7 @@ docker pull weather-mcp-server ``` ### Resource Limits + ```yaml # In catalog definition registry: @@ -261,6 +290,7 @@ registry: ## Monitoring & Debugging ### View Gateway Logs + ```bash # If running as container docker logs mcp-gateway @@ -270,12 +300,14 @@ docker logs $(docker ps | grep mcp-gateway | awk '{print $1}') ``` ### List Active Connections + ```bash # See what's currently running docker ps | grep mcp ``` ### Debug Mode + ```bash docker mcp gateway run --transport stdio --debug ``` @@ -283,16 +315,19 @@ docker mcp gateway run --transport stdio --debug ## Troubleshooting ### Gateway Won't Start + - Check Docker daemon is running - Verify socket permissions - Ensure no port conflicts (for SSE mode) ### Servers Not Available + - Verify catalog syntax - Check registry entries - Ensure Docker images exist ### Connection Issues + - Check firewall rules - Verify network settings - Test with curl: `curl http://localhost:8811/health` @@ -317,6 +352,7 @@ docker mcp gateway run --transport stdio --debug ## Future Possibilities As mentioned in the video: + - Cloud-hosted gateways - Multi-user support - Tool marketplace @@ -332,4 +368,4 @@ As mentioned in the video: --- -*"The Docker MCP Gateway is like USB-C for AI tools"* - NetworkChuck \ No newline at end of file +*"The Docker MCP Gateway is like USB-C for AI tools"* - NetworkChuck diff --git a/docs/installation.md b/docs/installation.md index 05bde6e..98130aa 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -3,6 +3,7 @@ Detailed platform-specific instructions for setting up Docker MCP servers. ## Table of Contents + - [macOS Installation](#macos-installation) - [Windows Installation](#windows-installation) - [Linux Installation](#linux-installation) @@ -55,6 +56,7 @@ Add the MCP gateway configuration (see Quick Start guide for details). ## Windows Installation ### Prerequisites + - Windows 10 64-bit: Pro, Enterprise, or Education (Build 19041 or higher) - Windows 11 64-bit: Home, Pro, Enterprise, or Education @@ -107,6 +109,7 @@ notepad "$env:APPDATA\Claude\claude_desktop_config.json" ``` **Important for Windows paths:** Use double backslashes in JSON: + ```json "C:\\Users\\YourUsername\\.docker\\mcp" ``` @@ -116,6 +119,7 @@ notepad "$env:APPDATA\Claude\claude_desktop_config.json" ## Linux Installation ### Supported Distributions + - Ubuntu 20.04 LTS or later - Debian 11 or later - Fedora 36 or later @@ -123,7 +127,8 @@ notepad "$env:APPDATA\Claude\claude_desktop_config.json" ### Step 1: Install Docker -#### Ubuntu/Debian: +#### Ubuntu/Debian + ```bash # Update package index sudo apt-get update @@ -151,7 +156,8 @@ sudo usermod -aG docker $USER newgrp docker ``` -#### Fedora: +#### Fedora + ```bash # Install Docker sudo dnf -y install dnf-plugins-core @@ -181,6 +187,7 @@ sudo rpm -i docker-desktop-*.rpm ### Step 3: Install Claude Desktop Currently, Claude Desktop requires running through a compatibility layer on Linux. Alternatively, use: + - Cursor IDE with MCP support - LM Studio - Custom MCP clients @@ -228,12 +235,14 @@ docker mcp secret list ### Test MCP Connection 1. Build a test server: + ```bash cd examples/dice-roller docker build -t test-mcp . ``` 2. Check if it appears in Docker: + ```bash docker images | grep test-mcp ``` @@ -248,16 +257,19 @@ docker images | grep test-mcp ### Docker Desktop Won't Start **macOS:** + - Check System Preferences → Security & Privacy - Ensure Docker has necessary permissions - Try resetting Docker: Troubleshoot → Reset to factory defaults **Windows:** + - Ensure virtualization is enabled in BIOS - Check WSL 2 is properly installed: `wsl --status` - Run as Administrator **Linux:** + - Check Docker daemon: `sudo systemctl status docker` - Verify user is in docker group: `groups` @@ -277,6 +289,7 @@ docker images | grep test-mcp ### Permission Errors **macOS/Linux:** + ```bash # Fix Docker socket permissions sudo chmod 666 /var/run/docker.sock @@ -286,17 +299,20 @@ sudo usermod -aG docker $USER ``` **Windows:** + - Run Docker Desktop as Administrator - Check WSL 2 integration in Docker settings ### Build Failures Common causes: + - Network issues downloading packages - Dockerfile syntax errors - Missing dependencies Debug with: + ```bash # Verbose build output docker build --no-cache --progress=plain -t test . @@ -310,8 +326,9 @@ docker logs [container-id] ## Next Steps ✅ Installation complete? Now: + 1. Try the [Quick Start Guide](../quick-start/setup-guide.md) 2. Build a custom server with the [MCP Builder Prompt](../mcp-builder-prompt/) 3. Learn about [Docker MCP Gateway](docker-gateway.md) -Need help? Check the [Troubleshooting Guide](troubleshooting.md) or watch the video tutorial! \ No newline at end of file +Need help? Check the [Troubleshooting Guide](troubleshooting.md) or watch the video tutorial! diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 2ccda2a..97e6e3e 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -5,6 +5,7 @@ Common issues and solutions for Docker MCP servers. ## Quick Diagnostics Run these commands first: + ```bash # Check Docker is running docker ps @@ -27,6 +28,7 @@ docker images | grep mcp ### 🔴 Tools Not Appearing in Claude **Symptoms:** + - MCP gateway shows in Claude but no tools - Tools were working but disappeared - Some tools show but not others @@ -39,30 +41,38 @@ docker images | grep mcp - Relaunch Claude 2. **Check Docker image exists:** + ```bash docker images | grep your-server-name ``` + If missing, rebuild: + ```bash docker build -t your-server-name . ``` 3. **Verify catalog entry:** + ```bash cat ~/.docker/mcp/catalogs/custom.yaml ``` + Check for: - Correct image name - Tools list populated - No syntax errors 4. **Check registry:** + ```bash cat ~/.docker/mcp/registry.yaml ``` + Ensure your server is listed under `registry:` key 5. **Validate Claude config:** + ```bash # macOS cat ~/Library/Application\ Support/Claude/claude_desktop_config.json @@ -70,11 +80,13 @@ docker images | grep mcp # Windows type %APPDATA%\Claude\claude_desktop_config.json ``` + Look for custom catalog in args ### 🔴 Docker MCP Toolkit Not Available **Symptoms:** + - No MCP option in Docker Desktop settings - `docker mcp` command not found @@ -96,6 +108,7 @@ docker images | grep mcp ### 🔴 Build Failures **Symptoms:** + - `docker build` fails with errors - Package installation fails - Dockerfile syntax errors @@ -103,6 +116,7 @@ docker images | grep mcp **Solutions:** 1. **Check Dockerfile syntax:** + ```dockerfile # Correct FROM python:3.11-slim @@ -112,6 +126,7 @@ docker images | grep mcp ``` 2. **Network issues:** + ```bash # Build with no cache docker build --no-cache -t server-name . @@ -121,6 +136,7 @@ docker images | grep mcp ``` 3. **Requirements issues:** + ```bash # Test requirements locally pip install -r requirements.txt @@ -129,6 +145,7 @@ docker images | grep mcp ### 🔴 Authentication Errors **Symptoms:** + - API calls failing with 401/403 - "Token not configured" errors - Secret not found @@ -136,11 +153,13 @@ docker images | grep mcp **Solutions:** 1. **Check secret is set:** + ```bash docker mcp secret list ``` 2. **Set secret correctly:** + ```bash docker mcp secret set API_KEY="your-actual-key" ``` @@ -151,6 +170,7 @@ docker images | grep mcp - Names must match exactly! 4. **Test locally:** + ```bash export API_KEY="your-key" python your_server.py @@ -159,6 +179,7 @@ docker images | grep mcp ### 🔴 Container Crashes **Symptoms:** + - Tools appear but don't work - "Server error" messages - Container exits immediately @@ -166,6 +187,7 @@ docker images | grep mcp **Solutions:** 1. **Check logs:** + ```bash # Find container ID docker ps -a | grep your-server @@ -175,6 +197,7 @@ docker images | grep mcp ``` 2. **Test server directly:** + ```bash # Run interactively docker run -it your-server-name /bin/bash @@ -192,6 +215,7 @@ docker images | grep mcp ### 🔴 Permission Errors **Symptoms:** + - "Permission denied" errors - Cannot access Docker socket - Cannot write files @@ -199,11 +223,13 @@ docker images | grep mcp **Solutions:** 1. **Fix Docker socket (Linux/Mac):** + ```bash sudo chmod 666 /var/run/docker.sock ``` 2. **Add user to docker group:** + ```bash sudo usermod -aG docker $USER newgrp docker @@ -217,6 +243,7 @@ docker images | grep mcp ### 🔴 Gateway Connection Issues **Symptoms:** + - SSE transport not working - Cannot connect remotely - n8n integration failing @@ -224,6 +251,7 @@ docker images | grep mcp **Solutions:** 1. **Check port is open:** + ```bash # Is gateway running? docker ps | grep mcp-gateway @@ -233,6 +261,7 @@ docker images | grep mcp ``` 2. **Firewall issues:** + ```bash # macOS sudo pfctl -d # Disable firewall temporarily @@ -242,6 +271,7 @@ docker images | grep mcp ``` 3. **Correct startup command:** + ```bash docker run -p 8811:8811 docker/mcp-gateway --transport sse ``` @@ -251,17 +281,21 @@ docker images | grep mcp ### macOS **Apple Silicon Issues:** + - Some images need platform flag: + ```bash docker build --platform linux/amd64 -t server . ``` **Permissions:** + - Grant Docker full disk access in System Preferences ### Windows **WSL 2 Issues:** + ```powershell # Check WSL version wsl --status @@ -274,12 +308,14 @@ wsl --set-default-version 2 ``` **Path Issues:** + - Use double backslashes in JSON configs - Or use forward slashes ### Linux **Docker Daemon:** + ```bash # Check status sudo systemctl status docker @@ -294,6 +330,7 @@ sudo systemctl enable docker ## Debug Commands ### Verbose Logging + ```bash # Build with verbose output docker build --progress=plain -t server . @@ -303,6 +340,7 @@ DEBUG=true python server.py ``` ### Test MCP Protocol + ```bash # List tools echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python server.py @@ -312,6 +350,7 @@ echo '{"jsonrpc":"2.0","method":"tools/call","params":{"name":"tool_name","argum ``` ### Clean Slate + ```bash # Remove all MCP images docker images | grep mcp | awk '{print $3}' | xargs docker rmi @@ -326,28 +365,34 @@ cd your-server && docker build -t your-server . ## Error Messages Explained **"Gateway panic"** + - Usually a syntax error in server code - Check for multi-line docstrings (use single-line only) **"No such image"** + - Docker image not built - Wrong image name in catalog **"Transport error"** + - MCP protocol issue - Check JSON formatting **"Tool not found"** + - Tool not decorated with @mcp.tool() - Tool not listed in catalog **"Invalid parameters"** + - Type hints too complex - Use simple string parameters ## Getting Help ### Logs to Collect + 1. Docker Desktop version: `docker --version` 2. Claude logs: Help → Show Logs 3. Container logs: `docker logs [container]` @@ -355,6 +400,7 @@ cd your-server && docker build -t your-server . 5. Catalog and registry files ### Where to Get Help + - GitHub Issues on this repo - Docker Community Forums - NetworkChuck Discord @@ -363,6 +409,7 @@ cd your-server && docker build -t your-server . ## Prevention Tips 1. **Always test locally first:** + ```bash python your_server.py ``` @@ -384,4 +431,4 @@ cd your-server && docker build -t your-server . --- -*Remember: Most issues are typos or missing restarts. When in doubt, restart everything!* \ No newline at end of file +*Remember: Most issues are typos or missing restarts. When in doubt, restart everything!*