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

prompt markdown

Browse Source
This commit is contained in:
John Lancaster
2026-08-07 20:30:54 -05:00
parent 5b6d5aaec4
commit 88ff4c2c71
30 changed files with 475 additions and 373 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/contracts/frontmatter.md
+15 -7
View File
@@ -29,20 +29,28 @@ The provider uses the directory name as the URI identity and the frontmatter `de
## Prompt Documentation Frontmatter
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:
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. 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.
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.
@@ -54,11 +62,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 is provider- and renderer-oriented. Provider discovery validates decorated functions, while focused tests render every prompt and reject placeholder drift.
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.
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/`.
docs/contracts/prompt.md
+25 -23
View File
@@ -4,11 +4,11 @@ icon: lucide/messages-square
# Prompt Contract
This page defines the canonical contract for typed prompts discovered by FastMCP's `FileSystemProvider`.
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 has a Python component and one canonical Markdown document:
Each prompt is one self-describing Markdown document:
```mermaid
---
@@ -22,31 +22,32 @@ config:
lineColor: '#FFFFFF'
---
treeView-beta
"src/personal_mcp/prompts/"
"components/"
"<prompt_module>.py"
"content.py"
"provider.py"
"docs/prompts/"
"<prompt-id>/"
"PROMPT.md"
"src/personal_mcp/prompts/"
"content.py"
"models.py"
"provider.py"
```
Rules:
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.
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. 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.
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
@@ -57,7 +58,7 @@ 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. The `@prompt` name and Markdown directory name must equal `prompt-id`.
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:
@@ -74,9 +75,10 @@ Invalid examples:
## Rendering 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.
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.