@yawlabs/mcp-compliance 0.1.0

package/dist/mcp/server.js

@@ -0,0 +1,128 @@
+import {
+  TEST_DEFINITIONS,
+  runComplianceSuite
+} from "../chunk-4AQGMM2X.js";
+
+// src/mcp/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+var server = new McpServer({
+  name: "mcp-compliance",
+  version: "0.1.0"
+});
+server.tool(
+  "mcp_compliance_test",
+  "Run the full MCP compliance test suite against a server URL. Returns grade (A-F), score, and detailed results for all 24 tests.",
+  {
+    url: z.string().url().describe("The MCP server URL to test (must be HTTP or HTTPS)")
+  },
+  async ({ url }) => {
+    try {
+      const report = await runComplianceSuite(url);
+      const summary = [
+        `Grade: ${report.grade} (${report.score}%)`,
+        `Overall: ${report.overall}`,
+        `Tests: ${report.summary.passed}/${report.summary.total} passed (${report.summary.requiredPassed}/${report.summary.required} required)`,
+        "",
+        ...report.tests.map(
+          (t) => `${t.passed ? "PASS" : "FAIL"} ${t.name}${t.required ? " (required)" : ""} \u2014 ${t.details}`
+        )
+      ];
+      if (report.serverInfo.name) {
+        summary.unshift(`Server: ${report.serverInfo.name} v${report.serverInfo.version || "?"}`);
+      }
+      return {
+        content: [
+          { type: "text", text: summary.join("\n") },
+          { type: "text", text: `
+
+Full report:
+${JSON.stringify(report, null, 2)}` }
+        ]
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: `Error running compliance test: ${err.message}` }],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "mcp_compliance_badge",
+  "Get the badge markdown embed code for an MCP server. Runs the compliance test suite first to determine the grade.",
+  {
+    url: z.string().url().describe("The MCP server URL to test")
+  },
+  async ({ url }) => {
+    try {
+      const report = await runComplianceSuite(url);
+      const badge = report.badge;
+      return {
+        content: [{
+          type: "text",
+          text: [
+            `Grade: ${report.grade} (${report.score}%)`,
+            "",
+            "Markdown:",
+            badge.markdown,
+            "",
+            "HTML:",
+            badge.html
+          ].join("\n")
+        }]
+      };
+    } catch (err) {
+      return {
+        content: [{ type: "text", text: `Error: ${err.message}` }],
+        isError: true
+      };
+    }
+  }
+);
+server.tool(
+  "mcp_compliance_explain",
+  "Explain what a specific compliance test ID checks and why it matters.",
+  {
+    testId: z.string().describe('The test ID to explain (e.g., "transport-post", "lifecycle-init", "tools-schema")')
+  },
+  async ({ testId }) => {
+    const def = TEST_DEFINITIONS.find((t) => t.id === testId);
+    if (!def) {
+      const ids = TEST_DEFINITIONS.map((t) => t.id).join(", ");
+      return {
+        content: [{
+          type: "text",
+          text: `Unknown test ID: "${testId}"
+
+Valid test IDs:
+${ids}`
+        }],
+        isError: true
+      };
+    }
+    return {
+      content: [{
+        type: "text",
+        text: [
+          `Test: ${def.id}`,
+          `Name: ${def.name}`,
+          `Category: ${def.category}`,
+          `Required: ${def.required ? "Yes" : "No"}`,
+          `Spec reference: https://modelcontextprotocol.io/specification/2025-11-25/${def.specRef}`,
+          "",
+          def.description
+        ].join("\n")
+      }]
+    };
+  }
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  console.error("MCP server error:", err);
+  process.exit(1);
+});

package/dist/runner.d.ts

@@ -0,0 +1,99 @@
+type TestCategory = 'transport' | 'lifecycle' | 'tools' | 'resources' | 'prompts' | 'errors' | 'schema';
+interface TestResult {
+    id: string;
+    name: string;
+    category: TestCategory;
+    passed: boolean;
+    required: boolean;
+    details: string;
+    durationMs: number;
+    specRef?: string;
+}
+type Grade = 'A' | 'B' | 'C' | 'D' | 'F';
+type Overall = 'pass' | 'partial' | 'fail';
+interface ComplianceReport {
+    specVersion: string;
+    url: string;
+    timestamp: string;
+    score: number;
+    grade: Grade;
+    overall: Overall;
+    summary: {
+        total: number;
+        passed: number;
+        failed: number;
+        required: number;
+        requiredPassed: number;
+    };
+    categories: Record<string, {
+        passed: number;
+        total: number;
+    }>;
+    tests: TestResult[];
+    serverInfo: {
+        protocolVersion: string | null;
+        name: string | null;
+        version: string | null;
+        capabilities: Record<string, unknown>;
+    };
+    toolCount: number;
+    toolNames: string[];
+    resourceCount: number;
+    promptCount: number;
+    badge: {
+        imageUrl: string;
+        reportUrl: string;
+        markdown: string;
+        html: string;
+    };
+}
+interface TestDefinition {
+    id: string;
+    name: string;
+    category: TestCategory;
+    required: boolean;
+    specRef: string;
+    description: string;
+}
+/** All 24 test IDs with descriptions for the explain command */
+declare const TEST_DEFINITIONS: TestDefinition[];
+
+declare function computeGrade(score: number): Grade;
+declare function computeScore(tests: TestResult[]): {
+    score: number;
+    grade: Grade;
+    overall: 'pass' | 'partial' | 'fail';
+    summary: {
+        total: number;
+        passed: number;
+        failed: number;
+        required: number;
+        requiredPassed: number;
+    };
+    categories: Record<string, {
+        passed: number;
+        total: number;
+    }>;
+};
+
+/**
+ * Generate badge URLs and markdown for a compliance report.
+ * Badge images are served by mcp.hosting.
+ */
+declare function generateBadge(url: string): {
+    imageUrl: string;
+    reportUrl: string;
+    markdown: string;
+    html: string;
+};
+
+interface RunOptions {
+    /** Optional callback for progress updates */
+    onProgress?: (testId: string, passed: boolean, details: string) => void;
+}
+/**
+ * Run the full MCP compliance test suite against a URL.
+ */
+declare function runComplianceSuite(url: string, options?: RunOptions): Promise<ComplianceReport>;
+
+export { type ComplianceReport, type RunOptions, TEST_DEFINITIONS, type TestResult, computeGrade, computeScore, generateBadge, runComplianceSuite };

package/dist/runner.js

@@ -0,0 +1,14 @@
+import {
+  TEST_DEFINITIONS,
+  computeGrade,
+  computeScore,
+  generateBadge,
+  runComplianceSuite
+} from "./chunk-4AQGMM2X.js";
+export {
+  TEST_DEFINITIONS,
+  computeGrade,
+  computeScore,
+  generateBadge,
+  runComplianceSuite
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@yawlabs/mcp-compliance",
+  "version": "0.1.0",
+  "description": "CLI tool and MCP server that tests MCP servers for spec compliance",
+  "license": "MIT",
+  "author": "Yaw Labs (https://yaw.sh)",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/runner.js",
+      "types": "./dist/runner.d.ts"
+    }
+  },
+  "main": "./dist/runner.js",
+  "types": "./dist/runner.d.ts",
+  "bin": {
+    "mcp-compliance": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "undici": "^7.8.0",
+    "zod": "^3.24.4"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.1"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "compliance",
+    "testing",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yawlabs/mcp-compliance"
+  },
+  "homepage": "https://mcp.hosting"
+}