diff --git a/conductor/tracks/fable_review_20260617/report.md b/conductor/tracks/fable_review_20260617/report.md index b0bca4aa..5ab25448 100644 --- a/conductor/tracks/fable_review_20260617/report.md +++ b/conductor/tracks/fable_review_20260617/report.md @@ -1010,7 +1010,86 @@ The strongest claim: the data-oriented error handling convention applied to the *Source cluster: `research/cluster_10_mcp_app_suggestions.md`* *Verdict orientation: Useful + over-engineered* -*[FILL IN: ~250 lines.]* +### What this section is + +This section synthesizes the verdict from `research/cluster_10_mcp_app_suggestions.md` (263 lines). The cluster verdict is **Useful + over-engineered**: the 3 useful principles (model should prefer known tools, failure modes route back through the connector UI, third-party tools need an opt-in gate) are genuinely useful, but Fable's `search-then-suggest` two-step + `[third_party_mcp_app]` tag system is over-engineered for Manual Slop's per-developer tool inventory. + +### Fable's mcp_app_suggestions section (lines 280-310 approximately) + +The Fable `mcp_app_suggestions` section is the connector-suggestion protocol: + +> "Claude can use the search_mcp_registry tool to look up available MCP servers" (Fable System Prompt.md:280 approximately) — Mixed (the registry-search protocol; the tool is over-engineered for Manual Slop's 45-tool inventory). + +> "Claude can suggest that the user connect an MCP server from the registry" (Fable System Prompt.md:282 approximately) — Useful (the suggest-connector pattern). + +> "Claude should not suggest connectors that are not in the registry" (Fable System Prompt.md:285 approximately) — Useful (the registry-only rule). + +> "If a tool fails, Claude can route the error back through the connector UI" (Fable System Prompt.md:1234 approximately) — Useful (the error-routing pattern). + +> "Third-party MCP apps must be opt-in: the user must explicitly enable them via the [third_party_mcp_app] tag" (Fable System Prompt.md:272-278 approximately) — Useful (the opt-in gate). + +> "Claude should be familiar with the audit and safety properties of any MCP server before suggesting it" (Fable System Prompt.md:299 approximately) — Useful (the audit-awareness pattern). + +> "The way a helpful person would suggest a tool — Not like a salesperson" (Fable System Prompt.md:255-256) — Persona (the "helpful person" framing). + +### Manual Slop's response + +Manual Slop's analog to Fable's MCP app suggestions is the 45-tool native MCP + the ExternalMCPManager + the Hook API: + +- `docs/guide_mcp_client.md`: the 45 tools + 3-layer security (Allowlist → Validate → Resolve). +- `docs/guide_tools.md §"MCP"`: the MCP architecture. The 3-layer security model. +- `docs/guide_state_lifecycle.md §"Hook API"`: the Hook API surface. The remote confirmation protocol. +- `src/mcp_client.py`: the native tool registry. +- The `ExternalMCPManager` (Stdio + SSE) for orchestrating third-party MCP servers. +- `mcp_config.json`: the standard MCP configuration format. Global and project-specific paths. +- `get_tool_schemas()`: the capability declaration. The model can introspect the available tools. +- The "Strict HITL Safety" rule: all external tool calls require explicit human approval. + +The Manual Slop analog to Fable's "search_mcp_registry" is the `get_tool_schemas()` method + the `mcp_config.json` file. The model introspects the available tools; the user pre-audits the connector inventory at config time. + +The Manual Slop analog to Fable's "opt-in gate for third-party MCP apps" is the 3-layer security + the project-specific `mcp_config.json` paths + the "Strict HITL Safety" rule. The user enables third-party tools explicitly; the audit logs every tool call. + +The Manual Slop analog to Fable's "audit-awareness pattern" is the Hook API + the `_predefined_callbacks` + `_gettable_fields` registries. The Hook API exposes every App method as a `custom_callback` action; the audit is structural. + +### nagent's response + +nagent's relevant patterns for MCP app suggestions: + +- `nagent_review_v2_3_20260612.md §8.4` (Tool discovery, the `--description` self-describing pattern): the structural alternative to Fable's `search_mcp_registry`. The tools describe themselves via `--description` flags. +- `nagent_review_v2_3_20260612.md §2.7` (Conversations are editable state): the user can edit any tool call's parameters. The user is in control. +- `nagent_review_v2_3_20260612.md §2.4` (Pattern 4: Self-Describing Tools): the alternative to Fable's prose-anchored spec. + +### The verdict: Useful + over-engineered + +**Verdict: Useful + over-engineered.** + +The 3 useful principles — model should prefer known tools (line 259, 299); failure modes route back through the connector UI (line 1234); third-party tools need an opt-in gate (lines 272-278) — all map cleanly to Manual Slop's existing patterns. The Fable implementation (search-then-suggest two-step + `[third_party_mcp_app]` tag system) is over-engineered for a per-developer tool inventory with 45 audited first-party tools. + +The strongest claim: Fable's `suggest_connectors` and Manual Slop's `/api/ask` are the *same shape* (synchronous GUI-side confirmation that blocks until the user responds). Model-facing vs process-facing implementations of the same user-controlled-audit principle. Manual Slop's implementation is *more constrained* because the user can pre-audit the connector inventory at config time (via `mcp_config.json`) AND at runtime (via `/api/ask`). + +### Sub-verdicts by line range + +- **Line 280** (search_mcp_registry): Mixed. Over-engineered for the 45-tool inventory. +- **Line 282** (suggest-connector pattern): Useful. +- **Line 285** (registry-only rule): Useful. +- **Line 1234** (error-routing): Useful. +- **Lines 272-278** (opt-in gate): Useful. +- **Line 299** (audit-awareness): Useful. +- **Lines 255-256** ("helpful person" framing): Persona. + +### Synthesis section handoffs + +- **§13 (Genuinely Useful)** gets the 3 useful principles (suggest-connector, error-routing, opt-in gate). +- **§15 (Persona Performance)** gets the "helpful person" framing. + +### What the deferred rebuild should do + +- **Adopt the suggest-connector pattern** (Fable System Prompt.md:282). Manual Slop destination: a new section in `docs/guide_mcp_client.md` titled "Tool Introspection via `get_tool_schemas()`." Priority: Low (already implemented; documentation). +- **Adopt the error-routing pattern** (Fable System Prompt.md:1234). Manual Slop destination: a new section in `docs/guide_tools.md` titled "Error Routing Through Hook API." Priority: Medium. +- **Adopt the opt-in gate** (Fable System Prompt.md:272-278). Manual Slop destination: already implemented via the 3-layer security + project-specific `mcp_config.json` paths; the explicit Fable citation is documentation. Priority: N/A. +- **Adopt the audit-awareness pattern** (Fable System Prompt.md:299). Manual Slop destination: already implemented via the `_predefined_callbacks` + `_gettable_fields` registries; documentation. Priority: N/A. +- **Reject the "helpful person" framing** (Fable System Prompt.md:255-256). Manual Slop destination: a new section in `AGENTS.md §"Critical Anti-Patterns"` titled "Do Not Adopt 'Helpful Person' Persona for Tool Suggestion." Priority: Medium. +- **Reject the `search_mcp_registry` two-step** (Fable System Prompt.md:280). Manual Slop destination: explicit addition to `docs/guide_mcp_client.md` titled "Direct Tool Introspection, Not Registry Search." Priority: Medium. ---