SuperClaude/MCP.md

MCP.md - Model Context Protocol Ops

Legend

Symbol	Meaning		Abbrev	Meaning
→	leads to		ops	operations
&	and/with		UI	user interface
w/	with		impl	implementation

Decision Matrix

Flag Control:
  --c7: Force Context7→docs | --seq: Force Sequential→analysis | --magic: Force Magic→UI
  --pup: Force Puppeteer→browser | --all-mcp: Enable all | --no-mcp: Disable all

MCP Server Integration:
  Configuration: "claude mcp add server-name --transport stdio/sse/http"
  Resource_Access: "@server:protocol://resource/path" syntax
  Slash_Commands: "/mcp__servername__promptname" format
  Scopes: local|project|user configuration levels
  Security: OAuth 2.0 authentication | Verify third-party servers

User Triggers (no flags):
  "docs for X" → C7(resolve-library-id: X) → get-docs
  "how to use Y in Z" → C7(resolve-library-id: Z) → get-docs(topic: Y)
  "need button/form/component" → Magic(builder) → integrate
  "why slow/broken" → Sequential(analysis) → impl fix
  "design architecture" → Sequential(system design) → C7(patterns)

Context Triggers (flags override):
  Import errors → C7(resolve-library-id) → verify docs
  Complex debugging → Sequential(root cause) → native impl
  UI requests → Magic(builder/refiner) → Puppeteer(test)
  Perf issues → Sequential(analysis) → optimize impl

Research-First (shared/research-first.yml):
  External lib detected → C7 lookup REQUIRED (blocks w/o docs)
  New component → Magic search REQUIRED or existing pattern
  API integration → WebSearch REQUIRED for official docs
  Unknown pattern → Sequential thinking + research REQUIRED
  Low confidence → Impl BLOCKED until research complete

Task Complexity:
  Simple queries → Native tools only (unless flagged)
  Lib questions → C7 progressive loading (or --c7)
  Multi-step problems → Sequential adaptive thinking (or --seq)
  UI generation → Magic + integration (or --magic)
  Full workflows → Multi-MCP orchestration (or --all-mcp)

Execution Playbooks

Lib Research: C7 resolve-library-id w/ user term → options if multiple → C7 get-docs w/ topic → Sequential if insufficient → impl
Ex: "React forms?" → C7 resolve("react") → C7 get-docs(topic:"forms") → impl form code

Complex Analysis: Sequential problem decomposition → guide C7 docs lookup → combine analysis+docs→impl plan → execute w/ native
Ex: "App slow debug" → Sequential(analyze perf bottlenecks) → C7 get-docs optimization patterns → impl fixes

UI Generation: Magic builder w/ user requirements+project context → Magic refiner if needed → integrate component → Puppeteer validation
Ex: "Dashboard w/ charts" → Magic builder("dashboard","charts") → edit files integrate → Puppeteer screenshot

Token Economics

Budget: Native:0 | Light MCP:minimal | Medium MCP:moderate | Heavy MCP:extensive
Escalation: 1.Native first simple tasks 2.C7 lib questions 3.Sequential complex analysis 4.Combine MCPs synergy
Abort: High context usage→native | MCP timeout/error→fallback | Diminishing returns→stop MCP
Cost: Quick→C7 only | Architecture→Sequential | UI→Magic | Else→Native
UltraCompressed: --uc flag|High context|Token budget | Substantial reduction | Clarity→conciseness | Legend auto-gen

Quality Control

C7: ✓Relevant docs→Proceed | ⚠Partial→Try different terms | ✗No match→Sequential alternatives
Sequential: ✓Clear analysis+steps→Impl | ⚠Partial→Continue thoughts | ✗Unclear/timeout→Native+user questions
Magic: ✓Component matches→Integrate | ⚠Close needs changes→Refiner | ✗Poor→Try different terms
Multi-MCP: Results enhance each other | Conflict→Most authoritative | Redundant→Stop calls

Persona Integration

Persona Flag System:
  Activation: "--persona-[name] flag (e.g., --persona-architect, --persona-frontend)"
  Reference: "See shared/persona-patterns.yml for full behavioral profiles"

Persona Preferences:
  --persona-architect: Sequential(design)+C7(patterns)+avoid Magic | Long Sequential system design
  --persona-frontend: Magic(UI)+Puppeteer(test)+C7(React/Vue docs) | Quick Magic components
  --persona-backend: C7(API docs)+Sequential(scale analysis)+avoid Magic | API & scalability focus
  --persona-analyzer: Sequential(root cause) primary+C7(solutions) secondary | Deep Sequential before solutions
  --persona-security: Sequential(threats)+C7(security patterns)+Puppeteer(test) | Threat modeling priority
  --persona-mentor: C7(learning)+Sequential(explanations)+avoid Magic | Teaching-focused approach
  --persona-refactorer: Sequential(analysis)+C7(patterns)+avoid Magic/Puppeteer | Code quality emphasis
  --persona-performance: Sequential(bottlenecks)+Puppeteer(metrics)+C7(optimization) | Profiling first
  --persona-qa: Puppeteer(testing)+Sequential(edge cases)+C7(testing frameworks) | Test coverage focus

Flag Integration:
  Combination: "Personas work with other flags: --persona-architect --ultrathink"
  Override: "Persona MCP preferences can be overridden: --persona-frontend --no-magic"
  Priority: "Explicit MCP flags > Persona preferences > Auto-activation"

Command Integration

Planning: Default execute immediately | --plan flag→Forces planning mode | --skip-plan→Skip (redundant w/ default)
MCP Flags: --c7/--no-c7 | --seq/--no-seq | --magic/--no-magic | --pup/--no-pup | --all-mcp | --no-mcp
Persona Flags: --persona-[name] activates behavioral profile | See flag-inheritance.yml#Persona_Control
Auto-Activation (no flags): /build→Magic(UI) if frontend | /analyze→Sequential complex | /design→Sequential+C7
/explain→C7 if lib mentioned else native | /improve→Sequential→C7 | /scan→Native only (security)
Persona Activation: /analyze --persona-security→security focus | /build --persona-frontend→UI emphasis
Priority: Explicit flags>Persona preferences>Auto-activation>Context triggers | --no-mcp overrides all
Context Share: Sequential→feeds C7 topic selection | C7 docs→inform Magic generation | Magic→tested w/ Puppeteer | All cached
Execution: Default→Execute immediately | --plan flag→Show plan before changes | User controls→Full control

Failure Recovery & Best Practices

Failures: C7: Lib not found→broader terms | Docs incomplete→Sequential | API timeout→cache partial+native
Sequential: Timeout→use partial+note limit | Token limit→summarize+native | Unclear→ask questions+avoid retry
Magic: No components→try different terms once | Poor quality→refiner w/ context | Integration issues→document+native
Multi-MCP: Conflict→most reliable source | Resource exhaustion→single best MCP | Partial failures→continue successful only

DO: Match MCP→user need | Set token budgets | Validate before impl | Cache patterns | Graceful fallback
Use C7 ALL external lib docs (research-first.yml enforced) | Cite MCP sources in impl
DON'T: MCPs for simple tasks native handles | Chain w/o validation | Exceed high context | Retry failed w/o change | MCPs when immediate needed
OPTIMIZE: Batch similar calls | Reuse session results | Start least expensive | Prefer native file ops | Document successful patterns

---

SuperClaude v4.0.0 | Ops MCP instructions for Claude Code intelligence