From 323f02102d89cd6db5257a70952eee563596bdc8 Mon Sep 17 00:00:00 2001 From: John Lancaster <32917998+jsl12@users.noreply.github.com> Date: Sat, 20 Jun 2026 19:30:37 -0500 Subject: [PATCH] step6 --- .../plan-fastMcpServerGreenfield.prompt.md | 4 +- .github/prompts/plan-step6.prompt.md | 67 +++++++++++++++++++ 2 files changed, 69 insertions(+), 2 deletions(-) diff --git a/.github/prompts/plan-fastMcpServerGreenfield.prompt.md b/.github/prompts/plan-fastMcpServerGreenfield.prompt.md index 7ac7ecc..09ddcd2 100644 --- a/.github/prompts/plan-fastMcpServerGreenfield.prompt.md +++ b/.github/prompts/plan-fastMcpServerGreenfield.prompt.md @@ -8,7 +8,7 @@ Create a docs-first FastMCP architecture where all Markdown remains in docs/ as 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. Deliverable: update the current docs/ directory with the finalized URI contract and break-and-replace policy from this step. 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. -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. Define canonical fallback tool names (`list_resources`, `read_resource`, `search_patterns`, `get_pattern_by_id`, `get_skill_document_by_id`), research host-specific naming behavior for GitHub Copilot, Cursor, Claude Desktop, and generic MCP clients, and require client-side name mapping or intentionally documented aliases when providers expose namespaced wrappers. Depends on step 5. 7. Phase 3: Implement packaging so docs/ is copied into package resource space at build time (wheel + sdist) while docs/ remains canonical in source control. Use importlib.resources at runtime only; avoid direct filesystem assumptions. Depends on steps 4-6. 8. Phase 3: Remove materialization coupling between skill source modules and docs. The website build reads docs/ directly, while MCP reads packaged docs resources from the installed package. This preserves one authored source with two distribution surfaces. Depends on step 7. 9. Phase 4: Add validation and CI gates: frontmatter schema checks, URI uniqueness checks, reference integrity checks, docs build check, package content check, and stdio smoke checks that read representative skill/document resources from an installed wheel. Depends on steps 5-8. @@ -31,7 +31,7 @@ Create a docs-first FastMCP architecture where all Markdown remains in docs/ as 2. Run uv run pytest -q with tests that validate frontmatter parsing, URI generation, reference mapping, and catalog responses. 3. Run a packaging integrity check using importlib.resources.files(...) to confirm packaged docs resources exist and are readable from an installed wheel. 4. Run a stdio MCP smoke test that lists resources and reads at least one skill document and one reference document. -5. Run fallback-client smoke tests verifying list_resources/read_resource tools work and return expected metadata for both static and templated resources. +5. Run fallback-client smoke tests verifying list_resources/read_resource tools work and return expected metadata for both static and templated resources, and that GitHub Copilot, Cursor, Claude Desktop, and protocol-level SDK tests use canonical tool names or documented mapped aliases. **Decisions** - Anthropic compatibility: strict skill directory pattern with SKILL.md and references subtree. diff --git a/.github/prompts/plan-step6.prompt.md b/.github/prompts/plan-step6.prompt.md index effe93a..eb3802c 100644 --- a/.github/prompts/plan-step6.prompt.md +++ b/.github/prompts/plan-step6.prompt.md @@ -38,6 +38,26 @@ Applied conclusions for this step: 2. Tool-first compatibility layers should wrap canonical resource reads rather than creating alternate authored-content stores. 3. URI-template-backed resource identity remains stable across direct-resource and tool-compatibility access paths. +### Client Tool-Naming Research Baseline + +Authoritative and client-specific references to verify during implementation: + +1. [MCP specification: tools](https://modelcontextprotocol.io/specification/latest/server/tools) +2. [MCP client concepts](https://modelcontextprotocol.io/docs/learn/client-concepts) +3. [FastMCP tools](https://gofastmcp.com/servers/tools) +4. [FastMCP resources-as-tools transform](https://gofastmcp.com/servers/transforms/resources-as-tools) +5. [VS Code MCP servers](https://code.visualstudio.com/docs/agent-customization/mcp-servers) +6. [VS Code MCP configuration reference](https://code.visualstudio.com/docs/agents/reference/mcp-configuration) +7. [Cursor MCP documentation](https://docs.cursor.com/context/model-context-protocol) +8. [Claude Desktop local MCP server setup](https://support.anthropic.com/en/articles/10949351-getting-started-with-local-mcp-servers-on-claude-desktop) + +Baseline naming conclusions: + +1. MCP protocol tool identity is the server-advertised `name` returned by `tools/list` and used in `tools/call`. +2. FastMCP tool identity should be treated as the canonical server contract unless a tool is intentionally registered with an explicit alternate name. +3. Clients and host integrations may display, namespace, or internally route tool names with provider-specific prefixes, but those wrappers are not canonical server tool names. +4. Compatibility should be validated by observed `tools/list` and successful `tools/call` behavior in each target client rather than by assuming one global host naming convention. + ### Discovery Priority Contract (Normative) Preferred sequence for skill discovery and loading: @@ -73,6 +93,19 @@ The fallback tool surface includes: 4. `get_pattern_by_id` 5. `get_skill_document_by_id` +Canonical naming rule: + +1. The server-level tool contract uses the exact registered FastMCP tool names above. +2. Clients that expose provider-prefixed names (for example, namespaced wrappers) must map those names to the canonical server tool name before invocation. +3. `catalog_get_skill_document_by_id` is not a canonical server tool name for this contract unless an explicit alias is intentionally registered. + +Compatibility alias policy: + +1. Prefer canonical server tool names over aliases. +2. Add server-side aliases only when a major client cannot reliably map its wrapper name back to the canonical name. +3. Any alias must be read-only, delegate to the same payload builder as the canonical tool, and be documented as compatibility-only. +4. If aliases are added, canonical and alias tools must return byte-for-byte equivalent payloads for the same input. + Fallback order: 1. call `list_resources` to inspect canonical static/template resource surfaces @@ -85,6 +118,40 @@ Tool behavior requirements: 2. deterministic ordering and bounded pagination 3. explicit not-found responses (`found: false` style) where applicable 4. payloads remain schema-aligned with catalog resources +5. tool invocation examples and Copilot guidance must use canonical server tool names to avoid unknown-tool errors + +### Major Client Compatibility Plan + +Target clients and expected validation: + +1. GitHub Copilot in VS Code + - primary path: attach MCP resources when `MCP Resources...` is available + - fallback path: call `list_resources`, `read_resource`, then canonical thin tools only when needed + - validation: confirm Copilot-visible tool inventory includes or can invoke `list_resources`, `read_resource`, `search_patterns`, `get_pattern_by_id`, and `get_skill_document_by_id` + - compatibility risk: host-generated wrapper names may differ from canonical FastMCP names; document any observed wrapper-to-canonical mapping +2. Cursor + - primary path: use the client MCP server configuration and resource/tool surfaces supported by the active Cursor version + - fallback path: prefer resource-backed tools first, then canonical thin tools + - validation: capture Cursor `tools/list` equivalent behavior and verify the canonical tool names or required host mappings + - compatibility risk: Cursor may present MCP tools through its own UI labels or internal routing names +3. Claude Desktop + - primary path: configure the local MCP server and inspect advertised tools/resources in Claude Desktop + - fallback path: invoke canonical server tool names exactly as returned by `tools/list` + - validation: run a local smoke prompt that reads `resource://catalog/skills_index` and loads one skill document through `read_resource` or `get_skill_document_by_id` + - compatibility risk: local server configuration and transport setup may fail before tool-name compatibility is tested +4. Generic MCP clients and SDK-based tests + - primary path: protocol-level `resources/list`, `resources/read`, `tools/list`, and `tools/call` + - fallback path: none beyond the canonical tool contract + - validation: automated smoke tests assert exact tool names returned by `tools/list` and successful calls for canonical names + - compatibility risk: SDK/client libraries may expose helper names that differ from raw protocol names + +Implementation checklist: + +1. Capture each target client's advertised tool names before adding aliases. +2. Prefer fixing documentation or client-side mapping when the server already advertises canonical names correctly. +3. Add a server-side alias only for a confirmed major-client incompatibility. +4. Add regression tests for canonical names, resource-backed tools, and any intentionally supported aliases. +5. Keep public examples centered on `list_resources`/`read_resource` and canonical thin tool names. ### Resources-As-Tools Compatibility Layer