prompts/docs/contracts/prompt.md

icon

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:

---
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.