Skip to content

Commit 211ff03

Browse files
Garfield-yinclaude
andcommitted
Record the implementation notes in the RFC
Marks the RFC implemented and documents where v0.1.0 departed from it: the compact list_targets default, the per-entry path in probe_batch, the indent threshold, error keying on error.code rather than exit status, and the permissive outputSchema. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
1 parent 6275379 commit 211ff03

1 file changed

Lines changed: 48 additions & 13 deletions

File tree

docs/rfc.md

Lines changed: 48 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
| | |
44
|---|---|
5-
| **Status** | Draft |
5+
| **Status** | Implemented in v0.1.0 — see [Implementation notes](#16-implementation-notes) |
66
| **Author** | guangfei.me@gmail.com |
77
| **Created** | 2026-08-22 |
88
| **Repository** | `deckflow/deckprobe-mcp-server` (standalone; engine consumed from npm) |
@@ -223,9 +223,9 @@ name:
223223

224224
- `list_formats` — no arguments → `deckprobe formats` (drivers, profiles,
225225
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).
229229

230230
Discovery output is static per engine binary, so results are **cached
231231
in-process** keyed by the resolved engine version; the first call per session
@@ -447,12 +447,47 @@ teach the same vocabulary).
447447
- **Exposing `--strict`**: meaningless over MCP; exit codes are not the
448448
signaling channel, `execution.unresolved_targets` is.
449449

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

Comments
 (0)