[Phase 2] Document recommended MCP servers per tech stack

[github-actions]

Story

As a downstream repo maintainer,
I want a docs page recommending an MCP server set per stack and how to enable MCP review via the engine knob,
so that teams can pick the right server for their stack (React / Python / Go) and turn MCP review on correctly.

Acceptance Criteria

1. A new doc (e.g. docs/initiatives/mcp-powered-review.md) lists recommended servers mapped to stacks: Context7 (library docs, free/no-auth), GitHub MCP (secret scanning GA + dependency scanning public preview), and SonarQube MCP (code-quality enrichment).
2. The doc documents the engine knob from story 1 (REVIEW_MCP_CONFIG + the allowed-tools knob) and the graceful-degradation behavior from story 2.
3. The doc states the security-first sequencing (pilot only after in-flight security hardening) and notes that the MCP-Powered CI Review Enhancement — Standard #650 weekly update revises the recommended starter to GitHub MCP secret scanning.
4. If the doc introduces a new standard surface, a one-line pointer is added to AGENTS.md or CLAUDE.md; otherwise no standards edit is made.

Tasks / Subtasks

• Write the doc using the existing initiative-doc header shape (Status/Author/Date/Scope/Constraints). (AC: test issue from agent #1)
• Document the engine knob and the fail-loud degradation behavior with a worked Context7 example. (AC: Go-live improvements for PR review agent #2)
• Capture the security-first sequencing and the revised starter recommendation from the MCP-Powered CI Review Enhancement — Standard #650 weekly update. (AC: Add @claude delegation, auto-merge, and rebase handling #3)
• Add a one-line pointer in AGENTS.md/CLAUDE.md only if a new standard surface is introduced. (AC: Optimize review: small-PR and incremental fast paths #4)

Dev Notes

• Match the existing initiative-doc shape: docs/initiatives/agentic-release-strategy.md header block (Status / Author / Date / Scope (confirmed) / Constraints (confirmed)).
• Ground all server claims in MCP-Powered CI Review Enhancement — Standard #650's body + the 2026-06-13 weekly-update comment: Context7 is free/stateless/no-auth; GitHub MCP secret scanning reached GA (May 2026) and dependency scanning is public preview; SonarQube MCP enriches with code-quality data. Do not overstate availability (e.g. dependency scanning is preview, not GA).
• Cross-reference the broader review-engine initiative Generalize pr-review into a context-adaptive review agent (artifact contract + rubric registry) #610 so readers know MCP plumbing lands independently of the artifact-contract rework.

Project Structure Notes

New markdown under docs/ (docs/initiatives/ matches existing initiative docs). Optional one-line standards pointer.

References

• docs/initiatives/agentic-release-strategy.md (doc header shape)
• docs/initiatives/idea-to-initiative-pipeline.md
• discussion MCP-Powered CI Review Enhancement — Standard #650 (body + 2026-06-13 weekly update comment)

Likely target surface

• docs/initiatives/
• AGENTS.md
• CLAUDE.md

Story prepared by the BMAD Scrum Master (Bob) for epic #676. Status: ready-for-dev.

[don-petry]

Dev-Lead Implementation Plan

Issue: #680 — [Phase 2] Document recommended MCP servers per tech stack

Scope

Add a new initiative doc, docs/initiatives/mcp-powered-review.md, that recommends an MCP server set per stack (React/Python/Go), documents the existing engine.sh MCP knob and its fail-loud graceful degradation, and captures the security-first sequencing + the #650 weekly-update revised starter (GitHub MCP secret scanning).

Implementation Checklist

• Create docs/initiatives/mcp-powered-review.md using the existing initiative-doc header shape (Status / Author / Date / Scope (confirmed) / Constraints (confirmed)), matching agentic-release-strategy.md. (AC test issue from agent #1)
• Per-stack recommended servers table: Context7 (library docs, free/stateless/no-auth), GitHub MCP (secret scanning GA May 2026 + dependency scanning public preview), SonarQube MCP (code-quality enrichment). Do not overstate availability. (AC test issue from agent #1)
• Document the engine knob REVIEW_MCP_CONFIG + REVIEW_MCP_ALLOWED_TOOLS (threads --mcp-config <file> --strict-mcp-config and merges --allowed-tools) with a worked Context7 example, and the fail-loud ::warning::[mcp] graceful-degradation behavior ([Phase 1] Thread an optional MCP config into the Claude agentic review tiers (engine.sh) #677/[Phase 1] Graceful degradation: warn (never fake) when an MCP server is unavailable #678). (AC Go-live improvements for PR review agent #2)
• Capture security-first sequencing (pilot only after in-flight security hardening) and the MCP-Powered CI Review Enhancement — Standard #650 2026-06-13 weekly update revising the recommended starter to GitHub MCP secret scanning. Cross-reference epic MCP-powered review enrichment for the self-hosted Claude review engine (engine.sh) #676 and broader review-engine initiative Generalize pr-review into a context-adaptive review agent (artifact contract + rubric registry) #610. (AC Add @claude delegation, auto-merge, and rebase handling #3)
• AC Optimize review: small-PR and incremental fast paths #4: this is a descriptive recommendations/reference doc, not a new standard surface — plan is NO AGENTS.md/CLAUDE.md edit. Will re-confirm during rubber-duck review and note the rationale in the Phase 6 report.

Tests to Write

• None. This is a pure-documentation change with no observable behavioral change — Phase 2 (TDD) is exempted per the dev-lead exception clause. The existing engine.sh MCP behavior is already covered by tests/dev-lead/unit/test_engine_mcp.bats; the doc only describes it.

Test Command

bats tests/dev-lead/unit/test_engine_mcp.bats (regression guard) + repo lint bash .dev-lead/scripts/dev-lead-lint.sh

[don-petry]

Dev-Lead: Implementation Complete

Plan Execution

• Created docs/initiatives/mcp-powered-review.md with the initiative-doc header shape (Status / Author / Date / Scope (confirmed) / Constraints (confirmed)), matching agentic-release-strategy.md. (AC test issue from agent #1)
• Per-stack recommended-server table: Context7 (library docs, free/stateless/no-auth, all stacks), GitHub MCP secret scanning (GA May 2026), GitHub MCP dependency scanning (public preview, explicitly flagged as not GA), SonarQube MCP (code-quality enrichment). Per-stack starters for React/Python/Go. (AC test issue from agent #1)
• Documented the engine knob REVIEW_MCP_CONFIG + REVIEW_MCP_ALLOWED_TOOLS (threads --mcp-config <file> --strict-mcp-config; merges into the Bash,Read,Grep,Glob allowed-tools base; agentic + rubber-duck tiers only, never triage) with a worked Context7 example, plus the fail-loud ::warning::[mcp] graceful-degradation behavior (inert when unconfigured). (AC Go-live improvements for PR review agent #2)
• Captured security-first sequencing (pilot only after in-flight security hardening) and the MCP-Powered CI Review Enhancement — Standard #650 2026-06-13 weekly update revising the recommended starter to GitHub MCP secret scanning. Cross-referenced epic MCP-powered review enrichment for the self-hosted Claude review engine (engine.sh) #676 and the broader review-engine initiative Generalize pr-review into a context-adaptive review agent (artifact contract + rubric registry) #610. (AC Add @claude delegation, auto-merge, and rebase handling #3)
• AC Optimize review: small-PR and incremental fast paths #4: descriptive recommendations/reference doc — introduces no new standard surface, so no AGENTS.md/CLAUDE.md edit. Consistent with the existing convention (only agentic-release-strategy.md, which codifies a normative standard, is pointed to from AGENTS.md; idea-to-initiative-pipeline.md has no pointer).

Test Results

Pure-documentation change (no source/behavior change) — Phase 2 TDD exempted per the dev-lead exception clause. Existing engine.sh MCP behavior remains covered by tests/dev-lead/unit/test_engine_mcp.bats (unchanged by this PR).

Repo lint gate (bash .dev-lead/scripts/dev-lead-lint.sh):

  [lint] shellcheck on 51 file(s)...
  [lint] validating 4 agent profile(s)...
OK: agents/agentic-workflows.md
OK: agents/compliance-auditor.md
OK: agents/feature-ideator.md
OK: agents/pr-reviewer.md
  [lint] all checks passed

Note: bats is not installed in this environment, so the MCP unit suite was not executed here; it is unaffected because no .sh/test files changed.

Files Changed

• docs/initiatives/mcp-powered-review.md (new): recommended MCP server set per stack, the engine.sh enablement knob with a worked Context7 example, fail-loud graceful-degradation behavior, and security-first sequencing + the MCP-Powered CI Review Enhancement — Standard #650 revised starter.

Notes

• All server-availability claims grounded in MCP-Powered CI Review Enhancement — Standard #650 (body + 2026-06-13 weekly update); preview vs. GA distinction preserved (dependency scanning = preview, not GA).
• Warning-annotation text and knob/flag behavior in the doc mirror scripts/engine.sh verbatim.
• No unrelated files touched; no standards edit (AC Optimize review: small-PR and incremental fast paths #4 condition not met).