@certscore/mcp 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { createCertScoreMcpServer } from "./server.js";
+export { explainFinding, exportFindings, findingsFromReport } from "./tools.js";
+export { CERTSCORE_MCP_VERSION } from "./version.js";
+export interface CertScoreMcpDoctorOptions {
+    env?: Record<string, string | undefined>;
+    fetch?: typeof fetch;
+    nodeVersion?: string;
+}
+export declare function getCertScoreMcpDoctorReport(options?: CertScoreMcpDoctorOptions): Promise<{
+    exitCode: number;
+    lines: string[];
+}>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChF,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAMrD,MAAM,WAAW,yBAAyB;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA+CD,wBAAsB,2BAA2B,CAAC,OAAO,GAAE,yBAA8B;;;GA0DxF"}

package/dist/index.js

@@ -0,0 +1,129 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { createCertScoreMcpServer } from "./server.js";
+import { CERTSCORE_MCP_VERSION } from "./version.js";
+export { createCertScoreMcpServer } from "./server.js";
+export { explainFinding, exportFindings, findingsFromReport } from "./tools.js";
+export { CERTSCORE_MCP_VERSION } from "./version.js";
+const DEFAULT_CERTSCORE_BASE_URL = "https://certscore.ai";
+const MIN_NODE_MAJOR = 20;
+const MAX_NODE_MAJOR_EXCLUSIVE = 25;
+function parseTimeout(value) {
+    if (!value) {
+        return undefined;
+    }
+    const timeout = Number(value);
+    return Number.isFinite(timeout) && timeout > 0 ? timeout : undefined;
+}
+async function main() {
+    if (process.argv.includes("--version")) {
+        console.log(CERTSCORE_MCP_VERSION);
+        return;
+    }
+    if (process.argv.includes("--help") || process.argv.includes("-h")) {
+        console.log([
+            "certscore-mcp",
+            "",
+            "CertScore MCP stdio server.",
+            "",
+            "Environment:",
+            "  CERTSCORE_API_KEY              CertScore API token.",
+            "  CERTSCORE_BASE_URL             Optional API base URL. Defaults to https://certscore.ai.",
+            "  CERTSCORE_REQUEST_TIMEOUT_MS   Optional request timeout.",
+            "",
+            "Usage:",
+            "  certscore-mcp",
+            "  certscore-mcp doctor"
+        ].join("\n"));
+        return;
+    }
+    if (process.argv.includes("doctor")) {
+        const result = await getCertScoreMcpDoctorReport();
+        console.log(result.lines.join("\n"));
+        process.exitCode = result.exitCode;
+        return;
+    }
+    const server = createCertScoreMcpServer({
+        apiKey: process.env.CERTSCORE_API_KEY,
+        baseUrl: process.env.CERTSCORE_BASE_URL,
+        timeout: parseTimeout(process.env.CERTSCORE_REQUEST_TIMEOUT_MS)
+    });
+    await server.connect(new StdioServerTransport());
+}
+export async function getCertScoreMcpDoctorReport(options = {}) {
+    const env = options.env ?? process.env;
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const nodeVersion = options.nodeVersion ?? process.versions.node;
+    const lines = ["CertScore MCP doctor"];
+    let exitCode = 0;
+    lines.push(`[ok] version ${CERTSCORE_MCP_VERSION}`);
+    const nodeMajor = Number(nodeVersion.split(".")[0]);
+    if (Number.isInteger(nodeMajor) && nodeMajor >= MIN_NODE_MAJOR && nodeMajor < MAX_NODE_MAJOR_EXCLUSIVE) {
+        lines.push(`[ok] Node.js ${nodeVersion} is compatible`);
+    }
+    else {
+        lines.push(`[error] Node.js ${nodeVersion || "unknown"} is not compatible; use Node.js >=20 <25`);
+        exitCode = 1;
+    }
+    const baseUrlInput = env.CERTSCORE_BASE_URL?.trim() || DEFAULT_CERTSCORE_BASE_URL;
+    let healthUrl = null;
+    try {
+        const baseUrl = new URL(baseUrlInput);
+        healthUrl = new URL("/api/v2/health", baseUrl);
+        lines.push(`[ok] base URL ${baseUrl.origin}`);
+    }
+    catch {
+        lines.push(`[error] CERTSCORE_BASE_URL is not a valid URL`);
+        exitCode = 1;
+    }
+    if (healthUrl) {
+        try {
+            const response = await fetchImpl(healthUrl, {
+                headers: { accept: "application/json" },
+                signal: AbortSignal.timeout(10_000)
+            });
+            if (response.ok) {
+                lines.push(`[ok] API health reachable at ${healthUrl.href}`);
+            }
+            else {
+                lines.push(`[error] API health returned HTTP ${response.status} at ${healthUrl.href}`);
+                exitCode = 1;
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error && error.message ? error.message : "request failed";
+            lines.push(`[error] API health unreachable at ${healthUrl.href}: ${message}`);
+            exitCode = 1;
+        }
+    }
+    if (env.CERTSCORE_API_KEY?.trim()) {
+        lines.push("[ok] CERTSCORE_API_KEY is present");
+        lines.push("[info] No dedicated auth-check endpoint is exposed; verify credentials with a real MCP tool call such as scan_site.");
+    }
+    else {
+        lines.push("[warn] CERTSCORE_API_KEY is not set");
+        lines.push("[info] Set CERTSCORE_API_KEY before connecting an MCP client or calling authenticated tools.");
+    }
+    lines.push("CertScore outputs are automated public-web observations for review, not legal advice, certification, or a compliance determination.");
+    return { exitCode, lines };
+}
+function isMainModule() {
+    const entrypoint = process.argv[1];
+    if (!entrypoint) {
+        return false;
+    }
+    try {
+        return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(entrypoint);
+    }
+    catch {
+        return import.meta.url === `file://${entrypoint}`;
+    }
+}
+if (isMainModule()) {
+    main().catch((error) => {
+        const message = error instanceof Error ? error.stack ?? error.message : String(error);
+        console.error(message);
+        process.exitCode = 1;
+    });
+}

package/dist/server.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface CertScoreMcpOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    timeout?: number;
+}
+export declare function createCertScoreMcpServer(options?: CertScoreMcpOptions): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIpE,MAAM,WAAW,mBAAmB;IAClC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAmCD,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,mBAAwB,aAkLzE"}

