aidevops 2.52.1 → 2.53.2

package/.agent/aidevops/add-new-mcp-to-aidevops.md

@@ -1,456 +0,0 @@
----
-description: Guide for adding new MCP integrations
-mode: subagent
-tools:
-  read: true
-  write: true
-  edit: true
-  bash: true
-  glob: true
-  grep: true
-  webfetch: true
----
-
-# Adding New MCP Integrations to AI DevOps
-
-<!-- AI-CONTEXT-START -->
-
-## Quick Reference
-
-- **Purpose**: Standardized process for adding new MCP server integrations
-- **Output Files**: Documentation, config templates, setup script updates
-- **Coverage**: All supported AI assistants (see list below)
-
-**Supported AI Assistants** (configure MCP for each):
-
-- OpenCode, Cursor, Claude Code/Desktop, Gemini CLI
-- Windsurf, Continue.dev, Cody, Zed
-- GitHub Copilot, Kilo Code, Kiro, AntiGravity
-- Droid (Factory.AI), Warp AI, Aider, Qwen
-
-**Checklist**:
-
-1. Research MCP (official docs, npm/pip package, GitHub)
-2. Create `.agent/tools/{category}/{mcp-name}.md` documentation
-3. Create `configs/{mcp-name}-config.json.txt` template
-4. Create `configs/mcp-templates/{mcp-name}.json` snippets
-5. Update `.agent/scripts/generate-opencode-agents.sh` (add to selected agents)
-6. Update `.agent/scripts/ai-cli-config.sh` (add configure function)
-7. Update `setup.sh` (add setup function if prerequisites needed)
-8. Run quality checks and linters
-9. Test with verification prompt
-
-**MCP Tool Enablement Strategy**:
-
-- **Global Config**: Disabled (`"enabled": false` in opencode.json)
-- **Subagent Only**: Enable `mcp-name_*: true` in the subagent's `tools:` section
-- **Never in Main Agents**: Main agents (sales.md, marketing.md, etc.) reference subagents but never enable MCPs directly
-- **Rationale**: Context efficiency - MCP only loads when subagent is invoked
-
-**Correct Pattern**:
-
-```yaml
-# In services/crm/fluentcrm.md (SUBAGENT) - CORRECT
-tools:
-  fluentcrm_*: true  # MCP enabled here
-
-# In sales.md (MAIN AGENT) - references subagent, no MCP
-tools:
-  read: true
-  # NO fluentcrm_* here - main agents don't enable MCPs
-```
-
-**Related Agents to Call**:
-
-- `@Build-Agent` - Design guidance for agent/subagent structure
-- `@agent-review` - Review new documentation quality
-- `@best-practices` - Code quality standards
-- `@secretlint` - Check for credential leaks before commit
-
-<!-- AI-CONTEXT-END -->
-
-## Overview
-
-This guide ensures consistent, comprehensive MCP integration across the aidevops
-framework. Follow this process for any new MCP server to maintain quality and
-coverage across all supported AI assistants.
-
-## Pre-Implementation: Call Related Agents
-
-Before starting, consider calling these agents:
-
-```text
-@Build-Agent - Should this MCP have its own subagent? Which agents need it?
-@architecture - Does this fit the current framework structure?
-```
-
-## Step 1: Research the MCP
-
-Before implementation, gather all necessary information.
-
-### Required Information
-
-| Item | Description | Example |
-|------|-------------|---------|
-| **Official docs URL** | Primary documentation source | `https://docs.example.com/mcp/overview` |
-| **Install command** | npm/pip/binary installation | `npm install -g @example/mcp@latest` |
-| **Auth method** | How users authenticate | CLI login, API key, OAuth |
-| **Credentials location** | Where auth is stored | `~/.example/session.json` |
-| **MCP tool names** | Tools exposed by the MCP | `codebase-retrieval`, `search-docs` |
-| **Prerequisites** | Required dependencies | Node.js 22+, Python 3.8+ |
-| **Supported AI tools** | Which tools have official docs | OpenCode, Cursor, Claude Code, etc. |
-
-### Research Commands
-
-```bash
-# Check npm package details
-npm view @example/mcp --json | head -50
-
-# Check if already installed
-command -v example-cli
-
-# Check package documentation
-npm docs @example/mcp
-```
-
-### Fetch Official Documentation
-
-Use WebFetch to gather official setup guides for each AI tool the MCP supports.
-
-## Step 1.5: Pre-Flight Version Check (CRITICAL)
-
-Before configuring any MCP, verify you have the latest version:
-
-```bash
-# Check installed vs latest
-npm view {package} version  # Latest available
-{tool} --version            # Currently installed
-
-# If outdated, update FIRST
-npm update -g {package}
-```
-
-**Why this matters**: MCP integration methods change between versions.
-For example:
-- osgrep v0.4.x used `osgrep serve` (HTTP server)
-- osgrep v0.5.x uses `osgrep mcp` (native MCP) + `osgrep install-opencode`
-
-Using outdated commands will result in "Connection closed" errors.
-
-## Step 2: Determine Agent Enablement
-
-**Critical Decision**: Which agents should have this MCP enabled?
-
-### Ask the User
-
-Before proceeding, ask:
-
-> "Which main agents and subagents should have this MCP enabled?
->
-> **Main Agents Available**:
-> Plan+, Build+, Accounts, AI-DevOps, Content, Health, Legal, Marketing,
-> Research, Sales, SEO, WordPress
->
-> **Recommendation**: Enable globally disabled, then enable per-agent only
-> where needed for context efficiency.
->
-> **Common patterns**:
-> - Codebase/context tools → Plan+, Build+, AI-DevOps, WordPress, Research
-> - Documentation tools → All development agents
-> - Domain-specific → Only relevant domain agents
->
-> Which agents should have `{mcp-name}_*: true`?"
-
-### Document the Decision
-
-Record which agents and why:
-
-```markdown
-## Agent Enablement
-
-| Agent | Enabled | Rationale |
-|-------|---------|-----------|
-| Plan+ | Yes | Needs codebase context for planning |
-| Build+ | Yes | Primary development agent |
-| AI-DevOps | Yes | Infrastructure development |
-| WordPress | No | Not relevant to WordPress tasks |
-| ... | ... | ... |
-```
-
-## Step 3: Create Documentation File
-
-Create `.agent/tools/{category}/{mcp-name}.md`:
-
-### File Location Categories
-
-| Category | Use For |
-|----------|---------|
-| `context/` | Codebase understanding, documentation lookup, context building |
-| `code-review/` | Linting, security scanning, quality analysis |
-| `deployment/` | CI/CD, hosting, infrastructure |
-| `browser/` | Web automation, scraping, testing |
-| `git/` | Version control, repository management |
-| `credentials/` | Secret management, API keys |
-| `ai-assistants/` | AI tool configuration, integration |
-
-### Documentation Template
-
-Use `.agent/tools/context/augment-context-engine.md` as a reference template.
-
-**Required Sections**:
-
-1. **AI-CONTEXT-START block** with Quick Reference:
-   - Purpose, Install command, Auth command
-   - MCP Tool names, Docs URL
-   - OpenCode config JSON snippet
-   - Verification prompt
-   - Supported AI Assistants list
-   - Enabled for Agents list
-
-2. **What It Does** - Explain MCP benefits
-
-3. **Prerequisites** - Dependencies and requirements
-
-4. **Installation** - Step-by-step install and auth
-
-5. **AI Assistant Configurations** - One section per assistant:
-   - OpenCode, Claude Code, Cursor, Windsurf
-   - Continue.dev, Cody, Zed, GitHub Copilot
-   - Kilo Code, Kiro, AntiGravity, Gemini CLI
-   - Droid (Factory.AI), Warp AI, Aider, Qwen
-
-6. **Verification** - Test prompt and expected results
-
-7. **Non-Interactive Setup (CI/CD)** - Environment variables
-
-8. **Troubleshooting** - Common issues and solutions
-
-9. **Updates** - Link to official docs for latest configs
-
-## Step 4: Create Config Templates
-
-### configs/{mcp-name}-config.json.txt
-
-Comprehensive JSON template with all AI assistant configurations.
-
-### configs/mcp-templates/{mcp-name}.json
-
-Quick-reference snippets organized by tool.
-
-## Step 5: Update generate-opencode-agents.sh
-
-Edit `.agent/scripts/generate-opencode-agents.sh`:
-
-### Add MCP to Selected Agents Only
-
-Based on the agent enablement decision from Step 2:
-
-```python
-"Plan+": {
-    "tools": {
-        # ... existing tools ...
-        "{mcp-name}_*": True  # Only if enabled for this agent
-    }
-},
-"Build+": {
-    "tools": {
-        # ... existing tools ...
-        "{mcp-name}_*": True  # Only if enabled for this agent
-    }
-},
-# Add to other enabled agents...
-```
-
-**Important**: Do NOT add to agents where not needed - this keeps context lean.
-
-## Step 6: Update ai-cli-config.sh
-
-Edit `.agent/scripts/ai-cli-config.sh`:
-
-### Add Configure Function
-
-The function should configure all detected AI assistants:
-
-```bash
-configure_{mcp_name}_mcp() {
-    log_info "Configuring {MCP Name} for AI assistants..."
-
-    # Check prerequisites
-    if ! command -v {cli} >/dev/null 2>&1; then
-        log_warning "{CLI} not found - skipping"
-        log_info "Install with: {install command}"
-        return 0
-    fi
-
-    # Configure OpenCode
-    # Configure Cursor
-    # Configure Gemini CLI
-    # Configure Claude Code (if installed)
-    # Configure Windsurf (if installed)
-    # Configure Continue.dev (if installed)
-    # Configure Droid (if installed)
-    # ... etc for all supported assistants
-
-    log_success "{MCP Name} configured for detected AI assistants"
-}
-```
-
-### AI Assistant Config Locations
-
-| Assistant | Config Location | Method |
-|-----------|-----------------|--------|
-| OpenCode | `~/.config/opencode/opencode.json` | JSON merge |
-| Cursor | `~/.cursor/mcp.json` | JSON merge |
-| Claude Code | Via `claude mcp add-json` | CLI |
-| Windsurf | `~/.codeium/windsurf/` | JSON merge |
-| Continue.dev | `~/.continue/` | JSON merge |
-| Cody | `~/.cody/` | JSON merge |
-| Gemini CLI | `~/.gemini/settings.json` | JSON merge |
-| Droid | Via `droid mcp add` | CLI |
-| Zed | Custom server UI | Document only |
-| GitHub Copilot | `.vscode/mcp.json` | Per-project |
-| Kilo/Kiro | Global MCP config | JSON merge |
-| AntiGravity | `~/.gemini/antigravity/` | JSON merge |
-
-## Step 7: Update setup.sh (If Prerequisites Needed)
-
-Add setup function if the MCP has prerequisites to validate.
-
-## Step 8: Run Quality Checks
-
-**Before committing, run all quality checks:**
-
-```bash
-# ShellCheck for any modified shell scripts
-shellcheck .agent/scripts/ai-cli-config.sh
-shellcheck setup.sh
-
-# Markdown linting
-npx markdownlint-cli .agent/tools/{category}/{mcp-name}.md
-
-# Comprehensive quality check
-.agent/scripts/linters-local.sh
-
-# Check for credential leaks
-.agent/scripts/secretlint-helper.sh check
-```
-
-**Call the secretlint subagent:**
-
-```text
-@secretlint Check all new and modified files for credential leaks
-```
-
-## Step 9: Test the Integration
-
-### Run Scripts
-
-```bash
-# Test OpenCode agent generation
-bash .agent/scripts/generate-opencode-agents.sh
-
-# Verify configuration
-cat ~/.config/opencode/opencode.json | python3 -c "
-import json,sys
-d=json.load(sys.stdin)
-print('MCP in config:', '{mcp-name}' in d.get('mcp',{}))
-print('Agents with access:')
-for agent, cfg in d.get('agent',{}).items():
-    if cfg.get('tools',{}).get('{mcp-name}_*'):
-        print(f'  - {agent}')
-"
-```
-
-### Test with CLI First (No Restart Required)
-
-Use the OpenCode CLI to test MCP accessibility without restarting the TUI:
-
-```bash
-# Test MCP accessibility with specific agent
-~/.aidevops/agents/scripts/opencode-test-helper.sh test-mcp {mcp-name} Build+
-
-# Or direct CLI test
-opencode run "List tools from {mcp-name}" --agent Build+
-
-# List all tools available to an agent
-~/.aidevops/agents/scripts/opencode-test-helper.sh list-tools Build+
-```
-
-### Test in OpenCode TUI
-
-If CLI tests pass, restart OpenCode TUI for interactive testing:
-
-1. Restart OpenCode
-2. Switch to an enabled agent (Tab)
-3. Run verification prompt
-4. Confirm expected behavior
-
-### Call Agent Review
-
-After implementation:
-
-```text
-@agent-review Review the new {mcp-name} documentation and configuration
-```
-
-## Post-Implementation Checklist
-
-- [ ] Documentation follows template structure
-- [ ] All relevant AI assistants have configuration documented
-- [ ] Config template includes all assistants
-- [ ] MCP snippets file created
-- [ ] generate-opencode-agents.sh updated for **selected agents only**
-- [ ] ai-cli-config.sh has configure function for all assistants
-- [ ] setup.sh updated if prerequisites needed
-- [ ] ShellCheck passes on modified scripts
-- [ ] Markdown linting passes
-- [ ] Secretlint finds no credential leaks
-- [ ] Verification prompt tested in at least OpenCode
-- [ ] No hardcoded credentials in any file
-- [ ] Links to official docs included
-- [ ] Agent review completed
-
-## Common Patterns
-
-### MCP Config Formats by Assistant
-
-| Assistant | Format | Key Differences |
-|-----------|--------|-----------------|
-| OpenCode | `"type": "local"` | Has `enabled` flag, tools disabled globally |
-| Claude Code | `"type": "stdio"` | Added via CLI, scope: user/project |
-| Cursor | No type field | Uses `${WORKSPACE_FOLDER_PATHS}` |
-| Windsurf | Similar to Cursor | Check `.codeium/` directory |
-| Continue.dev | Check `.continue/` | May vary by version |
-| Gemini CLI | No type field | User or project level |
-| Droid | CLI-based | `droid mcp add` command |
-
-### Workspace Path Handling
-
-```json
-// Cursor/Windsurf (macOS/Linux)
-"args": ["-c", "cmd --mcp -w \"${WORKSPACE_FOLDER_PATHS%%,*}\""]
-
-// Cursor/Windsurf (Windows)
-"args": ["-Command", "cmd --mcp -w \"($env:WORKSPACE_FOLDER_PATHS -split ',')[0]\""]
-
-// Zed
-"args": ["-c", "cmd --mcp -w $(pwd)"]
-
-// Generic (specify path)
-"args": ["--mcp", "-w", "/path/to/project"]
-```
-
-## Example Implementation
-
-For reference, see the Augment Context Engine implementation:
-
-| File | Purpose |
-|------|---------|
-| `.agent/tools/context/augment-context-engine.md` | Documentation |
-| `configs/augment-context-engine-config.json.txt` | Config template |
-| `configs/mcp-templates/augment-context-engine.json` | MCP snippets |
-| `.agent/scripts/generate-opencode-agents.sh` | Agent config |
-| `.agent/scripts/ai-cli-config.sh` | CLI config function |
-| `setup.sh` | Setup function |
-
-Search for `augment-context-engine` in these files to see the patterns.