feat: Skills extension phase 3 — CLI, TUI, directory reads, frontmatter check
Closes #2248. Completes SEP-2640 support across all three clients, and closes the one obligation #2234 deliberately left open. - `checkSkillFrontmatterMatch` compares a served SKILL.md's own YAML frontmatter against the entry the listing advertised, field by field. No digest can cover this: a digest is taken over the bytes the server served, so it proves the file was not altered in transit and says nothing about whether the listing described it honestly. Needs a real YAML parser; `yaml` was already a root dependency, so this adds no package — but it does newly put it on core/'s import graph, hence the three bundler `external` lists. - `resources/directory/read`: result schemas defined against the normative text, `InspectorClient.readResourceDirectory`, a Directory section on the Skills screen, and `--method resources/directory/read` in the CLI. The client refuses the call locally when the server did not declare `directoryRead`, which is the SEP's MUST NOT. A child the directory lists but the entry does not is marked `not listed` rather than merged into the manifest — the SEP calls a directory result a live observation and forbids treating it as extending the manifest. - CLI: `skills/list`, `skills/get` and `resources/directory/read`, plus `--verify` — one NDJSON report per skill, a summary on stderr, exit 7 on a violation. Reads are sequential; a conforming manifest may declare 512 entries. - TUI: a Skills pane, shown only when the server declares the extension. Each row carries its conformance verdict as a glyph as well as a colour, since the pane is read over ssh and through script(1). Enter verifies. - `verifySkills` re-throws `AuthRecoveryRequiredError` rather than recording it per file: it says the session's authorization expired, so absorbing it would report N identical read failures and swallow the error the TUI and the web commands key off to reauthorize. Two open questions settled, both in code comments where they will be found: `skills/get` carries no caching attributes because SEP-2640 leaves the question open in as many words, so requiring them would fail a conforming server; and there is no `PagedSkillsState` because every consumer of this list is a whole-catalog verdict — computed over page one of three, "this server's skills conform" is not merely partial but wrong. The fixture grows two skills, both for checks that were otherwise undemonstrable: `lying-listing` (listing and file disagree, digest still verifies) and `stale-manifest` (serves a file its manifest does not declare). Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01ND46Ci64DC3tzBy9aG81Nc Signed-off-by: cliffhall <cliff@futurescale.com>
This commit is contained in:
parent
219a08e1b5
commit
9a8488681e
1 changed files with 4750 additions and 191 deletions
|
|
@ -29,6 +29,7 @@
|
|||
*/
|
||||
|
||||
import { z } from "zod/v4";
|
||||
import { ResourceSchema } from "@modelcontextprotocol/core";
|
||||
|
||||
/** SEP-2133 extension identifier for the Skills extension (SEP-2640). */
|
||||
export const SKILLS_EXTENSION_KEY = "io.modelcontextprotocol/skills";
|
||||
|
|
@ -143,6 +144,22 @@ export const ModernListSkillsResultSchema = ListSkillsResultSchema.extend({
|
|||
/**
|
||||
* The `skills/get` result envelope: the entry wrapped under `skill`.
|
||||
*
|
||||
* ⚠️ **Not era-aware, and that is settled rather than pending (#2248).** The
|
||||
* obvious symmetry would be a modern variant requiring the caching attributes
|
||||
* the way {@link ModernListSkillsResultSchema} does. SEP-2640 forecloses it in
|
||||
* as many words, under `skills/get`: *"whether the result should also carry the
|
||||
* base protocol's caching attributes (`ttlMs` and `cacheScope`, per SEP-2549),
|
||||
* as `resources/read` results do, is **left open**"*.
|
||||
*
|
||||
* So there is no requirement to enforce, and inventing one would do real harm
|
||||
* rather than none: a server that reasonably reads "left open" as "not
|
||||
* required" would be reported as non-conforming by the tool whose job is to
|
||||
* tell it whether it conforms. `looseObject` means a server that *does* send
|
||||
* them still parses, which is the right handling for an attribute the spec
|
||||
* permits and does not mandate. Revisit only if a later revision closes the
|
||||
* question — and note that the same sentence is why `skills/get` carries no
|
||||
* `nextCursor` handling either: "a single entry is not a list".
|
||||
*
|
||||
* Required, not one of two accepted shapes. An earlier revision of this module
|
||||
* also accepted a bare entry at the top level, on the reading that the SEP
|
||||
* settled the entry but not its wrapper. It does settle the wrapper, and
|
||||
|
|
@ -165,13 +182,70 @@ export const GetSkillResultSchema = GetSkillEnvelopeSchema.transform(
|
|||
export type GetSkillResult = SkillEntry;
|
||||
|
||||
/**
|
||||
* ⚠️ **No `resources/directory/read` result schema here yet, on purpose.**
|
||||
* One `resources/directory/read` child: **the SDK's own `Resource`**, not a
|
||||
* shape restated here.
|
||||
*
|
||||
* The method name and the directory MIME type above are stated in SEP-2640;
|
||||
* the shape of the result it returns is not something this PR verified against
|
||||
* the normative text, and the Inspector does not call the method (phase 3,
|
||||
* #2248). Declaring a guessed schema would put an unverified claim in the one
|
||||
* module that is supposed to be the authority on the wire format — and one
|
||||
* nothing exercises, so it could be wrong indefinitely without failing
|
||||
* anything. Phase 3 adds it against the spec, alongside the call that uses it.
|
||||
* SEP-2640 defines the result as carrying "the same `Resource` objects that
|
||||
* `resources/list` returns, with the same `nextCursor` pagination contract", so
|
||||
* the schema that already decodes `resources/list` in this app is the literal
|
||||
* statement of that sentence — and one the SDK, not this module, keeps current.
|
||||
* Restating it would let the two drift, at which point a directory child and a
|
||||
* listed resource could disagree about what a `Resource` is while both claimed
|
||||
* to be one.
|
||||
*
|
||||
* ⚠️ It is **stricter than everything else in this module**, and that is the
|
||||
* deliberate exception rather than an oversight. `ResourceSchema` requires
|
||||
* `name` and strips unknown members, so one child missing `name` rejects the
|
||||
* whole page instead of being reported as a per-child finding — the opposite of
|
||||
* the posture the entry schemas above take. The reason the trade goes the other
|
||||
* way here is ownership: the skills entry types are consumer-owned and nothing
|
||||
* else validates them, so this module has to be the reporter; `Resource` is
|
||||
* base-protocol and already validated exactly this strictly on the
|
||||
* `resources/list` path, where {@link listSalvage} is the answer to a single bad
|
||||
* entry. Being *more* permissive here would mean a URI that fails as a listed
|
||||
* resource succeeds as a directory child, which is a worse inconsistency than
|
||||
* an all-or-nothing page.
|
||||
*/
|
||||
export const DirectoryChildSchema = ResourceSchema;
|
||||
|
||||
/**
|
||||
* `resources/directory/read` result on a **legacy** connection: the directory's
|
||||
* direct children plus the opaque cursor.
|
||||
*
|
||||
* `looseObject`, matching every other result schema here: a server that also
|
||||
* sends the caching attributes is not wrong for doing so, and a schema is not
|
||||
* the place to reject an extra member.
|
||||
*/
|
||||
export const DirectoryReadResultSchema = z.looseObject({
|
||||
resources: z.array(DirectoryChildSchema),
|
||||
nextCursor: z.string().optional(),
|
||||
});
|
||||
|
||||
export type DirectoryReadResult = z.infer<typeof DirectoryReadResultSchema>;
|
||||
|
||||
/**
|
||||
* `resources/directory/read` result on a **modern** (2026-07-28+) connection:
|
||||
* the page plus `resultType`, and deliberately **not** `ttlMs` / `cacheScope`.
|
||||
*
|
||||
* That asymmetry with {@link ModernListSkillsResultSchema} is the one judgement
|
||||
* call in this module, so it is written down rather than left to be re-derived:
|
||||
*
|
||||
* - For `skills/list` the SEP states the requirement outright — *"In protocol
|
||||
* versions 2026-07-28 and later, the result also carries … `ttlMs` and
|
||||
* `cacheScope`"* — so requiring them is quoting the spec.
|
||||
* - For `resources/directory/read` it states **nothing of the kind**, and its
|
||||
* one worked example of the result carries `resultType: "complete"` and no
|
||||
* caching attributes at all. Requiring them here would fail a server that
|
||||
* matched the SEP's own example, which is the failure direction this module
|
||||
* works hardest to avoid.
|
||||
*
|
||||
* `resultType` is required because it is the base protocol's, not this
|
||||
* extension's: SEP-2322 makes it a member of every modern result, the SEP's
|
||||
* example carries it, and `skills/*` being consumer-owned means the SDK codec
|
||||
* validates none of it — so if this schema does not, nothing does.
|
||||
*
|
||||
* ⚠️ Picked by `InspectorClient.readResourceDirectory` from the negotiated era.
|
||||
*/
|
||||
export const ModernDirectoryReadResultSchema = DirectoryReadResultSchema.extend(
|
||||
{ resultType: z.literal("complete") },
|
||||
);
|
||||
|
|
|
|||
Loading…
Reference in a new issue