|
2 | 2 |
|
3 | 3 | | | | |
4 | 4 | |---|---| |
5 | | -| **Status** | Draft | |
| 5 | +| **Status** | Implemented in v0.1.0 — see [Implementation notes](#16-implementation-notes) | |
6 | 6 | | **Author** | guangfei.me@gmail.com | |
7 | 7 | | **Created** | 2026-08-22 | |
8 | 8 | | **Repository** | `deckflow/deckprobe-mcp-server` (standalone; engine consumed from npm) | |
@@ -223,9 +223,9 @@ name: |
223 | 223 |
|
224 | 224 | - `list_formats` — no arguments → `deckprobe formats` (drivers, profiles, |
225 | 225 | support boundaries). |
226 | | -- `list_targets` — `{ format: z.string() }` → `deckprobe targets --format |
227 | | - <fmt>` (ids, aliases, value types, selector membership, `min_level`, cost |
228 | | - class, selector expansions). |
| 226 | +- `list_targets` — `{ format: z.string(), detail?: "compact" | "full" }` → |
| 227 | + `deckprobe targets --format <fmt>` (ids, aliases, value types, selector |
| 228 | + membership, `min_level`, cost class, selector expansions). |
229 | 229 |
|
230 | 230 | Discovery output is static per engine binary, so results are **cached |
231 | 231 | in-process** keyed by the resolved engine version; the first call per session |
@@ -447,12 +447,47 @@ teach the same vocabulary). |
447 | 447 | - **Exposing `--strict`**: meaningless over MCP; exit codes are not the |
448 | 448 | signaling channel, `execution.unresolved_targets` is. |
449 | 449 |
|
450 | | -## 15. Open questions |
451 | | - |
452 | | -1. Package name/scope confirmation: `@deckflow/deckprobe-mcp` vs. |
453 | | - `@deckflow/mcp-server`. This RFC assumes the former (searchable, |
454 | | - convention-matching). |
455 | | -2. Should `probe_batch` accept glob patterns server-side, or stay |
456 | | - literal-paths-only (current proposal) and let the agent expand globs? |
457 | | -3. Default for `DECKPROBE_MCP_ROOTS` in *registry-listed hosted* contexts — |
458 | | - revisit when the HTTP transport lands. |
| 450 | +## 15. Resolved questions |
| 451 | + |
| 452 | +1. **Package name** — confirmed as `@deckflow/deckprobe-mcp`, bin |
| 453 | + `deckprobe-mcp`, registry name `io.github.deckflow/deckprobe`. |
| 454 | +2. **Globs in `probe_batch`** — not accepted. Literal paths only; the agent |
| 455 | + expands globs, which keeps the server free of a second path grammar and of |
| 456 | + filesystem traversal it would then have to bound. |
| 457 | +3. **`DECKPROBE_MCP_ROOTS` in hosted contexts** — still open, and deferred with |
| 458 | + the HTTP transport it belongs to. The variable exists and is enforced; only |
| 459 | + its default in a hosted deployment is undecided. |
| 460 | + |
| 461 | +## 16. Implementation notes |
| 462 | + |
| 463 | +Where v0.1.0 departs from the proposal above, and why. |
| 464 | + |
| 465 | +- **`list_targets` returns a compact catalogue by default.** The full engine |
| 466 | + report is roughly 22 KB per format — about 6k tokens — most of it per-target |
| 467 | + JSON Schema fragments and fully expanded selector member lists that an agent |
| 468 | + choosing a target never reads. The compact projection keeps every field |
| 469 | + needed to name a target correctly at roughly a third of the size, and |
| 470 | + `detail: "full"` returns the engine report verbatim. This is the one place |
| 471 | + besides the batch wrapper where output is reshaped, and it is opt-out. |
| 472 | +- **Each `probe_batch` entry carries its requested `path`.** The engine's error |
| 473 | + envelope has no `input` field, so a failed record is otherwise |
| 474 | + indistinguishable from any other and correlation would rest on array position |
| 475 | + alone. Entries are `{ path, report }` with the report verbatim. |
| 476 | +- **Text blocks are indented only below 8 KB.** Indenting a long batch or a |
| 477 | + full target catalogue roughly doubles it for no gain, and `structuredContent` |
| 478 | + carries the same value for anything parsing it. |
| 479 | +- **Errors are keyed on `error.code`, not the exit status.** Status 4 covers |
| 480 | + both `MALFORMED_INPUT` and `BUDGET_EXCEEDED`, which call for opposite |
| 481 | + responses; the exit status is only the fallback. |
| 482 | +- **Pre-engine rejections inside a batch stay per-file.** A missing path or one |
| 483 | + outside the allow-list becomes an error envelope in its own entry rather than |
| 484 | + failing the call, matching how the engine's JSONL mode treats a bad record. |
| 485 | +- **The WebAssembly fallback derives the values view itself.** The SDK has no |
| 486 | + `--view` equivalent and always resolves the full report. The projection is |
| 487 | + asserted equal to the CLI's own values envelope in `engine.test.ts`, so the |
| 488 | + two paths cannot drift silently. |
| 489 | +- **`outputSchema` is declared and deliberately permissive.** The SDK skips |
| 490 | + output validation on `isError` results and does not strip fields from |
| 491 | + `structuredContent`, so a loose envelope schema documents the shape without |
| 492 | + ever rejecting a valid report. The authoritative contract remains the |
| 493 | + `deckprobe://schema` resource. |
0 commit comments