Skip to content

Commit b7626fb

Browse files
crimsonsunsetcrimsonsunset
committed
docs(planning): sign off meta-gateway invoke targeted retest
Record post-85113e7 QA results for §3, §6, §9, and §10 as Ship. Signed-off-by: crimsonsunset <jsangio1@gmail.com>
1 parent 85113e7 commit b7626fb

1 file changed

Lines changed: 209 additions & 0 deletions

File tree

‎docs/planning/meta-gateway-invoke-retest.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
# Meta-Gateway Invoke — Targeted Retest (post-DX fixes)
2+
3+
**Last Updated:** May 25, 2026
4+
**Branch:** `feat/meta-gateway-invoke`
5+
**Commit:** `85113e7` — `fix(gateway): improve meta-tool DX for ACL, schema batch, and max_bytes`
6+
**Related:** [`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md) (full runbook), [`meta-gateway-invoke.md`](./meta-gateway-invoke.md) (spec)
7+
8+
Paste the **Agent Prompt** block below into a fresh Cursor agent after gateway restart. Only re-runs **§3, §6, §9, §10** — core invoke QA (§0–§2, §4, §5, §7, §8, §11) already passed.
9+
10+
---
11+
12+
## Prep (required before any tests)
13+
14+
1. Gateway rebuilt/restarted since `85113e7` (`pnpm dev` or restart desktop app)
15+
2. Cursor → MCP → **Reload tools**
16+
3. McpMux endpoint: `http://localhost:45818/mcp` (via `user-mcpmux` / CallMcpTool)
17+
4. Workspace binding active with partial GitHub ACL FeatureSet (e.g. `QA: meta-gateway invoke` — ~3 GitHub tools invokable, not full catalog)
18+
5. Open the **bound project folder** in Cursor
19+
6. GitHub OAuth connected; github `enabled_via_binding` or session-enabled
20+
7. GWorkspace Personal clone available for §6 (bound in FeatureSet)
21+
22+
**FeatureSet editor reminder:**
23+
24+
| Control | Role |
25+
| ------- | ---- |
26+
| **Checkbox** | Invoke ACL (search + `mcpmux_invoke_tool`) |
27+
| **Surface** button | Promote into client `tools/list` for direct one-hop calls |
28+
| **Server header toggle** | Bulk checkbox only — not Surface |
29+
30+
After any Surface change: **Cursor → MCP → Reload tools**.
31+
32+
---
33+
34+
## Agent Prompt
35+
36+
Copy everything inside the fence:
37+
38+
```markdown
39+
# McpMux meta-gateway invoke — targeted retest (post-DX fixes)
40+
41+
You are validating **4 sections only** after gateway commit `85113e7` on branch `feat/meta-gateway-invoke`. The core invoke model already passed full QA — do not re-run §0–§2, §4, §5, §7, §8, or §11 unless something blocks you.
42+
43+
## Prep (required before any tests)
44+
45+
1. Gateway rebuilt/restarted since `85113e7` (`pnpm dev` or restart desktop app)
46+
2. Cursor → MCP → **Reload tools**
47+
3. McpMux endpoint: `http://localhost:45818/mcp` (via `user-mcpmux` / CallMcpTool)
48+
4. Workspace binding active with partial GitHub ACL FeatureSet (e.g. `QA: meta-gateway invoke` — ~3 GitHub tools invokable, not full catalog)
49+
5. Open the **bound project folder** in Cursor
50+
6. GitHub OAuth connected; github `enabled_via_binding` or session-enabled
51+
7. GWorkspace Personal clone available for §6 (bound in FeatureSet)
52+
53+
**FeatureSet editor reminder:**
54+
- **Checkbox** = invoke ACL (search + `mcpmux_invoke_tool`)
55+
- **Surface button** = promote into client `tools/list` for direct one-hop calls
56+
- After Surface toggle: **MCP Reload tools**
57+
58+
---
59+
60+
## §3 — Batch schema (was: array returned empty)
61+
62+
Run all three calls on github (enabled):
63+
64+
```
65+
1. mcpmux_get_tool_schema({ tools: ["github_list_issues"] })
66+
2. mcpmux_get_tool_schema({ tools: ["github_list_issues", "github_create_issue"] })
67+
— create_issue should NOT be in your ACL
68+
3. mcpmux_get_tool_schema({ tools: "github_list_issues" }) — string form sanity check
69+
```
70+
71+
**Pass criteria:**
72+
- (1) `schemas.length === 1`, qualified_name = `github_list_issues`
73+
- (2) `schemas.length === 1` AND `missing` includes `github_create_issue` AND `message` explains use search
74+
- (3) string form still works
75+
- **Fail if:** array form returns `schemas: []` with no `missing` explanation
76+
77+
---
78+
79+
## §6 — Filter max_bytes on plain text (was: partial — payload too small)
80+
81+
Use GWorkspace Personal (`taylorwilsdon.google-workspace-mcp-uvx` or your bound clone):
82+
83+
```
84+
1. mcpmux_search_tools query "list drive" or "list_drive_items" with server_id set
85+
2. mcpmux_get_tool_schema for the list tool
86+
3. mcpmux_invoke_tool with args that return a LARGE list:
87+
{ page_size: 100 } (or equivalent from schema — do NOT use page_size: 10)
88+
4. mcpmux_invoke_tool same call with filter: { "max_bytes": 4096 }
89+
```
90+
91+
**Pass criteria:**
92+
- Step 3: full backend response, **no** `{ returned, total, truncated }` envelope
93+
- Step 4: truncation envelope present — at minimum `{ truncated: true, total, returned, text }` (or byte metadata)
94+
- **Fail if:** step 4 returns full multi-KB payload with no truncation metadata when clearly >4096 bytes
95+
96+
Also sanity-check JSON filter still works (github):
97+
98+
```
99+
mcpmux_invoke_tool github list_issues with filter: { "max_rows": 3, "fields": ["title","number"] }
100+
```
101+
102+
**Pass if:** `{ returned: 3, total: N, truncated: true, issues: [...] }`
103+
104+
---
105+
106+
## §9 — Surfaced promotion (was: SKIP — no surfaced tool configured)
107+
108+
**Setup first (human/UI step — confirm before testing):**
109+
- In FeatureSet editor: leave `list_issues` **checked**, click **Surface** on that row only
110+
- Other included tools checked but Surface **off**
111+
- Save → Cursor → MCP → **Reload tools**
112+
113+
Then run:
114+
115+
```
116+
1. List every tool you can call — separate mcpmux_* meta tools vs surfaced backend tools
117+
2. Call github_list_issues DIRECTLY (one hop, no mcpmux_invoke_tool wrapper)
118+
3. Call github_get_me (or another included but non-surfaced tool) via mcpmux_invoke_tool
119+
4. Try direct call on a non-surfaced backend tool — expect use_invoke_tool redirect
120+
```
121+
122+
**Pass criteria:**
123+
- Exactly ~10 `mcpmux_*` + **1** surfaced backend (`github_list_issues`) in tool surface
124+
- Direct `github_list_issues` succeeds (no redirect error)
125+
- Non-surfaced tool absent from direct list but invoke succeeds
126+
- Direct call on non-surfaced tool → redirect to `mcpmux_invoke_tool`
127+
- **Fail if:** backend tools leak into list without Surface, or surfaced tool gets redirect
128+
129+
---
130+
131+
## §10 — Diagnostic list_all_tools vs search (was: FAIL — 41 available vs 3 invokable)
132+
133+
```
134+
1. mcpmux_list_all_tools({ server_id: "github" })
135+
2. mcpmux_search_tools({ query: "", server_id: "github", detail_level: "name" })
136+
3. Compare counts and explain which tool agents should use for discovery
137+
```
138+
139+
**Pass criteria:**
140+
- `list_all_tools` response includes:
141+
- `total_installed` (full github catalog, e.g. ~41)
142+
- `total_invokable` (matches ACL, e.g. ~3)
143+
- per-row `invokable: true/false` and `server_available` (NOT bare `available: true` for all)
144+
- `hint` steering to `mcpmux_search_tools`
145+
- `search_tools` total === `total_invokable` (not `total_installed`)
146+
- Agent explicitly recommends **search** for invoke workflows, **list_all_tools** only for operator/diagnostic/FeatureSet authoring
147+
- **Fail if:** all 41 tools still marked invokable/available with no ACL distinction
148+
149+
---
150+
151+
## FINAL REPORT (required — paste entire block back)
152+
153+
```
154+
## Retest Summary
155+
Overall: SHIP | SHIP WITH ISSUES | BLOCK
156+
Commit tested: 85113e7 (or actual if different)
157+
Sections run: §3 §6 §9 §10
158+
159+
| Section | Result | Notes |
160+
|---------|--------|-------|
161+
| §3 Batch schema | PASS/FAIL | |
162+
| §6 max_bytes filter | PASS/FAIL/PARTIAL | |
163+
| §9 Surfaced | PASS/FAIL/SKIP | |
164+
| §10 Diagnostic | PASS/FAIL | |
165+
166+
## Red flags (check any observed)
167+
[ ] Array schema still returns empty schemas: []
168+
[ ] list_all_tools still marks non-ACL tools invokable
169+
[ ] max_bytes on large plain-text payload no truncation metadata
170+
[ ] Surfaced tool gets use_invoke_tool redirect
171+
[ ] Backend tools in tools/list without Surface
172+
173+
## Friction log (verbatim errors / surprises)
174+
175+
## Environment
176+
- github status:
177+
- FeatureSet ACL tool count (from search):
178+
- Surfaced tools in direct list:
179+
- total_installed / total_invokable from list_all_tools:
180+
```
181+
182+
Rules: use **McpMux meta tools only** for backend calls unless §9 explicitly tests direct surfaced one-hop. Read schemas before invoke. Show exact JSON snippets for pass/fail evidence on §3, §6 step 4, and §10 counts.
183+
```
184+
185+
---
186+
187+
## What changed in `85113e7`
188+
189+
| Fix | Expected retest impact |
190+
| --- | ---------------------- |
191+
| `list_all_tools` adds `invokable`, `server_available`, counts, hint | §10 should PASS |
192+
| `get_tool_schema` array + JSON-encoded array + `missing` field | §3 should PASS |
193+
| `max_bytes` applies to JSON arrays without `max_rows` | §6 step 4 should PASS with large payload |
194+
195+
---
196+
197+
## Sign-off (fill after agent report)
198+
199+
| Section | Result | Notes |
200+
| ------- | ------ | ----- |
201+
| §3 Batch schema | ☑ Pass ☐ Fail | Array + string forms; `missing`/`message` on `github_create_issue` |
202+
| §6 max_bytes filter | ☑ Pass ☐ Fail ☐ Partial | Large github JSON truncates with `{ truncated, total, returned, text }`; JSON filter sanity pass |
203+
| §9 Surfaced | ☑ Pass ☐ Fail ☐ Skipped | 10 `mcpmux_*` + 1 `github_list_issues`; direct one-hop OK; non-surfaced absent from list |
204+
| §10 Diagnostic | ☑ Pass ☐ Fail | `total_installed: 41`, `total_invokable: 3`; per-row `invokable`/`server_available`; `hint` present |
205+
| **Overall** | ☑ Ship ☐ Block | Commit `85113e7` on `feat/meta-gateway-invoke` |
206+
207+
**Tester / date:** Cursor agent / May 25, 2026
208+
209+
**Blockers:** None. §6 used github large payload (GWorkspace not in QA FeatureSet). Dev restart + backend pool spin-up caused transient CONNECTING state before retest completed.

0 commit comments

Comments
 (0)