@yawlabs/mcp-compliance 0.3.0 → 0.4.0

package/dist/index.js

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 
 // src/index.ts
+import { createRequire as createRequire3 } from "module";
+import chalk2 from "chalk";
+import { Command } from "commander";
+
+// src/mcp/server.ts
 import { createRequire as createRequire2 } from "module";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import chalk2 from "chalk";
-import { Command } from "commander";
 
 // src/mcp/tools.ts
 import { z } from "zod";
@@ -77,7 +80,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",
@@ -85,7 +89,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",
@@ -93,7 +98,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",
@@ -101,7 +107,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",
@@ -109,7 +116,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",
@@ -117,7 +125,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",
@@ -125,7 +134,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) ─────────────────────────────────────────
   {
@@ -134,7 +144,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",
@@ -142,7 +153,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",
@@ -150,7 +162,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",
@@ -158,7 +171,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",
@@ -166,7 +180,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",
@@ -174,7 +189,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",
@@ -182,7 +198,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",
@@ -190,7 +207,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",
@@ -198,7 +216,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",
@@ -206,7 +225,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) ──────────────────────────────────────────────
   {
@@ -215,7 +235,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",
@@ -223,7 +244,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",
@@ -231,7 +253,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",
@@ -239,7 +262,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) ──────────────────────────────────────────
   {
@@ -248,7 +272,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",
@@ -256,7 +281,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",
@@ -264,7 +290,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",
@@ -272,7 +299,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",
@@ -280,7 +308,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) ────────────────────────────────────────────
   {
@@ -289,7 +318,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",
@@ -297,7 +327,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",
@@ -305,7 +336,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) ─────────────────────────────────────
   {
@@ -314,7 +346,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",
@@ -322,7 +355,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",
@@ -330,7 +364,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",
@@ -338,7 +373,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",
@@ -346,7 +382,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",
@@ -354,7 +391,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",
@@ -362,7 +400,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",
@@ -370,7 +409,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) ──────────────────────────────────
   {
@@ -379,7 +419,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",
@@ -387,7 +428,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",
@@ -395,7 +437,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",
@@ -403,7 +446,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",
@@ -411,7 +455,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",
@@ -419,7 +464,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."
   }
 ];
 
@@ -762,13 +808,13 @@ async function runComplianceSuite(url, options = {}) {
     true,
     "basic/lifecycle#version-negotiation",
     async () => {
-      const version2 = initRes?.body?.result?.protocolVersion;
-      if (!version2) return { passed: false, details: "No protocolVersion" };
-      const valid = /^\d{4}-\d{2}-\d{2}$/.test(version2);
-      if (valid && version2 !== SPEC_VERSION) {
-        warnings.push(`Server negotiated protocol version ${version2} (latest is ${SPEC_VERSION})`);
+      const version3 = initRes?.body?.result?.protocolVersion;
+      if (!version3) return { passed: false, details: "No protocolVersion" };
+      const valid = /^\d{4}-\d{2}-\d{2}$/.test(version3);
+      if (valid && version3 !== SPEC_VERSION) {
+        warnings.push(`Server negotiated protocol version ${version3} (latest is ${SPEC_VERSION})`);
       }
-      return { passed: valid, details: `Version: ${version2}` };
+      return { passed: valid, details: `Version: ${version3}` };
     }
   );
   await test(
@@ -1737,7 +1783,9 @@ ${TEST_DEFINITIONS.map((t) => t.id).join(", ")}`
               `Required: ${def.required ? "Yes" : "No"}`,
               `Spec reference: https://modelcontextprotocol.io/specification/2025-11-25/${def.specRef}`,
               "",
-              def.description
+              def.description,
+              "",
+              `Fix: ${def.recommendation}`
             ].join("\n")
           }
         ]
@@ -1746,6 +1794,27 @@ ${TEST_DEFINITIONS.map((t) => t.id).join(", ")}`
   );
 }
 
+// src/mcp/server.ts
+var require2 = createRequire2(import.meta.url);
+var { version } = require2("../../package.json");
+function createComplianceServer() {
+  const server = new McpServer({ name: "mcp-compliance", version });
+  registerTools(server);
+  return server;
+}
+async function startServer() {
+  const server = createComplianceServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+var isDirectRun = process.argv[1]?.endsWith("mcp/server.js") || process.argv[1]?.endsWith("mcp\\server.js");
+if (isDirectRun) {
+  startServer().catch((err) => {
+    console.error("MCP server error:", err);
+    process.exit(1);
+  });
+}
+
 // src/reporter.ts
 import chalk from "chalk";
 var CATEGORY_LABELS = {
@@ -1788,8 +1857,16 @@ function testLine(t) {
   const icon = t.passed ? chalk.green("  PASS") : chalk.red("  FAIL");
   const req = t.required ? chalk.dim(" (required)") : "";
   const dur = chalk.dim(` ${t.durationMs}ms`);
-  return `${icon}  ${t.name}${req}${dur}
+  let line = `${icon}  ${t.name}${req}${dur}
 ${chalk.dim(`         ${t.details}`)}`;
