john/prompts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

adjustments

Browse Source
This commit is contained in:
John Lancaster
2026-06-20 13:33:18 -05:00
parent 85355a8509
commit adaa4177fe
3 changed files with 29 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/prompts/plan-fastMcpServerGreenfield.prompt.md
+2 -2
View File
@@ -5,7 +5,7 @@ Create a docs-first FastMCP architecture where all Markdown remains in docs/ as
**Steps** **Steps**
1. Phase 1: Define the end-state content contract. Confirm canonical structure as docs/skills/<skill-id>/SKILL.md plus docs/skills/<skill-id>/references/..., with strict per-skill ownership and no metadata.yaml sidecar. Also define stable skill-id rules (kebab-case, immutable after release). 1. Phase 1: Define the end-state content contract. Confirm canonical structure as docs/skills/<skill-id>/SKILL.md plus docs/skills/<skill-id>/references/..., with strict per-skill ownership and no metadata.yaml sidecar. Also define stable skill-id rules (kebab-case, immutable after release).
2. Phase 1: Define SKILL.md frontmatter schema with Pydantic-compatible fields: id, version, name, description, tags, capabilities, depends_on, and references manifest entries. The references manifest must map logical reference ids to relative paths so each skill can reorganize references internally without changing global server code. Depends on step 1. 2. Phase 1: Define SKILL.md frontmatter schema with Pydantic-compatible fields: id, version, name, description, tags, capabilities, depends_on, and references manifest entries. The references manifest must map logical reference ids to relative paths so each skill can reorganize references internally without changing global server code. Depends on step 1.
3. Phase 1: Define URI contract and lightweight compatibility policy. Recommend resource://catalog/skills_index, resource://catalog/skills/{skill_id}, resource://skills/{skill_id}/document, resource://skills/{skill_id}/references/{ref_id}, and resource://docs/{path*}. Add change-friendly guidance for evolving URIs and reference ids with optional short-lived aliases when needed. Depends on steps 1-2. 3. Phase 1: Define URI contract with explicit break-and-replace policy. Recommend resource://catalog/skills_index, resource://catalog/skills/{skill_id}, resource://skills/{skill_id}/document, resource://skills/{skill_id}/references/{ref_id}, and resource://docs/{path*}. Evolving URIs and reference ids requires direct replacement, with no aliases or compatibility shims. Depends on steps 1-2.
4. Phase 2: Build a docs registry loader that reads packaged docs via importlib.resources.files(...) Traversable APIs, parses SKILL.md frontmatter, validates schema, and creates an in-memory registry keyed by skill_id. Fail fast for duplicate ids, missing files, broken reference mappings, or invalid depends_on. Depends on steps 2-3. 4. Phase 2: Build a docs registry loader that reads packaged docs via importlib.resources.files(...) Traversable APIs, parses SKILL.md frontmatter, validates schema, and creates an in-memory registry keyed by skill_id. Fail fast for duplicate ids, missing files, broken reference mappings, or invalid depends_on. Depends on steps 2-3.
5. Phase 2: Register FastMCP resources from the registry using RFC6570 templates (including wildcard paths where appropriate), read-only/idempotent annotations, explicit mime types, and on_duplicate_resources="error" for startup safety. Depends on step 4. 5. Phase 2: Register FastMCP resources from the registry using RFC6570 templates (including wildcard paths where appropriate), read-only/idempotent annotations, explicit mime types, and on_duplicate_resources="error" for startup safety. Depends on step 4.
6. Phase 2: Add discovery surfaces as resources first, then tool fallback. Keep catalog discovery in resources, then add ResourcesAsTools for tool-only clients. Add thin discovery tools only for parity and optional BM25/regex tool search when catalog/tool volume grows enough to affect token efficiency. Depends on step 5. 6. Phase 2: Add discovery surfaces as resources first, then tool fallback. Keep catalog discovery in resources, then add ResourcesAsTools for tool-only clients. Add thin discovery tools only for parity and optional BM25/regex tool search when catalog/tool volume grows enough to affect token efficiency. Depends on step 5.
@@ -43,4 +43,4 @@ Create a docs-first FastMCP architecture where all Markdown remains in docs/ as
**Further Considerations** **Further Considerations**
1. Prefer recursive references support under each skill plus frontmatter manifest ids, so skill teams can reorganize internal reference folders without URI churn. 1. Prefer recursive references support under each skill plus frontmatter manifest ids, so skill teams can reorganize internal reference folders without URI churn.
2. Define a hard rule that skill_id and directory name must match exactly to eliminate namespace/slug drift classes of bugs. 2. Define a hard rule that skill_id and directory name must match exactly to eliminate namespace/slug drift classes of bugs.
3. Prefer optional, short-lived URI aliases only when active clients depend on older catalog or skill resource paths; otherwise simplify quickly. 3. Do not provide URI aliases; client updates must track canonical URI contract changes directly.
.github/prompts/plan-step4.prompt.md
+13 -3
View File
@@ -2,6 +2,15 @@
This section finalizes Step 4 by defining a production-ready docs registry loader that reads packaged docs through Python resource APIs, parses SKILL.md frontmatter, validates schema and cross-links, and builds an immutable in-memory registry keyed by skill_id. This section finalizes Step 4 by defining a production-ready docs registry loader that reads packaged docs through Python resource APIs, parses SKILL.md frontmatter, validates schema and cross-links, and builds an immutable in-memory registry keyed by skill_id.
### Greenfield Framing (Normative)
This Step 4 design is for the greenfield target state:
1. No legacy metadata sidecars (`metadata.yaml`) are part of the runtime contract.
2. No dual-loader compatibility path is required.
3. Registry loading from packaged resources is the only runtime source of truth.
4. Compatibility shims are prohibited.
### Research Baseline (Python + Design Guidance) ### Research Baseline (Python + Design Guidance)
Authoritative references used for this step: Authoritative references used for this step:
@@ -171,11 +180,11 @@ Runtime safety rules:
Primary integration target: Primary integration target:
1. Replace path-based logic in `src/personal_mcp/skills/document_loader.py` with package-resource-based registry loading. 1. Implement the canonical package-resource-based registry loader in `src/personal_mcp/skills/document_loader.py` as the only supported runtime loader path.
Catalog integration: Catalog integration:
1. Update `src/personal_mcp/catalog/server.py` to consume the shared in-memory registry instead of scanning `metadata.yaml` files. 1. Update `src/personal_mcp/catalog/server.py` to consume the shared in-memory registry as the only catalog data source.
2. Keep catalog payload normalization deterministic and sourced from registry records only. 2. Keep catalog payload normalization deterministic and sourced from registry records only.
Startup wiring: Startup wiring:
@@ -235,4 +244,5 @@ Step 4 is complete when all are true:
1. No FastMCP resource registration wiring details (Step 5). 1. No FastMCP resource registration wiring details (Step 5).
2. No discovery-tool fallback behavior design (Step 6). 2. No discovery-tool fallback behavior design (Step 6).
3. No final packaging/build-system migration mechanics (Step 7). 3. No final packaging/build-system migration mechanics (Step 7).
4. No backward-compat alias rollout mechanics beyond validation readiness. 4. No backward-compat alias rollout mechanics in the greenfield baseline.
5. No compatibility layer of any kind (URI aliases, dual reads, adapter shims, or legacy schema bridges).
.github/prompts/plan-step5.prompt.md
+14 -3
View File
@@ -2,6 +2,16 @@
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. 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) ### Research Baseline (FastMCP + URI Templates)
Authoritative references used for this step: Authoritative references used for this step:
@@ -159,9 +169,9 @@ Wildcard docs handler:
Primary composition updates: Primary composition updates:
1. Introduce registry-driven registration in [src/personal_mcp/mcp.py](src/personal_mcp/mcp.py). 1. Implement registry-driven registration in [src/personal_mcp/mcp.py](src/personal_mcp/mcp.py) as the canonical resource composition path.
2. Keep [src/personal_mcp/main.py](src/personal_mcp/main.py) responsible for startup wiring order (load registry first, then register resources). 2. Keep [src/personal_mcp/main.py](src/personal_mcp/main.py) responsible for startup wiring order (load registry first, then register resources).
3. Refactor [src/personal_mcp/catalog/server.py](src/personal_mcp/catalog/server.py) toward registry-backed handlers. 3. Use [src/personal_mcp/catalog/server.py](src/personal_mcp/catalog/server.py) as registry-backed handlers only.
Lifecycle order (required): Lifecycle order (required):
@@ -206,5 +216,6 @@ Step 5 is complete when all are true:
1. No tool fallback discovery behavior implementation (Step 6). 1. No tool fallback discovery behavior implementation (Step 6).
2. No packaging build inclusion mechanics (Step 7). 2. No packaging build inclusion mechanics (Step 7).
3. No CI gate expansion details (Step 9). 3. No CI gate expansion details (Step 9).
4. No migration shims for legacy URI aliases beyond what is needed to preserve current behavior. 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. 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.