diff --git a/.agent/scripts/generate-opencode-agents.sh b/.agent/scripts/generate-opencode-agents.sh index 75ded2892..4f4a889e5 100755 --- a/.agent/scripts/generate-opencode-agents.sh +++ b/.agent/scripts/generate-opencode-agents.sh @@ -123,60 +123,61 @@ AGENT_TOOLS = { # Bash enabled with granular permissions for read-only file discovery commands "write": True, "edit": True, "bash": True, "read": True, "glob": True, "grep": True, "webfetch": True, "task": False, - "context7_*": True, "osgrep_*": True, "augment-context-engine_*": True, "repomix_*": True + "context7_*": True, "osgrep_*": True, "augment-context-engine_*": True, "repomix_*": True, + "gh_grep_*": True, "playwriter_*": True }, "Build+": { "write": True, "edit": True, "bash": True, "read": True, "glob": True, "grep": True, "webfetch": True, "task": True, "todoread": True, "todowrite": True, "context7_*": True, "osgrep_*": True, "augment-context-engine_*": True, "repomix_*": True, - "claude-code-mcp_*": True + "gh_grep_*": True, "playwriter_*": True }, "AI-DevOps": { "write": True, "edit": True, "bash": True, "read": True, "glob": True, "grep": True, "webfetch": True, "task": True, "todoread": True, "todowrite": True, "context7_*": True, "osgrep_*": True, "augment-context-engine_*": True, "repomix_*": True, - "claude-code-mcp_*": True + "gh_grep_*": True, "playwriter_*": True }, "Onboarding": { "write": True, "edit": True, "bash": True, "read": True, "glob": True, "grep": True, "webfetch": True, "task": True, - "osgrep_*": True, "augment-context-engine_*": True + "osgrep_*": True, "augment-context-engine_*": True, "repomix_*": True, "playwriter_*": True }, "Accounts": { "write": True, "edit": True, "bash": True, "read": True, "glob": True, "grep": True, "webfetch": True, "task": True, "quickfile_*": True, - "osgrep_*": True, "augment-context-engine_*": True + "osgrep_*": True, "augment-context-engine_*": True, "repomix_*": True, "playwriter_*": True }, "Social-Media": { "write": True, "edit": True, "bash": True, "read": True, "glob": True, "grep": True, "webfetch": True, "task": True, - "osgrep_*": True, "augment-context-engine_*": True + "osgrep_*": True, "augment-context-engine_*": True, "repomix_*": True, "playwriter_*": True }, "SEO": { "write": True, "read": True, "bash": True, "webfetch": True, "gsc_*": True, "ahrefs_*": True, "dataforseo_*": True, - "context7_*": True, "osgrep_*": True, "augment-context-engine_*": True + "context7_*": True, "osgrep_*": True, "augment-context-engine_*": True, "repomix_*": True, "playwriter_*": True }, "WordPress": { "write": True, "edit": True, "bash": True, "read": True, "glob": True, "grep": True, - "localwp_*": True, "context7_*": True, "osgrep_*": True, "augment-context-engine_*": True + "localwp_*": True, "context7_*": True, "osgrep_*": True, "augment-context-engine_*": True, "repomix_*": True, "playwriter_*": True }, "Content": { "write": True, "edit": True, "read": True, "webfetch": True, - "osgrep_*": True, "augment-context-engine_*": True + "osgrep_*": True, "augment-context-engine_*": True, "repomix_*": True, "playwriter_*": True }, "Research": { "read": True, "webfetch": True, "bash": True, - "context7_*": True, "osgrep_*": True, "augment-context-engine_*": True + "context7_*": True, "osgrep_*": True, "augment-context-engine_*": True, "repomix_*": True, "playwriter_*": True }, } # Default tools for agents not in AGENT_TOOLS +# Note: claude-code-mcp_* NOT included - use @claude-code subagent instead DEFAULT_TOOLS = { "write": True, "edit": True, "bash": True, "read": True, "glob": True, "grep": True, "webfetch": True, "task": True, - "osgrep_*": True, "augment-context-engine_*": True, - "claude-code-mcp_*": False + "osgrep_*": True, "augment-context-engine_*": True, "repomix_*": True, "playwriter_*": True } # Temperature settings (by display name, default 0.2) @@ -481,6 +482,16 @@ if model_count > 0: # ============================================================================= # MCP SERVERS - Ensure required MCP servers are configured # ============================================================================= +# Loading strategy: +# - enabled: True = Server starts at OpenCode launch (for MCPs used by all main agents) +# - enabled: False = Server starts on-demand when subagent invokes it (lazy loading) +# +# MCPs enabled at startup (used by main agents): +# - osgrep, augment-context-engine, context7, repomix, playwriter, gh_grep +# +# MCPs lazy-loaded (subagent-only): +# - claude-code-mcp, outscraper, dataforseo, shadcn, macos-automator, gsc, localwp, etc. +# ============================================================================= if 'mcp' not in config: config['mcp'] = {} @@ -488,6 +499,45 @@ if 'mcp' not in config: if 'tools' not in config: config['tools'] = {} +import shutil +import platform +import sys +bun_path = shutil.which('bun') +npx_path = shutil.which('npx') +if not npx_path and not bun_path: + print(" Warning: Neither bun nor npx found in PATH", file=sys.stderr) +pkg_runner = f"{bun_path} x" if bun_path else (npx_path or "npx") + +# ----------------------------------------------------------------------------- +# MCP LOADING POLICY - Enforce enabled states for all MCPs +# ----------------------------------------------------------------------------- +# Eager-loaded (enabled: True): Used by all main agents, start at launch +EAGER_MCPS = {'osgrep', 'augment-context-engine', 'context7', 'repomix', 'playwriter', 'gh_grep', 'sentry', 'socket'} + +# Lazy-loaded (enabled: False): Subagent-only, start on-demand +LAZY_MCPS = {'claude-code-mcp', 'outscraper', 'dataforseo', 'shadcn', 'macos-automator', + 'gsc', 'localwp', 'chrome-devtools', 'quickfile', 'amazon-order-history', + 'google-analytics-mcp', 'MCP_DOCKER', 'ahrefs'} + +# Apply loading policy to existing MCPs and warn about uncategorized ones +uncategorized = [] +for mcp_name in list(config.get('mcp', {}).keys()): + if mcp_name in EAGER_MCPS: + config['mcp'][mcp_name]['enabled'] = True + elif mcp_name in LAZY_MCPS: + config['mcp'][mcp_name]['enabled'] = False + else: + uncategorized.append(mcp_name) + +if uncategorized: + print(f" Warning: Uncategorized MCPs (add to EAGER_MCPS or LAZY_MCPS): {uncategorized}", file=sys.stderr) + +print(f" Applied MCP loading policy: {len(EAGER_MCPS)} eager, {len(LAZY_MCPS)} lazy") + +# ----------------------------------------------------------------------------- +# EAGER-LOADED MCPs (enabled: True) - Used by all main agents +# ----------------------------------------------------------------------------- + # osgrep MCP - local semantic search (primary, try first) # Install: npm install -g osgrep && osgrep install-opencode if 'osgrep' not in config['mcp']: @@ -496,107 +546,128 @@ if 'osgrep' not in config['mcp']: "command": ["osgrep", "mcp"], "enabled": True } + print(" Added osgrep MCP (eager load - used by all agents)") + +# osgrep_* enabled globally (used by all main agents) +config['tools']['osgrep_*'] = True + +# Playwriter MCP - browser automation via Chrome extension (used by all main agents) +# Requires: Chrome extension from https://chromewebstore.google.com/detail/playwriter-mcp/jfeammnjpkecdekppnclgkkffahnhfhe +if 'playwriter' not in config['mcp']: + if bun_path: + config['mcp']['playwriter'] = { + "type": "local", + "command": ["bun", "x", "playwriter@latest"], + "enabled": True + } + else: + config['mcp']['playwriter'] = { + "type": "local", + "command": ["npx", "playwriter@latest"], + "enabled": True + } + print(" Added playwriter MCP (eager load - used by all agents)") + +# playwriter_* enabled globally (used by all main agents) +config['tools']['playwriter_*'] = True + +# gh_grep MCP - GitHub code search (used by Plan+, Build+, AI-DevOps) +# This is a remote MCP, no local process to start +if 'gh_grep' not in config['mcp']: + config['mcp']['gh_grep'] = { + "type": "remote", + "url": "https://mcp.grep.app", + "enabled": True + } + print(" Added gh_grep MCP (eager load - used by Plan+/Build+/AI-DevOps)") + +# gh_grep tools disabled globally, enabled for specific agents +if 'gh_grep_*' not in config['tools']: + config['tools']['gh_grep_*'] = False + print(" Set gh_grep_* disabled globally (enabled for Plan+/Build+/AI-DevOps)") + +# repomix_* enabled globally (used by all main agents) +config['tools']['repomix_*'] = True -# Ensure osgrep_* is disabled globally (enabled per-agent) -if 'osgrep_*' not in config['tools']: - config['tools']['osgrep_*'] = False +# ----------------------------------------------------------------------------- +# LAZY-LOADED MCPs (enabled: False) - Subagent-only, start on-demand +# ----------------------------------------------------------------------------- # Outscraper MCP - for business intelligence extraction (subagent only) +# Note: enabled state is set by MCP loading policy above if 'outscraper' not in config['mcp']: config['mcp']['outscraper'] = { "type": "local", "command": ["/bin/bash", "-c", "OUTSCRAPER_API_KEY=$OUTSCRAPER_API_KEY uv tool run outscraper-mcp-server"], - "enabled": True + "enabled": False } - print(" Added outscraper MCP server") + print(" Added outscraper MCP (lazy load - @outscraper subagent only)") if 'outscraper_*' not in config['tools']: config['tools']['outscraper_*'] = False - print(" Added outscraper_* to tools (disabled globally, enabled for @outscraper subagent)") - -# DataForSEO MCP - for comprehensive SEO data -# Uses bun x if available, falls back to npx -import shutil -import platform -bun_path = shutil.which('bun') -npx_path = shutil.which('npx') or '/opt/homebrew/bin/npx' -pkg_runner = f"{bun_path} x" if bun_path else npx_path + print(" Set outscraper_* disabled globally") +# DataForSEO MCP - for comprehensive SEO data (SEO agent and @dataforseo subagent) +# Note: enabled state is set by MCP loading policy above if 'dataforseo' not in config['mcp']: config['mcp']['dataforseo'] = { "type": "local", "command": ["/bin/bash", "-c", f"source ~/.config/aidevops/mcp-env.sh && DATAFORSEO_USERNAME=$DATAFORSEO_USERNAME DATAFORSEO_PASSWORD=$DATAFORSEO_PASSWORD {pkg_runner} dataforseo-mcp-server"], - "enabled": True + "enabled": False } - print(" Added dataforseo MCP server") + print(" Added dataforseo MCP (lazy load - SEO agent/@dataforseo subagent)") if 'dataforseo_*' not in config['tools']: config['tools']['dataforseo_*'] = False - print(" Added dataforseo_* to tools (disabled globally, enabled for SEO agent)") - -# Serper - REMOVED: Now uses curl-based subagent (.agent/seo/serper.md) -# No MCP overhead, same functionality via direct API calls - -# Playwriter MCP - browser automation via Chrome extension -# Requires: Chrome extension from https://chromewebstore.google.com/detail/playwriter-mcp/jfeammnjpkecdekppnclgkkffahnhfhe -if 'playwriter' not in config['mcp']: - if bun_path: - config['mcp']['playwriter'] = { - "type": "local", - "command": ["bun", "x", "playwriter@latest"], - "enabled": True - } - else: - config['mcp']['playwriter'] = { - "type": "local", - "command": ["npx", "playwriter@latest"], - "enabled": True - } - print(" Added playwriter MCP server (install Chrome extension separately)") + print(" Set dataforseo_* disabled globally") -# shadcn MCP - UI component library for browsing, searching, and installing components +# shadcn MCP - UI component library (subagent only) # Docs: https://ui.shadcn.com/docs/mcp +# Note: enabled state is set by MCP loading policy above if 'shadcn' not in config['mcp']: config['mcp']['shadcn'] = { "type": "local", "command": ["npx", "shadcn@latest", "mcp"], - "enabled": True + "enabled": False } - print(" Added shadcn MCP server") + print(" Added shadcn MCP (lazy load - @shadcn subagent only)") if 'shadcn_*' not in config['tools']: config['tools']['shadcn_*'] = False - print(" Added shadcn_* to tools (disabled globally, enabled for @shadcn subagent)") - -# Claude Code MCP - forked for local automation -# Source: https://github.com/marcusquinn/claude-code-mcp -# Upstream: https://github.com/steipete/claude-code-mcp (revert if merged) + print(" Set shadcn_* disabled globally") + +# Claude Code MCP - spawn Claude as sub-agent (subagent only) +# Source: https://github.com/steipete/claude-code-mcp +# Use @claude-code subagent to invoke this MCP +# Fork: https://github.com/marcusquinn/claude-code-mcp (until PR #40 merged upstream) +# Upstream: https://github.com/steipete/claude-code-mcp +# Note: Always overwrite to ensure correct fork is used config['mcp']['claude-code-mcp'] = { "type": "local", "command": ["npx", "-y", "github:marcusquinn/claude-code-mcp"], - "enabled": True + "enabled": False } -print(" Ensured claude-code-mcp MCP server (forked)") +print(" Set claude-code-mcp to lazy load (@claude-code subagent only)") -# Claude Code MCP tools disabled globally (enable per-agent in AGENT_TOOLS if needed) +# Claude Code MCP tools disabled globally config['tools']['claude-code-mcp_*'] = False -print(" Set claude-code-mcp_* tools disabled globally (enabled for Build+/AI-DevOps only)") +print(" Set claude-code-mcp_* disabled globally") -# macOS Automator MCP - AppleScript and JXA automation (macOS only) +# macOS Automator MCP - AppleScript and JXA automation (macOS only, subagent only) # Docs: https://github.com/steipete/macos-automator-mcp -# Note: import platform is at line 412 with other imports +# Note: enabled state is set by MCP loading policy above if platform.system() == 'Darwin': if 'macos-automator' not in config['mcp']: config['mcp']['macos-automator'] = { "type": "local", "command": ["npx", "-y", "@steipete/macos-automator-mcp@0.2.0"], - "enabled": True + "enabled": False } - print(" Added macos-automator MCP server (macOS only)") + print(" Added macos-automator MCP (lazy load - @mac subagent only)") if 'macos-automator_*' not in config['tools']: config['tools']['macos-automator_*'] = False - print(" Added macos-automator_* to tools (disabled globally, enabled for @mac subagent)") + print(" Set macos-automator_* disabled globally") with open(config_path, 'w') as f: json.dump(config, f, indent=2) @@ -643,6 +714,9 @@ while IFS= read -r f; do dataforseo) extra_tools=$' dataforseo_*: true\n webfetch: true' ;; + claude-code) + extra_tools=$' claude-code-mcp_*: true' + ;; # serper - REMOVED: Uses curl subagent now, no MCP tools playwriter) extra_tools=$' playwriter_*: true' diff --git a/.agent/subagent-index.toon b/.agent/subagent-index.toon index 49e361dd4..6f59e0d75 100644 --- a/.agent/subagent-index.toon +++ b/.agent/subagent-index.toon @@ -31,7 +31,7 @@ tools/content/,Content tools - summarization and extraction,summarize tools/social-media/,Social media tools - X/Twitter CLI,bird tools/build-agent/,Agent design - composing efficient agents,build-agent|agent-review tools/build-mcp/,MCP development - creating MCP servers,build-mcp|server-patterns|api-wrapper|transports|deployment -tools/ai-assistants/,AI tool integration - configuring assistants,agno|capsolver|windsurf|configuration +tools/ai-assistants/,AI tool integration - configuring assistants,agno|capsolver|windsurf|claude-code|configuration tools/ai-orchestration/,AI orchestration - visual builders and multi-agent,overview|langflow|crewai|autogen|openprose tools/browser/,Browser automation - scraping and testing,agent-browser|stagehand|playwright|playwriter|crawl4ai|pagespeed|peekaboo tools/mobile/,Mobile development - iOS/Android emulators,minisim diff --git a/.agent/tools/ai-assistants/claude-code.md b/.agent/tools/ai-assistants/claude-code.md new file mode 100644 index 000000000..228dd113f --- /dev/null +++ b/.agent/tools/ai-assistants/claude-code.md @@ -0,0 +1,112 @@ +--- +description: Claude Code MCP - spawn Claude as a sub-agent for complex tasks +mode: subagent +tools: + read: true + bash: true + claude-code-mcp_*: true +--- + +# Claude Code MCP + + + +## Quick Reference + +- **Purpose**: Spawn Claude Code as a sub-agent for complex, multi-step tasks +- **MCP**: `claude-code-mcp` (loaded on-demand when this subagent is invoked) +- **Source**: https://github.com/steipete/claude-code-mcp +- **Install**: `npm install -g @steipete/claude-code-mcp` + +**When to use**: +- Complex multi-file refactoring that benefits from fresh context +- Tasks requiring extended thinking or different model capabilities +- Parallel execution of independent subtasks +- Second opinion on complex architectural decisions + +**When NOT to use**: +- Simple file edits (use native Edit tool) +- Quick searches (use grep/osgrep) +- Single-file changes (overhead not worth it) + + + +## Overview + +The Claude Code MCP allows spawning Claude Code as a sub-agent. This is useful for: + +1. **Context isolation**: Sub-agent gets fresh context, avoiding token bloat +2. **Parallel execution**: Multiple sub-agents can work on independent tasks +3. **Model flexibility**: Sub-agent can use different model/settings +4. **Complex workflows**: Multi-step tasks that benefit from dedicated focus + +## Usage + +Invoke this subagent when you need Claude Code capabilities: + +```text +@claude-code Refactor the authentication module to use JWT tokens +``` + +The subagent will: +1. Load the `claude-code-mcp` tools +2. Execute the task using Claude Code +3. Return results to the parent agent + +## Available Tools + +When this subagent is invoked, these tools become available: + +| Tool | Description | +|------|-------------| +| `claude_code` | Execute a prompt via Claude Code CLI | + +## Example Prompts + +```text +# Complex refactoring +@claude-code Refactor src/auth/ to use the new token validation library + +# Multi-file analysis +@claude-code Analyze all API endpoints and create a comprehensive test suite + +# Architecture review +@claude-code Review the database schema and suggest optimizations + +# Parallel tasks (invoke multiple times) +@claude-code Update all React components to use the new design system +@claude-code Migrate all API routes to the new error handling pattern +``` + +## Configuration + +The MCP is configured in `opencode.json`: + +```json +{ + "mcp": { + "claude-code-mcp": { + "type": "local", + "command": ["npx", "-y", "@steipete/claude-code-mcp"], + "enabled": false + } + }, + "tools": { + "claude-code-mcp_*": false + } +} +``` + +The MCP starts on-demand when this subagent is invoked, avoiding startup overhead. + +## Best Practices + +1. **Be specific**: Provide clear, detailed prompts for best results +2. **Scope appropriately**: Don't use for trivial tasks +3. **Check results**: Review sub-agent output before proceeding +4. **Avoid loops**: Don't have sub-agents spawn more sub-agents + +## Related + +- `tools/ai-assistants/overview.md` - AI assistant comparison +- `tools/ai-orchestration/openprose.md` - Multi-agent orchestration DSL diff --git a/configs/mcp-templates/claude-code-mcp.json b/configs/mcp-templates/claude-code-mcp.json index b00243e65..5ecc778c3 100644 --- a/configs/mcp-templates/claude-code-mcp.json +++ b/configs/mcp-templates/claude-code-mcp.json @@ -1,7 +1,7 @@ { "_comment": "Claude Code MCP (fork) configuration snippets for various AI tools", "_documentation": "https://github.com/marcusquinn/claude-code-mcp", - "_upstream": "https://github.com/steipete/claude-code-mcp (revert if merged)", + "_upstream": "https://github.com/steipete/claude-code-mcp (revert when PR #40 merged)", "_note": "Requires Claude CLI with --dangerously-skip-permissions accepted (swap to ./start.sh for local dev)", "_install": "npx -y github:marcusquinn/claude-code-mcp", @@ -11,7 +11,7 @@ "claude-code-mcp": { "type": "local", "command": ["npx", "-y", "github:marcusquinn/claude-code-mcp"], - "enabled": true + "enabled": false } },