refactor(mcp): centralize presentation contract markers and document versioning

This refactor enhances the maintainability of the MCP stdio safety contract:

- Centralized markers in `src/constants/markers.ts` (single source of truth)

- Updated renderer and tests to import markers, eliminating drift risk

- Documented marker versioning rules in README to prevent accidental breaking changes

Author: PaulJPhilp

packages/mcp-server/README.md

@@ -900,6 +900,17 @@ The server implements a hierarchical logging system to ensure production safety
 
 **Note:** All logs are strictly routed to `stderr` to prevent interference with the MCP protocol on `stdout`.
 
+## Presentation Contract
+
+The server output embeds stable, hidden contract markers to facilitate automated testing and client integration without relying on brittle markdown styling.
+
+- **`<!-- kind:pattern-index:v1 -->`**: Indicates the presence of the search results index table.
+- **`<!-- kind:pattern-card:v1 -->`**: Indicates the start of a pattern detail card.
+
+These markers are guaranteed to be present in the raw tool output content, enabling robust regression testing of the presentation layer.
+
+**Versioning Rule:** If marker semantics change, the version suffix (e.g., `v1`) must be incremented, and backward compatibility should be maintained where feasible.
+
 ## CI/CD Requirements
 
 Integration tests (`test:integration`) require specific environment variables in your CI/CD pipeline:

packages/mcp-server/src/constants/markers.ts

@@ -0,0 +1,14 @@
+/**
+ * Presentation Contract Markers
+ *
+ * These hidden HTML comments serve as stable contract markers for automated testing
+ * and client integration. They ensure that even if the visual markdown styling changes,
+ * the structural semantics of the output remain verifiable.
+ *
+ * Usage:
+ * - Renderers include these markers in the output.
+ * - Tests assert the presence and count of these markers.
+ */
+
+export const MARKER_PATTERN_INDEX_V1 = "<!-- kind:pattern-index:v1 -->";
+export const MARKER_PATTERN_CARD_V1 = "<!-- kind:pattern-card:v1 -->";

packages/mcp-server/src/mcp-content-builders.ts

@@ -12,6 +12,10 @@
  */
 
 import type { TextContent } from "@modelcontextprotocol/sdk/shared/messages.js";
+import {
+  MARKER_PATTERN_CARD_V1,
+  MARKER_PATTERN_INDEX_V1,
+} from "./constants/markers.js";
 
 /**
  * MCP 2.0 Annotation structure
@@ -678,7 +682,7 @@ function buildScanFirstPatternContent(pattern: PatternData): TextContent[] {
 
   // Hidden presentation marker for contract testing
   content.push(
-    createTextBlock("<!-- kind:pattern-card:v1 -->", {
+    createTextBlock(MARKER_PATTERN_CARD_V1, {
       priority: 1,
       audience: ["user"],
     })
@@ -815,7 +819,7 @@ function buildIndexTable(patterns: readonly PatternData[]): string {
 
   // Pre-allocate buffer and use single join pass (O(N) instead of O(N²))
   const rows: string[] = [];
-  rows.push("<!-- kind:pattern-index:v1 -->"); // Hidden marker for contract testing
+  rows.push(MARKER_PATTERN_INDEX_V1); // Hidden marker for contract testing
   rows.push("| Pattern | Category | Difficulty | Tags |");
   rows.push("| :--- | :--- | :--- | :--- |");
 

packages/mcp-server/tests/mcp-protocol/local.test.ts

@@ -19,6 +19,10 @@
 import { describe, it, expect, beforeAll, afterEach } from "vitest";
 import { MCPTestClient, createMCPTestClient } from "./helpers/mcp-test-client";
 import { getMCPEnvironmentConfig } from "../../src/config/mcp-environments";
+import {
+  MARKER_PATTERN_CARD_V1,
+  MARKER_PATTERN_INDEX_V1,
+} from "../../src/constants/markers";
 
 function extractContentText(
   content: Array<{ type: string; text?: string }> | { type: string; text?: string }
@@ -129,11 +133,11 @@ describe("Local MCP Server", () => {
       }
 
       // Positive assertion: Check for contractual structural markers (stable IDs and markers)
-      expect(searchText).toContain("<!-- kind:pattern-index:v1 -->"); // Index contract marker
-      expect(searchText).toContain("<!-- kind:pattern-card:v1 -->"); // Card contract marker
+      expect(searchText).toContain(MARKER_PATTERN_INDEX_V1); // Index contract marker
+      expect(searchText).toContain(MARKER_PATTERN_CARD_V1); // Card contract marker
 
       // Ensure cards are rendered (K=1 requested in args)
-      const cardMatches = searchText.match(/<!-- kind:pattern-card:v1 -->/g);
+      const cardMatches = searchText.match(new RegExp(MARKER_PATTERN_CARD_V1, "g"));
       expect(cardMatches?.length).toBe(1);
 
       // Test 2: Get pattern
@@ -144,9 +148,9 @@ describe("Local MCP Server", () => {
 
       // Structural markers for single pattern card
       expect(getText).toMatch(/^# /m); // Markdown H1 title
-      expect(getText).toContain("<!-- kind:pattern-card:v1 -->"); // Contract marker
+      expect(getText).toContain(MARKER_PATTERN_CARD_V1); // Contract marker
 
-      const getCardMatches = getText.match(/<!-- kind:pattern-card:v1 -->/g);
+      const getCardMatches = getText.match(new RegExp(MARKER_PATTERN_CARD_V1, "g"));
       expect(getCardMatches?.length).toBe(1);
 
       expect(getText).toContain("**API:**");