feat(flow-next): Add MCP review backend option

[Ranudar]

Summary

Add mcp as a new review backend for flow-next, enabling RepoPrompt integration via MCP server instead of rp-cli subprocess calls.

Benefits:

• No rp-cli dependency - works anywhere RepoPrompt MCP is connected
• Cross-platform (Linux containers, Windows, macOS)
• Direct integration without subprocess overhead
• Better error handling via MCP tool responses

Changes

• Add mcp to valid backends in flowctl.py
• Add MCP backend rules to plan-review and impl-review SKILL.md
• Add MCP Backend Workflow sections to workflow.md files
• Add MCP tool mapping documentation
• Update ralph.md with MCP backend documentation and troubleshooting

MCP Tool Mapping

flowctl rp command	MCP Tool
rp setup-review	mcp__RepoPrompt__manage_workspaces (list_tabs, select_tab)
rp select-add	mcp__RepoPrompt__manage_selection (op: "add")
rp chat-send	mcp__RepoPrompt__chat_send
rp prompt-get	mcp__RepoPrompt__prompt (op: "get")

Testing

Tested MCP backend workflow manually - all operations work:

• MCP connection verification ✓
• Tab listing and selection ✓
• File selection ✓
• Chat send with verdict response ✓

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[gmickel]

PR Review: MCP Review Backend

Thanks for the contribution! The concept is solid - MCP backend provides an alternative path to RepoPrompt that doesn't require rp-cli installation (useful for MCP proxying from sandboxes/containers). Found some issues that need addressing before merge.

---

🔴 Critical: Ralph Mode Broken

plugins/flow-next/skills/flow-next-ralph-init/templates/ralph.sh lines 919, 931

Receipt verification only checks rp and codex:

if [[ "$status" == "plan" && ( "$PLAN_REVIEW" == "rp" || "$PLAN_REVIEW" == "codex" ) ]]; then

Impact: MCP reviews skip receipt verification entirely in Ralph mode - tasks marked complete without proof. Silent failure.

Fix: Add || "$PLAN_REVIEW" == "mcp" to both conditions (lines 919 and 931).

---

🔴 Critical: UI Functions Missing MCP

ralph.sh lines 241-264 - ui_plan_review() and ui_impl_review() don't handle mcp:

ui_plan_review() {
  if [[ "$mode" == "rp" ]]; then
    ...
  elif [[ "$mode" == "codex" ]]; then
    ...
  fi
  # mcp falls through silently
}

Fix: Add elif [[ "$mode" == "mcp" ]] branch with appropriate UI message.

---

🟡 Medium: No Guard Hook Support

ralph-guard.py enforces workflow rules for rp/codex (blocks --json, validates receipts, etc). MCP calls go directly to MCP tools, bypassing all guards.

Options:

1. Add flowctl mcp * wrappers (consistent with rp/codex pattern) - significant work
2. Document that MCP backend is manual-mode only (not supported in Ralph) - quick fix
3. Accept the gap for now and track as follow-up issue

I'd suggest option 2 for this PR, option 1 as follow-up.

---

🟡 Medium: Workflow Doc Inconsistency

flow-next-plan-review/workflow.md MCP tool mapping includes:

| `rp builder` | `mcp__RepoPrompt__context_builder` |

But flow-next-impl-review/workflow.md doesn't have this entry. Should be consistent - either both have it or neither.

---

🟢 Minor: No Tests

Consider adding a basic smoke test or note in the PR that testing was manual-only.

---

Summary

The core documentation additions are good. Main gaps:

1. ralph.sh needs MCP handling (receipt checks + UI) - this is the blocker
2. Document Ralph limitation or add guard support
3. Fix workflow.md inconsistency

Happy to help if you have questions on any of these!

[tiagoefreitas]

I currently run flow-next in a linux sandbox and rp-cli over ssh which works well enough, but I don't keep track of rp-cli failures where the model has to retry due to json issues and wastes time/tokens (have seen it in the logs often), would mcp help with that? I guess it helps in the sense of keeping the rp prompts up to date but I though flow-next used a controlled subset of rp-cli commands to avoid errors?

@gmickel whats your veredict would you use this over rp-cli even for controlled flows?