prompts/docs/mcp_contract_steps_1_5.md

FastMCP Greenfield Contracts (Steps 1-5)

Step 1: End-State Content Contract

1. All authored markdown lives under docs/.
2. Skill docs live under docs/skills//.
3. Canonical skill shape is:

docs/
  skills/
    <skill-id>/
      SKILL.md
      references/

4. SKILL.md is required for every skill.
5. references/ is the only place for skill-specific supporting docs.
6. Skill directories are ownership boundaries.
7. Skill id rules:
   • lowercase kebab-case
   • starts with a letter
   • directory name matches skill id
   • SKILL frontmatter id matches directory name

Step 2: SKILL Frontmatter and Metadata Contract

1. name and description are required top-level frontmatter fields.
2. Repository indexing metadata lives in x-personal-mcp.
3. x-personal-mcp fields:
   • required: id, version, capabilities
   • optional: tags, depends_on, references
4. references maps stable ref ids to skill-relative markdown paths under references/.
5. metadata.yaml sidecars are not part of the canonical model.

Step 3: URI Contract and Compatibility Policy

Canonical URI surface:

1. resource://catalog/skills_index
2. resource://catalog/skills/{skill_id}
3. resource://skills/{skill_id}/document
4. resource://skills/{skill_id}/references/{ref_id}
5. resource://docs/{path*}

Rules:

1. skill_id and ref_id are lowercase kebab-case.
2. docs path is markdown-only and cannot traverse outside docs/.
3. URI families are unversioned and canonical in this phase.
4. Breaking changes use direct replacement with no compatibility aliases.

Step 4: Docs Registry Loader Contract

1. Loader uses importlib.resources.files(...) and Traversable APIs.
2. Startup validates SKILL frontmatter schema, id invariants, reference integrity, dependency graph, and URI uniqueness.
3. Registry is immutable for request-time reads.
4. Invalid docs state is a hard startup error.

Step 5: Registry-Driven Resource Registration Contract

1. FastMCP resources are registered from the validated registry.
2. RFC6570 templates are used for parameterized routes.
3. Docs resources declare explicit MIME types.
4. Docs resources include readOnlyHint and idempotentHint annotations.
5. Duplicate registrations fail startup via strict duplicate policy.