@certscore/mcp 0.2.2 → 0.2.4

package/README.md

@@ -2,7 +2,7 @@
 
 CertScore MCP exposes a focused Model Context Protocol server for CertScore Pulse workflows.
 
-Status: public developer preview. The server is distributed for external macOS MCP clients through Homebrew. Local WC01 development uses `pnpm mcp:certscore`.
+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`.
 
 Public docs:
 
@@ -13,7 +13,7 @@ Public docs:
 
 ## Tools
 
-- `scan_site` - Start or reuse a CertScore public-web scan for a public URL.
+- `scan_site` - Start or reuse a CertScore public-web scan for a public URL. API docs: https://certscore.ai/api/v2/openapi.json
 - `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.
@@ -60,12 +60,9 @@ Run from this monorepo for local development:
 CERTSCORE_API_KEY=... pnpm mcp:certscore
 ```
 
-Generate a scoped preview key after applying DB migrations:
-
-```bash
-pnpm db:migrate
-pnpm mcp:certscore:generate-key -- --name "CertScore MCP preview"
-```
+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.
 
 Run the built package directly after local build:
 
@@ -80,11 +77,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 preview 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 integration 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`, `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.
+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.
 
 ## Verify Install
 
@@ -217,7 +214,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 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.
+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.
 
 ## Troubleshooting
 

package/dist/certscore-mcp.mjs

@@ -18065,16 +18065,22 @@ 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.")
 };
-var scanCreationAnnotations = {
-  readOnlyHint: false,
-  destructiveHint: true,
-  idempotentHint: false,
-  openWorldHint: true
-};
-var readOnlyOpenWorldAnnotations = {
-  readOnlyHint: true,
-  openWorldHint: true
-};
+function scanCreationAnnotations(title) {
+  return {
+    title,
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: true
+  };
+}
+function readOnlyOpenWorldAnnotations(title) {
+  return {
+    title,
+    readOnlyHint: true,
+    openWorldHint: true
+  };
+}
 var mcpToolErrorPayloadSchema = external_exports.object({
   error: external_exports.object({
     name: external_exports.string(),
@@ -18160,10 +18166,10 @@ var certScoreMcpToolContracts = [
   {
     name: "scan_site",
     title: "Scan site",
-    description: "Start or reuse a CertScore public-web scan for a public URL.",
+    description: "Start or reuse a CertScore public-web scan for a public URL. API docs: https://certscore.ai/api/v2/openapi.json",
     inputSchema: mcpCreateScanInputSchema,
     outputSchema: mcpScanSiteOutputSchema,
-    annotations: scanCreationAnnotations
+    annotations: scanCreationAnnotations("Scan site")
   },
   {
     name: "get_scan",
@@ -18171,31 +18177,31 @@ var certScoreMcpToolContracts = [
     description: "Retrieve the API v2 public-safe scan resource for a stable scan ID.",
     inputSchema: mcpGetScanInputSchema,
     outputSchema: apiV2ScanResourceSchema,
-    annotations: readOnlyOpenWorldAnnotations
+    annotations: readOnlyOpenWorldAnnotations("Get CertScore scan")
   },
   {
     name: "get_scan_status",
-    title: "Get CertScore Pulse 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.",
     inputSchema: mcpGetScanStatusInputSchema,
     outputSchema: mcpScanStatusOutputSchema,
-    annotations: readOnlyOpenWorldAnnotations
+    annotations: readOnlyOpenWorldAnnotations("Get CertScore scan status")
   },
   {
     name: "get_report",
-    title: "Get CertScore Pulse report",
+    title: "Get CertScore 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
+    annotations: readOnlyOpenWorldAnnotations("Get CertScore report")
   },
   {
     name: "get_evidence",
-    title: "Get CertScore Pulse evidence",
+    title: "Get CertScore 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
+    annotations: readOnlyOpenWorldAnnotations("Get CertScore evidence")
   },
   {
     name: "export_findings",
@@ -18203,7 +18209,7 @@ var certScoreMcpToolContracts = [
     description: "Return structured findings from a CertScore Pulse report for downstream review or ticketing workflows.",
     inputSchema: mcpExportFindingsInputSchema,
     outputSchema: mcpFindingsExportOutputSchema,
-    annotations: readOnlyOpenWorldAnnotations
+    annotations: readOnlyOpenWorldAnnotations("Export CertScore findings")
   },
   {
     name: "list_findings",
@@ -18211,15 +18217,15 @@ var certScoreMcpToolContracts = [
     description: "List API v2 public-safe findings already projected for a scan.",
     inputSchema: mcpListFindingsInputSchema,
     outputSchema: mcpFindingListOutputSchema,
-    annotations: readOnlyOpenWorldAnnotations
+    annotations: readOnlyOpenWorldAnnotations("List CertScore findings")
   },
   {
     name: "get_pre_consent_cookies_trackers",
-    title: "Get pre-consent cookies and trackers",
+    title: "Get pre-consent cookies & trackers",
     description: "Retrieve the public-safe Cookies & Trackers (Pre-consent) report table as compact JSON for a scan.",
     inputSchema: mcpGetPreConsentCookiesTrackersInputSchema,
     outputSchema: mcpPreConsentCookiesTrackersOutputSchema,
-    annotations: readOnlyOpenWorldAnnotations
+    annotations: readOnlyOpenWorldAnnotations("Get pre-consent cookies & trackers")
   },
   {
     name: "explain_finding",
@@ -18227,7 +18233,7 @@ var certScoreMcpToolContracts = [
     description: "Explain a single CertScore finding with public evidence, caveats, and reviewer next steps.",
     inputSchema: mcpExplainFindingInputSchema,
     outputSchema: apiV2FindingDetailSchema,
-    annotations: readOnlyOpenWorldAnnotations
+    annotations: readOnlyOpenWorldAnnotations("Explain CertScore finding")
   },
   {
     name: "get_latest_domain_scan",
@@ -18235,15 +18241,15 @@ var certScoreMcpToolContracts = [
     description: "Retrieve the latest eligible API v2 public-safe scan for a domain.",
     inputSchema: mcpGetLatestDomainScanInputSchema,
     outputSchema: apiV2DomainLatestScanSchema,
-    annotations: readOnlyOpenWorldAnnotations
+    annotations: readOnlyOpenWorldAnnotations("Get latest domain scan")
   },
   {
     name: "get_latest_domain_pre_consent_cookies_trackers",
-    title: "Get latest domain pre-consent cookies and trackers",
+    title: "Get latest pre-consent cookies & 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
+    annotations: readOnlyOpenWorldAnnotations("Get latest pre-consent cookies & trackers")
   }
 ];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@certscore/mcp",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "mcpName": "ai.certscore/mcp",
   "private": false,
   "description": "MCP server for CertScore public website risk-signal workflows.",
@@ -46,14 +46,6 @@
     "url": "https://certscore.ai/contact",
     "email": "support@certscore.ai"
   },
-  "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",
-    "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --banner:js='#!/usr/bin/env node' --outfile=dist/certscore-mcp.mjs",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "node --import tsx --test src/*.test.ts",
-    "prepack": "pnpm run build",
-    "clean": "rm -rf dist"
-  },
   "keywords": [
     "certscore",
     "pulse",
@@ -67,7 +59,14 @@
     "zod": "^3.25.76"
   },
   "devDependencies": {
-    "@certscore/api-contracts": "workspace:*",
-    "@certscore/sdk": "workspace:*"
+    "@certscore/api-contracts": "0.1.0",
+    "@certscore/sdk": "0.1.0"
+  },
+  "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",
+    "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --banner:js='#!/usr/bin/env node' --outfile=dist/certscore-mcp.mjs",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --import tsx --test src/*.test.ts",
+    "clean": "rm -rf dist"
   }
-}
+}

package/server.json

@@ -7,12 +7,12 @@
     "url": "https://github.com/ergoveritas1-alt/certscore.ai",
     "source": "github"
   },
-  "version": "0.2.2",
+  "version": "0.2.4",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@certscore/mcp",
-      "version": "0.2.2",
+      "version": "0.2.4",
       "transport": {
         "type": "stdio"
       },