vm-cloudflare/MCP_GUIDE.md

# 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+