From 58a94ad9b605e5b71ad34b4504b9180348029aaf Mon Sep 17 00:00:00 2001 From: John Lancaster <32917998+jsl12@users.noreply.github.com> Date: Sun, 21 Jun 2026 22:35:05 -0500 Subject: [PATCH] doc updates --- docs/architecture.md | 20 +++++++++------- docs/contracts/uris.md | 53 ++++++++++++++++++++++++++++++++++++++---- docs/mcp_layout.md | 6 ++++- docs/usage.md | 8 ++++--- 4 files changed, 70 insertions(+), 17 deletions(-) diff --git a/docs/architecture.md b/docs/architecture.md index db84550..e1c3a8d 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -75,9 +75,11 @@ The catalog is the canonical discovery layer and publishes normalized records fo Typical catalog resources: 1. resource://catalog/skills_index -2. resource://catalog/skills/{skill_id} -3. resource://catalog/prompts_index -4. resource://catalog/prompts/{prompt_id} +2. resource://catalog/skills_index{?q,tag,capability,cursor,limit} +3. resource://catalog/skills/{skill_id} +4. resource://catalog/prompts_index +5. resource://catalog/prompts_index{?q,tag,cursor,limit} +6. resource://catalog/prompts/{prompt_id} Only canonical catalog resources are part of the runtime contract in this phase. @@ -151,11 +153,13 @@ For the full URI semantics, parameter validation rules, and compatibility policy 1. resource://skills//document 2. resource://skills//references/ 3. resource://catalog/skills_index -4. resource://catalog/skills/{skill_id} -5. resource://docs/{path*} -6. resource://catalog/prompts_index -7. resource://catalog/prompts/{prompt_id} -8. resource://prompts/{prompt_id}/document +4. resource://catalog/skills_index{?q,tag,capability,cursor,limit} +5. resource://catalog/skills/{skill_id} +6. resource://docs/{path*} +7. resource://catalog/prompts_index +8. resource://catalog/prompts_index{?q,tag,cursor,limit} +9. resource://catalog/prompts/{prompt_id} +10. resource://prompts/{prompt_id}/document Validation rules: diff --git a/docs/contracts/uris.md b/docs/contracts/uris.md index a5cea32..1fb88b6 100644 --- a/docs/contracts/uris.md +++ b/docs/contracts/uris.md @@ -6,9 +6,11 @@ icon: lucide/link This page defines the canonical resource URI contract, template parameter rules, and compatibility policy. +Conventions in this document follow [MCP resource semantics](https://modelcontextprotocol.io/docs/learn/server-concepts#resources), [URI generic syntax (RFC3986)](https://www.rfc-editor.org/rfc/rfc3986), and [URI templates (RFC6570)](https://www.rfc-editor.org/rfc/rfc6570). + ## Canonical URI Surface -The public, preferred URIs are: +The public, preferred direct resource URIs are: 1. `resource://catalog/skills_index` 2. `resource://catalog/skills/{skill_id}` @@ -19,11 +21,23 @@ The public, preferred URIs are: 7. `resource://catalog/prompts/{prompt_id}` 8. `resource://prompts/{prompt_id}/document` +The public, preferred resource template URIs are: + +1. `resource://catalog/skills_index{?q,tag,capability,cursor,limit}` +2. `resource://catalog/prompts_index{?q,tag,cursor,limit}` + Contract intent: 1. Catalog URIs are discovery surfaces. 2. Skill URIs are the primary per-skill guidance surfaces. -3. The docs wildcard URI is a direct authored-markdown access surface under `docs/`. +3. Catalog query templates are additive discovery helpers for filtering and pagination. +4. The docs wildcard URI is a direct authored-markdown access surface under `docs/`. + +Best-practice alignment: + +1. Resource identifiers are stable and noun-oriented. +2. Dynamic lookup variants are represented as RFC6570 templates. +3. Resources remain read-oriented and are described with explicit MIME types. ## URI Semantics @@ -52,7 +66,7 @@ Contract intent: ### `resource://docs/{path*}` 1. Returns authored markdown at a normalized relative path under `docs/`. -2. Supports nested paths via RFC6570 wildcard expansion. +2. Supports nested paths via [RFC6570 wildcard expansion](https://www.rfc-editor.org/rfc/rfc6570). 3. Typical examples include `index.md`, `usage.md`, `skills//SKILL.md`, and `skills//references/.md`. ### `resource://catalog/prompts_index` @@ -61,6 +75,18 @@ Contract intent: 2. Contains one entry per `prompt_id`. 3. Includes `id`, `name`, `description`, `tags`, `version`, and canonical document URI. +### `resource://catalog/skills_index{?q,tag,capability,cursor,limit}` + +1. Returns the same record family as `resource://catalog/skills_index` with optional filtering and pagination. +2. Query parameters are optional and composable. +3. Unknown query keys are ignored or rejected deterministically by server policy. + +### `resource://catalog/prompts_index{?q,tag,cursor,limit}` + +1. Returns the same record family as `resource://catalog/prompts_index` with optional filtering and pagination. +2. Query parameters are optional and composable. +3. Unknown query keys are ignored or rejected deterministically by server policy. + ### `resource://catalog/prompts/{prompt_id}` 1. Returns one normalized record for `prompt_id`. @@ -86,17 +112,27 @@ Contract intent: ### `path*` -1. Relative POSIX path only. +1. Relative POSIX path only, expressed as URI path segments under [RFC3986 path syntax](https://www.rfc-editor.org/rfc/rfc3986#section-3.3). 2. No leading slash. 3. No `..` traversal segments. 4. Resolves only inside `docs/`. 5. Markdown-only in the end state, meaning `.md` files. +6. Any reserved URI characters in path segments must be [percent-encoded](https://www.rfc-editor.org/rfc/rfc3986#section-2.1). ### `prompt_id` 1. Lowercase kebab-case. 2. Must be unique across prompt ids and must not collide with skill ids. +## URI Hygiene Rules + +1. Use lowercase, human-readable path segments for stable discoverability. +2. Keep identifiers immutable once public whenever practical. +3. Keep template variables semantic (`skill_id`, `prompt_id`, `ref_id`, `path*`) and avoid overloading one variable for unrelated meanings. +4. Do not include secrets, tokens, or user-identifying data in URI paths or query strings. +5. Prefer additive query parameters for discovery over introducing parallel URI families, matching [MCP resource-template discovery patterns](https://modelcontextprotocol.io/docs/learn/server-concepts#resources). +6. Return clear not-found semantics for unknown ids and invalid template resolution. + ## URI Versioning Policy Default rule: @@ -140,4 +176,11 @@ This contract does not define: 1. Implementation-specific transform wiring details, such as `VersionFilter`, mounts, or provider composition. 2. Migration script mechanics for auto-generating aliases. -3. Authorization policy design for URI-level access control. \ No newline at end of file +3. Authorization policy design for URI-level access control. + +## Sources + +1. [MCP Server Concepts: Resources](https://modelcontextprotocol.io/docs/learn/server-concepts#resources) +2. [MCP Architecture Overview](https://modelcontextprotocol.io/docs/learn/architecture) +3. [MCP Specification Repository](https://github.com/modelcontextprotocol/spec) +4. [RFC6570 URI Template](https://www.rfc-editor.org/rfc/rfc6570) diff --git a/docs/mcp_layout.md b/docs/mcp_layout.md index e23e65c..2f8ffff 100644 --- a/docs/mcp_layout.md +++ b/docs/mcp_layout.md @@ -127,7 +127,11 @@ Example mapping model: Catalog discovery resources are: 1. resource://catalog/skills_index -2. resource://catalog/skills/{skill_id} +2. resource://catalog/skills_index{?q,tag,capability,cursor,limit} +3. resource://catalog/skills/{skill_id} +4. resource://catalog/prompts_index +5. resource://catalog/prompts_index{?q,tag,cursor,limit} +6. resource://catalog/prompts/{prompt_id} Registry-backed registration details: diff --git a/docs/usage.md b/docs/usage.md index 8f788bd..cae6c9f 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -31,9 +31,11 @@ Prompt guidance is now exposed through both prompt resources and MCP prompt obje `personal-mcp` registers resources from the validated docs registry and exposes catalog discovery resources: 1. `resource://catalog/skills_index` -2. `resource://catalog/skills/{skill_id}` -3. `resource://catalog/prompts_index` -4. `resource://catalog/prompts/{prompt_id}` +2. `resource://catalog/skills_index{?q,tag,capability,cursor,limit}` +3. `resource://catalog/skills/{skill_id}` +4. `resource://catalog/prompts_index` +5. `resource://catalog/prompts_index{?q,tag,cursor,limit}` +6. `resource://catalog/prompts/{prompt_id}` Each skill publishes a canonical Markdown document resource: