John Lancaster
67 lines
2.2 KiB
Markdown
67 lines
2.2 KiB
Markdown
# 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/<skill-id>/.
|
|
3. Canonical skill shape is:
|
|
|
|
```text
|
|
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.
|