Skip to content

feat: MCP on-demand loading - reduce startup tokens by ~4.6K #275

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
marcusquinn merged 1 commit into from
Feb 2, 2026
Merged

feat: MCP on-demand loading - reduce startup tokens by ~4.6K #275

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 29 additions & 16 deletions .agent/scripts/generate-opencode-agents.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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):
Copy link

@augmentcode augmentcode bot Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The comments here say playwriter_* is disabled globally, but later in this script config['tools']['playwriter_*'] = True and the Playwriter MCP is configured as eager-loaded, so it will still load for all agents and likely negate the intended token savings.

Other Locations
  • .agent/scripts/generate-opencode-agents.sh:549
  • .agent/scripts/generate-opencode-agents.sh:566

Fix This in Augment

🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.

# - playwriter_*: ~3K tokens - enable via @playwriter subagent
# - augment-context-engine_*: ~1K tokens - enable via @augment-context-engine subagent
Copy link

@augmentcode augmentcode bot Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

After removing augment-context-engine_* from DEFAULT_TOOLS, it looks like @augment-context-engine won’t actually be granted augment-context-engine_* anywhere during subagent generation (only playwriter is handled in the case block), so invoking that subagent may not work as described.

Other Locations
  • .agent/scripts/generate-opencode-agents.sh:691
  • .agent/scripts/generate-opencode-agents.sh:712

Fix This in Augment

🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.

# - gh_grep_*: ~600 tokens - replaced by @github-search subagent (uses rg/bash)
Copy link

@augmentcode augmentcode bot Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This claims gh_grep_* is disabled and replaced by @github-search, but the script still configures gh_grep as an eager-loaded MCP server; if the goal is to remove its startup overhead, this likely needs to be made lazy/optional too.

Other Locations
  • .agent/scripts/generate-opencode-agents.sh:569
  • .agent/scripts/generate-opencode-agents.sh:510

Fix This in Augment

🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.

#
# 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)
Expand Down
2 changes: 1 addition & 1 deletion .agent/subagent-index.toon
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions .agent/tools/browser/playwriter.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ tools:
grep: true
webfetch: true
task: true
mcp:
- playwriter
---

# Playwriter - Browser Extension MCP
Expand Down
2 changes: 2 additions & 0 deletions .agent/tools/context/augment-context-engine.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ tools:
grep: true
webfetch: false
task: true
mcp:
- augment-context-engine
---

# Augment Context Engine MCP Setup
Expand Down
161 changes: 161 additions & 0 deletions .agent/tools/context/github-search.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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

<!-- AI-CONTEXT-START -->

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

<!-- AI-CONTEXT-END -->

## 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
Copy link

@augmentcode augmentcode bot Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

gh search code ... --filename "*.ts" likely won’t match anything because GitHub’s filename: qualifier doesn’t treat * as a glob; this example may be misleading unless the CLI explicitly supports wildcards here.

Fix This in Augment

🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.

```

### 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
Copy link
Contributor

@coderabbitai coderabbitai bot Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🏁 Script executed:

# First, check if the file exists and read the relevant lines
cat -n .agent/tools/context/github-search.md | sed -n '70,110p'

Repository: marcusquinn/aidevops

Length of output: 1050

🏁 Script executed:

# Verify ripgrep's type system
rg --type-list | head -100

Repository: marcusquinn/aidevops

Length of output: 2914

🏁 Script executed:

# Specifically search for ts/tsx types
rg --type-list | grep -i "ts\|tsx"

Repository: marcusquinn/aidevops

Length of output: 755

Use --type ts to match both TypeScript and TSX files — the ts type built-in type in ripgrep explicitly includes *.tsx files, so -t ts or --type ts covers both.

The --type tsx flag doesn't exist as a built-in ripgrep type. While the proposed glob pattern fix (-g '*.tsx') would work, the more direct approach is to use the existing ts type which already encompasses .tsx files.

Apply at lines 74 and 104:

Recommended approach 
-rg "useState\(.*loading" --type tsx
+rg "useState\(.*loading" --type ts
-rg "useEffect\(\(\) => \{" --type tsx -C 2
+rg "useEffect\(\(\) => \{" --type ts -C 2

Also correct line 77: -t tsx should be -t ts.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
rg "useState\(.*loading" --type tsx
rg "useState\(.*loading" --type ts
🤖 Prompt for AI Agents 
In @.agent/tools/context/github-search.md at line 74, Replace ripgrep usages
that specify the non-existent built-in type "tsx" with the existing "ts" type so
both .ts and .tsx files are matched; update the occurrences of --type tsx and -t
tsx in the document (e.g., the command shown as rg "useState\(.*loading" --type
tsx and the -t tsx mention) to --type ts and -t ts respectively, and also change
the other instance around line 104 to use --type ts.


# 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
Comment on lines +88 to +95
Copy link

@gemini-code-assist gemini-code-assist bot Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The Clone and Search Pattern example uses a fixed directory name (next.js) and rm -rf for cleanup. This could lead to accidental data loss if a directory with the same name already exists for other reasons. A more robust approach is to use a temporary directory created with mktemp to avoid name collisions and ensure the cleanup is safe.

Suggested change
# 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
# Create a temporary directory to avoid name collisions
CLONE_DIR=$(mktemp -d)
# Clone a specific repo into the temp directory
gh repo clone vercel/next.js "$CLONE_DIR" -- --depth 1
# Search within it
rg "getServerSession" "$CLONE_DIR"
# Clean up
rm -rf "$CLONE_DIR"

```

## 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.
31 changes: 27 additions & 4 deletions .agent/tools/context/mcp-discovery.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

<!-- AI-CONTEXT-END -->

## Architecture
Expand Down Expand Up @@ -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
Copy link

@augmentcode augmentcode bot Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The doc says the mcp: field is declarative and "actual enabling happens" in generate-opencode-agents.sh, but the generator currently doesn’t appear to read mcp: frontmatter (subagent tool enablement is hardcoded by subagent name). This mismatch could confuse users about how on-demand MCPs are actually activated.

Other Locations
  • .agent/scripts/generate-opencode-agents.sh:238
  • .agent/scripts/generate-opencode-agents.sh:691

Fix This in Augment

🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.

configures OpenCode's per-agent tool permissions.
Comment on lines +154 to +156
Copy link

@gemini-code-assist gemini-code-assist bot Feb 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

This note appears to contradict the changes in generate-opencode-agents.sh. The script is modified to disable MCPs from the default configuration, while this note claims the script is where the "actual enabling happens". This is confusing for anyone trying to understand the on-demand loading mechanism.

Could you clarify how the enabling works? If it's a dynamic, runtime process triggered by the mcp: frontmatter, the documentation should be updated to reflect that, rather than pointing to the static generation script. A clearer note might be: "The mcp: field is a directive for the agent runtime to dynamically load the required MCP tools when this subagent is invoked."


### Main Agent Pattern

Main agents don't enable MCPs directly. They:
Expand Down
Loading