step6

.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.

.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