@certscore/mcp 0.2.4 → 0.2.5

package/README.md

@@ -2,7 +2,7 @@
 
 CertScore MCP exposes a focused Model Context Protocol server for CertScore Pulse workflows.
 
-Status: public remote endpoint plus local stdio package. Remote clients can use `https://mcp.certscore.ai/mcp`; external macOS MCP clients can use the Homebrew-distributed stdio command. Local WC01 development uses `pnpm mcp:certscore`.
+Status: public developer preview. The server is distributed for external macOS MCP clients through Homebrew. Local WC01 development uses `pnpm mcp:certscore`.
 
 Public docs:
 
@@ -13,7 +13,8 @@ Public docs:
 
 ## Tools
 
-- `scan_site` - Start or reuse a CertScore public-web scan for a public URL. API docs: https://certscore.ai/api/v2/openapi.json
+- `create_scan` - Deprecated compatibility alias of scan_site. Removed in 0.2.0. Use scan_site. Start a CertScore Pulse scan for a public URL and return immediately with status, scan, and polling links.
+- `scan_site` - Start or reuse a CertScore public-web scan for a public URL.
 - `get_scan` - Retrieve the API v2 public-safe scan resource for a stable scan ID.
 - `get_scan_status` - Pass scanId (preferred, API v2). Pass jobId only for a just-created scan that has not yet returned a scanId.
 - `get_report` - Retrieve a summary CertScore Pulse report by stable scan ID. Use get_evidence for the larger bounded evidence packet.
@@ -25,7 +26,17 @@ Public docs:
 - `get_latest_domain_scan` - Retrieve the latest eligible API v2 public-safe scan for a domain.
 - `get_latest_domain_pre_consent_cookies_trackers` - Retrieve the public-safe Cookies & Trackers (Pre-consent) table from the latest eligible scan for a domain.
 
-The initial MCP surface intentionally does not include account scan browsing, scan comparison tools, or the removed `create_scan` compatibility alias.
+The initial MCP surface intentionally does not include account scan browsing or scan comparison tools.
+
+## Scan Timing Fields
+
+MCP tools backed by API v2 scan resources return scan timing when CertScore has enough timing evidence:
+
+- `startedAt`
+- `completedAt`
+- `scanTimeSeconds`
+
+This applies to `scan_site` when it returns an API v2 scan resource or job, `get_scan`, and `get_scan_status` when called with a `scanId`. `scanTimeSeconds: null` means timing is unavailable or incomplete and should not be displayed as `0`.
 
 ## Configuration
 
@@ -60,9 +71,12 @@ Run from this monorepo for local development:
 CERTSCORE_API_KEY=... pnpm mcp:certscore
 ```
 
-Public API/MCP access uses self-serve read-only keys from `POST https://certscore.ai/api/v2/keys/request` or support-granted
-`scan:create` access. Repository-only key generation commands may exist for internal smoke tests, but they are not the public
-integration path.
+Generate a scoped preview key after applying DB migrations:
+
+```bash
+pnpm db:migrate
+pnpm mcp:certscore:generate-key -- --name "CertScore MCP preview"
+```
 
 Run the built package directly after local build:
 
@@ -77,11 +91,11 @@ CERTSCORE_BASE_URL=https://certscore.ai
 CERTSCORE_REQUEST_TIMEOUT_MS=300000
 ```
 
-`CERTSCORE_API_KEY` should be a scoped CertScore API token for the workspace or integration user. The MCP server passes it to Pulse as a bearer token and does not persist it.
+`CERTSCORE_API_KEY` should be a scoped CertScore API token for the workspace or preview user. The MCP server passes it to Pulse as a bearer token and does not persist it.
 
 ## API Key Access
 
-MCP clients usually need `scan:read` and `mcp` for read workflows. Starting scans also requires `scan:create`, which is grant-gated for launch. Request scan creation access by emailing `support@certscore.ai` with your organization, MCP client, expected workflow, expected request volume, contact email, and requested scopes.
+MCP clients usually need `scan:read`, `scan:create`, and `mcp` scopes. Request developer-preview access by emailing `support@certscore.ai` with your organization, MCP client, expected workflow, expected request volume, contact email, and requested scopes.
 
 ## Verify Install
 
@@ -214,7 +228,7 @@ For the full production operator smoke, run from the WC01 repo:
 pnpm ops:smoke:mcp-production
 ```
 
