feat: health score, conformance checks, CI reporters, and badge generation (#60)

Add "Lighthouse for MCP" scoring system with five weighted dimensions:
- Protocol compliance (conformance check)
- Schema quality (tool/prompt/resource description quality)
- Security (existing security check)
- Reliability (tools/prompts/resources/invoke checks)
- Performance (connection + operation latency)

New features:
- `score` CLI command: visual health score with bar chart (0-100, A-F grade)
- `badge` CLI command: generate shields.io-style SVG badge for READMEs
- `--format junit`: JUnit XML output for GitHub Actions test annotations
- `--format sarif`: SARIF v2.1.0 output for GitHub Security tab
- `score_server` MCP tool: health scoring for AI agents
- Conformance check: validates capabilities, endpoint responses, error handling
- Schema quality check: tool descriptions, input schemas, property docs
- Performance metrics: connect time, per-check latency, percentiles
- Health score displayed in terminal and markdown reporters

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: KryptosAI

src/badge.ts

@@ -0,0 +1,46 @@
+import type { HealthGrade } from "./types.js";
+
+const GRADE_COLORS: Record<HealthGrade, string> = {
+  A: "#4c1",
+  B: "#97ca00",
+  C: "#dfb317",
+  D: "#fe7d37",
+  F: "#e05d44",
+};
+
+export interface BadgeOptions {
+  label?: string;
+  score: number;
+  grade: HealthGrade;
+}
+
+export function generateBadgeSvg(options: BadgeOptions): string {
+  const label = options.label ?? "MCP Health";
+  const value = `${options.score}/100`;
+  const color = GRADE_COLORS[options.grade];
+
+  // Approximate text widths (7px per character for the 11px Verdana used by shields.io)
+  const labelWidth = label.length * 7 + 10;
+  const valueWidth = value.length * 7 + 10;
+  const totalWidth = labelWidth + valueWidth;
+
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${totalWidth}" height="20" role="img" aria-label="${label}: ${value}">
+  <title>${label}: ${value}</title>
+  <linearGradient id="s" x2="0" y2="100%">
+    <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+    <stop offset="1" stop-opacity=".1"/>
+  </linearGradient>
+  <clipPath id="r"><rect width="${totalWidth}" height="20" rx="3" fill="#fff"/></clipPath>
+  <g clip-path="url(#r)">
+    <rect width="${labelWidth}" height="20" fill="#555"/>
+    <rect x="${labelWidth}" width="${valueWidth}" height="20" fill="${color}"/>
+    <rect width="${totalWidth}" height="20" fill="url(#s)"/>
+  </g>
+  <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110">
+    <text aria-hidden="true" x="${labelWidth * 5}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)">${label}</text>
+    <text x="${labelWidth * 5}" y="140" transform="scale(.1)">${label}</text>
+    <text aria-hidden="true" x="${(labelWidth + valueWidth / 2) * 10}" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)">${value}</text>
+    <text x="${(labelWidth + valueWidth / 2) * 10}" y="140" transform="scale(.1)">${value}</text>
+  </g>
+</svg>`;
+}

src/checks/conformance.ts

@@ -0,0 +1,188 @@
+import { performance } from "node:perf_hooks";
+
+import { isCapabilityAdvertised, makeCheckResult, type CheckContext, type ObservedCheck } from "./base.js";
+import type { EvidenceSummary } from "../types.js";
+
+interface ConformanceFinding {
+  rule: string;
+  passed: boolean;
+  detail: string;
+}
+
+function checkCapabilitiesPresent(context: CheckContext): ConformanceFinding {
+  const caps = context.serverCapabilities;
+  if (caps === undefined) {
+    return { rule: "capabilities-present", passed: false, detail: "Server did not return capabilities during initialization." };
+  }
+  return { rule: "capabilities-present", passed: true, detail: "Server returned capabilities object." };
+}
+
+function checkServerInfo(context: CheckContext): ConformanceFinding {
+  const caps = context.serverCapabilities;
+  if (!caps) {
+    return { rule: "server-info", passed: false, detail: "Cannot verify server info — no capabilities returned." };
+  }
+  return { rule: "server-info", passed: true, detail: "Server provided initialization info." };
+}
+
+async function checkToolsEndpoint(context: CheckContext): Promise<ConformanceFinding> {
+  if (!isCapabilityAdvertised(context.serverCapabilities, "tools")) {
+    return { rule: "tools-capability-match", passed: true, detail: "Tools not advertised — endpoint check skipped." };
+  }
+  try {
+    const resp = await context.client.listTools(undefined, { timeout: context.timeoutMs });
+    if (!Array.isArray(resp.tools)) {
+      return { rule: "tools-capability-match", passed: false, detail: "tools/list did not return an array of tools." };
+    }
+    return { rule: "tools-capability-match", passed: true, detail: `tools/list returned ${resp.tools.length} tool(s).` };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return { rule: "tools-capability-match", passed: false, detail: `Advertised tools but tools/list failed: ${msg}` };
+  }
+}
+
+async function checkPromptsEndpoint(context: CheckContext): Promise<ConformanceFinding> {
+  if (!isCapabilityAdvertised(context.serverCapabilities, "prompts")) {
+    return { rule: "prompts-capability-match", passed: true, detail: "Prompts not advertised — endpoint check skipped." };
+  }
+  try {
+    const resp = await context.client.listPrompts(undefined, { timeout: context.timeoutMs });
+    if (!Array.isArray(resp.prompts)) {
+      return { rule: "prompts-capability-match", passed: false, detail: "prompts/list did not return an array of prompts." };
+    }
+    return { rule: "prompts-capability-match", passed: true, detail: `prompts/list returned ${resp.prompts.length} prompt(s).` };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return { rule: "prompts-capability-match", passed: false, detail: `Advertised prompts but prompts/list failed: ${msg}` };
+  }
+}
+
+async function checkResourcesEndpoint(context: CheckContext): Promise<ConformanceFinding> {
+  if (!isCapabilityAdvertised(context.serverCapabilities, "resources")) {
+    return { rule: "resources-capability-match", passed: true, detail: "Resources not advertised — endpoint check skipped." };
+  }
+  try {
+    const resp = await context.client.listResources(undefined, { timeout: context.timeoutMs });
+    if (!Array.isArray(resp.resources)) {
+      return { rule: "resources-capability-match", passed: false, detail: "resources/list did not return an array of resources." };
+    }
+    return { rule: "resources-capability-match", passed: true, detail: `resources/list returned ${resp.resources.length} resource(s).` };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return { rule: "resources-capability-match", passed: false, detail: `Advertised resources but resources/list failed: ${msg}` };
+  }
+}
+
+async function checkToolResponseContent(context: CheckContext): Promise<ConformanceFinding> {
+  if (!isCapabilityAdvertised(context.serverCapabilities, "tools")) {
+    return { rule: "tool-response-content", passed: true, detail: "No tools — content check skipped." };
+  }
+  try {
+    const { tools } = await context.client.listTools(undefined, { timeout: context.timeoutMs });
+    // Find a tool safe to invoke (no required params)
+    const safeTool = tools.find(t => {
+      const schema = t.inputSchema as Record<string, unknown> | undefined;
+      const required = schema?.["required"] as string[] | undefined;
+      return !required || required.length === 0;
+    });
+    if (!safeTool) {
+      return { rule: "tool-response-content", passed: true, detail: "No safe tool to invoke — content validation skipped." };
+    }
+    const result = await context.client.callTool({ name: safeTool.name, arguments: {} }, undefined, { timeout: context.timeoutMs });
+    if (!Array.isArray(result.content)) {
+      return { rule: "tool-response-content", passed: false, detail: `Tool "${safeTool.name}" response.content is not an array.` };
+    }
+    for (const item of result.content) {
+      const typed = item as Record<string, unknown>;
+      if (typeof typed["type"] !== "string") {
+        return { rule: "tool-response-content", passed: false, detail: `Tool "${safeTool.name}" response content item missing 'type' field.` };
+      }
+    }
+    return { rule: "tool-response-content", passed: true, detail: `Tool "${safeTool.name}" response has valid content array.` };
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error);
+    return { rule: "tool-response-content", passed: false, detail: `Tool response content check failed: ${msg}` };
+  }
+}
+
+async function checkErrorHandling(context: CheckContext): Promise<ConformanceFinding> {
+  try {
+    // Try calling a method that shouldn't exist
+    await context.client.request(
+      { method: "observatory/nonexistent", params: {} },
+      { method: "object" } as never,
+      { timeout: Math.min(context.timeoutMs, 5000) },
+    );
+    // If we get here, server didn't error — that's actually acceptable per JSON-RPC
+    return { rule: "error-handling", passed: true, detail: "Server responded to unknown method without crashing." };
+  } catch (error) {
+    // Getting an error is the expected behavior
+    const err = error as Record<string, unknown>;
+    const code = err["code"];
+    if (typeof code === "number") {
+      return { rule: "error-handling", passed: true, detail: `Server returned proper error code ${String(code)} for unknown method.` };
+    }
+    if (code !== undefined && code !== null) {
+      return { rule: "error-handling", passed: true, detail: "Server returned an error response for unknown method." };
+    }
+    // Connection-level error is ok — server closed cleanly
+    return { rule: "error-handling", passed: true, detail: "Server handled unknown method gracefully." };
+  }
+}
+
+export async function runConformanceCheck(context: CheckContext): Promise<ObservedCheck> {
+  const startedAt = performance.now();
+
+  const asyncFindings = await Promise.all([
+    checkToolsEndpoint(context),
+    checkPromptsEndpoint(context),
+    checkResourcesEndpoint(context),
+    checkToolResponseContent(context),
+    checkErrorHandling(context),
+  ]);
+
+  const findings = [
+    checkCapabilitiesPresent(context),
+    checkServerInfo(context),
+    ...asyncFindings,
+  ];
+
+  const passed = findings.filter(f => f.passed).length;
+  const failed = findings.filter(f => !f.passed).length;
+  const total = findings.length;
+
+  let status: "pass" | "partial" | "fail";
+  if (failed === 0) {
+    status = "pass";
+  } else if (passed > failed) {
+    status = "partial";
+  } else {
+    status = "fail";
+  }
+
+  const message = failed === 0
+    ? `All ${total} conformance checks passed.`
+    : `${passed}/${total} conformance checks passed, ${failed} failed.`;
+
+  const diagnostics = findings.map(f => `[${f.passed ? "pass" : "FAIL"}] ${f.rule}: ${f.detail}`);
+
+  const evidence: EvidenceSummary = {
+    endpoint: "conformance/check",
+    advertised: true,
+    responded: true,
+    minimalShapePresent: failed === 0,
+    itemCount: total,
+    identifiers: findings.filter(f => !f.passed).map(f => f.rule),
+    diagnostics,
+  };
+
+  return {
+    result: makeCheckResult(
+      "conformance",
+      status,
+      performance.now() - startedAt,
+      message,
+      [evidence],
+    ),
+  };
+}