Repository navigation
2026 11 20 directory resources
History. Drafted 2026-11-20 for #185, built on #183 (the listing names
SKILL.mdalone, every other file reads by its exact URI, throughEntryOnlySkillProvider). 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 byresources/directory/read, bound as an extension method the wayskills/*already is, with_index.jsonand_index.mdbeside each folder for every hop that cannot send that method (agentgateway refuses methods it does not know)._manifeststays. The calls made here:
- The folder code is a module of its own,
mcp/directories.py, which knows no scheme: a provider hands it aFolders(async children(uri)), soagents://andprompts://can reuse it.skill_extension.pystays deletable (PLG-61); the method is bound bySkillsExtensionbecausedirectoryReadis a setting of the Skills extension, which is what Claude Code checks.- Children are the folder's real files and subfolders.
_manifestand 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.mdsays something better than "File from selenium-flow skill".SKILL.mdkeeps the skill's description; other files keep FastMCP's.- The result is SEP-2640's bare
{resources, nextCursor?}, notskills/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.mdonly (the file a model reads), for the root as for any folder, raised by a middleware as mcp-kb'sNameTheFileToReaddoes. A trailing-slash URI gets the plain not-found, since it is not a folder URI.read_resourcepasses the same hint on.- Errors:
Directory not foundandInvalid directory cursor, both-32602, afterSkill not foundandInvalid skills cursor. After the whole-branch review: a skill file named_index.mdor_index.jsonsent 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 forint()is refused, and the cursor text says what is accepted (PLG-66).showandread_resourcerefuse a folder as a plain miss with the hint (PLG-69).
For agentic workers: steps use checkbox (
- [ ]) syntax for tracking. Every python command runs withSF_WORKTREEandPYTHONPATHpointing 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.
- A folder URI has no trailing slash,
mimeType: inode/directory, and is unlisted. -
resources/directory/read: direct children only, paginated,-32602on a URI that is missing or not a folder. -
resources/readon a folder URI answers not found and names<folder>/_index.md. -
_index.jsonis exactly the method'sresourcesarray;_index.mdis one<uri>: <description>line per child. Both unlisted. -
_manifeststays. 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.
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,Foldersprotocol withasync 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 andreferences):application/json, a list ofResourcedicts; the root's URIs areSKILL.mdandreferences,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:referenceshasmimeType: inode/directory, no trailing slash,nameselenium-flow/references. -
test_a_markdown_child_is_described_by_its_headingandSKILL.mdby the skill description. -
test_folders_and_indexes_are_unlisted: nothing inresources/listis a folder or an index. -
test_the_manifest_is_never_a_childand still reads. -
test_an_empty_folder_has_an_empty_indexon a tmp skill with an emptyassets/.
-
-
Step 2: Run them; they fail (
_index.jsonnot found). -
Step 3: Implement
directories.py's wire helpers andindex_resource, then the provider: scan folders from the disk (rglobdirectories 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 throughdirectories.folder),_get_resourceanswers an index URI first and titlesSkillFileResourceMarkdown 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).
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.childrenfrom Task 1. -
Produces:
directories.METHOD = "resources/directory/read",DirectoryRead(folders)withpage_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}inautoandlegacymodes (change the existingtest_the_extension_is_declared_beside_resources); -
test_the_root_lists_its_direct_children: rawresources/directory/readonskill://selenium-flowreturnsSKILL.mdandreferences, nonextCursor; -
test_descending_lists_the_folder_alone: onreferences, 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 emptyuri, a cursor ofabc,0,99: all-32602, withDirectory not foundorInvalid directory cursor; -
test_pages_join_to_the_whole_folder: a tmp skill of five files withpage_size2: three pages, each but the last withnextCursor, 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.
- the extension value is
-
Step 2: Run them; they fail (
-32601). -
Step 3: Implement
DirectoryRead.read:children(uri)orDirectory not found; the cursor isNoneor an ASCII decimal in1..len-1, elseInvalid directory cursor; the page ischildren[start:start + page_size], withnextCursorwhen more remain.SkillsExtensiontakes the provider, binds the method besideskills/*, and returnsSETTINGSfromsettings();AdvertiseLegacyExtensionsgets the same value. -
Step 4: Run them; they pass. Full suite and ruff.
-
Step 5: Commit
skill: resources/directory/read, declared as directoryRead (#185).
Files:
- Modify:
kubed/selenium_flow/mcp/directories.py(hint,FolderNotFound,NameTheIndex) - Modify:
kubed/selenium_flow/mcp/skill.py(registeradds the middleware) - Modify:
kubed/selenium_flow/mcp/mirror.py(read_resourcepasses 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 andreferences):-32602, the message startsResource not found: '<uri>'.and names<uri>/_index.md,datais{"uri": <uri>}; -
test_a_trailing_slash_is_a_plain_miss: no hint; -
test_read_resource_passes_the_hint_on: theread_resourcetool's error names the index.
-
-
Step 2: Run them; they fail (bare
Resource not found). -
Step 3: Implement
NameTheIndex.on_read_resource: onNotFoundError, a URI whosechildrenis notNoneraisesFolderNotFound(uri); anything else re-raises.skill.registeradds it whatever the extension does. The mirror catchesFolderNotFoundand raises its hint. -
Step 4: Run them; they pass. Full suite and ruff; regenerate the wiki if
test_wikiasks. -
Step 5: Commit
skill: a folder read names its _index.md (#185)with the CHANGELOG line under [Unreleased].
- Commit the spec and this plan inside
docs/onfeat/directory-resources, then the submodule pointer in the worktree's repo.
The action pages are generated from the server's tool schemas, so they describe the version that shipped.
selenium-flow · MIT
Start here
Guides
Lifecycle
Going places
Doing things
Getting things out
Site data
Console and network