john/prompts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc updates

Browse Source
This commit is contained in:
John Lancaster
2026-06-21 22:35:05 -05:00
parent c893173fcc
commit 58a94ad9b6
4 changed files with 70 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+12 -8
View File
@@ -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/<skill_id>/document
2. resource://skills/<skill_id>/references/<ref_id>
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:
docs/contracts/uris.md
+47 -4
View File
@@ -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-id>/SKILL.md`, and `skills/<skill-id>/references/<file>.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:
@@ -141,3 +177,10 @@ 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.
## 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)
docs/mcp_layout.md
+5 -1
View File
@@ -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:
docs/usage.md
+5 -3
View File
@@ -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: