prompts/.github/prompts/plan-step5.prompt.md

Step 5 Results: Registry-Driven FastMCP Resource Registration (RFC6570 + Startup Safety)

This section finalizes Step 5 by defining how FastMCP resources are registered from the Step 4 docs registry using RFC6570 URI templates, explicit metadata, and strict duplicate-registration safety.

Greenfield Framing (Normative)

This Step 5 design is for the greenfield target state:

1. Registry-driven resources are the primary and authoritative discovery/read surface.
2. No legacy per-skill hardcoded resource registration is retained.
3. Resource contracts are defined for net-new clients and replace prior contracts without transition shims.
4. Step 6 tool fallback layers on top of this resource contract, not as a competing source of truth.
5. Breaking changes are intentional in this full-refactor phase.

Research Baseline (FastMCP + URI Templates)

Authoritative references used for this step:

1. FastMCP Resources and Templates docs (resource decorator, template behavior)
2. FastMCP RFC6570 support docs (simple params, wildcard params, query params)
3. FastMCP duplicate handling docs (on_duplicate_resources)
4. FastMCP annotations guidance (readOnlyHint, idempotentHint)

Best-practice conclusions applied to this design:

1. Use URI templates for parameterized resources instead of generating N static resource handlers.
2. Use wildcard template parameters ({path*}) for hierarchical docs paths.
3. Set startup duplicate policy to on_duplicate_resources="error" to fail fast on contract collisions.
4. Set explicit mime_type and resource annotations for all docs resources.
5. Keep registration deterministic and sourced only from the validated Step 4 registry.

Registration Responsibilities (Normative)

The Step 5 registration layer MUST:

1. Consume only the validated in-memory registry produced by Step 4.
2. Register canonical resource discovery surfaces and skill document/reference surfaces.
3. Use RFC6570 templates where URI patterns are parameterized.
4. Use wildcard templates where path depth is variable.
5. Attach read-only/idempotent annotations to documentation resources.
6. Set explicit MIME types for all registered resources.
7. Fail startup if duplicate URI/template keys are encountered.

Canonical Resource Surface (from Registry)

The preferred resources registered in this phase are:

1. resource://catalog/skills_index
2. resource://catalog/skills_index{?q,tag,capability,cursor,limit} (optional filtered/paginated discovery template)
3. resource://catalog/skills/{skill_id}
4. resource://skills/{skill_id}/document
5. resource://skills/{skill_id}/references/{ref_id}
6. resource://docs/{path*}

Registration decision rules:

1. Use static resource registration for fixed singleton endpoints (for example skills_index).
2. Use template registration for parameterized endpoints ({skill_id}, {ref_id}) and optional discovery query templates.
3. Use wildcard template registration for hierarchical docs routing ({path*}).
4. Keep the singleton and query-template discovery surfaces semantically equivalent (same schema, query template adds filtering/pagination only).

Progressive Discovery Contract

Discovery-first behavior for Step 5 resources:

1. skills_index returns summaries only (no embedded full SKILL.md bodies).
2. Each summary includes canonical follow-up URIs so clients can progressively fetch detail (catalog/skills/{skill_id} then skills/{skill_id}/document).
3. Filtered/paginated discovery uses RFC6570 query params (q, tag, capability, cursor, limit) with deterministic ordering.
4. Handlers should enforce bounded page size and return explicit continuation metadata when pagination is active.
5. Errors for unsupported filter params or invalid cursor/limit are explicit and actionable.

RFC6570 Template Contract

Path parameters:

1. {skill_id} and {ref_id} are single-segment template params.
2. {path*} is a wildcard param and may capture multi-segment paths separated by /.

Validation contract at resource-read time:

1. skill_id must exist in registry.
2. ref_id must exist in that skill’s reference manifest.
3. wildcard path* must normalize to an allowed docs-relative markdown path.
4. invalid params return explicit not-found or validation errors (no silent fallback).

Template function signature contract:

1. Required URI params must exist as function parameters.
2. Avoid hidden implicit params not represented in template.
3. Keep template handlers side-effect free.

Metadata and Annotation Contract

Each docs/resource registration should specify explicit metadata:

1. mime_type
   • skill docs and references: text/markdown
   • catalog payloads: application/json
2. annotations
   • readOnlyHint: true
   • idempotentHint: true
3. tags
   • include stable categories such as catalog, skill-doc, reference, docs
4. version
   • project-defined version from registry metadata where applicable
5. meta
   • include normalized identifiers (for example skill_id, ref_id, source_relpath) when useful

Startup Safety and Duplicate Policy

FastMCP initialization contract for this phase:

1. Construct the root server with on_duplicate_resources="error".
2. Register all Step 5 resources during startup composition before serving traffic.
3. Treat duplicate registration as a hard startup failure.

Duplicate conflict classes covered:

1. static URI vs static URI collision
2. static URI vs template key collision
3. template URI vs template URI collision
4. conflicting registrations introduced by future aliases without explicit migration handling

Registration Architecture

Use one dedicated registration module that converts registry records into FastMCP resources.

Recommended API:

1. register_docs_resources(mcp: FastMCP, registry: DocsRegistry) -> None

Responsibilities of register_docs_resources:

1. register singleton catalog resources
2. register parameterized catalog/detail templates
3. register skill document and reference templates
4. register docs wildcard template
5. apply shared annotations and MIME defaults consistently

Separation of concerns:

1. Step 4 validates and normalizes docs state.
2. Step 5 only registers handlers and reads from validated registry state.
3. Request handlers do not re-discover filesystem/package structure.

Handler Behavior Contract

Catalog handlers:

1. skills_index returns compact deterministic discovery payload (summary records only) and supports progressive follow-up links.
2. skills/{skill_id} returns one normalized detail record or not-found.

Skill document handlers:

1. skills/{skill_id}/document returns canonical SKILL markdown content.
2. MIME type is always text/markdown.

Reference handlers:

1. skills/{skill_id}/references/{ref_id} resolves via frontmatter manifest mapping.
2. MIME type is explicit from manifest or defaults to text/markdown.

Wildcard docs handler:

1. docs/{path*} serves markdown docs under canonical packaged docs tree.
2. traversal outside docs root is blocked.

Integration Plan for Existing Modules

Primary composition updates:

1. Implement registry-driven registration in src/personal_mcp/mcp.py as the canonical resource composition path.
2. Keep src/personal_mcp/main.py responsible for startup wiring order (load registry first, then register resources).
3. Use src/personal_mcp/catalog/server.py as registry-backed handlers only.

Lifecycle order (required):

1. load and validate registry (Step 4)
2. initialize FastMCP with duplicate error policy
3. register all Step 5 resources/templates
4. start server

Testing Plan (Step 5 Scope)

Unit/integration tests:

1. resource registration succeeds with valid registry
2. duplicate resource registration fails at startup
3. skills/{skill_id} template resolves expected record
4. skills/{skill_id}/document returns markdown with correct MIME
5. skills/{skill_id}/references/{ref_id} resolves manifest-mapped file
6. docs/{path*} resolves nested docs paths and blocks traversal attempts
7. all registered docs resources include readOnlyHint and idempotentHint
8. catalog payload order is deterministic
9. filtered/paginated skills_index{?q,tag,capability,cursor,limit} responses are deterministic and schema-compatible with the singleton index response
10. catalog index payload excludes full markdown bodies and includes follow-up URIs for progressive reads

Smoke tests:

1. list resources includes singleton and template entries
2. read representative skill doc URI and reference URI successfully
3. read representative wildcard docs URI successfully

Acceptance Criteria for Step 5 Completion

Step 5 is complete when all are true:

1. Resource registration is fully registry-driven (no per-skill hardcoded decorators required for core docs surfaces).
2. RFC6570 templates are used for parameterized URI families, including wildcard where needed.
3. All docs resources declare explicit MIME types and read-only/idempotent annotations.
4. on_duplicate_resources="error" is enabled and verified by tests.
5. Startup fails safely on registration conflicts.

Non-goals for Step 5

1. No tool fallback discovery behavior implementation (Step 6).
2. No packaging build inclusion mechanics (Step 7).
3. No CI gate expansion details (Step 9).
4. No migration shims for legacy URI aliases in the greenfield baseline.
5. No ranking-strategy implementation for discovery tools beyond what is needed to preserve deterministic resource-first discovery contracts.
6. No backward-compat resource aliases, adapter handlers, or dual registration paths.