@yawlabs/mcp-compliance 0.10.1 → 0.11.0

package/README.md

@@ -5,7 +5,7 @@
 [![GitHub stars](https://img.shields.io/github/stars/YawLabs/mcp-compliance)](https://github.com/YawLabs/mcp-compliance/stargazers)
 [![CI](https://github.com/YawLabs/mcp-compliance/actions/workflows/ci.yml/badge.svg)](https://github.com/YawLabs/mcp-compliance/actions/workflows/ci.yml)
 
-**Test any MCP server for spec compliance.** 85-test suite covering transport, lifecycle, tools, resources, prompts, error handling, schema validation, and security against the [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25). Works against **HTTP endpoints** (`https://my-server.com/mcp`) and **stdio servers** (`npx @modelcontextprotocol/server-filesystem /tmp`) alike. CLI, MCP server, and programmatic API.
+**Test any MCP server for spec compliance.** 88-test suite covering transport, lifecycle, tools, resources, prompts, error handling, schema validation, and security against the [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25). Works against **HTTP endpoints** (`https://my-server.com/mcp`) and **stdio servers** (`npx @modelcontextprotocol/server-filesystem /tmp`) alike. CLI, MCP server, and programmatic API.
 
 Built and maintained by [Yaw Labs](https://yaw.sh).
 
@@ -479,7 +479,7 @@ Restart your MCP client and approve the server when prompted.
 
 ### Tools
 
-- **mcp_compliance_test** — Run the full 85-test suite against a URL or stdio command. Supports auth, custom headers, env vars, timeout, retries, and category/test filtering. Returns grade, score, and detailed results.
+- **mcp_compliance_test** — Run the full 88-test suite against a URL or stdio command. Supports auth, custom headers, env vars, timeout, retries, and category/test filtering. Returns grade, score, and detailed results.
 - **mcp_compliance_badge** — Get the badge markdown/HTML for a server. Supports auth and custom headers.
 - **mcp_compliance_explain** — Explain what a specific test ID checks and why it matters.
 
@@ -540,8 +540,16 @@ Consumer guidance:
 
 The compliance testing methodology is published as an open specification:
 
-- **[MCP Compliance Testing Specification](./MCP_COMPLIANCE_SPEC.md)** — test execution model, scoring algorithm, all 84 test rules with pass/fail criteria (CC BY 4.0)
+- **[MCP Compliance Testing Specification](./MCP_COMPLIANCE_SPEC.md)** — test execution model, scoring algorithm, all 88 test rules with pass/fail criteria (CC BY 4.0)
 - **[Machine-readable rule catalog](./mcp-compliance-rules.json)** — JSON Schema-compliant catalog for programmatic consumption
+- **[Why `mcp-compliance`](./docs/WHY.md)** — the problem, existing alternatives, what this tool does differently
+- **[Fixing common failures](./docs/FIXES.md)** — recipes for the most frequent test failures with code snippets
+- **[Spec version migration policy](./docs/SPEC_VERSION_MIGRATION.md)** — how this tool evolves with MCP spec releases
+- **[mcp.hosting external API](./docs/EXT_API.md)** — public submit/retrieve/badge/delete endpoints used by `mcp-compliance badge` and any custom integrations
+- **[Enterprise tier (draft)](./docs/ENTERPRISE.md)** — paid tier structure for organizations with scheduled/private/audit-track compliance needs
+- **[Performance deep-dive](./docs/PERFORMANCE.md)** — why the suite is sequential and what parallel execution would cost
+- **[Spec PR drafts](./docs/spec-prs/)** — our proposed MCP spec clarifications for ambiguous cases we've hit
+- **[mcp.hosting integration spec](./docs/mcp-hosting-integration.md)** — the contract between this engine and the mcp.hosting platform: URL surfaces, data flow, storage model, badge API, leaderboard, router integration
 
 These are complementary to (not competing with) the [official MCP specification](https://modelcontextprotocol.io/specification/2025-11-25). The MCP spec defines what servers must do; this spec defines how to verify compliance.
 

package/dist/{chunk-7KISK3FS.js → chunk-DGGPE3ZM.js}

@@ -701,6 +701,33 @@ var TEST_DEFINITIONS = [
     description: "Sends a tools/call request with _meta.progressToken and checks if the server sends progress notifications via SSE. Progress support is optional but recommended for long-running operations.",
     recommendation: "When a request includes _meta.progressToken, send notifications/progress events via SSE to report progress. Include progressToken, progress (current), and optionally total fields."
   },
+  {
+    id: "lifecycle-sampling-capability",
+    name: "Sampling capability shape",
+    category: "lifecycle",
+    required: false,
+    specRef: "client/sampling",
+    description: "If the server's initialize response or serverInfo implies it uses client-side sampling (sampling/createMessage), verify the capability declaration shape. Currently this is an advisory shape check \u2014 actually exercising the server\u2192client flow requires a client-side sampling handler and is out of scope.",
+    recommendation: "Sampling is a client capability (the client provides LLM access to the server). Servers don't declare sampling in their own capabilities; they just call sampling/createMessage against clients that advertise it. No server-side action required."
+  },
+  {
+    id: "lifecycle-roots-capability",
+    name: "Roots capability shape",
+    category: "lifecycle",
+    required: false,
+    specRef: "client/roots",
+    description: "Roots (filesystem root paths) is a client capability. This test verifies that if a server sends roots/list requests, it handles gracefully when the client doesn't declare the roots capability (i.e., doesn't crash).",
+    recommendation: "Before calling roots/list, check if the initialized client capabilities include 'roots'. If not, skip the call \u2014 the client can't respond. Never assume roots is available; it's opt-in on the client side."
+  },
+  {
+    id: "lifecycle-elicitation-capability",
+    name: "Elicitation capability shape",
+    category: "lifecycle",
+    required: false,
+    specRef: "client/elicitation",
+    description: "Elicitation (asking the user for structured input mid-operation) is a client capability added in 2025-11-25. This test verifies servers that use elicitation/create handle the case where clients don't support it.",
+    recommendation: "Before calling elicitation/create, check the initialized client capabilities. If elicitation is absent, fall back to a safer default (ask once up-front via tool parameters, or fail cleanly with a clear error)."
+  },
   {
     id: "lifecycle-meta-tolerance",
     name: "Tolerates _meta field on requests",
@@ -1604,7 +1631,11 @@ async function runComplianceSuite(target, options = {}) {
     try {
       initRes = await rpc("initialize", {
         protocolVersion: SPEC_VERSION,
-        capabilities: {},
+        capabilities: {
+          sampling: {},
+          roots: { listChanged: true },
+          elicitation: {}
+        },
         clientInfo: { name: "mcp-compliance", version: TOOL_VERSION }
       });
       const result = initRes?.body?.result;
@@ -2026,6 +2057,47 @@ async function runComplianceSuite(target, options = {}) {
         }
       }
     );
+    await test(
+      "lifecycle-sampling-capability",
+      "Sampling capability shape",
+      "lifecycle",
+      false,
+      "client/sampling",
+      async () => {
+        if (!initRes || initRes.body?.error) {
+          return { passed: false, details: "Server rejected initialize" };
+        }
+        return {
+          passed: true,
+          details: "Server accepted initialize with client sampling capability. Full server\u2192client sampling flow not exercised."
+        };
+      }
+    );
+    await test("lifecycle-roots-capability", "Roots capability shape", "lifecycle", false, "client/roots", async () => {
+      if (!initRes || initRes.body?.error) {
+        return { passed: false, details: "Server rejected initialize" };
+      }
+      return {
+        passed: true,
+        details: "Server accepted initialize. Full server\u2192client roots/list flow not exercised (requires a roots-aware client)."
+      };
+    });
+    await test(
+      "lifecycle-elicitation-capability",
+      "Elicitation capability shape",
+      "lifecycle",
+      false,
+      "client/elicitation",
+      async () => {
+        if (!initRes || initRes.body?.error) {
+          return { passed: false, details: "Server rejected initialize" };
+        }
+        return {
+          passed: true,
+          details: "Server accepted initialize. Full server\u2192client elicitation/create flow not exercised."
+        };
+      }
+    );
     await test(
       "lifecycle-meta-tolerance",
       "Tolerates _meta field on requests",
@@ -3958,6 +4030,7 @@ async function runComplianceSuite(target, options = {}) {
 }
 
 export {
+  urlHash,
   generateBadge,
   computeGrade,
   computeScore,

package/dist/index.js

@@ -1047,6 +1047,33 @@ var TEST_DEFINITIONS = [
     description: "Sends a tools/call request with _meta.progressToken and checks if the server sends progress notifications via SSE. Progress support is optional but recommended for long-running operations.",
     recommendation: "When a request includes _meta.progressToken, send notifications/progress events via SSE to report progress. Include progressToken, progress (current), and optionally total fields."
   },
+  {
+    id: "lifecycle-sampling-capability",
+    name: "Sampling capability shape",
+    category: "lifecycle",
+    required: false,
+    specRef: "client/sampling",
+    description: "If the server's initialize response or serverInfo implies it uses client-side sampling (sampling/createMessage), verify the capability declaration shape. Currently this is an advisory shape check \u2014 actually exercising the server\u2192client flow requires a client-side sampling handler and is out of scope.",
+    recommendation: "Sampling is a client capability (the client provides LLM access to the server). Servers don't declare sampling in their own capabilities; they just call sampling/createMessage against clients that advertise it. No server-side action required."
+  },
+  {
+    id: "lifecycle-roots-capability",
+    name: "Roots capability shape",
+    category: "lifecycle",
+    required: false,
+    specRef: "client/roots",
+    description: "Roots (filesystem root paths) is a client capability. This test verifies that if a server sends roots/list requests, it handles gracefully when the client doesn't declare the roots capability (i.e., doesn't crash).",
+    recommendation: "Before calling roots/list, check if the initialized client capabilities include 'roots'. If not, skip the call \u2014 the client can't respond. Never assume roots is available; it's opt-in on the client side."
+  },
+  {
+    id: "lifecycle-elicitation-capability",
+    name: "Elicitation capability shape",
+    category: "lifecycle",
+    required: false,
+    specRef: "client/elicitation",
+    description: "Elicitation (asking the user for structured input mid-operation) is a client capability added in 2025-11-25. This test verifies servers that use elicitation/create handle the case where clients don't support it.",
+    recommendation: "Before calling elicitation/create, check the initialized client capabilities. If elicitation is absent, fall back to a safer default (ask once up-front via tool parameters, or fail cleanly with a clear error)."
+  },
   {
     id: "lifecycle-meta-tolerance",
     name: "Tolerates _meta field on requests",
@@ -1950,7 +1977,11 @@ async function runComplianceSuite(target, options = {}) {
     try {
       initRes = await rpc("initialize", {
         protocolVersion: SPEC_VERSION,
-        capabilities: {},
+        capabilities: {
+          sampling: {},
+          roots: { listChanged: true },
+          elicitation: {}
+        },
         clientInfo: { name: "mcp-compliance", version: TOOL_VERSION }
       });
       const result = initRes?.body?.result;
@@ -2372,6 +2403,47 @@ async function runComplianceSuite(target, options = {}) {
         }
       }
     );
+    await test(
+      "lifecycle-sampling-capability",
+      "Sampling capability shape",
+      "lifecycle",
+      false,
+      "client/sampling",
+      async () => {
+        if (!initRes || initRes.body?.error) {
+          return { passed: false, details: "Server rejected initialize" };
+        }
+        return {
+          passed: true,
+          details: "Server accepted initialize with client sampling capability. Full server\u2192client sampling flow not exercised."
+        };
+      }
+    );
+    await test("lifecycle-roots-capability", "Roots capability shape", "lifecycle", false, "client/roots", async () => {
+      if (!initRes || initRes.body?.error) {
+        return { passed: false, details: "Server rejected initialize" };
+      }
+      return {
+        passed: true,
+        details: "Server accepted initialize. Full server\u2192client roots/list flow not exercised (requires a roots-aware client)."
+      };
+    });
+    await test(
+      "lifecycle-elicitation-capability",
+      "Elicitation capability shape",
+      "lifecycle",
+      false,
+      "client/elicitation",
+      async () => {
+        if (!initRes || initRes.body?.error) {
+          return { passed: false, details: "Server rejected initialize" };
+        }
+        return {
+          passed: true,
+          details: "Server accepted initialize. Full server\u2192client elicitation/create flow not exercised."
+        };
+      }
+    );
     await test(
       "lifecycle-meta-tolerance",
       "Tolerates _meta field on requests",

package/dist/mcp/server.js

@@ -2,7 +2,7 @@ import {
   SPEC_BASE,
   TEST_DEFINITIONS,
   runComplianceSuite
-} from "../chunk-7KISK3FS.js";
+} from "../chunk-DGGPE3ZM.js";
 
 // src/mcp/server.ts
 import { existsSync, readFileSync } from "fs";

package/dist/runner.d.ts

@@ -98,6 +98,16 @@ declare function computeScore(tests: TestResult[]): {
     }>;
 };
 
+/**
+ * Generate a short, deterministic hash of a URL for badge paths.
+ * SHA-256 truncated to 24 hex chars (96 bits of entropy) — matches the
+ * server-side hash width used by mcp.hosting for `/compliance/ext/<hash>`.
+ *
+ * Exported so mcp.hosting (and other consumers) can compute matching
+ * hashes when looking up reports/badges by URL. The hash is the canonical
+ * key for `/compliance/ext/<hash>` and `/api/compliance/ext/<hash>/badge`.
+ */
+declare function urlHash(url: string): string;
 /**
  * Generate badge URLs and markdown for a compliance report.
  * Badge images are served by mcp.hosting.
@@ -165,4 +175,4 @@ interface RunOptions {
  */
 declare function runComplianceSuite(target: string | TransportTarget, options?: RunOptions): Promise<ComplianceReport>;
 
-export { type ComplianceReport, type PreviewOptions, type RunOptions, SPEC_BASE, SPEC_VERSION, TEST_DEFINITIONS, type TestResult, computeGrade, computeScore, generateBadge, parseSSEResponse, previewTests, runComplianceSuite };
+export { type ComplianceReport, type PreviewOptions, type RunOptions, SPEC_BASE, SPEC_VERSION, TEST_DEFINITIONS, type TestResult, computeGrade, computeScore, generateBadge, parseSSEResponse, previewTests, runComplianceSuite, urlHash };

package/dist/runner.js

@@ -7,8 +7,9 @@ import {
   generateBadge,
   parseSSEResponse,
   previewTests,
-  runComplianceSuite
-} from "./chunk-7KISK3FS.js";
+  runComplianceSuite,
+  urlHash
+} from "./chunk-DGGPE3ZM.js";
 export {
   SPEC_BASE,
   SPEC_VERSION,
@@ -18,5 +19,6 @@ export {
   generateBadge,
   parseSSEResponse,
   previewTests,
-  runComplianceSuite
+  runComplianceSuite,
+  urlHash
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yawlabs/mcp-compliance",
-  "version": "0.10.1",
+  "version": "0.11.0",
   "description": "CLI tool and MCP server that tests MCP servers for spec compliance",
   "license": "MIT",
   "author": "Yaw Labs <contact@yaw.sh> (https://yaw.sh)",