83 lines
2.5 KiB
Markdown
83 lines
2.5 KiB
Markdown
---
|
|
icon: lucide/messages-square
|
|
---
|
|
|
|
# Prompt Contract
|
|
|
|
This page defines the canonical contract for typed prompts discovered by FastMCP's `FileSystemProvider`.
|
|
|
|
## Canonical Prompt Shape
|
|
|
|
Each prompt has a Python component and one canonical Markdown document:
|
|
|
|
```mermaid
|
|
---
|
|
config:
|
|
treeView:
|
|
rowIndent: 20
|
|
lineThickness: 2
|
|
themeVariables:
|
|
treeView:
|
|
labelColor: '#FFFFFF'
|
|
lineColor: '#FFFFFF'
|
|
---
|
|
treeView-beta
|
|
"src/personal_mcp/prompts/"
|
|
"components/"
|
|
"<prompt_module>.py"
|
|
"content.py"
|
|
"provider.py"
|
|
"docs/prompts/"
|
|
"<prompt-id>/"
|
|
"PROMPT.md"
|
|
```
|
|
|
|
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.
|
|
|
|
## 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.
|
|
|
|
## 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 `@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:
|
|
|
|
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 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.
|
|
|