+  if (!t.passed) {
+    const def = TEST_DEFINITIONS.find((d) => d.id === t.id);
+    if (def?.recommendation) {
+      line += `
+${chalk.cyan(`         Fix: ${def.recommendation}`)}`;
+    }
+  }
+  return line;
 }
 function formatTerminal(report) {
   const lines = [];
@@ -1872,10 +1949,80 @@ function formatTerminal(report) {
 function formatJson(report) {
   return JSON.stringify(report, null, 2);
 }
+function formatSarif(report) {
+  const SPEC_BASE2 = `https://modelcontextprotocol.io/specification/${report.specVersion}`;
+  const rules = report.tests.map((t) => {
+    const def = TEST_DEFINITIONS.find((d) => d.id === t.id);
+    return {
+      id: t.id,
+      name: t.name,
+      shortDescription: { text: t.name },
+      fullDescription: { text: def?.description || t.details },
+      helpUri: t.specRef || `${SPEC_BASE2}/basic`,
+      properties: {
+        category: t.category,
+        required: t.required
+      }
+    };
+  });
+  const results = report.tests.filter((t) => !t.passed).map((t) => {
+    const def = TEST_DEFINITIONS.find((d) => d.id === t.id);
+    return {
+      ruleId: t.id,
+      level: t.required ? "error" : "warning",
+      message: {
+        text: def?.recommendation ? `${t.details}. Fix: ${def.recommendation}` : t.details
+      },
+      locations: [
+        {
+          physicalLocation: {
+            artifactLocation: {
+              uri: report.url,
+              uriBaseId: "MCP_SERVER"
+            }
+          }
+        }
+      ],
+      properties: {
+        category: t.category,
+        durationMs: t.durationMs
+      }
+    };
+  });
+  const sarif = {
+    $schema: "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json",
+    version: "2.1.0",
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: "mcp-compliance",
+            version: report.toolVersion,
+            informationUri: "https://github.com/YawLabs/mcp-compliance",
+            rules
+          }
+        },
+        results,
+        invocations: [
+          {
+            executionSuccessful: report.overall !== "fail",
+            properties: {
+              grade: report.grade,
+              score: report.score,
+              overall: report.overall,
+              specVersion: report.specVersion
+            }
+          }
+        ]
+      }
+    ]
+  };
+  return JSON.stringify(sarif, null, 2);
+}
 
 // src/index.ts
-var require2 = createRequire2(import.meta.url);
-var { version } = require2("../package.json");
+var require3 = createRequire3(import.meta.url);
+var { version: version2 } = require3("../package.json");
 function parseHeaderArg(value, prev) {
   const idx = value.indexOf(":");
   if (idx === -1) {
@@ -1890,8 +2037,8 @@ function parseList(value) {
   return value.split(",").map((s) => s.trim()).filter(Boolean);
 }
 var program = new Command();
-program.name("mcp-compliance").description("Test MCP servers for spec compliance").version(version);
-program.command("test").description("Run the full compliance test suite against an MCP server").argument("<url>", "MCP server URL to test").option("--format <format>", "Output format: terminal or json", "terminal").option("--strict", "Exit with code 1 on any required test failure (for CI)").option("-H, --header <header>", 'Add header to all requests (format: "Key: Value", repeatable)', parseHeaderArg, {}).option("--auth <token>", 'Shorthand for -H "Authorization: <token>"').option("--timeout <ms>", "Request timeout in milliseconds", "15000").option("--retries <n>", "Number of retries for failed tests", "0").option("--only <items>", "Only run tests matching these categories or test IDs (comma-separated)", parseList).option("--skip <items>", "Skip tests matching these categories or test IDs (comma-separated)", parseList).option("--verbose", "Print each test result as it runs").action(
+program.name("mcp-compliance").description("Test MCP servers for spec compliance").version(version2);
+program.command("test").description("Run the full compliance test suite against an MCP server").argument("<url>", "MCP server URL to test").option("--format <format>", "Output format: terminal, json, or sarif", "terminal").option("--strict", "Exit with code 1 on any required test failure (for CI)").option("-H, --header <header>", 'Add header to all requests (format: "Key: Value", repeatable)', parseHeaderArg, {}).option("--auth <token>", 'Shorthand for -H "Authorization: <token>"').option("--timeout <ms>", "Request timeout in milliseconds", "15000").option("--retries <n>", "Number of retries for failed tests", "0").option("--only <items>", "Only run tests matching these categories or test IDs (comma-separated)", parseList).option("--skip <items>", "Skip tests matching these categories or test IDs (comma-separated)", parseList).option("--verbose", "Print each test result as it runs").action(
   async (url, opts) => {
     try {
       const headers = { ...opts.header };
@@ -1917,6 +2064,8 @@ Testing ${url}...
       }
       if (opts.format === "json") {
         console.log(formatJson(report));
+      } else if (opts.format === "sarif") {
+        console.log(formatSarif(report));
       } else {
         console.log(formatTerminal(report));
       }
@@ -1924,7 +2073,7 @@ Testing ${url}...
         process.exit(1);
       }
     } catch (err) {
-      if (opts.format === "json") {
+      if (opts.format === "json" || opts.format === "sarif") {
         console.error(JSON.stringify({ error: err.message }));
       } else {
         console.error(chalk2.red(`
@@ -1958,9 +2107,6 @@ Error: ${err.message}
   }
 });
 program.command("mcp").description("Start the MCP compliance server (stdio transport)").action(async () => {
-  const server = new McpServer({ name: "mcp-compliance", version });
-  registerTools(server);
-  const transport = new StdioServerTransport();
-  await server.connect(transport);
+  await startServer();
 });
 program.parse();

package/dist/mcp/server.d.ts

@@ -1,2 +1,12 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
-export {  }
+/**
+ * Create and configure the MCP compliance server instance.
+ */
+declare function createComplianceServer(): McpServer;
+/**
+ * Start the MCP compliance server with stdio transport.
+ */
+declare function startServer(): Promise<void>;
+
+export { createComplianceServer, startServer };