-This verifies the Homebrew-installed `certscore-mcp` command against live `https://certscore.ai`. It creates a short-lived internal smoke key, stores only the hash in production through the approved ECS/Fargate path, checks required tools, requests a fresh EU-IE scan with `freshness: "refresh"` and `scanFrom: "eu_ie"`, requires non-empty findings and pre-consent cookies/trackers rows, runs `explain_finding`, and revokes the temporary key afterward. It exercises existing public-safe API/MCP projections only.
+This verifies the Homebrew-installed `certscore-mcp` command against live `https://certscore.ai`. It creates a short-lived preview key, stores only the hash in production through the approved ECS/Fargate path, checks required tools, requests a fresh EU-IR scan with `freshness: "refresh"` and `scanFrom: "eu_ie"`, requires non-empty findings and pre-consent cookies/trackers rows, runs `explain_finding`, and revokes the temporary key afterward. It exercises existing public-safe API/MCP projections only.
 
 ## Troubleshooting
 

package/dist/certscore-mcp.mjs

@@ -17846,7 +17846,7 @@ var pulseErrorSchema = external_exports.object({
 var apiV2Disclaimer = "CertScore outputs are automated public-web observations for review. They are not legal advice, certification, or a compliance determination.";
 var apiV2ScanStatusSchema = external_exports.enum(["queued", "running", "finalizing", "completed", "completed_limited", "failed", "expired", "rate_limited"]);
 var apiV2ScanFreshnessSchema = external_exports.enum(["latest", "refresh"]);
-var apiV2ScanFromSchema = external_exports.enum(["eu_ie", "eu_de", "california"]);
+var apiV2ScanFromSchema = external_exports.enum(["eu_ie"]);
 var apiV2FindingCriticalitySchema = external_exports.enum(["critical", "high", "medium", "low", "info", "unknown"]);
 var apiV2FindingConfidenceSchema = external_exports.enum(["strong", "good", "moderate", "weak", "unknown"]);
 var apiV2EvidenceBasisSchema = external_exports.enum(["runtime_observation", "policy_surface_detection", "accessibility_check", "public_report_projection"]);
@@ -17888,6 +17888,9 @@ var apiV2ScanJobSchema = external_exports.object({
   status: apiV2ScanStatusSchema,
   phase: external_exports.string().optional(),
   createdAt: external_exports.string().optional(),
+  startedAt: external_exports.string().nullable().optional(),
+  completedAt: external_exports.string().nullable().optional(),
+  scanTimeSeconds: external_exports.number().nullable().optional(),
   lastUpdatedAt: external_exports.string().optional(),
   retryAfterSeconds: external_exports.number().int().nullable().optional(),
   links: apiV2LinksSchema.optional(),
@@ -17903,6 +17906,7 @@ var apiV2ScanResourceSchema = external_exports.object({
   createdAt: external_exports.string().nullable().optional(),
   startedAt: external_exports.string().nullable().optional(),
   completedAt: external_exports.string().nullable().optional(),
+  scanTimeSeconds: external_exports.number().nullable().optional(),
   score: external_exports.number().int().min(0).max(100).nullable().optional(),
   riskLevel: external_exports.string().nullable().optional(),
   coverage: external_exports.object({
@@ -18017,7 +18021,7 @@ var mcpPulseDetailSchema = external_exports.enum(["tiny", "quick", "standard", "
 var mcpGptSafePulseDetailSchema = external_exports.enum(["tiny", "standard", "summary"]);
 var mcpPulseFormatSchema = external_exports.enum(["json", "markdown"]);
 var mcpPulseFreshnessSchema = external_exports.enum(["latest", "refresh"]);
-var mcpScanFromSchema = external_exports.enum(["eu_ie", "eu_de", "california"]);
+var mcpScanFromSchema = external_exports.enum(["eu_ie"]);
 var mcpCreateScanInputSchema = {
   url: external_exports.string().min(1).describe("Public URL or domain to scan."),
   detail: mcpPulseDetailSchema.optional().describe("Pulse detail level. Defaults to summary."),
@@ -18065,22 +18069,16 @@ var mcpGetLatestDomainPreConsentCookiesTrackersInputSchema = {
   scanFrom: mcpScanFromSchema.optional().describe("Optional scan execution context for matching eligible scans."),
   maxRows: external_exports.number().int().min(1).max(200).optional().describe("Maximum inventory rows to return. Defaults to 200.")
 };
-function scanCreationAnnotations(title) {
-  return {
-    title,
-    readOnlyHint: false,
-    destructiveHint: true,
-    idempotentHint: false,
-    openWorldHint: true
-  };
-}
-function readOnlyOpenWorldAnnotations(title) {
-  return {
-    title,
-    readOnlyHint: true,
-    openWorldHint: true
-  };
-}
+var scanCreationAnnotations = {
+  readOnlyHint: false,
+  destructiveHint: false,
+  idempotentHint: false,
+  openWorldHint: true
+};
+var readOnlyOpenWorldAnnotations = {
+  readOnlyHint: true,
+  openWorldHint: true
+};
 var mcpToolErrorPayloadSchema = external_exports.object({
   error: external_exports.object({
     name: external_exports.string(),
@@ -18108,7 +18106,10 @@ var mcpScanSiteOutputSchema = external_exports.object({
   jobId: external_exports.string().optional(),
   domain: external_exports.string().nullable().optional(),
   status: apiV2ScanStatusSchema,
-  scanFrom: apiV2ScanFromSchema.optional()
+  scanFrom: apiV2ScanFromSchema.optional(),
+  startedAt: external_exports.string().nullable().optional(),
+  completedAt: external_exports.string().nullable().optional(),
+  scanTimeSeconds: external_exports.number().nullable().optional()
 }).passthrough();
 var mcpScanStatusOutputSchema = external_exports.object({
   type: external_exports.enum(["certscore_scan_job", "certscore_pulse_status"]).optional(),
@@ -18117,6 +18118,9 @@ var mcpScanStatusOutputSchema = external_exports.object({
   scan_id: external_exports.string().nullable().optional(),
   domain: external_exports.string().nullable().optional(),
   status: external_exports.union([apiV2ScanStatusSchema, pulseStatusSchema.shape.status]).optional(),
+  startedAt: external_exports.string().nullable().optional(),
+  completedAt: external_exports.string().nullable().optional(),
+  scanTimeSeconds: external_exports.number().nullable().optional(),
   error: mcpToolErrorPayloadSchema.shape.error.optional()
 }).passthrough();
 var mcpReportOutputSchema = external_exports.object({
@@ -18163,45 +18167,53 @@ var mcpPreConsentCookiesTrackersOutputSchema = apiV2PreConsentCookiesTrackersSch
   })
 });
 var certScoreMcpToolContracts = [
+  {
+    name: "create_scan",
+    title: "Create CertScore Pulse scan",
+    description: "Deprecated compatibility alias of scan_site. Removed in 0.2.0. Use scan_site. Start a CertScore Pulse scan for a public URL and return immediately with status, scan, and polling links.",
+    inputSchema: mcpCreateScanInputSchema,
+    outputSchema: mcpCreateScanOutputSchema,
+    annotations: scanCreationAnnotations
+  },
   {
     name: "scan_site",
     title: "Scan site",
-    description: "Start or reuse a CertScore public-web scan for a public URL. API docs: https://certscore.ai/api/v2/openapi.json",
+    description: "Start or reuse a CertScore public-web scan for a public URL. API v2 responses may include startedAt, completedAt, and scanTimeSeconds.",
     inputSchema: mcpCreateScanInputSchema,
     outputSchema: mcpScanSiteOutputSchema,
-    annotations: scanCreationAnnotations("Scan site")
+    annotations: scanCreationAnnotations
   },
   {
     name: "get_scan",
     title: "Get CertScore scan",
-    description: "Retrieve the API v2 public-safe scan resource for a stable scan ID.",
+    description: "Retrieve the API v2 public-safe scan resource for a stable scan ID, including startedAt, completedAt, and scanTimeSeconds when available.",
     inputSchema: mcpGetScanInputSchema,
     outputSchema: apiV2ScanResourceSchema,
-    annotations: readOnlyOpenWorldAnnotations("Get CertScore scan")
+    annotations: readOnlyOpenWorldAnnotations
   },
   {
     name: "get_scan_status",
-    title: "Get CertScore scan status",
-    description: "Pass scanId (preferred, API v2). Pass jobId only for a just-created scan that has not yet returned a scanId.",
+    title: "Get CertScore Pulse scan status",
+    description: "Pass scanId (preferred, API v2) to retrieve status and scan timing fields. Pass jobId only for a just-created scan that has not yet returned a scanId.",
     inputSchema: mcpGetScanStatusInputSchema,
     outputSchema: mcpScanStatusOutputSchema,
-    annotations: readOnlyOpenWorldAnnotations("Get CertScore scan status")
+    annotations: readOnlyOpenWorldAnnotations
   },
   {
     name: "get_report",
-    title: "Get CertScore report",
+    title: "Get CertScore Pulse report",
     description: "Retrieve a summary CertScore Pulse report by stable scan ID. Use get_evidence for the larger bounded evidence packet.",
     inputSchema: mcpGetReportInputSchema,
     outputSchema: mcpReportOutputSchema,
-    annotations: readOnlyOpenWorldAnnotations("Get CertScore report")
+    annotations: readOnlyOpenWorldAnnotations
   },
   {
     name: "get_evidence",
-    title: "Get CertScore evidence",
+    title: "Get CertScore Pulse evidence",
     description: "Retrieve the bounded structured Evidence JSON packet for a stable scan ID. Excludes raw cookie values, raw bodies, sensitive payloads, full DOM, and unredacted query values.",
     inputSchema: mcpGetEvidenceInputSchema,
     outputSchema: pulseResponseSchema,
-    annotations: readOnlyOpenWorldAnnotations("Get CertScore evidence")
+    annotations: readOnlyOpenWorldAnnotations
   },
   {
     name: "export_findings",
@@ -18209,7 +18221,7 @@ var certScoreMcpToolContracts = [
     description: "Return structured findings from a CertScore Pulse report for downstream review or ticketing workflows.",
     inputSchema: mcpExportFindingsInputSchema,
     outputSchema: mcpFindingsExportOutputSchema,
-    annotations: readOnlyOpenWorldAnnotations("Export CertScore findings")
+    annotations: readOnlyOpenWorldAnnotations
   },
   {
     name: "list_findings",
@@ -18217,15 +18229,15 @@ var certScoreMcpToolContracts = [
     description: "List API v2 public-safe findings already projected for a scan.",
     inputSchema: mcpListFindingsInputSchema,
     outputSchema: mcpFindingListOutputSchema,
-    annotations: readOnlyOpenWorldAnnotations("List CertScore findings")
+    annotations: readOnlyOpenWorldAnnotations
   },
   {
     name: "get_pre_consent_cookies_trackers",
-    title: "Get pre-consent cookies & trackers",
+    title: "Get pre-consent cookies and trackers",
     description: "Retrieve the public-safe Cookies & Trackers (Pre-consent) report table as compact JSON for a scan.",
     inputSchema: mcpGetPreConsentCookiesTrackersInputSchema,
     outputSchema: mcpPreConsentCookiesTrackersOutputSchema,
-    annotations: readOnlyOpenWorldAnnotations("Get pre-consent cookies & trackers")
+    annotations: readOnlyOpenWorldAnnotations
   },
   {
     name: "explain_finding",
@@ -18233,7 +18245,7 @@ var certScoreMcpToolContracts = [
     description: "Explain a single CertScore finding with public evidence, caveats, and reviewer next steps.",
     inputSchema: mcpExplainFindingInputSchema,
     outputSchema: apiV2FindingDetailSchema,
-    annotations: readOnlyOpenWorldAnnotations("Explain CertScore finding")
+    annotations: readOnlyOpenWorldAnnotations
   },
   {
     name: "get_latest_domain_scan",
@@ -18241,15 +18253,15 @@ var certScoreMcpToolContracts = [
     description: "Retrieve the latest eligible API v2 public-safe scan for a domain.",
     inputSchema: mcpGetLatestDomainScanInputSchema,
     outputSchema: apiV2DomainLatestScanSchema,
-    annotations: readOnlyOpenWorldAnnotations("Get latest domain scan")
+    annotations: readOnlyOpenWorldAnnotations
   },
   {
     name: "get_latest_domain_pre_consent_cookies_trackers",
-    title: "Get latest pre-consent cookies & trackers",
+    title: "Get latest domain pre-consent cookies and trackers",
     description: "Retrieve the public-safe Cookies & Trackers (Pre-consent) table from the latest eligible scan for a domain.",
     inputSchema: mcpGetLatestDomainPreConsentCookiesTrackersInputSchema,
     outputSchema: mcpPreConsentCookiesTrackersOutputSchema,
-    annotations: readOnlyOpenWorldAnnotations("Get latest pre-consent cookies & trackers")
+    annotations: readOnlyOpenWorldAnnotations
   }
 ];
 
@@ -22702,6 +22714,7 @@ function explainFinding(report, findingId) {
 }
 
 // src/server.ts
+var createScanDeprecationWarningPrinted = false;
 function toolContract(name) {
   const contract = certScoreMcpToolContracts.find((candidate) => candidate.name === name);
   if (!contract) {
@@ -22726,6 +22739,40 @@ function createCertScoreMcpServer(options = {}) {
     version: CERTSCORE_MCP_VERSION
   });
   const registerTool = server.registerTool.bind(server);
+  async function createPulseScanTool(input) {
+    const result = await client.submitScan(input.url, {
+      detail: normalizeDetail2(input.detail),
+      format: normalizeFormat2(input.format),
+      freshness: input.freshness ?? "latest",
+      scanFrom: input.scanFrom
+    });
+    return {
+      type: "certscore_mcp_scan_created",
+      status: result.status,
+      jobId: result.jobId ?? null,
+      scanId: result.scanId ?? result.scan_id ?? null,
+      completed: result.completed ?? false,
+      statusUrl: result.statusUrl ?? result.nextCheckUrl ?? null,
+      resultUrl: result.resultUrl ?? null,
+      reportUrl: result.reportUrl ?? null,
+      pulse: result.pulse ?? null
+    };
+  }
+  registerTool(
+    "create_scan",
+    toolContract("create_scan"),
+    async (input) => {
+      try {
+        if (!createScanDeprecationWarningPrinted) {
+          createScanDeprecationWarningPrinted = true;
+          console.error("[certscore-mcp] create_scan is deprecated and will be removed in 0.2.0. Use scan_site.");
+        }
+        return toToolResult(await createPulseScanTool(input));
+      } catch (error2) {
+        return toToolError(error2);
+      }
+    }
+  );
   registerTool(
     "scan_site",
     toolContract("scan_site"),

package/dist/server.d.ts.map

@@ -1 +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"}
+{"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;AAqCD,wBAAgB,wBAAwB,CAAC,OAAO,GAAE,mBAAwB,aAsNzE"}

package/dist/server.js

@@ -3,6 +3,7 @@ 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";
+let createScanDeprecationWarningPrinted = false;
 function toolContract(name) {
     const contract = certScoreMcpToolContracts.find((candidate) => candidate.name === name);
     if (!contract) {
@@ -27,6 +28,37 @@ export function createCertScoreMcpServer(options = {}) {
         version: CERTSCORE_MCP_VERSION
     });
     const registerTool = server.registerTool.bind(server);
+    async function createPulseScanTool(input) {
+        const result = await client.submitScan(input.url, {
+            detail: normalizeDetail(input.detail),
+            format: normalizeFormat(input.format),
+            freshness: input.freshness ?? "latest",
+            scanFrom: input.scanFrom
+        });
+        return {
+            type: "certscore_mcp_scan_created",
+            status: result.status,
+            jobId: result.jobId ?? null,
+            scanId: result.scanId ?? result.scan_id ?? null,
+            completed: result.completed ?? false,
+            statusUrl: result.statusUrl ?? result.nextCheckUrl ?? null,
+            resultUrl: result.resultUrl ?? null,
+            reportUrl: result.reportUrl ?? null,
+            pulse: result.pulse ?? null
+        };
+    }
+    registerTool("create_scan", toolContract("create_scan"), async (input) => {
+        try {
+            if (!createScanDeprecationWarningPrinted) {
+                createScanDeprecationWarningPrinted = true;
+                console.error("[certscore-mcp] create_scan is deprecated and will be removed in 0.2.0. Use scan_site.");
+            }
+            return toToolResult(await createPulseScanTool(input));
+        }
+        catch (error) {
+            return toToolError(error);
+        }
+    });
     registerTool("scan_site", toolContract("scan_site"), async (input) => {
         try {
             return toToolResult(await client.scans.create(input.url, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@certscore/mcp",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "mcpName": "ai.certscore/mcp",
   "private": false,
   "description": "MCP server for CertScore public website risk-signal workflows.",
@@ -60,7 +60,7 @@
   },
   "devDependencies": {
     "@certscore/api-contracts": "0.1.0",
-    "@certscore/sdk": "0.1.0"
+    "@certscore/sdk": "0.2.3"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json && esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --banner:js='#!/usr/bin/env node' --outfile=dist/certscore-mcp.mjs",

package/server.json

@@ -1,37 +1,23 @@
 {
-  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
   "name": "ai.certscore/mcp",
-  "title": "CertScore MCP",
-  "description": "CertScore website risk-signal tools for scans, findings, evidence, and latest-domain lookups.",
+  "description": "MCP server for CertScore public website risk-signal workflows.",
+  "status": "active",
   "repository": {
     "url": "https://github.com/ergoveritas1-alt/certscore.ai",
     "source": "github"
   },
-  "version": "0.2.4",
+  "version": "0.2.5",
   "packages": [
     {
       "registryType": "npm",
+      "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@certscore/mcp",
-      "version": "0.2.4",
+      "version": "0.2.5",
       "transport": {
         "type": "stdio"
       },
-      "environmentVariables": [
-        {
-          "name": "CERTSCORE_API_KEY",
-          "description": "CertScore API key with scan:read, scan:create, and mcp scopes.",
-          "isRequired": true,
-          "format": "string",
-          "isSecret": true
-        },
-        {
-          "name": "CERTSCORE_BASE_URL",
-          "description": "Optional CertScore API base URL. Defaults to https://certscore.ai.",
-          "isRequired": false,
-          "format": "string",
-          "isSecret": false
-        }
-      ]
+      "runtimeHint": "node"
     }
   ]
 }