swapped docs symlink
This commit is contained in:
John Lancaster
@@ -0,0 +1,72 @@
|
||||
---
|
||||
icon: lucide/braces
|
||||
---
|
||||
|
||||
# Frontmatter Contract
|
||||
|
||||
This page defines frontmatter ownership for native skills and prompt documentation.
|
||||
|
||||
## Skill Frontmatter
|
||||
|
||||
Skills use the standard Agent Skills fields consumed by the [FastMCP Skills Provider](https://gofastmcp.com/servers/providers/skills):
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: <skill-id>
|
||||
description: <what the skill does and when to use it>
|
||||
---
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
1. `name` and `description` are required.
|
||||
2. `name` must equal the skill directory name.
|
||||
3. The repository uses lowercase kebab-case directory names.
|
||||
4. Skill frontmatter contains no `x-personal-mcp` catalog metadata.
|
||||
5. Supporting files require no frontmatter manifest. The provider discovers files recursively and generates `_manifest` with relative paths, byte sizes, and SHA256 hashes.
|
||||
|
||||
The provider uses the directory name as the URI identity and the frontmatter `description` as the main resource description. Repository tests enforce directory/name parity and reject extra skill frontmatter fields.
|
||||
|
||||
## Prompt Documentation Frontmatter
|
||||
|
||||
Each prompt stores runtime metadata in a nested `prompt` mapping beside fields consumed by the static documentation site. The runtime mapping uses this shape:
|
||||
|
||||
```yaml
|
||||
---
|
||||
icon: lucide/messages-square
|
||||
prompt:
|
||||
version: "1.0.0"
|
||||
description: Describe when to use the prompt.
|
||||
tags: [example, prompts]
|
||||
arguments: {topic: {description: "Topic to process.", required: true, choices: [first, second]}, notes: {description: "Optional constraints.", required: false}}
|
||||
---
|
||||
```
|
||||
|
||||
Prompt rules:
|
||||
|
||||
1. `version`, `description`, `tags`, and `arguments` are required; unknown fields inside `prompt` or an argument are rejected.
|
||||
2. The directory name supplies the prompt id. Do not add a duplicate `name` field.
|
||||
3. Argument names must be valid identifiers and preserve their authored mapping order.
|
||||
4. Every argument requires a non-empty `description` and explicit `required` boolean.
|
||||
5. Optional `choices` must be a non-empty list of unique, non-empty strings.
|
||||
6. Markdown placeholders must exactly match the declared argument names.
|
||||
7. Top-level fields such as `icon` remain owned by the documentation site and are not runtime prompt metadata.
|
||||
|
||||
See the MCP [prompts concept documentation](https://modelcontextprotocol.io/docs/learn/server-concepts#prompts) and [schema reference](https://modelcontextprotocol.io/specification/latest/schema) for the protocol-level prompt shape.
|
||||
|
||||
## Validation Timing
|
||||
|
||||
Skill validation is file- and provider-oriented:
|
||||
|
||||
1. `SkillsDirectoryProvider` discovers each directory containing `SKILL.md`.
|
||||
2. FastMCP parses the description and scans all files when the provider is created.
|
||||
3. Repository tests enforce the stricter standard-only frontmatter and directory/name rules.
|
||||
|
||||
Prompt validation is provider- and renderer-oriented. Every list or get request reloads and validates the authored files. A malformed definition fails the request instead of publishing a partial prompt set.
|
||||
|
||||
## Invariants
|
||||
|
||||
1. Skills remain directly portable to tools that understand standard Agent Skills directories.
|
||||
2. Native skill discovery has no parallel catalog metadata source.
|
||||
3. Prompts use FastMCP's native component metadata and protocol surface without a parallel catalog or Python component file.
|
||||
4. All authored content remains under `docs/`.
|
||||
@@ -0,0 +1,88 @@
|
||||
---
|
||||
icon: lucide/file-check-2
|
||||
---
|
||||
|
||||
# Contracts
|
||||
|
||||
This section groups the core data and contract documents for the repository.
|
||||
|
||||
## Pages
|
||||
|
||||
1. [Prompt Contract](./prompt.md)
|
||||
2. [Skill Contract](./skill_contract.md)
|
||||
3. [Frontmatter Contract](./frontmatter.md)
|
||||
4. [URI Contract](./uris.md)
|
||||
|
||||
Use these pages as the normative source for authored content layout, frontmatter schema, and canonical MCP URI semantics.
|
||||
|
||||
## Content Contract
|
||||
|
||||
This page defines the authored content contract for the docs-first MCP architecture.
|
||||
|
||||
## Canonical Source Of Truth
|
||||
|
||||
1. All authored Markdown lives under `docs/`.
|
||||
2. MCP resources and static docs are two distribution surfaces of the same authored files.
|
||||
3. No parallel authored markdown is allowed in `src/` or other package-only paths.
|
||||
|
||||
## Canonical Content Shape
|
||||
|
||||
Authored content is organized under `docs/`:
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
treeView:
|
||||
rowIndent: 20
|
||||
lineThickness: 2
|
||||
themeVariables:
|
||||
treeView:
|
||||
labelColor: '#FFFFFF'
|
||||
lineColor: '#FFFFFF'
|
||||
---
|
||||
treeView-beta
|
||||
"docs/"
|
||||
"*.md (top-level docs pages)"
|
||||
"contracts/"
|
||||
"prompt.md"
|
||||
"skill_contract.md"
|
||||
"frontmatter.md"
|
||||
"uris.md"
|
||||
"prompts/"
|
||||
"<prompt-id>/"
|
||||
"PROMPT.md"
|
||||
"skills/"
|
||||
"<skill-id>/"
|
||||
"SKILL.md"
|
||||
"references/..."
|
||||
```
|
||||
|
||||
## File Placement And Ownership Boundaries
|
||||
|
||||
1. Top-level project docs stay in `docs/*.md`.
|
||||
2. Skill docs stay in `docs/skills/<skill-id>/...`.
|
||||
3. Prompt docs stay in `docs/prompts/<prompt-id>/...`.
|
||||
4. A skill or prompt may link across sections, but must not store content in another artifact's directory.
|
||||
5. Server and runtime code may index and serve docs, but must not be the source of authored markdown.
|
||||
|
||||
## Delegated Contracts
|
||||
|
||||
1. Skill-specific directory, metadata, and id rules are defined in [Skill Contract](./skill_contract.md).
|
||||
2. Prompt-specific directory, metadata, and id rules are defined in [Prompt Contract](./prompt.md).
|
||||
|
||||
## Invariants
|
||||
|
||||
This contract guarantees:
|
||||
|
||||
1. One authored source tree in `docs/` for both website and MCP.
|
||||
2. Skill and prompt artifacts remain path-stable within their own sections.
|
||||
3. Cross-surface publishing remains deterministic because authored content paths are canonical.
|
||||
|
||||
## Non-Goals
|
||||
|
||||
This contract does not define:
|
||||
|
||||
1. URI versioning policy details.
|
||||
2. The full frontmatter schema.
|
||||
3. Detailed skill rules (see [Skill Contract](./skill_contract.md)).
|
||||
4. Detailed prompt rules (see [Prompt Contract](./prompt.md)).
|
||||
@@ -0,0 +1,84 @@
|
||||
---
|
||||
icon: lucide/messages-square
|
||||
---
|
||||
|
||||
# Prompt Contract
|
||||
|
||||
This page defines the canonical contract for declarative prompts published through a custom [FastMCP provider](https://gofastmcp.com/servers/providers/custom).
|
||||
|
||||
## Canonical Prompt Shape
|
||||
|
||||
Each prompt is one self-describing Markdown document:
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
treeView:
|
||||
rowIndent: 20
|
||||
lineThickness: 2
|
||||
themeVariables:
|
||||
treeView:
|
||||
labelColor: '#FFFFFF'
|
||||
lineColor: '#FFFFFF'
|
||||
---
|
||||
treeView-beta
|
||||
"docs/prompts/"
|
||||
"<prompt-id>/"
|
||||
"PROMPT.md"
|
||||
"src/personal_mcp/prompts/"
|
||||
"content.py"
|
||||
"models.py"
|
||||
"provider.py"
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
1. The parent directory name defines the public prompt id.
|
||||
2. The nested `prompt` frontmatter block defines version, description, tags, and arguments.
|
||||
3. Argument declarations define names, descriptions, requiredness, and optional string choices.
|
||||
4. The Markdown body owns the rendered prompt prose and uses `{{argument_name}}` placeholders.
|
||||
5. Declared arguments and body placeholders must match exactly.
|
||||
6. No Python file is added when authoring a prompt.
|
||||
|
||||
## Ownership Boundary
|
||||
|
||||
1. Each `PROMPT.md` owns both its runtime metadata and prose.
|
||||
2. Python owns only generic parsing, validation, rendering, and provider behavior.
|
||||
3. There is no central prompt catalog, generated signature, or metadata sidecar.
|
||||
4. The provider scans direct children of packaged `docs/prompts/` on each list or get request.
|
||||
5. Additions, edits, and deletions become visible on the next request without restarting the server.
|
||||
6. Reload is pull-based; the provider does not watch files or emit proactive change notifications.
|
||||
|
||||
## Prompt Id Contract
|
||||
|
||||
`prompt-id` is the public identifier and should satisfy all rules below:
|
||||
|
||||
1. Format: lowercase kebab-case only.
|
||||
2. Character set: `a-z`, `0-9`, and `-`.
|
||||
3. Must start with a letter.
|
||||
4. No underscores, spaces, dots, or uppercase characters.
|
||||
5. Directory name should equal `prompt-id` in each committed revision.
|
||||
6. The provider derives the prompt name from the directory; frontmatter must not duplicate it.
|
||||
7. Treat `prompt-id` as immutable after release; a rename is a breaking replacement.
|
||||
|
||||
Valid examples:
|
||||
|
||||
1. `pytest-fill-scaffold`
|
||||
2. `review-pr-comments`
|
||||
3. `scaffold-fastapi-service`
|
||||
|
||||
Invalid examples:
|
||||
|
||||
1. `fill_pytest_scaffold`
|
||||
2. `Prompt-Template`
|
||||
3. `docs.prompt`
|
||||
|
||||
## Rendering Contract
|
||||
|
||||
1. The loader requires one leading YAML frontmatter block and validates its nested `prompt` mapping strictly.
|
||||
2. All MCP arguments are strings; `choices` optionally restricts accepted values.
|
||||
3. Missing required arguments, unknown arguments, and invalid choices fail before rendering.
|
||||
4. An omitted optional value renders as `Not provided`.
|
||||
5. Unknown prompt ids, malformed metadata, and mismatched placeholders fail immediately.
|
||||
6. Prompt content is read through [importlib resources](https://docs.python.org/3/library/importlib.resources.html) and does not depend on the working directory.
|
||||
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
icon: lucide/brain-circuit
|
||||
---
|
||||
|
||||
# Skill Contract
|
||||
|
||||
This page defines the canonical contract for skills in the docs-first MCP architecture.
|
||||
|
||||
## Canonical Skill Shape
|
||||
|
||||
Each skill is one directory under `docs/skills/`:
|
||||
|
||||
```mermaid
|
||||
---
|
||||
config:
|
||||
treeView:
|
||||
rowIndent: 20
|
||||
lineThickness: 2
|
||||
themeVariables:
|
||||
treeView:
|
||||
labelColor: '#FFFFFF'
|
||||
lineColor: '#FFFFFF'
|
||||
---
|
||||
treeView-beta
|
||||
"docs/"
|
||||
"... (other docs)"
|
||||
"skills/"
|
||||
"<skill-id>/"
|
||||
"SKILL.md"
|
||||
"references/"
|
||||
"... (one or more markdown files, optional nested folders)"
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
1. `SKILL.md` is required for every skill.
|
||||
2. `references/` is the only place for skill-specific supporting docs.
|
||||
3. Nested folders inside `references/` are allowed so a skill can reorganize internals without changing global architecture.
|
||||
4. Skill directories are independent ownership boundaries; no cross-skill file writes.
|
||||
|
||||
## Metadata Location Constraint
|
||||
|
||||
1. `SKILL.md` frontmatter contains only standard `name` and `description` fields.
|
||||
2. No `metadata.yaml` sidecar or repository-specific skill metadata block exists.
|
||||
3. The provider discovers supporting files recursively; their real relative paths are published in the generated `_manifest`.
|
||||
|
||||
## Skill Id Contract
|
||||
|
||||
`skill-id` is the public identifier and should satisfy all rules below:
|
||||
|
||||
1. Format: lowercase kebab-case only.
|
||||
2. Character set: `a-z`, `0-9`, and `-`.
|
||||
3. Must start with a letter.
|
||||
4. No underscores, spaces, dots, or uppercase characters.
|
||||
5. Directory name equals `skill-id` in each committed revision.
|
||||
6. Frontmatter `name` equals the directory name.
|
||||
7. Treat `skill-id` as immutable after release; any rename is a breaking replacement and clients must move to the new id.
|
||||
|
||||
Valid examples:
|
||||
|
||||
1. `fastapi-uv-docker`
|
||||
2. `zensical-docs`
|
||||
3. `pytesting`
|
||||
|
||||
Invalid examples:
|
||||
|
||||
1. `fastapi_uv_docker`
|
||||
2. `Zensical-Docs`
|
||||
3. `docs.zensical`
|
||||
|
||||
## Provider Publication
|
||||
|
||||
[`SkillsDirectoryProvider`](https://gofastmcp.com/servers/providers/skills) scans `docs/skills/` with `supporting_files="template"` and publishes:
|
||||
|
||||
1. `skill://<skill-id>/SKILL.md`
|
||||
2. `skill://<skill-id>/_manifest`
|
||||
3. `skill://<skill-id>/{path*}` for supporting files
|
||||
|
||||
Only the main file and manifest appear in `resources/list`. Clients inspect the manifest before reading supporting paths.
|
||||
|
||||
## Direct Documentation Inclusion
|
||||
|
||||
1. For direct API documentation, use mkdocstrings directives rather than pasting large code blocks.
|
||||
2. Keep manually-authored code examples short and task-focused; large implementation excerpts are out of scope for this contract.
|
||||
|
||||
@@ -0,0 +1,77 @@
|
||||
---
|
||||
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)
|
||||
Reference in New Issue
Block a user