78 lines
3.0 KiB
Markdown
78 lines
3.0 KiB
Markdown
---
|
|
icon: lucide/link
|
|
---
|
|
|
|
# URI Contract
|
|
|
|
This page defines the public resource URI contract for native skills and general authored documentation.
|
|
|
|
## Native Skill URIs
|
|
|
|
The [FastMCP Skills Provider](https://gofastmcp.com/servers/providers/skills) publishes each skill through the `skill://` scheme:
|
|
|
|
1. `skill://<skill-name>/SKILL.md`
|
|
2. `skill://<skill-name>/_manifest`
|
|
3. `skill://<skill-name>/<supporting-path>`
|
|
|
|
The first two are concrete resources returned by `resources/list`. Supporting files use a per-skill wildcard resource template when the provider is configured with `supporting_files="template"`:
|
|
|
|
```text
|
|
skill://<skill-name>/{path*}
|
|
```
|
|
|
|
### Main File
|
|
|
|
`skill://<skill-name>/SKILL.md` returns the canonical authored skill document. The skill directory name supplies `<skill-name>`, and the resource description comes from `SKILL.md` frontmatter.
|
|
|
|
### Manifest
|
|
|
|
`skill://<skill-name>/_manifest` returns JSON containing the skill name and every file beneath its directory. Each file entry includes:
|
|
|
|
1. relative POSIX path
|
|
2. byte size
|
|
3. SHA256 hash
|
|
|
|
Clients read the manifest before requesting supporting files. FastMCP client utilities such as `list_skills()` and `get_skill_manifest()` understand this contract directly.
|
|
|
|
### Supporting Files
|
|
|
|
Supporting files retain their real skill-relative paths. For example:
|
|
|
|
```text
|
|
skill://pytesting/references/pytest-docs.md
|
|
```
|
|
|
|
FastMCP confines reads to the selected skill directory. Absolute paths, traversal outside the directory, missing files, directories, and symlinks that resolve outside the skill root are rejected.
|
|
|
|
## General Docs URI
|
|
|
|
General authored documentation is exposed through `resource://docs/{path*}`. The wildcard accepts normalized relative POSIX Markdown paths beneath `docs/`, excludes the provider-owned `skills/` subtree, and rejects absolute paths, traversal segments, backslashes, and non-Markdown targets.
|
|
|
|
Prompts are MCP prompt components rather than resources. Clients discover them with the protocol `prompts/list` operation and render them with `prompts/get`.
|
|
|
|
## Discovery Order
|
|
|
|
For skills:
|
|
|
|
1. list resources or call FastMCP `list_skills()`
|
|
2. select a skill by name and description
|
|
3. read `skill://<skill-name>/SKILL.md`
|
|
4. read `_manifest` when supporting material may be needed
|
|
5. fetch only the supporting paths relevant to the task
|
|
|
|
For prompts, use the native MCP prompt APIs or their generic tool projection.
|
|
|
|
## Stability Policy
|
|
|
|
The provider and protocol surfaces documented here are the complete public contract. Contract changes replace the affected surface directly.
|
|
|
|
Skill renames are breaking because the directory name is part of every native skill URI. Supporting-file renames change the corresponding manifest path and URI.
|
|
|
|
## Sources
|
|
|
|
1. [FastMCP Skills Provider](https://gofastmcp.com/servers/providers/skills)
|
|
2. [MCP resources](https://modelcontextprotocol.io/specification/latest/server/resources)
|
|
3. [RFC 3986 URI syntax](https://www.rfc-editor.org/rfc/rfc3986)
|
|
4. [RFC 6570 URI templates](https://www.rfc-editor.org/rfc/rfc6570)
|
|
5. [FastMCP prompts](https://gofastmcp.com/servers/prompts)
|