Initial commit

skills/claude-code/references/mcp-integration.md

@@ -0,0 +1,386 @@
+# MCP Integration
+
+Model Context Protocol (MCP) integration for connecting Claude Code to external tools and services.
+
+## What is MCP?
+
+Model Context Protocol enables Claude Code to:
+- Connect to external tools and services
+- Access resources (files, databases, APIs)
+- Use custom tools
+- Provide prompts and completions
+
+## Configuration
+
+MCP servers are configured in `.claude/mcp.json`:
+
+### Basic Configuration
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "command-to-run",
+      "args": ["arg1", "arg2"],
+      "env": {
+        "VAR_NAME": "value"
+      }
+    }
+  }
+}
+```
+
+### Example Configuration
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
+      "env": {}
+    },
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    },
+    "postgres": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-postgres"],
+      "env": {
+        "DATABASE_URL": "postgresql://user:pass@localhost:5432/db"
+      }
+    }
+  }
+}
+```
+
+## Common MCP Servers
+
+### Filesystem Access
+```json
+{
+  "filesystem": {
+    "command": "npx",
+    "args": [
+      "-y",
+      "@modelcontextprotocol/server-filesystem",
+      "/path/to/allowed/files"
+    ]
+  }
+}
+```
+
+**Capabilities:**
+- Read/write files
+- List directories
+- File search
+- Path restrictions for security
+
+### GitHub Integration
+```json
+{
+  "github": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-github"],
+    "env": {
+      "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+    }
+  }
+}
+```
+
+**Capabilities:**
+- Repository access
+- Issues and PRs
+- Code search
+- Workflow management
+
+### PostgreSQL Database
+```json
+{
+  "postgres": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-postgres"],
+    "env": {
+      "DATABASE_URL": "${DATABASE_URL}"
+    }
+  }
+}
+```
+
+**Capabilities:**
+- Query execution
+- Schema inspection
+- Transaction management
+- Connection pooling
+
+### Brave Search
+```json
+{
+  "brave-search": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+    "env": {
+      "BRAVE_API_KEY": "${BRAVE_API_KEY}"
+    }
+  }
+}
+```
+
+**Capabilities:**
+- Web search
+- News search
+- Local search
+- Result filtering
+
+### Puppeteer (Browser Automation)
+```json
+{
+  "puppeteer": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
+  }
+}
+```
+
+**Capabilities:**
+- Browser automation
+- Screenshots
+- PDF generation
+- Web scraping
+
+## Remote MCP Servers
+
+Connect to MCP servers over HTTP/SSE:
+
+### Basic Remote Server
+```json
+{
+  "mcpServers": {
+    "remote-service": {
+      "url": "https://api.example.com/mcp"
+    }
+  }
+}
+```
+
+### With Authentication
+```json
+{
+  "mcpServers": {
+    "remote-service": {
+      "url": "https://api.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer ${API_TOKEN}",
+        "X-Custom-Header": "value"
+      }
+    }
+  }
+}
+```
+
+### With Proxy
+```json
+{
+  "mcpServers": {
+    "remote-service": {
+      "url": "https://api.example.com/mcp",
+      "proxy": "http://proxy.company.com:8080"
+    }
+  }
+}
+```
+
+## Environment Variables
+
+Use environment variables for sensitive data:
+
+### .env File
+```bash
+# .claude/.env
+GITHUB_TOKEN=ghp_xxxxx
+DATABASE_URL=postgresql://user:pass@localhost/db
+BRAVE_API_KEY=BSAxxxxx
+API_TOKEN=token_xxxxx
+```
+
+### Reference in mcp.json
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## Testing MCP Servers
+
+### Inspector Tool
+```bash
+npx @modelcontextprotocol/inspector
+```
+
+Opens web UI for testing MCP servers:
+- List available tools
+- Test tool invocations
+- View resources
+- Debug connections
+
+### Manual Testing
+```bash
+# Test server command
+npx -y @modelcontextprotocol/server-filesystem /tmp
+
+# Check server output
+echo '{"jsonrpc":"2.0","method":"initialize","params":{}}' | \
+  npx -y @modelcontextprotocol/server-filesystem /tmp
+```
+
+## Creating Custom MCP Servers
+
+### Python Server
+```python
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+
+server = Server("my-server")
+
+@server.tool()
+async def my_tool(arg: str) -> str:
+    """Tool description"""
+    return f"Result: {arg}"
+
+if __name__ == "__main__":
+    stdio_server(server)
+```
+
+### Configuration
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "python",
+      "args": ["path/to/server.py"]
+    }
+  }
+}
+```
+
+### Node.js Server
+```javascript
+import { Server } from "@modelcontextprotocol/server-node";
+
+const server = new Server("my-server");
+
+server.tool({
+  name: "my-tool",
+  description: "Tool description",
+  parameters: { arg: "string" }
+}, async ({ arg }) => {
+  return `Result: ${arg}`;
+});
+
+server.listen();
+```
+
+## Security Considerations
+
+### Filesystem Access
+- Restrict to specific directories
+- Use read-only access when possible
+- Validate file paths
+- Monitor access logs
+
+### API Credentials
+- Use environment variables
+- Never commit credentials
+- Rotate keys regularly
+- Implement least-privilege access
+
+### Network Access
+- Whitelist allowed domains
+- Use HTTPS only
+- Implement timeouts
+- Rate limit requests
+
+### Remote Servers
+- Validate server certificates
+- Use authentication
+- Implement request signing
+- Monitor for anomalies
+
+## Troubleshooting
+
+### Server Not Starting
+```bash
+# Check server command
+npx -y @modelcontextprotocol/server-filesystem /tmp
+
+# Verify environment variables
+echo $GITHUB_TOKEN
+
+# Check logs
+cat ~/.claude/logs/mcp-*.log
+```
+
+### Connection Errors
+```bash
+# Test network connectivity
+curl https://api.example.com/mcp
+
+# Verify proxy settings
+echo $HTTP_PROXY
+
+# Check firewall rules
+```
+
+### Permission Errors
+```bash
+# Verify file permissions
+ls -la /path/to/allowed/files
+
+# Check user permissions
+whoami
+groups
+```
+
+### Tool Not Found
+- Verify server is running
+- Check server configuration
+- Inspect server capabilities
+- Review tool registration
+
+## Best Practices
+
+### Configuration Management
+- Use environment variables for secrets
+- Document server purposes
+- Version control mcp.json (without secrets)
+- Test configurations thoroughly
+
+### Performance
+- Use local servers when possible
+- Implement caching
+- Set appropriate timeouts
+- Monitor resource usage
+
+### Maintenance
+- Update servers regularly
+- Monitor server health
+- Review access logs
+- Clean up unused servers
+
+## See Also
+
+- MCP specification: https://modelcontextprotocol.io
+- Creating MCP servers: `references/api-reference.md`
+- Security best practices: `references/best-practices.md`
+- Troubleshooting: `references/troubleshooting.md`