From c649cfc17f895b58babf737dfdec2f6cc391e40a Mon Sep 17 00:00:00 2001 From: Matt Van Horn Date: Sun, 8 Mar 2026 12:43:21 -0700 Subject: [PATCH] fix(mcp): add API key auth support for Context7 server Add x-api-key header to Context7 MCP config using CONTEXT7_API_KEY env var with empty default so it remains optional. Without auth, all requests hit the anonymous rate limit ("Monthly quota exceeded"). Also update README to document the API key setup and the Known Issues workaround. Closes #153 Co-Authored-By: Claude Opus 4.6 --- plugins/compound-engineering/.mcp.json | 5 +- plugins/compound-engineering/README.md | 12 ++- .../commands/ce/compound.md | 78 ++++++++++++++++++- 3 files changed, 89 insertions(+), 6 deletions(-) diff --git a/plugins/compound-engineering/.mcp.json b/plugins/compound-engineering/.mcp.json index c5280c5..4290fa6 100644 --- a/plugins/compound-engineering/.mcp.json +++ b/plugins/compound-engineering/.mcp.json @@ -2,7 +2,10 @@ "mcpServers": { "context7": { "type": "http", - "url": "https://mcp.context7.com/mcp" + "url": "https://mcp.context7.com/mcp", + "headers": { + "x-api-key": "${CONTEXT7_API_KEY:-}" + } } } } diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index 33a4ea1..af43b0d 100644 --- a/plugins/compound-engineering/README.md +++ b/plugins/compound-engineering/README.md @@ -53,12 +53,11 @@ Agents are organized into categories for easier discovery. | `design-iterator` | Iteratively refine UI through systematic design iterations | | `figma-design-sync` | Synchronize web implementations with Figma designs | -### Workflow (5) +### Workflow (4) | Agent | Description | |-------|-------------| | `bug-reproduction-validator` | Systematically reproduce and validate bug reports | -| `every-style-editor` | Edit content to conform to Every's style guide | | `lint` | Run linting and code quality checks on Ruby and ERB files | | `pr-comment-resolver` | Address PR comments and implement fixes | | `spec-flow-analyzer` | Analyze user flows and identify gaps in specifications | @@ -190,6 +189,8 @@ Supports 100+ frameworks including Rails, React, Next.js, Vue, Django, Laravel, MCP servers start automatically when the plugin is enabled. +**Authentication:** To avoid anonymous rate limits, set the `CONTEXT7_API_KEY` environment variable with your Context7 API key. The plugin passes this automatically via the `x-api-key` header. Without it, requests go unauthenticated and will quickly hit the anonymous quota limit. + ## Browser Automation This plugin uses **agent-browser CLI** for browser automation tasks. Install it globally: @@ -220,13 +221,16 @@ claude /plugin install compound-engineering "mcpServers": { "context7": { "type": "http", - "url": "https://mcp.context7.com/mcp" + "url": "https://mcp.context7.com/mcp", + "headers": { + "x-api-key": "${CONTEXT7_API_KEY:-}" + } } } } ``` -Or add it globally in `~/.claude/settings.json` for all projects. +Set `CONTEXT7_API_KEY` in your environment to authenticate. Or add it globally in `~/.claude/settings.json` for all projects. ## Version History diff --git a/plugins/compound-engineering/commands/ce/compound.md b/plugins/compound-engineering/commands/ce/compound.md index 8637955..ca94c50 100644 --- a/plugins/compound-engineering/commands/ce/compound.md +++ b/plugins/compound-engineering/commands/ce/compound.md @@ -21,7 +21,45 @@ Captures problem solutions while context is fresh, creating structured documenta /ce:compound [brief context] # Provide additional context hint ``` -## Execution Strategy: Two-Phase Orchestration +## Execution Strategy: Context-Aware Orchestration + +### Phase 0: Context Budget Check + + +**Run this check BEFORE launching any subagents.** + +The /compound command is token-heavy - it launches 5 parallel subagents that collectively consume ~10k tokens of context. Running near context limits risks compaction mid-compound, which degrades output quality significantly. + + +Before proceeding, the orchestrator MUST: + +1. **Assess context usage**: Check how long the current conversation has been running. If there has been significant back-and-forth (many tool calls, large file reads, extensive debugging), context is likely constrained. + +2. **Warn the user**: + ``` + ⚠️ Context Budget Check + + /compound launches 5 parallel subagents (~10k tokens). Long conversations + risk compaction mid-compound, which degrades documentation quality. + + Tip: For best results, run /compound early in a session - right after + verifying a fix, before continuing other work. + ``` + +3. **Offer the user a choice**: + ``` + How would you like to proceed? + + 1. Full compound (5 parallel subagents, ~10k tokens) - best quality + 2. Compact-safe mode (single pass, ~2k tokens) - safe near context limits + ``` + +4. **If the user picks option 1** (or confirms full mode): proceed to Phase 1 below. +5. **If the user picks option 2** (or requests compact-safe): skip to the **Compact-Safe Mode** section below. + +--- + +### Full Mode **Only ONE file gets written - the final documentation.** @@ -99,6 +137,44 @@ Based on problem type, optionally invoke specialized agents to review the docume +--- + +### Compact-Safe Mode + + +**Single-pass alternative for context-constrained sessions.** + +When context budget is tight, this mode skips parallel subagents entirely. The orchestrator performs all work in a single pass, producing a minimal but complete solution document. + + +The orchestrator (main conversation) performs ALL of the following in one sequential pass: + +1. **Extract from conversation**: Identify the problem, root cause, and solution from conversation history +2. **Classify**: Determine category and filename (same categories as full mode) +3. **Write minimal doc**: Create `docs/solutions/[category]/[filename].md` with: + - YAML frontmatter (title, category, date, tags) + - Problem description (1-2 sentences) + - Root cause (1-2 sentences) + - Solution with key code snippets + - One prevention tip +4. **Skip specialized agent reviews** (Phase 3) to conserve context + +**Compact-safe output:** +``` +✓ Documentation complete (compact-safe mode) + +File created: +- docs/solutions/[category]/[filename].md + +Note: This was created in compact-safe mode. For richer documentation +(cross-references, detailed prevention strategies, specialized reviews), +re-run /compound in a fresh session. +``` + +**No subagents are launched. No parallel tasks. One file written.** + +--- + ## What It Captures - **Problem symptom**: Exact error messages, observable behavior