migration
This commit is contained in:
John Lancaster
@@ -4,7 +4,7 @@ icon: lucide/braces
|
||||
|
||||
# Frontmatter Contract
|
||||
|
||||
This page defines the authored frontmatter contracts for native FastMCP skills and registry-backed prompts.
|
||||
This page defines frontmatter ownership for native skills and prompt documentation.
|
||||
|
||||
## Skill Frontmatter
|
||||
|
||||
@@ -27,38 +27,22 @@ Rules:
|
||||
|
||||
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 Frontmatter
|
||||
## Prompt Documentation Frontmatter
|
||||
|
||||
Prompts remain registry-backed and retain repository metadata:
|
||||
Prompt runtime metadata is defined by typed Python components, not Markdown frontmatter. A prompt document may retain only fields consumed by the static documentation site:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: <prompt-id>
|
||||
description: <what the prompt does and when to use it>
|
||||
x-personal-mcp:
|
||||
id: <prompt-id>
|
||||
version: <semver>
|
||||
tags:
|
||||
- <tag>
|
||||
capabilities:
|
||||
- resource://prompts/<prompt-id>/document
|
||||
arguments:
|
||||
<argument-name>:
|
||||
title: <display title>
|
||||
description: <input guidance>
|
||||
required: true
|
||||
icon: lucide/messages-square
|
||||
---
|
||||
```
|
||||
|
||||
Prompt rules:
|
||||
|
||||
1. `name`, `description`, and `x-personal-mcp` are required.
|
||||
2. `x-personal-mcp.id`, `name`, and the prompt directory name must match.
|
||||
3. `version` must be semantic version text.
|
||||
4. `capabilities` must include `resource://prompts/<prompt-id>/document`.
|
||||
5. Argument names must be valid Python identifiers.
|
||||
6. Argument entries accept optional `title`, `description`, and `required` fields.
|
||||
7. Unknown prompt fields are rejected by the strict Pydantic registry models.
|
||||
1. Do not duplicate prompt names, descriptions, versions, tags, or arguments in Markdown YAML.
|
||||
2. Argument names must be valid Python identifiers in the component signature.
|
||||
3. Literal value constraints belong in Python type annotations.
|
||||
4. Markdown placeholders must exactly match the component argument names.
|
||||
|
||||
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.
|
||||
|
||||
@@ -70,11 +54,11 @@ Skill validation is file- and provider-oriented:
|
||||
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 remains registry-oriented and fails server startup for invalid metadata, duplicate prompt ids, or malformed arguments.
|
||||
Prompt validation is provider- and renderer-oriented. Provider discovery validates decorated functions, while focused tests render every prompt and reject placeholder drift.
|
||||
|
||||
## 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 retain the richer metadata required by their catalog and MCP prompt-object surfaces.
|
||||
3. Prompts use FastMCP's native component metadata and protocol surface without a parallel catalog.
|
||||
4. All authored content remains under `docs/`.
|
||||
|
||||
+29
-22
@@ -4,11 +4,11 @@ icon: lucide/messages-square
|
||||
|
||||
# Prompt Contract
|
||||
|
||||
This page defines the canonical contract for prompts in the docs-first MCP architecture.
|
||||
This page defines the canonical contract for typed prompts discovered by FastMCP's `FileSystemProvider`.
|
||||
|
||||
## Canonical Prompt Shape
|
||||
|
||||
Each prompt is one directory under `docs/prompts/`:
|
||||
Each prompt has a Python component and one canonical Markdown document:
|
||||
|
||||
```mermaid
|
||||
---
|
||||
@@ -22,27 +22,31 @@ config:
|
||||
lineColor: '#FFFFFF'
|
||||
---
|
||||
treeView-beta
|
||||
"docs/"
|
||||
"... (other docs)"
|
||||
"prompts/"
|
||||
"<prompt-id>/"
|
||||
"PROMPT.md"
|
||||
"references/"
|
||||
"... (one or more markdown files, optional nested folders)"
|
||||
"src/personal_mcp/prompts/"
|
||||
"components/"
|
||||
"<prompt_module>.py"
|
||||
"content.py"
|
||||
"provider.py"
|
||||
"docs/prompts/"
|
||||
"<prompt-id>/"
|
||||
"PROMPT.md"
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
1. `PROMPT.md` is required for every prompt.
|
||||
2. `references/` is the only place for prompt-specific supporting docs.
|
||||
3. Nested folders inside `references/` are allowed so a prompt can reorganize internals without changing global architecture.
|
||||
4. Prompt directories are independent ownership boundaries; no cross-prompt file writes.
|
||||
1. Each component exports one typed function decorated with `@prompt`.
|
||||
2. Function parameters define the MCP argument names, requiredness, and accepted values.
|
||||
3. Decorator fields define runtime name, description, tags, and version.
|
||||
4. The function loads its matching `docs/prompts/<prompt-id>/PROMPT.md` through `importlib.resources`.
|
||||
5. `PROMPT.md` owns the rendered prompt prose and uses `{argument_name}` placeholders.
|
||||
6. The renderer requires exact equality between the function's arguments and the Markdown placeholders.
|
||||
|
||||
## Metadata Location Constraint
|
||||
## Ownership Boundary
|
||||
|
||||
1. Prompt metadata is embedded in YAML frontmatter in `PROMPT.md`.
|
||||
2. No `metadata.yaml` sidecar exists in the end state.
|
||||
3. Reference lookup metadata is documented and explicit: top-level `references/*.md` are auto-discovered from filenames, while `PROMPT.md` frontmatter declares overrides and nested mappings when needed.
|
||||
1. Python owns runtime metadata and the callable schema.
|
||||
2. Markdown owns prompt prose and may contain only documentation-site frontmatter.
|
||||
3. There is no custom prompt catalog, prompt registry model, or metadata sidecar.
|
||||
4. `FileSystemProvider(reload=False)` discovers components when the server is created.
|
||||
|
||||
## Prompt Id Contract
|
||||
|
||||
@@ -53,8 +57,8 @@ Rules:
|
||||
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. Frontmatter `id` should equal directory name in each committed revision.
|
||||
7. Treat `prompt-id` as immutable after release; any rename is a breaking replacement and clients must move to the new id.
|
||||
6. The `@prompt` name and Markdown directory name must equal `prompt-id`.
|
||||
7. Treat `prompt-id` as immutable after release; a rename is a breaking replacement.
|
||||
|
||||
Valid examples:
|
||||
|
||||
@@ -68,8 +72,11 @@ Invalid examples:
|
||||
2. `Prompt-Template`
|
||||
3. `docs.prompt`
|
||||
|
||||
## Direct Documentation Inclusion
|
||||
## Rendering Contract
|
||||
|
||||
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.
|
||||
1. The renderer strips one leading YAML frontmatter block before returning prompt content.
|
||||
2. Required values are supplied by the typed function signature.
|
||||
3. An omitted optional value renders as `Not provided`.
|
||||
4. Unknown prompt ids and mismatched placeholders fail immediately.
|
||||
5. Prompt content is read from packaged resources and does not depend on the working directory.
|
||||
|
||||
|
||||
+8
-13
@@ -4,7 +4,7 @@ icon: lucide/link
|
||||
|
||||
# URI Contract
|
||||
|
||||
This page defines the public resource URI contract for native skills, registry-backed prompts, and general authored documentation.
|
||||
This page defines the public resource URI contract for native skills and general authored documentation.
|
||||
|
||||
## Native Skill URIs
|
||||
|
||||
@@ -44,17 +44,11 @@ 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.
|
||||
|
||||
## Prompt And Docs URIs
|
||||
## General Docs URI
|
||||
|
||||
Prompts and general documentation retain the existing registry-backed resource surface:
|
||||
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.
|
||||
|
||||
1. `resource://catalog/prompts_index`
|
||||
2. `resource://catalog/prompts_index{?q,tag,cursor,limit}`
|
||||
3. `resource://catalog/prompts/{prompt_id}`
|
||||
4. `resource://prompts/{prompt_id}/document`
|
||||
5. `resource://docs/{path*}`
|
||||
|
||||
Prompt ids remain lowercase kebab-case. The docs wildcard accepts normalized relative POSIX Markdown paths beneath `docs/` 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
|
||||
|
||||
@@ -66,11 +60,11 @@ For skills:
|
||||
4. read `_manifest` when supporting material may be needed
|
||||
5. fetch only the supporting paths relevant to the task
|
||||
|
||||
For prompts, use the prompt catalog or MCP prompt-object APIs.
|
||||
For prompts, use the native MCP prompt APIs or their generic tool projection.
|
||||
|
||||
## Compatibility Policy
|
||||
## Stability Policy
|
||||
|
||||
The native `skill://` family directly replaces the repository's former custom skill URI and catalog surfaces. No compatibility aliases or dual registrations are maintained. Prompt and general-doc URIs are unaffected.
|
||||
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.
|
||||
|
||||
@@ -80,3 +74,4 @@ Skill renames are breaking because the directory name is part of every native sk
|
||||
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