package/dist/server.js

@@ -0,0 +1,148 @@
+import { CertScoreClient } from "@certscore/sdk";
+import { certScoreMcpToolContracts } from "@certscore/api-contracts";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { CERTSCORE_MCP_VERSION } from "./version.js";
+import { boundEvidencePacket, exportFindings, limitPreConsentRows, normalizeDetail, normalizeFormat, paginateFindingList, scanIdFromStatus, toToolError, toToolResult } from "./tools.js";
+function toolContract(name) {
+    const contract = certScoreMcpToolContracts.find((candidate) => candidate.name === name);
+    if (!contract) {
+        throw new Error(`Missing CertScore MCP tool contract: ${name}`);
+    }
+    return {
+        title: contract.title,
+        description: contract.description,
+        inputSchema: contract.inputSchema,
+        outputSchema: contract.outputSchema,
+        annotations: contract.annotations
+    };
+}
+export function createCertScoreMcpServer(options = {}) {
+    const client = new CertScoreClient({
+        apiKey: options.apiKey,
+        baseUrl: options.baseUrl,
+        timeout: options.timeout
+    });
+    const server = new McpServer({
+        name: "certscore",
+        version: CERTSCORE_MCP_VERSION
+    });
+    const registerTool = server.registerTool.bind(server);
+    registerTool("scan_site", toolContract("scan_site"), async (input) => {
+        try {
+            return toToolResult(await client.scans.create(input.url, {
+                freshness: input.freshness ?? "latest",
+                scanFrom: input.scanFrom
+            }));
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
+    registerTool("get_scan", toolContract("get_scan"), async ({ scanId }) => {
+        try {
+            return toToolResult(await client.scans.get(scanId));
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
+    registerTool("get_scan_status", toolContract("get_scan_status"), async ({ jobId, scanId }) => {
+        try {
+            if (scanId) {
+                return toToolResult(await client.scans.status(scanId));
+            }
+            if (!jobId) {
+                return toToolResult({
+                    error: {
+                        name: "InvalidToolInput",
+                        message: "Provide either scanId for API v2 scan status or jobId for Pulse job status."
+                    }
+                });
+            }
+            const status = await client.getJobStatus(jobId);
+            return toToolResult({
+                ...status,
+                scanId: scanIdFromStatus(status)
+            });
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
+    registerTool("get_report", toolContract("get_report"), async ({ scanId, detail, format }) => {
+        try {
+            const normalizedFormat = normalizeFormat(format);
+            const result = normalizedFormat === "markdown"
+                ? await client.getScan(scanId, {
+                    detail: normalizeDetail(detail),
+                    format: "markdown"
+                })
+                : await client.getScan(scanId, {
+                    detail: normalizeDetail(detail),
+                    format: "json"
+                });
+            return toToolResult(result);
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
+    registerTool("get_evidence", toolContract("get_evidence"), async ({ scanId }) => {
+        try {
+            return toToolResult(boundEvidencePacket(await client.getScan(scanId, { detail: "evidence", format: "json" })));
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
+    registerTool("export_findings", toolContract("export_findings"), async ({ scanId }) => {
+        try {
+            const report = await client.getScan(scanId, { detail: "full", format: "json" });
+            return toToolResult(exportFindings(report));
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
+    registerTool("list_findings", toolContract("list_findings"), async ({ limit, offset, scanId }) => {
+        try {
+            return toToolResult(paginateFindingList(await client.findings.list(scanId), { limit, offset }));
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
+    registerTool("get_pre_consent_cookies_trackers", toolContract("get_pre_consent_cookies_trackers"), async ({ maxRows, scanId }) => {
+        try {
+            return toToolResult(limitPreConsentRows(await client.scans.preConsentCookiesTrackers(scanId), { maxRows }));
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
+    registerTool("explain_finding", toolContract("explain_finding"), async ({ scanId, findingId }) => {
+        try {
+            return toToolResult(await client.findings.explain(scanId, findingId));
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
+    registerTool("get_latest_domain_scan", toolContract("get_latest_domain_scan"), async ({ domain, scanFrom }) => {
+        try {
+            return toToolResult(await client.domains.latest(domain, { scanFrom }));
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
+    registerTool("get_latest_domain_pre_consent_cookies_trackers", toolContract("get_latest_domain_pre_consent_cookies_trackers"), async ({ domain, maxRows, scanFrom }) => {
+        try {
+            return toToolResult(limitPreConsentRows(await client.domains.latestPreConsentCookiesTrackers(domain, { scanFrom }), { maxRows }));
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
+    return server;
+}

package/dist/tools.d.ts

@@ -0,0 +1,77 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { type JobStatus, type PulseDetail, type PulseFormat, type PulseResult, type TopFinding } from "@certscore/sdk";
+export declare const MAX_EVIDENCE_PACKET_CHARS = 250000;
+export declare function toToolResult(payload: unknown): CallToolResult;
+export declare function toToolError(error: unknown): CallToolResult;
+export declare function boundEvidencePacket<T>(payload: T, maxSerializedChars?: number): T | Record<string, unknown>;
+export declare function normalizeDetail(detail: PulseDetail | undefined): PulseDetail;
+export declare function normalizeFormat(format: PulseFormat | undefined): PulseFormat;
+export declare function scanIdFromStatus(status: JobStatus): string | null;
+export declare function scanIdFromPulse(report: PulseResult): string | null;
+export declare function findingsFromReport(report: PulseResult): TopFinding[];
+export declare function exportFindings(report: PulseResult): {
+    type: string;
+    scanId: string | null;
+    domain: string | null;
+    summary: import("packages/certscore-sdk/dist/types.js").PulseSummary | null;
+    findings: {
+        id: string;
+        label: string | null;
+        criticality: string | null;
+        confidence: string | null;
+        plainEnglish: string | null;
+        evidenceDigest: import("@certscore/sdk").EvidenceDigest | null;
+        evidenceSummary: string | null;
+        reviewLenses: string[];
+        anchorUrl: string | null;
+        nextStep: string | null;
+    }[];
+    disclaimer: string | null;
+};
+export declare function paginateFindingList<T extends Record<string, unknown>>(payload: T, options?: {
+    limit?: number;
+    offset?: number;
+}): T;
+export declare function limitPreConsentRows<T extends Record<string, unknown>>(payload: T, options?: {
+    maxRows?: number;
+}): T;
+export declare function explainFinding(report: PulseResult, findingId: string): {
+    type: string;
+    scanId: string | null;
+    findingId: string;
+    found: boolean;
+    message: string;
+    availableFindingIds: string[];
+    disclaimer: string | null;
+    label?: undefined;
+    criticality?: undefined;
+    confidence?: undefined;
+    plainEnglish?: undefined;
+    evidenceSummary?: undefined;
+    evidenceDigest?: undefined;
+    exampleEvents?: undefined;
+    reviewLenses?: undefined;
+    anchorUrl?: undefined;
+    nextStep?: undefined;
+    caveats?: undefined;
+} | {
+    type: string;
+    scanId: string | null;
+    findingId: string;
+    found: boolean;
+    label: string;
+    criticality: string | null;
+    confidence: string | null;
+    plainEnglish: string | null;
+    evidenceSummary: string | null;
+    evidenceDigest: import("@certscore/sdk").EvidenceDigest | null;
+    exampleEvents: Record<string, unknown>[];
+    reviewLenses: string[];
+    anchorUrl: string | null;
+    nextStep: string | null;
+    caveats: string[];
+    disclaimer: string | null;
+    message?: undefined;
+    availableFindingIds?: undefined;
+};
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAkB,KAAK,SAAS,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,WAAW,EAAE,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGvI,eAAO,MAAM,yBAAyB,SAAU,CAAC;AAKjD,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,GAAG,cAAc,CAa7D;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,OAAO,GAAG,cAAc,CAyB1D;AAED,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,kBAAkB,SAA4B,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CA0C9H;AA6ID,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,WAAW,CAE5E;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,GAAG,WAAW,CAE5E;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,iBAEjD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,WAAW,iBAGlD;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,UAAU,EAAE,CAQpE;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW;;;;;;;;;;;;;;;;;;EAoBjD;AAED,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnE,OAAO,EAAE,CAAC,EACV,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAO,GAChD,CAAC,CAoBH;AAED,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnE,OAAO,EAAE,CAAC,EACV,OAAO,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAO,GACjC,CAAC,CAiBH;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EA+BpE"}