Initial commit: Cloudflare infrastructure with WAF Intelligence
- Complete Cloudflare Terraform configuration (DNS, WAF, tunnels, access) - WAF Intelligence MCP server with threat analysis and ML classification - GitOps automation with PR workflows and drift detection - Observatory monitoring stack with Prometheus/Grafana - IDE operator rules for governed development - Security playbooks and compliance frameworks - Autonomous remediation and state reconciliation
This commit is contained in:
Vault Sovereign
487
MCP_GUIDE.md
Normal file
487
MCP_GUIDE.md
Normal file
@@ -0,0 +1,487 @@
|
||||
# Complete MCP Guide for OpenCode
|
||||
|
||||
## Available MCPs and Configuration
|
||||
|
||||
This guide shows all the Model Context Protocol (MCP) servers configured in your OpenCode setup, with environment variables and usage examples.
|
||||
|
||||
---
|
||||
|
||||
## Essential MCPs (Always Enabled)
|
||||
|
||||
### 1. **filesystem** - File System Operations
|
||||
**Status:** ✅ Enabled by default
|
||||
**Environment:** `HOME` directory
|
||||
**Purpose:** Read/write files, explore directory structure, manage file operations
|
||||
|
||||
**Usage Examples:**
|
||||
```
|
||||
/use filesystem
|
||||
Please explore the terraform/ directory structure
|
||||
```
|
||||
|
||||
**Best For:**
|
||||
- Examining project files
|
||||
- Understanding directory organization
|
||||
- Reading configuration files
|
||||
|
||||
---
|
||||
|
||||
### 2. **git** - Version Control
|
||||
**Status:** ✅ Enabled by default
|
||||
**Purpose:** Git operations, commit history, diff review
|
||||
|
||||
**Usage Examples:**
|
||||
```
|
||||
/use git
|
||||
Show me the recent commits in the terraform/ directory
|
||||
```
|
||||
|
||||
```
|
||||
/use git
|
||||
What files changed in the last 5 commits?
|
||||
```
|
||||
|
||||
**Best For:**
|
||||
- Reviewing changes before committing
|
||||
- Understanding project history
|
||||
- Checking git status
|
||||
|
||||
---
|
||||
|
||||
### 3. **github** - GitHub Integration
|
||||
**Status:** ✅ Enabled by default
|
||||
**Environment Required:** `GITHUB_TOKEN`
|
||||
**Purpose:** Query GitHub APIs, search repos, manage PRs/issues
|
||||
|
||||
**Usage Examples:**
|
||||
```
|
||||
/use github
|
||||
Search for Cloudflare Terraform modules in GitHub
|
||||
```
|
||||
|
||||
```
|
||||
/use github
|
||||
Find how other projects implement WAF rules
|
||||
```
|
||||
|
||||
**Setup:**
|
||||
```bash
|
||||
export GITHUB_TOKEN="ghp_your_token_here"
|
||||
```
|
||||
|
||||
**Best For:**
|
||||
- Finding example implementations
|
||||
- Searching GitHub repositories
|
||||
- Managing pull requests
|
||||
|
||||
---
|
||||
|
||||
### 4. **gh_grep** - GitHub Code Search
|
||||
**Status:** ✅ Enabled by default (Remote)
|
||||
**URL:** https://mcp.grep.app
|
||||
**Purpose:** Search code examples across GitHub
|
||||
|
||||
**Usage Examples:**
|
||||
```
|
||||
/use gh_grep
|
||||
Find examples of Cloudflare Terraform patterns
|
||||
```
|
||||
|
||||
**Best For:**
|
||||
- Finding best practices on GitHub
|
||||
- Learning from real-world implementations
|
||||
- Code examples and snippets
|
||||
|
||||
---
|
||||
|
||||
## Optional MCPs (Disabled by Default - Enable as Needed)
|
||||
|
||||
### 5. **postgres** - PostgreSQL Database
|
||||
**Status:** ⚠️ Disabled (enable for data-engineer agent)
|
||||
**Environment Required:** `DATABASE_URL`
|
||||
**Purpose:** Query and manage PostgreSQL databases
|
||||
|
||||
**Setup:**
|
||||
```bash
|
||||
export DATABASE_URL="postgresql://user:password@localhost:5432/dbname"
|
||||
```
|
||||
|
||||
**Usage Example (when enabled):**
|
||||
```
|
||||
/agent data-engineer
|
||||
Query the users table to get the count of active users
|
||||
```
|
||||
|
||||
**Enable In Config:**
|
||||
```jsonc
|
||||
"postgres": {
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
**Best For:**
|
||||
- Database queries and analysis
|
||||
- Schema exploration
|
||||
- Data engineering tasks
|
||||
|
||||
---
|
||||
|
||||
### 6. **sqlite** - SQLite Database
|
||||
**Status:** ⚠️ Disabled (enable for data-engineer agent)
|
||||
**Purpose:** Work with local SQLite databases
|
||||
|
||||
**Usage Example (when enabled):**
|
||||
```
|
||||
/agent data-engineer
|
||||
Show me the schema of the analytics.db file
|
||||
```
|
||||
|
||||
**Enable In Config:**
|
||||
```jsonc
|
||||
"sqlite": {
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
**Best For:**
|
||||
- Local data analysis
|
||||
- Testing database queries
|
||||
- Small-scale data operations
|
||||
|
||||
---
|
||||
|
||||
### 7. **docker** - Docker Integration
|
||||
**Status:** ⚠️ Disabled (enable for container work)
|
||||
**Purpose:** Docker container management and operations
|
||||
|
||||
**Enable In Config:**
|
||||
```jsonc
|
||||
"docker": {
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
**Usage Example (when enabled):**
|
||||
```
|
||||
Build and run a Docker container for the GitOps pipeline
|
||||
```
|
||||
|
||||
**Best For:**
|
||||
- Container management
|
||||
- Docker compose operations
|
||||
- Container deployment
|
||||
|
||||
---
|
||||
|
||||
### 8. **aws** - AWS Integration
|
||||
**Status:** ⚠️ Disabled (enable for AWS operations)
|
||||
**Environment Required:**
|
||||
- `AWS_ACCESS_KEY_ID`
|
||||
- `AWS_SECRET_ACCESS_KEY`
|
||||
- `AWS_REGION`
|
||||
|
||||
**Setup:**
|
||||
```bash
|
||||
export AWS_ACCESS_KEY_ID="AKIA..."
|
||||
export AWS_SECRET_ACCESS_KEY="..."
|
||||
export AWS_REGION="us-east-1"
|
||||
```
|
||||
|
||||
**Usage Example (when enabled):**
|
||||
```
|
||||
Deploy this Lambda function to AWS
|
||||
```
|
||||
|
||||
**Enable In Config:**
|
||||
```jsonc
|
||||
"aws": {
|
||||
"enabled": true,
|
||||
"environment": {
|
||||
"AWS_ACCESS_KEY_ID": "{env:AWS_ACCESS_KEY_ID}",
|
||||
"AWS_SECRET_ACCESS_KEY": "{env:AWS_SECRET_ACCESS_KEY}",
|
||||
"AWS_REGION": "{env:AWS_REGION}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Best For:**
|
||||
- AWS infrastructure management
|
||||
- Lambda deployments
|
||||
- S3 operations
|
||||
|
||||
---
|
||||
|
||||
### 9. **slack** - Slack Integration
|
||||
**Status:** ⚠️ Disabled (enable for notifications)
|
||||
**Environment Required:** `SLACK_BOT_TOKEN`
|
||||
**Purpose:** Send messages, manage channels
|
||||
|
||||
**Setup:**
|
||||
```bash
|
||||
export SLACK_BOT_TOKEN="xoxb-..."
|
||||
```
|
||||
|
||||
**Usage Example (when enabled):**
|
||||
```
|
||||
Send a notification to #devops about the deployment
|
||||
```
|
||||
|
||||
**Enable In Config:**
|
||||
```jsonc
|
||||
"slack": {
|
||||
"enabled": true,
|
||||
"environment": {
|
||||
"SLACK_BOT_TOKEN": "{env:SLACK_BOT_TOKEN}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Best For:**
|
||||
- Sending notifications
|
||||
- Team communication
|
||||
- Alert automation
|
||||
|
||||
---
|
||||
|
||||
### 10. **linear** - Linear Issue Tracking
|
||||
**Status:** ⚠️ Disabled (enable for issue management)
|
||||
**Environment Required:** `LINEAR_API_KEY`
|
||||
**Purpose:** Create/manage issues in Linear
|
||||
|
||||
**Setup:**
|
||||
```bash
|
||||
export LINEAR_API_KEY="lin_..."
|
||||
```
|
||||
|
||||
**Usage Example (when enabled):**
|
||||
```
|
||||
Create a Linear ticket for the new WAF rule implementation
|
||||
```
|
||||
|
||||
**Enable In Config:**
|
||||
```jsonc
|
||||
"linear": {
|
||||
"enabled": true,
|
||||
"environment": {
|
||||
"LINEAR_API_KEY": "{env:LINEAR_API_KEY}"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Best For:**
|
||||
- Issue tracking
|
||||
- Task creation
|
||||
- Sprint management
|
||||
|
||||
---
|
||||
|
||||
### 11. **context7** - Documentation Search
|
||||
**Status:** ⚠️ Disabled (enable for documentation lookup)
|
||||
**Environment Required (Optional):** `CONTEXT7_API_KEY`
|
||||
**URL:** https://mcp.context7.com/mcp
|
||||
**Purpose:** Search through documentation and knowledge bases
|
||||
|
||||
**Setup (Optional - works without key but rate-limited):**
|
||||
```bash
|
||||
export CONTEXT7_API_KEY="your-key"
|
||||
```
|
||||
|
||||
**Usage Example (when enabled):**
|
||||
```
|
||||
/use context7
|
||||
Search for GDPR Article 33 requirements
|
||||
```
|
||||
|
||||
**Enable In Config:**
|
||||
```jsonc
|
||||
"context7": {
|
||||
"type": "remote",
|
||||
"url": "https://mcp.context7.com/mcp",
|
||||
"headers": {
|
||||
"CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
|
||||
},
|
||||
"enabled": true
|
||||
}
|
||||
```
|
||||
|
||||
**Best For:**
|
||||
- Compliance research
|
||||
- Documentation lookup
|
||||
- Learning about standards (GDPR, PCI-DSS, etc.)
|
||||
|
||||
---
|
||||
|
||||
### 12. **googlemaps** - Google Maps Integration
|
||||
**Status:** ⚠️ Disabled
|
||||
**Environment Required:** `GOOGLE_MAPS_API_KEY`
|
||||
**Purpose:** Map queries and geocoding
|
||||
|
||||
**Setup:**
|
||||
```bash
|
||||
export GOOGLE_MAPS_API_KEY="your-key"
|
||||
```
|
||||
|
||||
**Best For:**
|
||||
- Location-based queries
|
||||
- Geocoding operations
|
||||
|
||||
---
|
||||
|
||||
### 13. **memory** - Knowledge Base
|
||||
**Status:** ⚠️ Disabled
|
||||
**Purpose:** Store and retrieve project knowledge/context
|
||||
|
||||
**Best For:**
|
||||
- Recording important patterns
|
||||
- Storing decision history
|
||||
|
||||
---
|
||||
|
||||
## Quick Start for Your Project
|
||||
|
||||
### 1. Set Up Essential Environment Variables
|
||||
```bash
|
||||
# GitHub - Required for github and gh_grep MCPs
|
||||
export GITHUB_TOKEN="ghp_your_github_token"
|
||||
|
||||
# Optional but recommended
|
||||
export CONTEXT7_API_KEY="your_context7_key"
|
||||
|
||||
# If using data-engineer agent
|
||||
export DATABASE_URL="postgresql://..."
|
||||
|
||||
# If using AWS features
|
||||
export AWS_ACCESS_KEY_ID="AKIA..."
|
||||
export AWS_SECRET_ACCESS_KEY="..."
|
||||
export AWS_REGION="us-east-1"
|
||||
```
|
||||
|
||||
### 2. Initialize OpenCode
|
||||
```bash
|
||||
cd /Users/sovereign/Desktop/CLOUDFLARE
|
||||
opencode
|
||||
/init
|
||||
```
|
||||
|
||||
### 3. Check MCP Status
|
||||
```bash
|
||||
/mcp list
|
||||
```
|
||||
|
||||
### 4. Start Using MCPs
|
||||
```bash
|
||||
# Use built-in agent
|
||||
/agent cloudflare-ops
|
||||
I need to add DNS records. Can you search for Cloudflare Terraform examples?
|
||||
|
||||
# Or use MCPs directly in your prompts
|
||||
/use git
|
||||
/use gh_grep
|
||||
Show me recent commits and search for similar patterns
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Per-Agent MCP Configuration
|
||||
|
||||
### cloudflare-ops Agent
|
||||
Enabled MCPs:
|
||||
- filesystem
|
||||
- git
|
||||
- github
|
||||
- gh_grep
|
||||
|
||||
```bash
|
||||
/agent cloudflare-ops
|
||||
I need to implement HTTPS enforcement. Can you find similar patterns first?
|
||||
```
|
||||
|
||||
### security-audit Agent
|
||||
Enabled MCPs:
|
||||
- filesystem
|
||||
- git
|
||||
- github
|
||||
- gh_grep
|
||||
|
||||
```bash
|
||||
/agent security-audit
|
||||
Review the WAF rules and check against PCI-DSS requirements
|
||||
```
|
||||
|
||||
### data-engineer Agent
|
||||
Enabled MCPs:
|
||||
- filesystem
|
||||
- git
|
||||
- postgres
|
||||
- sqlite
|
||||
|
||||
```bash
|
||||
/agent data-engineer
|
||||
Query the database and generate a report of active users
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting MCPs
|
||||
|
||||
### MCP Not Loading?
|
||||
```bash
|
||||
# Check which MCPs are enabled
|
||||
/mcp list
|
||||
|
||||
# Check specific MCP
|
||||
/mcp status filesystem
|
||||
|
||||
# Restart OpenCode
|
||||
opencode
|
||||
```
|
||||
|
||||
### Environment Variables Not Working?
|
||||
```bash
|
||||
# Verify environment variable is set
|
||||
echo $GITHUB_TOKEN
|
||||
|
||||
# Make sure to set it before running OpenCode
|
||||
export GITHUB_TOKEN="your_token"
|
||||
opencode
|
||||
```
|
||||
|
||||
### Multiple Accounts Configuration 🔐
|
||||
|
||||
For managing multiple GitHub, GitLab, or Cloudflare accounts, see: [MULTI_ACCOUNT_AUTH.md](MULTI_ACCOUNT_AUTH.md)
|
||||
|
||||
### Context Size Too Large?
|
||||
If OpenCode runs out of context:
|
||||
1. Disable heavy MCPs like `github` in global config
|
||||
2. Enable them only per-agent when needed
|
||||
3. Use `tools` section to disable specific MCPs
|
||||
|
||||
```jsonc
|
||||
"tools": {
|
||||
"github": false, // Disable globally
|
||||
}
|
||||
```
|
||||
|
||||
Then enable per-agent:
|
||||
```jsonc
|
||||
"agents": {
|
||||
"cloudflare-ops": {
|
||||
"tools": {
|
||||
"github": true // Enable only for this agent
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## MCP References
|
||||
|
||||
- [OpenCode MCP Documentation](https://opencode.ai/docs/mcp-servers/)
|
||||
- [Model Context Protocol Spec](https://modelcontextprotocol.io/)
|
||||
- [Official MCP Servers](https://modelcontextprotocol.io/clients)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** December 8, 2025
|
||||
**OpenCode Version:** 1.0+
|
||||
Reference in New Issue
Block a user