Skip to content

Modern resources/directory/read results must carry ttlMs and cacheScope (ext-skills stable spec) #2740

Closed

Description

@olaservo

Problem

core/mcp/skillsSchemas.ts parses resources/directory/read results with one schema for both eras, and its closing comment says there is deliberately no modern variant because SEP-2640 "states nothing of the kind" about caching attributes on that method. The stable ext-skills specification (specification/stable/skills.mdx, updated upstream 2026-10-15 in ext-skills#157, decision recorded in docs/decisions.md) now settles that question the same way it settled skills/get in #2404:

ReadResourceDirectoryResult extends CacheableResult, so ttlMs and cacheScope are REQUIRED, as they are on resources/list, and carry the same semantics. They describe the freshness of the directory listing, not of the held entry, and do not alter Directory Reads and the Held Entry.

The spec's directory-read examples now carry "ttlMs": 300000, "cacheScope": "public".

As a result, the Inspector accepts a modern resources/directory/read result that is missing these required fields, so it reports a non-conforming server as clean. The test server has the same gap: readDirectoryPage in test-servers/src/skills.ts sends resultType only, with a comment saying a fixture that sent more than the SEP shows would make a client that wrongly required them look correct. Under the new text the fixture itself is non-conformant on the modern leg.

Expected

On modern (2026-07-28+) connections, validate resources/directory/read results against CacheableResult the same way skills/list and skills/get already are: require ttlMs as a non-negative integer and cacheScope as public or private. Legacy results stay permissive.

  • core/mcp/skillsSchemas.ts: add a ModernDirectoryReadResultSchema extending DirectoryReadResultSchema with the two attributes, and replace the "no modern variant" comment block with the new citation.
  • core/mcp/inspectorClient.ts readResourceDirectory: pick the schema from isModernEra(), as listSkills and getSkillResult do.
  • test-servers/src/skills.ts: readDirectoryPage and DirectoryReadResultShape send and validate the full modern envelope, matching the skills/* results.
  • Tests: the modern integration cases for resources/directory/read assert the attributes are required, mirroring the Modern skills/get results must carry ttlMs and cacheScope (ext-skills stable spec) #2404 coverage for skills/get. The CLI --method resources/directory/read prints the result as received, so its output gains the two fields on modern connections and nothing else changes.

Checked and not affected

The same ext-skills change also added named params interfaces with required _meta on skills/get and resources/directory/read requests, optional _meta on Skill, and *ResultResponse types. The SDK already stamps the required request metadata on modern connections (the strict modern test server reads clientCapabilities from it, #2373), SkillEntrySchema is a looseObject so _meta passes through, and the response types are documentation only. No Inspector change is needed for those.

Context

Spec diff: ext-skills#157, fixing ext-skills#156. Precedent: #2404 (same change for skills/get), #2373 (why the modern schemas omit resultType).

Activity

  1. added this to the v2.12.0 milestone on Oct 20, 2026
  2. added
    bugSomething isn't working
    v2Issues and PRs for v2
    on Oct 20, 2026
  3. self-assigned this
    on Oct 20, 2026
  4. olaservo commented on Oct 20, 2026

    @olaservo
    MemberAuthor

    Triage: Priority High (total 9)

    • Severity 4 — the Inspector reports a non-conforming modern resources/directory/read result as clean, and the test server's own fixture is non-conformant on the modern leg
    • Urgency 3 — wanted this milestone (v2.12.0), tracking a spec change published upstream on 2026-10-15
    • Bonuses: +1 bug label, +1 milestoned (filed through the create flow, so approved at filing)

    Board: #28, Status Todo → In Progress.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

bugSomething isn't workingv2Issues and PRs for v2

Type

No type

Projects

No projects

    Milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions