diff --git a/.agent/scripts/generate-opencode-agents.sh b/.agent/scripts/generate-opencode-agents.sh index ab42afbe2..2193c464c 100755 --- a/.agent/scripts/generate-opencode-agents.sh +++ b/.agent/scripts/generate-opencode-agents.sh @@ -122,59 +122,72 @@ SKIP_PRIMARY_AGENTS = {"plan-plus.md", "aidevops.md"} # Special tool configurations per agent (by display name) # These are MCP tools that specific agents need access to -# Note: playwriter_* is ONLY enabled for agents with browser subagents -# to reduce context bloat from verbose tool descriptions +# +# MCP On-Demand Loading Strategy: +# The following MCPs are DISABLED globally to reduce context token usage (~4.6K saved): +# - playwriter_*: ~3K tokens - enable via @playwriter subagent +# - augment-context-engine_*: ~1K tokens - enable via @augment-context-engine subagent +# - gh_grep_*: ~600 tokens - replaced by @github-search subagent (uses rg/bash) +# +# osgrep_* remains enabled as the primary semantic search tool (local, no auth). +# Use @augment-context-engine subagent when osgrep returns insufficient results. AGENT_TOOLS = { "Build+": { # Unified coding agent - planning, implementation, and DevOps - # Has browser subagents (playwright, stagehand) so needs playwriter + # Browser automation: use @playwriter subagent (enables playwriter MCP on-demand) + # Semantic search: osgrep primary, @augment-context-engine fallback + # GitHub search: use @github-search subagent (rg/bash, no MCP needed) "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, - "gh_grep_*": True, "playwriter_*": True + "context7_*": True, "osgrep_*": 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 }, "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 }, "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 }, "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 }, "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 }, "Content": { "write": True, "edit": True, "read": True, "webfetch": True, - "osgrep_*": True, "augment-context-engine_*": True + "osgrep_*": True }, "Research": { "read": True, "webfetch": True, "bash": True, - "context7_*": True, "osgrep_*": True, "augment-context-engine_*": True + "context7_*": True, "osgrep_*": True }, } # Default tools for agents not in AGENT_TOOLS -# Note: playwriter_* NOT included by default - it adds significant -# context overhead from verbose tool descriptions. Enable per-agent as needed. -# Note: claude-code-mcp_* NOT included - use @claude-code subagent instead +# +# MCP On-Demand Loading: +# - playwriter_*: DISABLED - use @playwriter subagent (~3K tokens saved) +# - augment-context-engine_*: DISABLED - use @augment-context-engine subagent (~1K saved) +# - gh_grep_*: DISABLED - use @github-search subagent (~600 tokens saved) +# - claude-code-mcp_*: DISABLED - use @claude-code subagent +# +# osgrep_* remains enabled as primary semantic search (local, fast, no auth) DEFAULT_TOOLS = { "write": True, "edit": True, "bash": True, "read": True, "glob": True, "grep": True, "webfetch": True, "task": True, - "osgrep_*": True, "augment-context-engine_*": True + "osgrep_*": True } # Temperature settings (by display name, default 0.2) diff --git a/.agent/subagent-index.toon b/.agent/subagent-index.toon index 2d69b914d..9536d4d41 100644 --- a/.agent/subagent-index.toon +++ b/.agent/subagent-index.toon @@ -39,7 +39,7 @@ tools/pdf/,PDF processing - form filling and digital signatures,overview|libpdf tools/performance/,Web performance - Core Web Vitals and network analysis,performance tools/ui/,UI components - design systems and debugging,shadcn|ui-skills|frontend-debugging tools/code-review/,Code quality - linting and security scanning,code-standards|code-simplifier|codacy|coderabbit|qlty|snyk|secretlint|security-analysis -tools/context/,Context optimization - semantic search and indexing,osgrep|augment-context-engine|context-builder|context7|toon|mcp-discovery +tools/context/,Context optimization - semantic search and indexing,osgrep|augment-context-engine|context-builder|context7|toon|mcp-discovery|github-search tools/conversion/,Format conversion - document transformation,pandoc tools/video/,Video creation and downloading - programmatic generation and YouTube downloads,remotion|higgsfield|yt-dlp|video-prompt-design tools/data-extraction/,Data extraction - scraping business data,outscraper diff --git a/.agent/tools/browser/playwriter.md b/.agent/tools/browser/playwriter.md index d9fa8e95b..3defc25d7 100644 --- a/.agent/tools/browser/playwriter.md +++ b/.agent/tools/browser/playwriter.md @@ -10,6 +10,8 @@ tools: grep: true webfetch: true task: true +mcp: + - playwriter --- # Playwriter - Browser Extension MCP diff --git a/.agent/tools/context/augment-context-engine.md b/.agent/tools/context/augment-context-engine.md index 9d5472abc..d1de70df8 100644 --- a/.agent/tools/context/augment-context-engine.md +++ b/.agent/tools/context/augment-context-engine.md @@ -10,6 +10,8 @@ tools: grep: true webfetch: false task: true +mcp: + - augment-context-engine --- # Augment Context Engine MCP Setup diff --git a/.agent/tools/context/github-search.md b/.agent/tools/context/github-search.md new file mode 100644 index 000000000..54e349bdc --- /dev/null +++ b/.agent/tools/context/github-search.md @@ -0,0 +1,161 @@ +--- +description: Search GitHub repositories for code patterns using ripgrep and bash +mode: subagent +tools: + read: true + write: false + edit: false + bash: true + glob: true + grep: true + webfetch: false + task: false +--- + +# GitHub Code Search + + + +## Quick Reference + +- **Purpose**: Find real-world code examples from public GitHub repositories +- **Tools**: `rg` (ripgrep), `gh` CLI, bash +- **No MCP required**: Uses standard CLI tools + +**When to use**: + +- Finding implementation patterns for unfamiliar APIs +- Discovering how libraries are used in production +- Learning correct syntax and configuration +- Understanding how different tools work together + +**Search patterns** (use actual code, not keywords): + +- Good: `useState(`, `import React from`, `async function` +- Bad: `react tutorial`, `best practices`, `how to use` + + + +## Search Methods + +### 1. GitHub Code Search (via gh CLI) + +Search across all public GitHub repositories: + +```bash +# Basic search +gh search code "pattern" --limit 10 + +# Filter by language +gh search code "useState(" --language typescript --limit 10 + +# Filter by repository +gh search code "getServerSession" --repo nextauthjs/next-auth --limit 10 + +# Filter by file path +gh search code "middleware" --filename "*.ts" --limit 10 +``` + +### 2. Local Repository Search (via ripgrep) + +Search within cloned repositories: + +```bash +# Basic pattern search +rg "pattern" --type ts + +# Case-insensitive +rg -i "pattern" --type py + +# With context lines +rg -C 3 "pattern" --type js + +# Regex patterns +rg "useState\(.*loading" --type tsx + +# Multiple file types +rg "pattern" -t ts -t tsx -t js + +# Exclude directories +rg "pattern" --glob '!node_modules' --glob '!dist' +``` + +### 3. Clone and Search Pattern + +For deeper analysis, clone popular repositories: + +```bash +# Clone a specific repo +gh repo clone vercel/next.js -- --depth 1 + +# Search within it +rg "getServerSession" next.js/ + +# Clean up +rm -rf next.js +``` + +## Common Search Patterns + +### React Patterns + +```bash +# Hooks usage +rg "useEffect\(\(\) => \{" --type tsx -C 2 + +# Error boundaries +rg "class.*ErrorBoundary" --type tsx + +# Context providers +rg "createContext<" --type tsx +``` + +### API Patterns + +```bash +# Express middleware +rg "app\.(use|get|post)\(" --type ts + +# Authentication +rg "getServerSession|getSession" --type ts + +# Database queries +rg "prisma\.\w+\.(find|create|update)" --type ts +``` + +### Configuration Patterns + +```bash +# Next.js config +rg "module\.exports.*=.*\{" next.config.js + +# TypeScript config +rg '"compilerOptions"' tsconfig.json -A 20 + +# Package scripts +rg '"scripts"' package.json -A 10 +``` + +## Tips + +1. **Be specific**: More words = better results. "auth" is vague, "JWT token validation middleware" is specific. + +2. **Use actual code**: Search for code patterns that would appear in files, not descriptions. + +3. **Filter by language**: Reduces noise significantly. + +4. **Check popular repos**: Well-maintained repos have better patterns. + +5. **Look at tests**: Test files often show correct usage patterns. + +## Comparison with gh_grep MCP + +| Feature | github-search (this) | gh_grep MCP | +|---------|---------------------|-------------| +| Token cost | 0 (no MCP) | ~600 tokens | +| Speed | Fast (local rg) | Network dependent | +| Scope | Local + gh CLI | GitHub API | +| Regex | Full ripgrep | Limited | +| Offline | Partial (local) | No | + +This subagent provides the same functionality as `gh_grep` MCP without the token overhead. diff --git a/.agent/tools/context/mcp-discovery.md b/.agent/tools/context/mcp-discovery.md index 7664cb0c5..cd2f6e7db 100644 --- a/.agent/tools/context/mcp-discovery.md +++ b/.agent/tools/context/mcp-discovery.md @@ -41,10 +41,21 @@ mcp-index-helper.sh status ``` **Why this matters**: + - MCP tool definitions consume context tokens - Loading all MCPs upfront wastes tokens on unused tools - On-demand discovery loads only what's needed +**Disabled MCPs** (enabled via subagents): + +| MCP | Tokens | Subagent | +|-----|--------|----------| +| `playwriter` | ~3K | `@playwriter` | +| `augment-context-engine` | ~1K | `@augment-context-engine` | +| `gh_grep` | ~600 | `@github-search` (uses rg/bash) | + +**Always enabled**: `osgrep` (primary semantic search, local, no auth) + ## Architecture @@ -120,18 +131,30 @@ mcp-index-helper.sh list dataforseo ### Subagent Frontmatter -Subagents declare which MCPs they need: +Subagents declare which MCPs they need via the `mcp:` field: ```yaml --- -description: SEO keyword research +description: Browser automation via Chrome extension mode: subagent tools: - dataforseo_*: true - serper_*: true + read: true + bash: true +mcp: + - playwriter --- ``` +When a subagent with `mcp:` is invoked, the agent should: + +1. Read the subagent file to get instructions +2. Note the MCP requirement in the frontmatter +3. Use the MCP tools as documented in the subagent + +**Note**: The `mcp:` field is declarative - it documents which MCP the subagent +requires. The actual enabling happens in `generate-opencode-agents.sh` which +configures OpenCode's per-agent tool permissions. + ### Main Agent Pattern Main agents don't enable MCPs directly. They: