85 lines
2.9 KiB
Markdown
85 lines
2.9 KiB
Markdown
---
|
|
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.
|
|
|