conductor(track): fable_review_20260617 cluster 10 (MCP App Suggestions) sub-report
Tier 3 worker dispatch. Verdict: Useful + over-engineered. 263 lines. Fable System Prompt.md:mcp_app_suggestions section cited. Project refs: guide_mcp_client.md (45 tools), guide_tools.md MCP architecture, Hook API. Fable artifact NOT committed.
This commit is contained in:
@@ -0,0 +1,263 @@
|
||||
# Cluster 10: MCP App Suggestions & Third-Party Connectors
|
||||
|
||||
**Sub-agent dispatch:** Tier 3 Worker (2026-06-17). Read-only research task.
|
||||
**Sources read:**
|
||||
- `docs/artifacts/Fable System Prompt.md` lines 252-302 (the `mcp_app_suggestions` section)
|
||||
- `docs/artifacts/Fable System Prompt.md` lines 1198-1234 (the `search_mcp_registry` tool description; the `suggest_connectors` tool description)
|
||||
- `docs/guide_mcp_client.md` (the 45-tool inventory; the 3-layer security model; the `ExternalMCPManager`, `StdioMCPServer`, `RemoteMCPServer`; JSON-RPC 2.0 engine)
|
||||
- `docs/guide_tools.md` (MCP bridge; native tool inventory; Hook API surface)
|
||||
- `docs/guide_state_lifecycle.md` lines 319-345 (Hook API Surface — the `_predefined_callbacks` and `_gettable_fields` registries)
|
||||
- `docs/guide_api_hooks.md` (the `/api/ask` Remote Confirmation Protocol; the 8+ endpoint surface)
|
||||
- `conductor/tracks/nagent_review_20260608/report.md` lines 379-430 (Pattern 12 — Tool discovery, the `--description` self-describing executable pattern)
|
||||
- `conductor/tracks/nagent_review_20260608/nagent_review_v2_3_20260612.md` lines 390-426 (§2.4 Pattern 4: Tool Discovery; the `exit_on_description` / `collect_bin_tool_descriptions` mechanism)
|
||||
- `conductor/tracks/nagent_review_20260608/nagent_takeaways_20260608.md` lines 234-263 (§8 Self-describing tools — let the tool tell the agent what it does)
|
||||
- `conductor/tracks/nagent_review_20260608/comparison_table.md` line 31 (row 12: Tool discovery = GAP)
|
||||
- `conductor/tracks/nagent_review_20260608/decisions.md` lines 144-150 (Candidate 5 / Future track: nagent-style `--description` pattern for `mcp_architecture_refactor_20260606`)
|
||||
- `conductor/tracks/fable_review_20260617/spec.md` lines 86-95 (Cluster 10's row in the 10-cluster table; the synthesis-section mapping)
|
||||
|
||||
---
|
||||
|
||||
## 1. What Fable says
|
||||
|
||||
The `mcp_app_suggestions` section (L252-302) is 51 lines. It is structurally different from the surrounding sections in that it documents **two specific tools** (`search_mcp_registry`, `suggest_connectors`) and an **audience-specific tag** (`[third_party_mcp_app]`) rather than a behavioral rule for the model.
|
||||
|
||||
### 1.1 The audience model
|
||||
|
||||
L254: "MCP App tools are identified by descriptions that begin with the tag `[third_party_mcp_app]`." The tag is a tool-side marker; the model's job is to recognise the tag and route through a different code path than for first-party tools.
|
||||
|
||||
L255-256: "Claude should use these naturally — the way a helpful person would suggest a tool they noticed sitting right there. Not like a salesperson. Not like a feature announcement." The framing is persona-anchored ("the way a helpful person would") but the actual rule is structural: search the registry first, then `suggest_connectors`, then wait for opt-in.
|
||||
|
||||
### 1.2 The decision tree (the load-bearing rule)
|
||||
|
||||
L259 ("**Connector directory first**"): "The person names a specific connector that isn't already connected ... still search_mcp_registry first. A connector is one click to connect — always better than browsing. Browser only after search comes back without it."
|
||||
|
||||
L262 ("**Don't search for**"): knowledge questions, shopping recommendations, general advice. The model is told *when not to* invoke the registry.
|
||||
|
||||
L265-271 ("**After search**"): the three outcomes. Hit → `suggest_connectors` ("Not optional — answering from general knowledge instead means the person never sees the option"). Miss → navigate (browser). Non-`[third_party_mcp_app]` tool already connected → just use it.
|
||||
|
||||
L272-275 ("**[third_party_mcp_app] tools need opt-in**"): "Tools tagged `[third_party_mcp_app]` are consumer partners (e.g., music streaming, trail guides, restaurant booking, rideshare, food delivery). Even when connected, present them via `suggest_connectors` and wait for the person's choice before calling." The "Urgency is not an exception" sentence (L276) is the most testable rule in the section: "I need a ride in 20 minutes still goes through suggest — the picker takes one tap."
|
||||
|
||||
### 1.3 The exceptions (when to skip search)
|
||||
|
||||
L279-285 ("**When to call an `[third_party_mcp_app]` tool directly**"): three cases where the model skips the registry and calls the tool directly: (1) the user named the connector, (2) the user just chose it via `suggest_connectors`, (3) durable preference (standing instructions). L286: "Outside these, every `[third_party_mcp_app]` tool goes through search → suggest first."
|
||||
|
||||
### 1.4 The two tool descriptions
|
||||
|
||||
**`search_mcp_registry`** (L1201, in the `<tool>` block): the description is ~250 words. It enumerates named-product examples ("'check my Asana tasks' → search ['asana', 'tasks', 'todo']") and intent-based examples ("'help me manage my tasks' → search ['tasks', 'todo', 'project management']"). It also encodes a **scope-amplification rule**: "If the request implies reading the user's data (email, calendar, tasks, files, tickets, etc.) and you don't already have a tool for it, search — even if the phrasing is casual. 'Did I get a reply' is an email check."
|
||||
|
||||
**`suggest_connectors`** (L1232, in the `<tool>` block): the description is ~280 words. The load-bearing rule: "Do NOT call this tool unless you have already called the `search_mcp_registry` tool or are handling a tool auth/credential error." Plus the auth-error case (L1234): "A tool call failed with an auth/credential error — pass the server UUID from the failed tool name `mcp__{uuid}__{toolName}` so the user can re-authenticate." The auth-error case is a re-entry loop: a failed tool can route the user back through `suggest_connectors` to re-authenticate the same connector.
|
||||
|
||||
### 1.5 The anti-patterns (what *not* to do)
|
||||
|
||||
L290: "**Do not use Imagine to generate UI or tools.** Never create mock interfaces, fake tool outputs, or simulated MCP experiences. Only use real, available MCP Apps." (Imagine = the model's ability to generate UI mockups.) L291: "Do not default to `ask_user_input_v0` when MCP Apps are available. Suggest the apps instead." L292: "Do not hold back the answer to create pressure to connect something." L293: "Don't repeat a suggestion the person ignored."
|
||||
|
||||
### 1.6 The 3 patterns to judge
|
||||
|
||||
1. **"Model should know about available connectors and check before browsing"** (L259, L299) — the audit/discovery principle.
|
||||
2. **"`[third_party_mcp_app]` tools need explicit opt-in via `suggest_connectors`** (L272-278) — the consumer-protection gate.
|
||||
3. **The auth-error re-entry loop** (L1234) — failure modes route back through the same UI rather than dumping a raw error.
|
||||
|
||||
---
|
||||
|
||||
## 2. What this project does
|
||||
|
||||
Manual Slop's connector model is **structurally different** from Fable's. The 45 native tools + the External MCP system + the Hook API together implement a different shape: connectors are first-class, audited-at-config-time, and have an explicit safety gate that does not exist in Fable's model.
|
||||
|
||||
### 2.1 The 45 native tools — config-time allowlist, not model-time discovery
|
||||
|
||||
Per `docs/guide_mcp_client.md` (the canonical reference for `src/mcp_client.py`):
|
||||
|
||||
- The tool inventory is **registered at config time** via `configure(file_items, base_dirs)` (L362 of `guide_mcp_client.md`). The allowlist is built from the user's project context, not from a runtime query.
|
||||
- The 3-layer security model (L46-52 of `guide_mcp_client.md`): Layer 1 `configure` builds the allowlist; Layer 2 `_is_allowed` validates every path; Layer 3 `_resolve_and_check` is the resolution gate that catches symlinks, traversal, and whitelist escape.
|
||||
- The 45 tools are organised by category: 4 File I/O, 3 File Edit, 18 Python AST, 10 C/C++ AST, 3 Analysis, 2 Network, 1 Runtime, 4 Beads (per L120-270 of `guide_mcp_client.md` and the parallel inventory in `guide_tools.md:55-150`).
|
||||
|
||||
The model does **not** "discover" these tools at runtime. It is told about them via the capability declaration (`get_tool_schemas()`, per L365 of `guide_mcp_client.md`) and the dispatch is a flat if/elif in `mcp_client.py:dispatch` (L1322 of `guide_tools.md`). This is the **opposite** of Fable's search-then-suggest model: Manual Slop's connector inventory is fixed at config time, audited by the user (the `file_items` are the user's project context), and dispatched by name lookup.
|
||||
|
||||
### 2.2 External MCP servers — opt-in, config-file-driven, with explicit lifecycle
|
||||
|
||||
Per `docs/guide_mcp_client.md:310-380`:
|
||||
|
||||
- `ExternalMCPManager` (L334) orchestrates **multiple concurrent MCP server sessions**. The lifecycle is explicit: `manager.add_server(server_config)`, `manager.start()`, `manager.list_tools()`, `manager.call_tool(name, args)`, `manager.stop_all()`.
|
||||
- Two transport classes: `StdioMCPServer` (local subprocess via stdin/stdout) and `RemoteMCPServer` (SSE for remote servers).
|
||||
- The `mcp_config.json` file (standard MCP format, L380-393) is the source of truth. It is **user-edited at the project or user-config level**. Per the config table, `mcp_config.json` is loaded from `<user_config>/mcp_config.json` or `<project_root>/mcp_config.json`.
|
||||
- JSON-RPC 2.0 over stdio/SSE is the wire protocol (L349-360). The MCP client handles request ID generation, async request/response matching, timeout handling, and JSON-RPC error code mapping.
|
||||
|
||||
The **disclosure model is different from Fable's**: Manual Slop discloses connectors via a **TOML/JSON config file the user curates**. The model is given the schema; the user (not the model) decides what to enable. There is no `search_mcp_registry` step because the registry is *the config file*.
|
||||
|
||||
### 2.3 The Hook API — the audit layer for the native + External MCP systems
|
||||
|
||||
Per `docs/guide_state_lifecycle.md:319-345` and `docs/guide_api_hooks.md`:
|
||||
|
||||
- The Hook API exposes the AppController over HTTP on `127.0.0.1:8999` (`guide_api_hooks.md:9`).
|
||||
- Two registries: `_predefined_callbacks: dict[str, Callable]` (the 11+ named actions the API can invoke) and `_gettable_fields: dict[str, str]` (the 50+ readable state fields).
|
||||
- The `/api/ask` endpoint (`guide_api_hooks.md:48`, `guide_tools.md:312`) implements **synchronous HITL approval** — when the AI wants to run a script, the GUI pops a confirmation dialog; the call blocks until the user responds. This is the **audit gate** for native + External MCP tool calls in the same way that Fable's `suggest_connectors` is the gate for `[third_party_mcp_app]` tools.
|
||||
|
||||
The Hook API + `_pending_gui_tasks` queue (`guide_tools.md:310`) means **every tool call's effect is observable** to the user via the GUI thread trampoline. The audit layer is the standard `ApiHookClient.get_session()` / `get_mma_status()` / `wait_for_event()` polling (`guide_api_hooks.md:355-401`).
|
||||
|
||||
### 2.4 The `_pending_gui_tasks` async-write contract
|
||||
|
||||
Per `docs/guide_tools.md:310-314` and `guide_testing.md`:357-373, asynchronous setters (`mma_state_update`, `rag_*`, `set_value` for `_pending_gui_tasks`-dispatched fields) require **poll-for-state** verification, not single `time.sleep` calls. The setter returns before the GUI render loop processes the task; the test must poll `get_value` with a bounded retry loop.
|
||||
|
||||
This is the **structural analog** of Fable's "End your turn after calling this with a short framing line like 'I found a few options — which would you like?'" (L1234). Both rule sets say: "return; wait for the user's response." Fable's pattern is a *behavioral* rule (the model is told what to say); Manual Slop's pattern is a *data-shape* rule (the setter returns before the dispatch; the consumer must poll).
|
||||
|
||||
### 2.5 The 3-layer security — the structural answer to "should I trust this connector?"
|
||||
|
||||
Per `docs/guide_mcp_client.md:46-52`:
|
||||
|
||||
- **Layer 1 (`configure`)** — the allowlist is built from the user's `file_items` + `base_dirs`. Only paths the user has explicitly added to the project context are eligible.
|
||||
- **Layer 2 (`_is_allowed`)** — every tool call's path is validated against the allowlist *before* execution. Symlinks are disallowed by default (`allow_symlinks = false` in `config.toml`).
|
||||
- **Layer 3 (`_resolve_and_check`)** — the resolution gate catches `..` traversal, symlink resolution to non-allowlisted paths, and edge cases like `mkdir` chains.
|
||||
|
||||
For External MCP, the equivalent is the `mcp_config.json` file: every external server is **declared by the user** with its command/URL, env vars, and any per-server config. The `ExternalMCPManager.add_server(server_config)` step is the config-time gate; runtime tool calls go through the same JSON-RPC engine as native tools, so the Hook API audit layer applies uniformly.
|
||||
|
||||
### 2.6 What the model is told about connectors
|
||||
|
||||
Per `src/models.py:PROVIDERS` and `get_tool_schemas()`, the model receives a **flat schema list** of all 45 native tools + any external tools registered via `manager.get_all_tools()`. There is **no `[third_party_mcp_app]` tag** and **no runtime search step**. The model is told "these are the tools; here are their parameter schemas." The decision tree is **the model's judgment + the Hook API's HITL confirmation**, not the model's search-then-suggest loop.
|
||||
|
||||
---
|
||||
|
||||
## 3. What nagent does
|
||||
|
||||
nagent's MCP-equivalent is **Pattern 4: Tool Discovery** (`--description` self-describing executables), not Fable's connector-search pattern. The two are different shapes for different problems.
|
||||
|
||||
### 3.1 The `--description` pattern
|
||||
|
||||
Per `nagent_review_v2_3_20260612.md:390-426` (§2.4 Pattern 4) and `nagent_takeaways_20260608.md:234-263` (§8):
|
||||
|
||||
- Every executable in `bin/` starts with `exit_on_description(description: str)`: if `--description` is in `sys.argv`, print the description and `SystemExit(0)`.
|
||||
- The main `nagent` loop calls `collect_bin_tool_descriptions(bin_dir)` once at startup: iterates `bin/`, runs each executable with `--description` (10s timeout per), parses stdout, concatenates into a single "Available tools: ..." block in the initial context.
|
||||
- The 9 nagent tools are listed in the README's "Common Commands": `nagent`, `nagent-llm-text`, `nagent-llm-upload`, `nagent-file-edit`, `nagent-file-split`, `nagent-file-patch`, `nagent-file-summarize`, `nagent-gc`. Each is a thin wrapper that calls the library and implements `exit_on_description`.
|
||||
|
||||
The pattern is **declarative**: the tool's *capability description is data on disk* (in the `--description` string), and the runtime aggregates that data into the model's context. **No central registry. No hard-coded if/elif chain.** Drop an executable in `bin/`, implement `exit_on_description`, and the tool is auto-discovered.
|
||||
|
||||
### 3.2 The comparison with Manual Slop
|
||||
|
||||
Per `comparison_table.md:31` (row 12: Tool discovery):
|
||||
|
||||
> **GAP** — nagent's pattern is genuinely better; current dispatch is fine but not extensible
|
||||
> **Domain:** BOTH (especially MT)
|
||||
> **Future-track:** subsumed by `mcp_architecture_refactor_20260606` (sub-MCPs as self-describing modules)
|
||||
|
||||
The verbatim `report.md:505-511` ("Pitfall 6: Hard-coded tool discovery"):
|
||||
|
||||
> The 45 MCP tools in `mcp_client.py:dispatch` are in a flat if/elif chain. nagent's `--description` self-describing executable pattern is more extensible.
|
||||
|
||||
The 4-step manual cost (per `report.md:495-500`): (1) edit `dispatch()` to add a branch, (2) update the security allowlist in `_resolve_and_check` (if filesystem access), (3) update the AI capability declaration in `get_tool_schemas()`, (4) add tests.
|
||||
|
||||
### 3.3 The future-track decision
|
||||
|
||||
Per `decisions.md:144-150` (Candidate 5 in the deferred-rebuild list):
|
||||
|
||||
> **Why it matters.** Manual Slop's 45 MCP tools are dispatched by a flat if/elif in `mcp_client.py:dispatch`. Adding a tool requires edits in 4 places (dispatch, security allowlist, capability declaration, tests). nagent's `--description` self-describing executable pattern is more extensible: drop an executable, it auto-appears.
|
||||
|
||||
And per `nagent_review_v2_3_20260612.md:4814`:
|
||||
|
||||
> `mcp_architecture_refactor_20260606` — The sub-MCP extraction is the right scope for nagent's `--description` self-describing pattern (Candidate 5).
|
||||
|
||||
The pattern is **deferred to a future track**; the user explicitly noted (per `report.md:509-511`) that "The tool use is kinda upfront, I want to add an intent based dsl to help with 'discovery' or combinatorics but no where near that ideation yet."
|
||||
|
||||
### 3.4 What nagent does NOT have
|
||||
|
||||
- **No "suggest before call" gate.** nagent's tools are first-party CLI binaries. There is no `[third_party_mcp_app]` opt-in step.
|
||||
- **No auth-error re-entry loop.** A failed CLI binary returns a non-zero exit code; nagent surfaces the error and continues. There is no `suggest_connectors` re-entry.
|
||||
- **No connector search step.** The "Available tools" block is built once at startup; the model does not search for new tools at runtime.
|
||||
|
||||
nagent's model is **trusted executables** + **config-time aggregation**; Fable's model is **third-party connectors** + **runtime search + opt-in**. Manual Slop is closer to nagent (config-time audit) than to Fable (runtime search).
|
||||
|
||||
---
|
||||
|
||||
## 4. Verdict
|
||||
|
||||
**Useful + over-engineered.** The `mcp_app_suggestions` section has **3 genuinely useful principles** that map cleanly to Manual Slop's existing patterns, but the Fable implementation is **over-engineered for a per-developer tool inventory**: the search-then-suggest two-step, the auth-error re-entry loop, and the `[third_party_mcp_app]` tag system are all justified for a consumer app with hundreds of MCP connectors (Claude.ai) and unjustified for a developer tool with 45 audited first-party tools.
|
||||
|
||||
### 4.1 What is genuinely Useful
|
||||
|
||||
**Pattern 1: "Model should know about available connectors and check before browsing"** (L259, L299). **Useful.** The principle is general: the model should be aware of its tools and prefer them over generic workarounds (browser → navigate; opinion → general knowledge). Manual Slop implements this via `get_tool_schemas()` (the model is told about the 45 native tools + external MCP tools at config time). The principle is sound even though Manual Slop's implementation does not require runtime search because the inventory is fixed.
|
||||
|
||||
**Pattern 2: "Tool calls need an audit/safety gate"** (the implicit principle behind `[third_party_mcp_app]` opt-in and `suggest_connectors`). **Useful.** Manual Slop implements this via the 3-layer security model + the Hook API's `/api/ask` synchronous HITL endpoint. The shapes are different (config-time allowlist + GUI confirmation dialog vs. runtime `suggest_connectors` modal), but the goal — *the user has a final say over what runs* — is the same. The Manual Slop version is **more constrained**: the user curates `file_items` at the project level, and every tool call's path is validated against that allowlist.
|
||||
|
||||
**Pattern 3: "Failure modes should route back through the connector UI rather than dump raw errors"** (the auth-error re-entry loop, L1234). **Useful + already implemented.** Manual Slop's `/api/ask` protocol (`guide_api_hooks.md:261-281`) is the same shape: when an external MCP tool fails with an auth/credential error, the failure surfaces in the GUI as a re-auth prompt; the user responds via `/api/ask/respond` and the call unblocks. The shapes are different (Fable: `suggest_connectors` re-entry; Manual Slop: `/api/ask` dialog), but the principle is the same.
|
||||
|
||||
### 4.2 What is over-engineered
|
||||
|
||||
**The two-step search → suggest dance.** The `search_mcp_registry` → `suggest_connectors` two-step is justified for Claude.ai's hundreds of connectors (where the model does not know in advance what is connected), but **unjustified for a per-developer tool inventory** that is fixed at config time. The 45 native tools are documented in `guide_mcp_client.md`; the external MCP config is in `mcp_config.json`; the model is told about all of them via `get_tool_schemas()`. There is no registry to search.
|
||||
|
||||
**The `[third_party_mcp_app]` tag.** This tag-based routing is a workaround for the **lack of config-time audit**: in Claude.ai, the model cannot trust a tool's provenance because the registry is dynamic and user-curated at session time. In Manual Slop, every tool's provenance is known: native tools are first-party code; external MCP tools are declared in `mcp_config.json` with explicit `name`, `command`/`url`, `env`. The Hook API audit layer applies uniformly.
|
||||
|
||||
**The `Imagine` anti-pattern (L290).** The "Do not use Imagine to generate UI or tools" rule is a Claude.ai-specific concern: the model has a UI-generation mode that can produce mock tool outputs, and the `mcp_app_suggestions` section tells it not to. Manual Slop has no analog — the model does not have UI-generation capability.
|
||||
|
||||
### 4.3 What is persona performance
|
||||
|
||||
**"The way a helpful person would suggest a tool they noticed sitting right there. Not like a salesperson."** (L255-256) The framing is persona-anchored. The actual rule (search before browsing; present options; wait for opt-in) is structural and does not require the persona framing.
|
||||
|
||||
**"A connector is one click to connect — always better than browsing."** (L259) The reasoning is correct; the framing ("always better") is overconfident. For some tasks (e.g., "check the weather for tomorrow"), the browser is faster than the connector setup.
|
||||
|
||||
### 4.4 The nagent pattern comparison
|
||||
|
||||
nagent's `--description` self-describing executable pattern is the **structural alternative** to Fable's search-then-suggest model. nagent trusts the tools (they are first-party executables) and aggregates their capabilities at startup. Manual Slop is closer to nagent (trusted first-party + config-time declaration) than to Fable (runtime search + opt-in). The deferred-rebuild `mcp_architecture_refactor_20260606` is the natural scope for porting nagent's pattern.
|
||||
|
||||
### 4.5 The structural verdict
|
||||
|
||||
**Manual Slop does NOT need `mcp_app_suggestions`.** The project's connector model — 45 first-party tools + ExternalMCPManager + 3-layer security + Hook API audit — is **already more constrained and more auditable** than Fable's model. The user has a final say at config time (`file_items`, `mcp_config.json`) and at runtime (`/api/ask` confirmation dialog). The model's job is to know the tools it has and use them appropriately, not to discover new tools at runtime.
|
||||
|
||||
**The one Fable principle worth porting:** the "model should prefer its known tools over generic workarounds" framing (L299 — "Claude should check its available MCPs before reaching for the browser"). This is already true in Manual Slop; the synthesis report should surface it as a behavioral rule for the Tier 3 worker's prompt: "If a native MCP tool or registered External MCP tool can do the job, use it; do not fall back to `fetch_url` or shell-out unless the user explicitly asks."
|
||||
|
||||
**The deferred-rebuild candidate:** nagent's `--description` pattern (via `mcp_architecture_refactor_20260606`) is a *different* future-track than `mcp_app_suggestions` — it is about **declarative tool discovery** (drop an executable in `bin/`, it auto-appears), not about **runtime connector search**. The two should not be conflated.
|
||||
|
||||
---
|
||||
|
||||
## 5. Synthesis notes for the Tier 1 writer
|
||||
|
||||
This cluster feeds `report.md` §12 ("Fable's MCP App Suggestions") directly. Cross-references to §13 ("Genuinely Useful") and §15 ("Persona Performance").
|
||||
|
||||
### 5.1 Key claims to surface in §12
|
||||
|
||||
1. **The principle "model should prefer known tools over generic workarounds" is Useful.** Fable L259, L299. Maps to Manual Slop's `get_tool_schemas()` capability declaration. The Tier 3 worker prompt should encode: "If a native MCP tool or registered External MCP tool can do the job, use it."
|
||||
|
||||
2. **The principle "failure modes should route back through the connector UI" is Useful.** Fable L1234 (the auth-error re-entry loop). Maps to Manual Slop's `/api/ask` protocol (`guide_api_hooks.md:261-281`). Both shapes say: when a tool fails with an auth/credential error, surface it to the user via the GUI confirmation dialog; do not dump raw errors.
|
||||
|
||||
3. **The principle "third-party tools need an opt-in gate" is Useful in spirit but over-engineered for Manual Slop.** Fable's `[third_party_mcp_app]` + `suggest_connectors` is justified for Claude.ai's runtime registry; Manual Slop's `mcp_config.json` is a config-time audit. The user curates the registry; the model is given the schema; the Hook API enforces runtime confirmation.
|
||||
|
||||
4. **The nagent `--description` pattern is the structural alternative.** Per `nagent_review_v2_3_20260612.md:390-426` (§2.4 Pattern 4), `comparison_table.md:31` (row 12: GAP), `decisions.md:144-150` (Candidate 5). The pattern is deferred to `mcp_architecture_refactor_20260606`.
|
||||
|
||||
5. **The persona framing ("the way a helpful person would suggest a tool", "Not like a salesperson") is Persona Performance.** Cite Fable L255-256; the actual rule is structural and does not need the persona.
|
||||
|
||||
### 5.2 Quotes to use in §12
|
||||
|
||||
- Fable L254: "MCP App tools are identified by descriptions that begin with the tag `[third_party_mcp_app]`." (≤15 words)
|
||||
- Fable L259: "A connector is one click to connect — always better than browsing." (≤15 words)
|
||||
- Fable L266: "Hit → call suggest_connectors. Not optional — answering from general knowledge instead means the person never sees the option." (≤15 words)
|
||||
- Fable L276: "Urgency is not an exception. 'I need a ride in 20 minutes' still goes through suggest." (paraphrase; the full quote exceeds 15 words)
|
||||
- Fable L290: "**Do not use Imagine to generate UI or tools.** Never create mock interfaces, fake tool outputs, or simulated MCP experiences." (paraphrase)
|
||||
- Fable L299: "Claude should check its available MCPs before reaching for the browser." (≤15 words)
|
||||
- Fable L1201 (search_mcp_registry): "If the request implies reading the user's data ... and you don't already have a tool for it, search — even if the phrasing is casual." (paraphrase)
|
||||
- Fable L1234 (suggest_connectors): "Do NOT call this tool unless you have already called the search_mcp_registry tool or are handling a tool auth/credential error." (≤15 words)
|
||||
- `guide_mcp_client.md:46-52` (the 3-layer security): "Layer 1 Allowlist Construction (`configure`) / Layer 2 Path Validation (`_is_allowed`) / Layer 3 Resolution Gate (`_resolve_and_check`)"
|
||||
- `guide_mcp_client.md:362` (Public API): "configure(file_items, base_dirs)" — the allowlist is built from the user's project context.
|
||||
- `guide_api_hooks.md:9`: "The Hook API is the bridge between external automation and the running app."
|
||||
- `guide_api_hooks.md:48`: "The `/api/ask` endpoint is special — it implements the Remote Confirmation Protocol for HITL approvals."
|
||||
- `nagent_review_v2_3_20260612.md:390-426` (§2.4 Pattern 4): the full Tool Discovery pattern with `exit_on_description` + `collect_bin_tool_descriptions`.
|
||||
- `nagent_takeaways_20260608.md:234-263` (§8): "Self-describing tools — let the tool tell the agent what it does."
|
||||
- `comparison_table.md:31` (row 12): "GAP — nagent's pattern is genuinely better; current dispatch is fine but not extensible. BOTH (especially MT). Future-track: subsumed by `mcp_architecture_refactor_20260606`."
|
||||
|
||||
### 5.3 The §13 / §14 / §15 cross-references
|
||||
|
||||
- **§13 ("Genuinely Useful Patterns").** Fable's "model should prefer known tools" principle (L259, L299) is useful and Manual Slop already implements it via `get_tool_schemas()` + the 3-layer security. Cite `guide_mcp_client.md:362`. The nagent `--description` pattern is a deferred candidate via `mcp_architecture_refactor_20260606`.
|
||||
- **§14 ("Anti-User Watchdog Patterns").** None in this cluster. Fable's `mcp_app_suggestions` is over-engineered but not anti-user; the `[third_party_mcp_app]` opt-in is consumer-protection, not watch-dogging.
|
||||
- **§15 ("Persona Performance Patterns").** Fable's "the way a helpful person would suggest a tool" / "Not like a salesperson" framing (L255-256) is persona. Cite Fable L255-256; reject explicitly in the rebuild.
|
||||
|
||||
### 5.4 The non-obvious connection to the Hook API
|
||||
|
||||
Fable's `suggest_connectors` and Manual Slop's `/api/ask` are **the same shape**: a synchronous, GUI-side confirmation that blocks until the user responds. Fable's version is model-facing (`End your turn after calling this with a short framing line`); Manual Slop's version is process-facing (`POST /api/ask` blocks the call until `/api/ask/respond` is called). Both surface a modal in the GUI; both require the user's explicit choice; both are the audit gate for tool calls that touch user data.
|
||||
|
||||
The synthesis report should surface this parallel in §12: **the "connector opt-in" pattern is a structural principle with two implementations — Fable's model-facing and Manual Slop's process-facing — both achieving the same goal of user-controlled audit.** Manual Slop's implementation is **more constrained** because the user can also pre-audit the connector inventory via `mcp_config.json` and the 3-layer security allowlist.
|
||||
|
||||
### 5.5 What the §12 verdict should be
|
||||
|
||||
**Verdict: Useful + over-engineered.** The 3 useful principles (model should prefer known tools; failure modes route through the UI; third-party tools need opt-in) all map to existing Manual Slop patterns, but the Fable implementation is over-engineered for a per-developer tool inventory. The persona framing is persona performance and should be rejected. The nagent `--description` pattern is the deferred-rebuild alternative via `mcp_architecture_refactor_20260606`.
|
||||
|
||||
**The recommended Manual Slop action:** keep the existing 45-tool + ExternalMCPManager + 3-layer security + Hook API model as-is. Do NOT import Fable's `search_mcp_registry` / `suggest_connectors` two-step. Do add a Tier 3 worker prompt rule: "If a native MCP tool or registered External MCP tool can do the job, use it." Defer the `--description` self-describing pattern to `mcp_architecture_refactor_20260606`.
|
||||
|
||||
---
|
||||
|
||||
**Sub-report complete.** This is the evidence base for §12 of `report.md`.
|
||||
Reference in New Issue
Block a user