prompts/docs/contracts/uris.md

icon

icon
lucide/link

URI Contract

This page defines the canonical resource URI contract, template parameter rules, and compatibility policy.

Conventions in this document follow MCP resource semantics, URI generic syntax (RFC3986), and URI templates (RFC6570).

Canonical URI Surface

The public, preferred direct resource URIs are:

1. resource://catalog/skills_index
2. resource://catalog/skills/{skill_id}
3. resource://skills/{skill_id}/document
4. resource://skills/{skill_id}/references/{ref_id}
5. resource://docs/{path*}
6. resource://catalog/prompts_index
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. 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

resource://catalog/skills_index

1. Returns a compact list of skill records for discovery.
2. Contains one entry per skill_id.
3. Includes enough metadata for client-side selection, at minimum id, name, description, tags, and capabilities.

resource://catalog/skills/{skill_id}

1. Returns one normalized record for skill_id.
2. Includes the canonical document URI and declared reference ids.
3. Returns not found when skill_id does not exist.

resource://skills/{skill_id}/document

1. Returns the canonical SKILL.md authored content for that skill.
2. skill_id must satisfy the stable skill id rules from the content contract.

resource://skills/{skill_id}/references/{ref_id}

1. Returns one reference document declared in the skill frontmatter references manifest.
2. ref_id is the stable public handle for that reference document.

resource://docs/{path*}

1. Returns authored markdown at a normalized relative path under docs/.
2. Supports nested paths via RFC6570 wildcard expansion.
3. Typical examples include index.md, usage.md, skills/<skill-id>/SKILL.md, and skills/<skill-id>/references/<file>.md.

resource://catalog/prompts_index

1. Returns a compact list of prompt records for discovery.
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.
2. Includes prompt argument metadata when declared in frontmatter.
3. Returns not found when prompt_id does not exist.

resource://prompts/{prompt_id}/document

1. Returns the canonical prompt markdown document.
2. prompt_id must satisfy lowercase kebab-case rules.

Template Parameter And Validation Rules

skill_id

1. Lowercase kebab-case.
2. Must satisfy the stable skill id rules from the content contract.

ref_id

1. Lowercase kebab-case.
2. Must be declared in the skill's references manifest.

path*

1. Relative POSIX path only, expressed as URI path segments under RFC3986 path syntax.
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.

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.
6. Return clear not-found semantics for unknown ids and invalid template resolution.

URI Versioning Policy

Default rule:

1. Keep URIs unversioned by default.
2. Allow URI and payload updates when they improve clarity or implementation simplicity.

Breaking-change rule:

1. Breaking changes use direct replacement of the canonical URI family.
2. No compatibility aliases or dual URI families are maintained.

FastMCP version metadata usage:

1. Resource version metadata may be used for implementation and version discovery.
2. URI readability and maintainability remain the primary contract.

Reference Id Compatibility Policy

ref_id is the public identifier for a reference document, separate from file path.

Rules:

1. Prefer keeping ref_id stable when practical.
2. File paths may change without URI churn as long as the mapped ref_id still resolves.
3. If a reference is renamed, introduce a new ref_id and treat the old one as retired.
4. Avoid reusing retired ref_id values for unrelated content.

Invariants

This contract guarantees:

1. One canonical URI pattern per core capability surface.
2. Fast, low-friction URI evolution through direct replacement of canonical URIs.
3. A single canonical catalog URI family with no alias maintenance overhead.
4. Reference mappings can evolve with minimal churn.

Non-Goals

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
2. MCP Architecture Overview
3. MCP Specification Repository
4. RFC6570 URI Template