Skip to content

2026 11 20 directory resources

Kelly Ferrone edited this page Nov 20, 2026 · 2 revisions

Directory Resources Plan

History. Drafted 2026-11-20 for #185, built on #183 (the listing names SKILL.md alone, every other file reads by its exact URI, through EntryOnlySkillProvider). From rulings 25, 26 and 30 and MD-54 of kubed-io/cluster's material-delivery design (2026-11-19): folders become SEP-2640 directory resources answered by resources/directory/read, bound as an extension method the way skills/* already is, with _index.json and _index.md beside each folder for every hop that cannot send that method (agentgateway refuses methods it does not know). _manifest stays. The calls made here:

  • The folder code is a module of its own, mcp/directories.py, which knows no scheme: a provider hands it a Folders (async children(uri)), so agents:// and prompts:// can reuse it. skill_extension.py stays deletable (PLG-61); the method is bound by SkillsExtension because directoryRead is a setting of the Skills extension, which is what Claude Code checks.
  • Children are the folder's real files and subfolders. _manifest and the index files are the server's, not the folder's, so they are never children (an index listing itself would be odd).
  • Folders come from the disk, not only from file parents, so an empty folder is a directory resource with no children (SEP-2640's empty-array rule has a real case).
  • A Markdown file's description is its first # heading, in the directory listing and on the resource a read resolves, so _index.md says something better than "File from selenium-flow skill". SKILL.md keeps the skill's description; other files keep FastMCP's.
  • The result is SEP-2640's bare {resources, nextCursor?}, not skills/list's kb envelope.
  • Pages of 100. The cursor is the decimal offset of the next child; any other value is refused.
  • The not-found hint names _index.md only (the file a model reads), for the root as for any folder, raised by a middleware as mcp-kb's NameTheFileToRead does. A trailing-slash URI gets the plain not-found, since it is not a folder URI. read_resource passes the same hint on.
  • Errors: Directory not found and Invalid directory cursor, both -32602, after Skill not found and Invalid skills cursor. After the whole-branch review: a skill file named _index.md or _index.json sent its folder into infinite recursion. It is now never a child, the entry leaves it out, and a warning names it (PLG-67, PLG-19). The heading read skips code fences and tolerates a file that is not UTF-8, so no file loses the skill (PLG-68). A cursor too long for int() is refused, and the cursor text says what is accepted (PLG-66). show and read_resource refuse a folder as a plain miss with the hint (PLG-69).

For agentic workers: steps use checkbox (- [ ]) syntax for tracking. Every python command runs with SF_WORKTREE and PYTHONPATH pointing at the worktree (see the brief).

Goal: Claude Code's ReadMcpResourceDirTool lists skill://selenium-flow and descends into references over a direct connection, and _index.json / _index.md beside each folder read with plain resources/read.

Architecture: mcp/directories.py holds the scheme-free parts: the wire shape of a directory resource, the index bodies and resources, the resources/directory/read handler with pagination, and the NameTheIndex middleware. EntryOnlySkillProvider (in mcp/skill.py) scans its folders at init, implements children(uri), answers the index URIs in _get_resource, and titles Markdown files. SkillsExtension binds the method and declares {"directoryRead": true}.

Tech Stack: Python 3.11+, fastmcp-slim 4.2.2 (MethodBinding, Middleware, TextResource), mcp 2.3.0, pytest, ruff.

Spec: PLG-13, PLG-14, PLG-17, PLG-54, PLG-61 (changed) and PLG-64 to PLG-70 (new) in plugin.md, PROT-5 in protocol.md, SURF-17 in surfaces.md.

Global Constraints

  • A folder URI has no trailing slash, mimeType: inode/directory, and is unlisted.
  • resources/directory/read: direct children only, paginated, -32602 on a URI that is missing or not a folder.
  • resources/read on a folder URI answers not found and names <folder>/_index.md.
  • _index.json is exactly the method's resources array; _index.md is one <uri>: <description> line per child. Both unlisted.
  • _manifest stays. The extension value is {"directoryRead": true}.
  • Tests go through the real entry points: a FastMCP Client, and a raw JSON-RPC request (tests.fakes.request) for the method.

Task 1: Folders and their index files

Files:

  • Create: kubed/selenium_flow/mcp/directories.py
  • Modify: kubed/selenium_flow/mcp/skill.py (EntryOnlySkillProvider)
  • Test: tests/test_directories.py

Interfaces:

  • Produces: directories.INODE_DIRECTORY, INDEX_JSON, INDEX_MD, wire(resource) -> dict, folder(uri, name, description) -> dict, index_json(children) -> str, index_md(children) -> str, async index_resource(folders, uri) -> Resource | None, Folders protocol with async children(uri) -> list[dict] | None.

  • Produces: EntryOnlySkillProvider.children(uri), folder_uri(rel) -> str.

  • Step 1: Write the failing tests — over Client(server.mcp):

    • test_index_json_reads_beside_each_folder (root and references): application/json, a list of Resource dicts; the root's URIs are SKILL.md and references, references' are the eight reference files.
    • test_index_md_is_one_line_per_child: text/markdown, each line <uri>: <description>, the same children as _index.json, in order.
    • test_a_folder_child_is_a_directory_resource: references has mimeType: inode/directory, no trailing slash, name selenium-flow/references.
    • test_a_markdown_child_is_described_by_its_heading and SKILL.md by the skill description.
    • test_folders_and_indexes_are_unlisted: nothing in resources/list is a folder or an index.
    • test_the_manifest_is_never_a_child and still reads.
    • test_an_empty_folder_has_an_empty_index on a tmp skill with an empty assets/.
  • Step 2: Run them; they fail (_index.json not found).

  • Step 3: Implement directories.py's wire helpers and index_resource, then the provider: scan folders from the disk (rglob directories inside the skill, plus the root), map each folder URI to its child file paths and subfolders, children(uri) returns wire dicts sorted by URI (files through _get_resource, folders through directories.folder), _get_resource answers an index URI first and titles SkillFileResource Markdown files.

  • Step 4: Run them; they pass. Full suite and ruff check ..

  • Step 5: Commit skill: folders as directory resources with _index.json and _index.md (#185).

Task 2: resources/directory/read and directoryRead

Files:

  • Modify: kubed/selenium_flow/mcp/directories.py (DirectoryReadParams, DirectoryRead)
  • Modify: kubed/selenium_flow/mcp/skill_extension.py (SkillsExtension(entry, folders), settings(), methods(), register)
  • Test: tests/test_directories.py, tests/test_skills_extension.py (the declared value)

Interfaces:

  • Consumes: Folders.children from Task 1.

  • Produces: directories.METHOD = "resources/directory/read", DirectoryRead(folders) with page_size = PAGE_SIZE (100), binding() -> MethodBinding, async read(ctx, params) -> dict; skill_extension.SETTINGS = {"directoryRead": True}.

  • Step 1: Write the failing tests:

    • the extension value is {"directoryRead": True} in auto and legacy modes (change the existing test_the_extension_is_declared_beside_resources);
    • test_the_root_lists_its_direct_children: raw resources/directory/read on skill://selenium-flow returns SKILL.md and references, no nextCursor;
    • test_descending_lists_the_folder_alone: on references, the eight files, none deeper;
    • test_the_method_returns_what_the_index_holds: resources == json.loads(_index.json);
    • test_a_file_child_is_its_resources_list_row: SKILL.md's entry equals its listed row;
    • test_refusals_are_invalid_params: a missing folder, a file, a trailing slash, another scheme, an empty uri, a cursor of abc, 0, 99: all -32602, with Directory not found or Invalid directory cursor;
    • test_pages_join_to_the_whole_folder: a tmp skill of five files with page_size 2: three pages, each but the last with nextCursor, joined equal _index.json;
    • test_an_empty_folder_returns_no_resources;
    • test_switching_the_skill_off_removes_the_method: -32601;
    • test_a_nonconforming_skill_keeps_its_indexes_without_the_method.
  • Step 2: Run them; they fail (-32601).

  • Step 3: Implement DirectoryRead.read: children(uri) or Directory not found; the cursor is None or an ASCII decimal in 1..len-1, else Invalid directory cursor; the page is children[start:start + page_size], with nextCursor when more remain. SkillsExtension takes the provider, binds the method beside skills/*, and returns SETTINGS from settings(); AdvertiseLegacyExtensions gets the same value.

  • Step 4: Run them; they pass. Full suite and ruff.

  • Step 5: Commit skill: resources/directory/read, declared as directoryRead (#185).

Task 3: A folder read names its index

Files:

  • Modify: kubed/selenium_flow/mcp/directories.py (hint, FolderNotFound, NameTheIndex)
  • Modify: kubed/selenium_flow/mcp/skill.py (register adds the middleware)
  • Modify: kubed/selenium_flow/mcp/mirror.py (read_resource passes the hint on)
  • Test: tests/test_directories.py

Interfaces:

  • Produces: directories.FolderNotFound(MCPError) with .hint; NameTheIndex(folders).

  • Step 1: Write the failing tests:

    • test_reading_a_folder_names_its_index (root and references): -32602, the message starts Resource not found: '<uri>'. and names <uri>/_index.md, data is {"uri": <uri>};
    • test_a_trailing_slash_is_a_plain_miss: no hint;
    • test_read_resource_passes_the_hint_on: the read_resource tool's error names the index.
  • Step 2: Run them; they fail (bare Resource not found).

  • Step 3: Implement NameTheIndex.on_read_resource: on NotFoundError, a URI whose children is not None raises FolderNotFound(uri); anything else re-raises. skill.register adds it whatever the extension does. The mirror catches FolderNotFound and raises its hint.

  • Step 4: Run them; they pass. Full suite and ruff; regenerate the wiki if test_wiki asks.

  • Step 5: Commit skill: a folder read names its _index.md (#185) with the CHANGELOG line under [Unreleased].

Task 4: Spec and pointer

  • Commit the spec and this plan inside docs/ on feat/directory-resources, then the submodule pointer in the worktree's repo.

Clone this wiki locally