@yawlabs/mcp-compliance 0.3.0 → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yaw Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -7,17 +7,31 @@
 
 **Test any MCP server for spec compliance.** 43-test suite covering transport, lifecycle, tools, resources, prompts, error handling, and schema validation against the [MCP specification](https://modelcontextprotocol.io/specification/2025-11-25). CLI, MCP server, and programmatic API.
 
-Built and maintained by [YawLabs](https://yaw.sh).
+Built and maintained by [Yaw Labs](https://yaw.sh).
 
-## Quick Start
+## Why this tool?
 
-**1. Run against any MCP server**
+MCP servers are multiplying fast — but most ship without compliance testing. Broken transport handling, missing error codes, malformed schemas, and silent capability violations are common. Hand-rolling test scripts is tedious and incomplete.
+
+This tool solves that:
+
+- **43 tests across 7 categories** — transport, lifecycle, tools, resources, prompts, error handling, and schema validation. No gaps.
+- **Capability-driven** — tests adapt to what the server declares. If it says it supports tools, tool tests become required. No false failures for features the server doesn't claim.
+- **Graded scoring** — A-F letter grade with a weighted score (required tests 70%, optional 30%). One number to communicate compliance.
+- **CI-ready** — `--strict` mode exits with code 1 on required test failures. Drop it into any pipeline.
+- **Spec-referenced** — every test links to the exact section of the MCP specification it validates. No ambiguity about what's being tested or why.
+- **Three interfaces** — CLI for humans, MCP server for AI assistants, programmatic API for integration.
+- **Published specification** — the [testing methodology](./MCP_COMPLIANCE_SPEC.md) and [rule catalog](./mcp-compliance-rules.json) are open (CC BY 4.0) so anyone can implement compatible tooling.
+
+## Quick start
+
+**Run against any MCP server:**
 
 ```bash
 npx @yawlabs/mcp-compliance test https://my-server.com/mcp
 ```
 
-**2. Or install globally**
+**Or install globally:**
 
 ```bash
 npm install -g @yawlabs/mcp-compliance
@@ -26,7 +40,7 @@ mcp-compliance test https://my-server.com/mcp
 
 That's it. You'll get a colored terminal report with a letter grade (A-F), per-test pass/fail, and a compliance score.
 
-## CLI Usage
+## CLI usage
 
 ```bash
 # Terminal output with colors and grade
@@ -35,6 +49,9 @@ mcp-compliance test https://my-server.com/mcp
 # JSON output (for scripting)
 mcp-compliance test https://my-server.com/mcp --format json
 
+# SARIF output (for GitHub Code Scanning)
+mcp-compliance test https://my-server.com/mcp --format sarif > compliance.sarif
+
 # Strict mode — exits with code 1 on required test failure (for CI)
 mcp-compliance test https://my-server.com/mcp --strict
 
@@ -65,7 +82,7 @@ mcp-compliance test https://my-server.com/mcp --verbose
 
 | Option | Description |
 |--------|-------------|
-| `--format <format>` | Output format: `terminal` or `json` (default: `terminal`) |
+| `--format <format>` | Output format: `terminal`, `json`, or `sarif` (default: `terminal`) |
 | `--strict` | Exit with code 1 on any required test failure (for CI) |
 | `-H, --header <header>` | Add header to all requests, format `"Key: Value"` (repeatable) |
 | `--auth <token>` | Shorthand for `-H "Authorization: <token>"` |
@@ -180,9 +197,9 @@ Outputs the markdown embed for a compliance badge hosted at [mcp.hosting](https:
 | D     | 40-59  |
 | F     | 0-39   |
 
-Required tests are worth 70% of the score, optional tests 30%.
+Required tests are worth 70% of the score, optional tests 30%. See the [full scoring algorithm](./MCP_COMPLIANCE_SPEC.md#2-scoring-algorithm) in the specification.
 
-## CI Integration
+## CI integration
 
 ```yaml
 # GitHub Actions example
@@ -204,13 +221,29 @@ Required tests are worth 70% of the score, optional tests 30%.
   run: npx @yawlabs/mcp-compliance test ${{ env.MCP_SERVER_URL }} --strict --retries 2 --timeout 30000
 ```
 
-## MCP Server (for Claude Code, Cursor, etc.)
+```yaml
+# SARIF output for GitHub Code Scanning
+- name: MCP Compliance Check
+  run: npx @yawlabs/mcp-compliance test ${{ env.MCP_SERVER_URL }} --format sarif > compliance.sarif
+- name: Upload SARIF
+  uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: compliance.sarif
+```
+
+## MCP server (for Claude Code, Cursor, etc.)
 
 This package also exposes an MCP server with 3 tools that can be used from Claude Code, Cursor, or any MCP client.
 
 ### Setup
 
-Create `.mcp.json` in your project root:
+**Claude Code (one-liner):**
+
+```bash
+claude mcp add mcp-compliance -- npx -y @yawlabs/mcp-compliance mcp
+```
+
+**Or create `.mcp.json` in your project root:**
 
 macOS / Linux / WSL:
 
@@ -250,7 +283,7 @@ Restart your MCP client and approve the server when prompted.
 
 All tools have [MCP tool annotations](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#annotations) (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) so MCP clients can skip confirmation dialogs for safe operations.
 
-## Programmatic Usage
+## Programmatic usage
 
 ```typescript
 import { runComplianceSuite } from '@yawlabs/mcp-compliance';
@@ -267,16 +300,48 @@ const report2 = await runComplianceSuite('https://my-server.com/mcp', {
 });
 ```
 
+## Specification
+
+The compliance testing methodology is published as an open specification:
+
+- **[MCP Compliance Testing Specification](./MCP_COMPLIANCE_SPEC.md)** — test execution model, scoring algorithm, all 43 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
+
+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.
+
 ## Requirements
 
 - Node.js 18+
 
+## Contributing
+
+```bash
+git clone https://github.com/YawLabs/mcp-compliance.git
+cd mcp-compliance
+npm install
+npm run build
+npm test
+```
+
+**Development commands:**
+
+| Command | Description |
+|---------|-------------|
+| `npm run build` | Compile with tsup |
+| `npm run dev` | Watch mode |
+| `npm test` | Run tests (vitest) |
+| `npm run lint` | Check with Biome |
+| `npm run lint:fix` | Auto-fix with Biome |
+| `npm run typecheck` | TypeScript type checking |
+| `npm run test:ci` | Build + test (CI-safe) |
+
 ## Links
 
 - [mcp.hosting](https://mcp.hosting) — Hosted MCP server infrastructure
 - [MCP Specification](https://modelcontextprotocol.io/specification/2025-11-25)
+- [MCP Compliance Testing Spec](./MCP_COMPLIANCE_SPEC.md)
 - [Yaw Labs](https://yaw.sh)
 
 ## License
 
-MIT
+MIT — see [LICENSE](./LICENSE).

package/dist/{chunk-U66YZGE5.js → chunk-KNOSZ3TD.js}

@@ -65,7 +65,8 @@ var TEST_DEFINITIONS = [
     category: "transport",
     required: true,
     specRef: "basic/transports#streamable-http",
-    description: "Verifies the server accepts HTTP POST requests and returns a 2xx status code. This is the fundamental transport requirement for Streamable HTTP MCP servers."
+    description: "Verifies the server accepts HTTP POST requests and returns a 2xx status code. This is the fundamental transport requirement for Streamable HTTP MCP servers.",
+    recommendation: "Ensure your server listens for POST requests on the MCP endpoint. If you see 401/403, pass --auth with a valid token. Check that the URL is correct and the server is running."
   },
   {
     id: "transport-content-type",
@@ -73,7 +74,8 @@ var TEST_DEFINITIONS = [
     category: "transport",
     required: true,
     specRef: "basic/transports#streamable-http",
-    description: "Checks that the server responds with Content-Type application/json or text/event-stream. MCP servers must use one of these two content types."
+    description: "Checks that the server responds with Content-Type application/json or text/event-stream. MCP servers must use one of these two content types.",
+    recommendation: 'Set the Content-Type response header to "application/json" for synchronous responses or "text/event-stream" for streaming. Do not use text/html or other types.'
   },
   {
     id: "transport-notification-202",
@@ -81,7 +83,8 @@ var TEST_DEFINITIONS = [
     category: "transport",
     required: false,
     specRef: "basic/transports#streamable-http",
-    description: "Verifies that sending a JSON-RPC notification (no id field) returns HTTP 202 Accepted with no body. Per spec, servers MUST return 202 for notifications."
+    description: "Verifies that sending a JSON-RPC notification (no id field) returns HTTP 202 Accepted with no body. Per spec, servers MUST return 202 for notifications.",
+    recommendation: "Detect JSON-RPC messages without an id field and return HTTP 202 with an empty body. Do not attempt to send a JSON-RPC response for notifications."
   },
   {
     id: "transport-session-id",
@@ -89,7 +92,8 @@ var TEST_DEFINITIONS = [
     category: "transport",
     required: false,
     specRef: "basic/transports#streamable-http",
-    description: "Tests that the server returns HTTP 400 when MCP-Session-Id header is missing on requests after initialization (when the server issued a session ID)."
+    description: "Tests that the server returns HTTP 400 when MCP-Session-Id header is missing on requests after initialization (when the server issued a session ID).",
+    recommendation: "If your server issues an MCP-Session-Id header in the initialize response, reject subsequent requests that omit this header with HTTP 400."
   },
   {
     id: "transport-get",
@@ -97,7 +101,8 @@ var TEST_DEFINITIONS = [
     category: "transport",
     required: false,
     specRef: "basic/transports#streamable-http",
-    description: "Tests the GET endpoint for server-initiated messages. Server should return text/event-stream or 405 Method Not Allowed."
+    description: "Tests the GET endpoint for server-initiated messages. Server should return text/event-stream or 405 Method Not Allowed.",
+    recommendation: "If your server supports server-initiated messages, handle GET with text/event-stream. Otherwise, return 405 Method Not Allowed."
   },
   {
     id: "transport-delete",
@@ -105,7 +110,8 @@ var TEST_DEFINITIONS = [
     category: "transport",
     required: false,
     specRef: "basic/transports#streamable-http",
-    description: "Tests the DELETE endpoint for session termination. Server should accept the request or return 405 Method Not Allowed."
+    description: "Tests the DELETE endpoint for session termination. Server should accept the request or return 405 Method Not Allowed.",
+    recommendation: "Handle DELETE requests for session cleanup, or return 405 if session termination is not supported. Do not return 500."
   },
   {
     id: "transport-batch-reject",
@@ -113,7 +119,8 @@ var TEST_DEFINITIONS = [
     category: "transport",
     required: true,
     specRef: "basic/transports#streamable-http",
-    description: "Sends a JSON-RPC batch request (array of messages) and verifies the server rejects it with an error. MCP does not support JSON-RPC batch requests."
+    description: "Sends a JSON-RPC batch request (array of messages) and verifies the server rejects it with an error. MCP does not support JSON-RPC batch requests.",
+    recommendation: "Check if the parsed JSON body is an array. If so, return a JSON-RPC error or HTTP 400. Do not process batch requests \u2014 MCP explicitly forbids them."
   },
   // ── Lifecycle (10 tests) ─────────────────────────────────────────
   {
@@ -122,7 +129,8 @@ var TEST_DEFINITIONS = [
     category: "lifecycle",
     required: true,
     specRef: "basic/lifecycle#initialization",
-    description: "Tests the initialize handshake by sending an initialize request with client capabilities. The server must return a result with protocolVersion."
+    description: "Tests the initialize handshake by sending an initialize request with client capabilities. The server must return a result with protocolVersion.",
+    recommendation: 'Implement the "initialize" method handler. Return a result object with at least protocolVersion, capabilities, and serverInfo fields.'
   },
   {
     id: "lifecycle-proto-version",
@@ -130,7 +138,8 @@ var TEST_DEFINITIONS = [
     category: "lifecycle",
     required: true,
     specRef: "basic/lifecycle#version-negotiation",
-    description: "Validates that the protocolVersion returned by the server matches the YYYY-MM-DD date format required by the spec."
+    description: "Validates that the protocolVersion returned by the server matches the YYYY-MM-DD date format required by the spec.",
+    recommendation: `Return protocolVersion as a YYYY-MM-DD string (e.g., "2025-11-25"). The server should negotiate based on the client's requested version.`
   },
   {
     id: "lifecycle-server-info",
@@ -138,7 +147,8 @@ var TEST_DEFINITIONS = [
     category: "lifecycle",
     required: false,
     specRef: "basic/lifecycle#initialization",
-    description: "Checks that the server includes a serverInfo object with at least a name field in its initialize response. While recommended, this is not strictly required."
+    description: "Checks that the server includes a serverInfo object with at least a name field in its initialize response. While recommended, this is not strictly required.",
+    recommendation: 'Add a serverInfo object to your initialize response: { name: "your-server", version: "1.0.0" }. This helps clients identify your server.'
   },
   {
     id: "lifecycle-capabilities",
@@ -146,7 +156,8 @@ var TEST_DEFINITIONS = [
     category: "lifecycle",
     required: true,
     specRef: "basic/lifecycle#capability-negotiation",
-    description: "Verifies the server returns a capabilities object in its initialize response. An empty object is valid (no optional features declared)."
+    description: "Verifies the server returns a capabilities object in its initialize response. An empty object is valid (no optional features declared).",
+    recommendation: "Include a capabilities object in your initialize response. Declare the features your server supports (tools, resources, prompts, logging, etc.). An empty object {} is valid."
   },
   {
     id: "lifecycle-jsonrpc",
@@ -154,7 +165,8 @@ var TEST_DEFINITIONS = [
     category: "lifecycle",
     required: true,
     specRef: "basic",
-    description: 'Validates that the initialize response is a proper JSON-RPC 2.0 message with jsonrpc="2.0", an id field, and either a result or error field.'
+    description: 'Validates that the initialize response is a proper JSON-RPC 2.0 message with jsonrpc="2.0", an id field, and either a result or error field.',
+    recommendation: 'Ensure every response includes jsonrpc: "2.0", the matching id from the request, and either a result or error field. Never omit the jsonrpc field.'
   },
   {
     id: "lifecycle-ping",
@@ -162,7 +174,8 @@ var TEST_DEFINITIONS = [
     category: "lifecycle",
     required: true,
     specRef: "basic/utilities#ping",
-    description: "Tests that the server responds to the ping method with an empty result object. This is a required utility method."
+    description: "Tests that the server responds to the ping method with an empty result object. This is a required utility method.",
+    recommendation: 'Implement a "ping" method handler that returns an empty result object {}. This is required by the MCP spec for keepalive and connectivity checking.'
   },
   {
     id: "lifecycle-instructions",
@@ -170,7 +183,8 @@ var TEST_DEFINITIONS = [
     category: "lifecycle",
     required: false,
     specRef: "basic/lifecycle#initialization",
-    description: "If the server includes an instructions field in the initialize response, validates it is a string. Instructions provide guidance for how the client should interact with the server."
+    description: "If the server includes an instructions field in the initialize response, validates it is a string. Instructions provide guidance for how the client should interact with the server.",
+    recommendation: "If you include an instructions field in the initialize response, ensure it is a string. Remove the field or fix the type if it is not a string."
   },
   {
     id: "lifecycle-id-match",
@@ -178,7 +192,8 @@ var TEST_DEFINITIONS = [
     category: "lifecycle",
     required: true,
     specRef: "basic",
-    description: "Verifies that the JSON-RPC response id matches the request id sent by the client. This is a fundamental JSON-RPC 2.0 requirement."
+    description: "Verifies that the JSON-RPC response id matches the request id sent by the client. This is a fundamental JSON-RPC 2.0 requirement.",
+    recommendation: "Copy the id field from the request into the response. This is a core JSON-RPC 2.0 requirement. Check that your framework does not modify or discard the request ID."
   },
   {
     id: "lifecycle-logging",
@@ -186,7 +201,8 @@ var TEST_DEFINITIONS = [
     category: "lifecycle",
     required: false,
     specRef: "server/utilities#logging",
-    description: "If the server declares logging capability, tests that logging/setLevel method is accepted with a valid log level."
+    description: "If the server declares logging capability, tests that logging/setLevel method is accepted with a valid log level.",
+    recommendation: 'If you declare logging in capabilities, implement the "logging/setLevel" handler. Accept standard log levels: debug, info, notice, warning, error, critical, alert, emergency.'
   },
   {
     id: "lifecycle-completions",
@@ -194,7 +210,8 @@ var TEST_DEFINITIONS = [
     category: "lifecycle",
     required: false,
     specRef: "server/utilities#completion",
-    description: "If the server declares completions capability, tests that the completion/complete method is accepted."
+    description: "If the server declares completions capability, tests that the completion/complete method is accepted.",
+    recommendation: 'If you declare completions in capabilities, implement the "completion/complete" handler. Return a completion object with a values array, even if empty.'
   },
   // ── Tools (4 tests) ──────────────────────────────────────────────
   {
@@ -203,7 +220,8 @@ var TEST_DEFINITIONS = [
     category: "tools",
     required: false,
     specRef: "server/tools#listing-tools",
-    description: "Calls tools/list and validates it returns an array of tool definitions. Required if the server declares tools capability."
+    description: "Calls tools/list and validates it returns an array of tool definitions. Required if the server declares tools capability.",
+    recommendation: "Implement the tools/list handler to return { tools: [...] } with an array of tool definition objects. Each tool needs at least a name and inputSchema."
   },
   {
     id: "tools-call",
@@ -211,7 +229,8 @@ var TEST_DEFINITIONS = [
     category: "tools",
     required: false,
     specRef: "server/tools#calling-tools",
-    description: "Calls the first tool with empty arguments and verifies the response format. Accepts both successful results and InvalidParams errors."
+    description: "Calls the first tool with empty arguments and verifies the response format. Accepts both successful results and InvalidParams errors.",
+    recommendation: "Ensure tools/call returns { content: [...] } with an array of content objects, each having a type field. Return isError: true for tool execution errors."
   },
   {
     id: "tools-pagination",
@@ -219,7 +238,8 @@ var TEST_DEFINITIONS = [
     category: "tools",
     required: false,
     specRef: "server/tools#listing-tools",
-    description: "Tests cursor-based pagination on tools/list. Validates nextCursor is a string if present and that fetching the next page returns a valid response."
+    description: "Tests cursor-based pagination on tools/list. Validates nextCursor is a string if present and that fetching the next page returns a valid response.",
+    recommendation: "If your server has many tools, include a nextCursor string in the response. Ensure passing this cursor back in a subsequent request returns the next page."
   },
   {
     id: "tools-content-types",
@@ -227,7 +247,8 @@ var TEST_DEFINITIONS = [
     category: "tools",
     required: false,
     specRef: "server/tools#calling-tools",
-    description: "Validates that content items returned by tools/call have a recognized type field (text, image, audio, resource, resource_link)."
+    description: "Validates that content items returned by tools/call have a recognized type field (text, image, audio, resource, resource_link).",
+    recommendation: 'Every content item returned by tools/call must have a type field set to one of: "text", "image", "audio", "resource", or "resource_link". Check for typos or missing type fields.'
   },
   // ── Resources (5 tests) ──────────────────────────────────────────
   {
@@ -236,7 +257,8 @@ var TEST_DEFINITIONS = [
     category: "resources",
     required: false,
     specRef: "server/resources#listing-resources",
-    description: "Calls resources/list and validates it returns an array. Required if the server declares resources capability."
+    description: "Calls resources/list and validates it returns an array. Required if the server declares resources capability.",
+    recommendation: "Implement resources/list to return { resources: [...] } with an array of resource objects. Each resource needs at least a uri and name."
   },
   {
     id: "resources-read",
@@ -244,7 +266,8 @@ var TEST_DEFINITIONS = [
     category: "resources",
     required: false,
     specRef: "server/resources#reading-resources",
-    description: "Reads the first resource and validates the response contains a contents array with proper uri and text/blob fields."
+    description: "Reads the first resource and validates the response contains a contents array with proper uri and text/blob fields.",
+    recommendation: "Implement resources/read to return { contents: [...] } where each item has a uri and either a text or blob field. Ensure the uri matches the requested resource."
   },
   {
     id: "resources-templates",
@@ -252,7 +275,8 @@ var TEST_DEFINITIONS = [
     category: "resources",
     required: false,
     specRef: "server/resources#resource-templates",
-    description: "Tests the resource templates endpoint. Accepts Method not found (-32601) since templates are optional."
+    description: "Tests the resource templates endpoint. Accepts Method not found (-32601) since templates are optional.",
+    recommendation: "If your server supports resource templates, implement resources/templates/list returning { resourceTemplates: [...] }. Otherwise, return error code -32601."
   },
   {
     id: "resources-pagination",
@@ -260,7 +284,8 @@ var TEST_DEFINITIONS = [
     category: "resources",
     required: false,
     specRef: "server/resources#listing-resources",
-    description: "Tests cursor-based pagination on resources/list. Validates nextCursor is a string if present and that fetching the next page works."
+    description: "Tests cursor-based pagination on resources/list. Validates nextCursor is a string if present and that fetching the next page works.",
+    recommendation: "If you return nextCursor in resources/list, ensure it is a string and that passing it back as cursor in the next request returns valid results."
   },
   {
     id: "resources-subscribe",
@@ -268,7 +293,8 @@ var TEST_DEFINITIONS = [
     category: "resources",
     required: false,
     specRef: "server/resources#subscriptions",
-    description: "If the server declares resources.subscribe capability, tests that resources/subscribe and resources/unsubscribe methods are accepted."
+    description: "If the server declares resources.subscribe capability, tests that resources/subscribe and resources/unsubscribe methods are accepted.",
+    recommendation: "If you declare resources.subscribe capability, implement both resources/subscribe and resources/unsubscribe handlers. Both should accept a uri parameter."
   },
   // ── Prompts (3 tests) ────────────────────────────────────────────
   {
@@ -277,7 +303,8 @@ var TEST_DEFINITIONS = [
     category: "prompts",
     required: false,
     specRef: "server/prompts#listing-prompts",
-    description: "Calls prompts/list and validates it returns an array. Required if the server declares prompts capability."
+    description: "Calls prompts/list and validates it returns an array. Required if the server declares prompts capability.",
+    recommendation: "Implement prompts/list to return { prompts: [...] } with an array of prompt objects. Each prompt needs at least a name field."
   },
   {
     id: "prompts-get",
@@ -285,7 +312,8 @@ var TEST_DEFINITIONS = [
     category: "prompts",
     required: false,
     specRef: "server/prompts#getting-a-prompt",
-    description: "Gets the first prompt and validates the response contains a messages array with proper role and content fields."
+    description: "Gets the first prompt and validates the response contains a messages array with proper role and content fields.",
+    recommendation: 'Implement prompts/get to return { messages: [...] } where each message has a role ("user" or "assistant") and a content field.'
   },
   {
     id: "prompts-pagination",
@@ -293,7 +321,8 @@ var TEST_DEFINITIONS = [
     category: "prompts",
     required: false,
     specRef: "server/prompts#listing-prompts",
-    description: "Tests cursor-based pagination on prompts/list. Validates nextCursor is a string if present and that fetching the next page works."
+    description: "Tests cursor-based pagination on prompts/list. Validates nextCursor is a string if present and that fetching the next page works.",
+    recommendation: "If you return nextCursor in prompts/list, ensure it is a string and that passing it back as cursor in the next request returns valid results."
   },
   // ── Error Handling (8 tests) ─────────────────────────────────────
   {
@@ -302,7 +331,8 @@ var TEST_DEFINITIONS = [
     category: "errors",
     required: true,
     specRef: "basic",
-    description: "Sends an unknown method and verifies the server returns a JSON-RPC error. The spec requires error code -32601 (Method not found)."
+    description: "Sends an unknown method and verifies the server returns a JSON-RPC error. The spec requires error code -32601 (Method not found).",
+    recommendation: "Return a JSON-RPC error with code -32601 (Method not found) for any unrecognized method name. Do not silently ignore unknown methods."
   },
   {
     id: "error-method-code",
@@ -310,7 +340,8 @@ var TEST_DEFINITIONS = [
     category: "errors",
     required: false,
     specRef: "basic",
-    description: "Checks the error code is specifically -32601 (Method not found) for unknown methods, as required by JSON-RPC 2.0."
+    description: "Checks the error code is specifically -32601 (Method not found) for unknown methods, as required by JSON-RPC 2.0.",
+    recommendation: "Use exactly error code -32601 for unknown methods. Do not use generic error codes like -32000. This is required by JSON-RPC 2.0."
   },
   {
     id: "error-invalid-jsonrpc",
@@ -318,7 +349,8 @@ var TEST_DEFINITIONS = [
     category: "errors",
     required: true,
     specRef: "basic",
-    description: "Sends a malformed JSON-RPC message (missing required fields) and verifies the server returns an error or 4xx status."
+    description: "Sends a malformed JSON-RPC message (missing required fields) and verifies the server returns an error or 4xx status.",
+    recommendation: "Validate incoming JSON-RPC messages for required fields (jsonrpc, method). Return error code -32600 (Invalid Request) or HTTP 400 for malformed messages."
   },
   {
     id: "error-invalid-json",
@@ -326,7 +358,8 @@ var TEST_DEFINITIONS = [
     category: "errors",
     required: false,
     specRef: "basic",
-    description: "Sends invalid JSON and verifies the server returns a parse error (-32700) or 4xx status code."
+    description: "Sends invalid JSON and verifies the server returns a parse error (-32700) or 4xx status code.",
+    recommendation: "Catch JSON parse errors and return error code -32700 (Parse error) with a descriptive message. Do not return 500 for malformed input."
   },
   {
     id: "error-missing-params",
@@ -334,7 +367,8 @@ var TEST_DEFINITIONS = [
     category: "errors",
     required: false,
     specRef: "server/tools#error-handling",
-    description: "Calls tools/call with an empty params object (missing required name field) and verifies an error is returned."
+    description: "Calls tools/call with an empty params object (missing required name field) and verifies an error is returned.",
+    recommendation: "Validate tools/call params and return error code -32602 (Invalid params) when the required name field is missing."
   },
   {
     id: "error-parse-code",
@@ -342,7 +376,8 @@ var TEST_DEFINITIONS = [
     category: "errors",
     required: false,
     specRef: "basic",
-    description: "Checks that the server returns the specific JSON-RPC error code -32700 (Parse error) when receiving invalid JSON, as required by the JSON-RPC 2.0 specification."
+    description: "Checks that the server returns the specific JSON-RPC error code -32700 (Parse error) when receiving invalid JSON, as required by the JSON-RPC 2.0 specification.",
+    recommendation: "Return exactly error code -32700 for JSON parse failures. Most JSON-RPC frameworks handle this automatically \u2014 check yours does not override the code."
   },
   {
     id: "error-invalid-request-code",
@@ -350,7 +385,8 @@ var TEST_DEFINITIONS = [
     category: "errors",
     required: false,
     specRef: "basic",
-    description: "Checks that the server returns the specific JSON-RPC error code -32600 (Invalid Request) for malformed JSON-RPC messages missing required fields."
+    description: "Checks that the server returns the specific JSON-RPC error code -32600 (Invalid Request) for malformed JSON-RPC messages missing required fields.",
+    recommendation: "Return exactly error code -32600 for structurally invalid JSON-RPC messages (e.g., missing method field). Check your JSON-RPC middleware configuration."
   },
   {
     id: "tools-call-unknown",
@@ -358,7 +394,8 @@ var TEST_DEFINITIONS = [
     category: "errors",
     required: false,
     specRef: "server/tools#error-handling",
-    description: "Calls tools/call with a nonexistent tool name and verifies the server returns an error response."
+    description: "Calls tools/call with a nonexistent tool name and verifies the server returns an error response.",
+    recommendation: "Return a JSON-RPC error or set isError: true when tools/call receives an unrecognized tool name. Do not return an empty success response."
   },
   // ── Schema Validation (6 tests) ──────────────────────────────────
   {
@@ -367,7 +404,8 @@ var TEST_DEFINITIONS = [
     category: "schema",
     required: false,
     specRef: "server/tools#data-types",
-    description: 'Validates every tool has a valid name (1-128 chars, alphanumeric/underscore/hyphen/dot) and a required inputSchema of type "object".'
+    description: 'Validates every tool has a valid name (1-128 chars, alphanumeric/underscore/hyphen/dot) and a required inputSchema of type "object".',
+    recommendation: 'Ensure every tool has a name (1-128 chars, [A-Za-z0-9_.-]) and an inputSchema with type: "object". Add descriptions to tools for better AI assistant integration.'
   },
   {
     id: "tools-annotations",
@@ -375,7 +413,8 @@ var TEST_DEFINITIONS = [
     category: "schema",
     required: false,
     specRef: "server/tools#annotations",
-    description: "Validates tool annotation fields if present: readOnlyHint, destructiveHint, idempotentHint, openWorldHint should be booleans; title should be a string."
+    description: "Validates tool annotation fields if present: readOnlyHint, destructiveHint, idempotentHint, openWorldHint should be booleans; title should be a string.",
+    recommendation: "If you include annotations on tools, ensure readOnlyHint, destructiveHint, idempotentHint, and openWorldHint are booleans. Title must be a string."
   },
   {
     id: "tools-title-field",
@@ -383,7 +422,8 @@ var TEST_DEFINITIONS = [
     category: "schema",
     required: false,
     specRef: "server/tools#data-types",
-    description: "Checks if tools include the optional title field for human-readable display names. Added in spec version 2025-11-25."
+    description: "Checks if tools include the optional title field for human-readable display names. Added in spec version 2025-11-25.",
+    recommendation: "Add a title field (human-readable string) to each tool definition. This helps MCP clients display your tools in a user-friendly way."
   },
   {
     id: "tools-output-schema",
@@ -391,7 +431,8 @@ var TEST_DEFINITIONS = [
     category: "schema",
     required: false,
     specRef: "server/tools#structured-content",
-    description: 'If tools declare an outputSchema, validates it is a valid JSON Schema object with type "object". Used for structured output validation.'
+    description: 'If tools declare an outputSchema, validates it is a valid JSON Schema object with type "object". Used for structured output validation.',
+    recommendation: 'If you declare outputSchema on a tool, ensure it is a valid JSON Schema object with type: "object". Remove outputSchema if you do not need structured output.'
   },
   {
     id: "prompts-schema",
@@ -399,7 +440,8 @@ var TEST_DEFINITIONS = [
     category: "schema",
     required: false,
     specRef: "server/prompts#data-types",
-    description: "Validates every prompt has a name and that any arguments array contains items with name fields."
+    description: "Validates every prompt has a name and that any arguments array contains items with name fields.",
+    recommendation: "Ensure every prompt has a name field. If the prompt has arguments, each argument object must include a name field."
   },
   {
     id: "resources-schema",
@@ -407,7 +449,8 @@ var TEST_DEFINITIONS = [
     category: "schema",
     required: false,
     specRef: "server/resources#data-types",
-    description: "Validates every resource has a valid URI (parseable as a URL) and a name field."
+    description: "Validates every resource has a valid URI (parseable as a URL) and a name field.",
+    recommendation: "Ensure every resource has a valid, parseable URI and a name field. Add description and mimeType for better client integration."
   }
 ];