mcp-scorecard 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-05-23
+
+### Added
+
+- Initial release.
+- CLI `mcp-scorecard <subject> [--json] [--min-score N]`.
+- Three resolvers: npm package (via `npm pack`), absolute local path, and GitHub URL.
+- Probe over `StdioClientTransport` with `MCP_PROBE=1` env flag set on the target.
+- Ten quality checks, each scored 0-10:
+  1. Schema validity (ajv-compiled inputSchema per tool)
+  2. Tool naming convention (shared prefix + snake_case)
+  3. Privacy modes documented (`privacy_mode` param or summary/structured/raw in descriptions)
+  4. Mutation gating (write tools must document a gate)
+  5. Agent manifest (`*_agent_manifest` returning `recommended_first_calls` + `standard_tools`)
+  6. Smoke test (presence of `scripts/smoke*.{mjs,js,ts}` or a real `test` script)
+  7. Resources advertised (count via `listResources`)
+  8. Tool descriptions (average length across tools)
+  9. Annotations (`annotations.readOnlyHint` on read tools)
+  10. Manifest discoverability (any of `*_agent_manifest`, `*_data_inventory`, `*_capabilities`, `*_connection_status`)
+- Markdown and JSON output formats.
+- Redaction pass on probe-derived strings: `customer_id`, `email`, `phone`,
+  `access_token`, `refresh_token`, `client_secret`, `developer_token`, `api_key`.
+- Four synthetic fixtures (`good`, `medium`, `bad`, `readonly`) under
+  `tests/fixtures/`. Test runner asserts each lands in its expected band.
+- Self-test (`scripts/smoke-self.mjs`) that audits the good fixture
+  end-to-end and asserts score >= 80 before publish.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Batista
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+<h1 align="center">mcp-scorecard</h1>
+
+<p align="center">
+  <a href="https://github.com/davidmosiah/mcp-scorecard/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/davidmosiah/mcp-scorecard/ci.yml?style=for-the-badge&labelColor=0F172A&color=10B981&logo=github" alt="CI" /></a>
+  <a href="https://www.npmjs.com/package/mcp-scorecard"><img src="https://img.shields.io/npm/v/mcp-scorecard?style=for-the-badge&labelColor=0F172A&color=10B981&logo=npm&logoColor=white" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/mcp-scorecard"><img src="https://img.shields.io/npm/dm/mcp-scorecard?style=for-the-badge&labelColor=0F172A&color=0EA5A3&logo=npm&logoColor=white" alt="npm downloads" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/LICENSE-MIT-22C55E?style=for-the-badge&labelColor=0F172A" alt="License MIT" /></a>
+  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/BUILT_FOR-MCP-7C3AED?style=for-the-badge&labelColor=0F172A" alt="Built for MCP" /></a>
+</p>
+
+<h3 align="center">
+  Agent-readiness scorecard for any MCP server.<br>
+  Probes a target over stdio, runs 10 checks, outputs a 0-100 score with itemized findings.
+</h3>
+
+---
+
+## Quick start
+
+```bash
+# Audit a published npm package
+npx -y mcp-scorecard whoop-mcp-unofficial
+
+# Audit a GitHub repo (auto-resolves to the published npm package, or local dist)
+npx -y mcp-scorecard https://github.com/davidmosiah/whoop-mcp
+
+# Audit a local build
+npx -y mcp-scorecard /Users/you/Desktop/my-mcp/dist/index.js
+
+# CI gate: fail the build if the score drops
+npx -y mcp-scorecard my-mcp --min-score 80
+
+# Structured JSON for piping into your own tooling
+npx -y mcp-scorecard my-mcp --json
+```
+
+## What it checks
+
+Ten quality dimensions, each scored 0-10. Final score is the sum, capped at 100.
+
+1. **Schema validity** - boots the server, lists tools, and validates each
+   tool's `inputSchema` with ajv. Missing or non-object schemas score zero
+   per tool.
+2. **Tool naming convention** - rewards a shared prefix and snake_case
+   (e.g. `whoop_get_sleep`). Mixed case, hyphens, and missing prefixes lose
+   points.
+3. **Privacy modes documented** - looks for a `privacy_mode` parameter on
+   any tool, or descriptions that mention `summary | structured | raw`.
+4. **Mutation gating** - any tool name matching `(set|update|delete|create|
+   pause|resume|enable|disable|cancel|publish|send)` must document a gate
+   in its description (`Gated by ALLOW_MUTATIONS`, `requires explicit user
+   intent`, `dry-run`, `confirm`).
+5. **Agent manifest** - calls `<prefix>_agent_manifest` and checks the
+   response object has `recommended_first_calls` (non-empty array) AND
+   `standard_tools` (non-empty array). The probe NEVER persists the payload
+   - only field names and lengths are recorded.
+6. **Smoke test present** - looks for `scripts/smoke*.{mjs,js,ts}` in the
+   package, or a real `test` script in `package.json` (not the npm default
+   echo-and-fail).
+7. **Resources advertised** - counts what `listResources()` returns. Zero
+   scores zero; one or two scores 5; three or more scores 10.
+8. **Tool descriptions** - average description length across all tools.
+   Below 30 chars scores 0; 30-60 scores 5; 60+ scores 10.
+9. **Annotations** - counts what fraction of read tools (any non-mutation
+   tool) carry `annotations.readOnlyHint = true`. Score scales linearly.
+10. **Manifest discoverability** - has any of `*_agent_manifest`,
+    `*_data_inventory`, `*_capabilities`, `*_connection_status`. Two or
+    more scores 10; exactly one scores 7; none scores 0.
+
+## Output format
+
+### Markdown (default)
+
+```
+# mcp-scorecard - whoop-mcp-unofficial @0.4.3
+
+**Agent-readiness score:** 88/100
+
+- [PASS] Schema validity              (28/28 tools have valid input schema)
+- [PASS] Tool naming convention       (consistent `whoop_` prefix, snake_case)
+- [PASS] Privacy modes documented     (privacy_mode parameter on 6 tool(s))
+- [PASS] Mutation gating              (no write tools - n/a)
+- [PASS] Agent manifest               (recommended_first_calls present, 5 entries)
+- [PASS] Smoke test                   (scripts/smoke-tools.mjs found)
+- [PASS] Resources advertised         (8 resources registered)
+- [PASS] Tool descriptions            (avg 142 chars across 28 tools)
+- [WARN] Annotations                  (20/28 read tools annotated)
+- [PASS] Manifest discoverability     (4/4 discovery tools present (agent_manifest, data_inventory, capabilities, connection_status))
+
+## Suggested fixes
+- Add `annotations: { readOnlyHint: true, openWorldHint: false }` to every read tool definition.
+
+_Generated by mcp-scorecard v0.1.0 at 2026-05-23T15:42:11.000Z_
+```
+
+### JSON (`--json`)
+
+```json
+{
+  "target": {
+    "displayName": "whoop-mcp-unofficial",
+    "version": "0.4.3",
+    "serverName": "whoop-mcp",
+    "serverVersion": "0.4.3"
+  },
+  "totalScore": 88,
+  "checks": [
+    {
+      "id": "schema_validity",
+      "label": "Schema validity",
+      "score": 10,
+      "status": "pass",
+      "summary": "28/28 tools have valid input schema",
+      "details": [],
+      "fixes": []
+    }
+  ],
+  "generatedAt": "2026-05-23T15:42:11.000Z",
+  "scorecardVersion": "0.1.0"
+}
+```
+
+## How it probes
+
+The scorecard launches the target MCP server over stdio with
+`MCP_PROBE=1` set on the child's env. **Author hook:** if your MCP needs
+OAuth or other credentials to even list tools, detect this env var and
+return your tool/resource/prompt manifests anyway. The scorecard expects
+to be able to read your contract without making any auth-requiring API
+calls.
+
+### Privacy model
+
+- The probe response is **never persisted**. Only counts and field names
+  are recorded into the in-memory snapshot used by checks.
+- Any string going into the report is run through a redaction pass that
+  replaces values for `customer_id`, `email`, `phone`, `access_token`,
+  `refresh_token`, `client_secret`, `developer_token`, and `api_key` with
+  `[REDACTED]`.
+- No telemetry. No network calls beyond `npm pack` (when auditing a
+  package by name) and `gh repo clone` (when auditing a GitHub URL).
+
+## Use cases
+
+- **CI gate** - block a PR if the score drops below a threshold:
+  `npx -y mcp-scorecard my-mcp --min-score 85`.
+- **Registry curation** - run the audit across a list of MCPs to pick
+  the best-documented and most agent-friendly options for a directory or
+  catalog.
+- **Pre-publish self-check** - add it to `prepublishOnly` so you never
+  ship a regressed contract by accident.
+- **Comparative review** - score two MCPs that ostensibly cover the same
+  API and see which is friendlier to agents.
+
+## Limitations
+
+- Cannot probe MCPs that REQUIRE auth before `listTools()` returns. If
+  your server is one of these, support the `MCP_PROBE` env hook so the
+  scorecard can still read your contract.
+- Cannot grade logic correctness - the scorecard only inspects shape,
+  metadata, and discoverability. A server can score 100/100 and still
+  return wrong data.
+- Mutation detection is name-based - if you call a write tool
+  `prepare_thing` instead of `set_thing`, the check will miss it. This
+  is intentional: we reward clear naming.
+
+## Roadmap
+
+- **v0.2** - rule pack for agent-rules-of-thumb (output shape stability,
+  pagination patterns, error envelope consistency), a perf benchmark
+  (median `listTools()` latency), and an OAuth probe with a mock token.
+
+## Support
+
+- Issues: <https://github.com/davidmosiah/mcp-scorecard/issues>
+- Email: support@delx.ai
+
+## Disclaimer
+
+This is a quality audit tool. It does not certify security, privacy,
+or correctness; it only measures whether a server follows agent-friendly
+conventions. Always do your own review before plugging an MCP into a
+production agent.
+
+## License
+
+MIT - see [LICENSE](LICENSE).

package/dist/audit/checks/agent-manifest.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Check 5 — Agent manifest.
+ *
+ * The probe already attempted to call `*_agent_manifest`. We grade what
+ * came back:
+ *   10 — recommended_first_calls (length > 0) AND standard_tools (length > 0)
+ *    7 — has one of those two
+ *    3 — manifest tool exists but returned an unusable shape
+ *    0 — no manifest tool at all
+ */
+import type { CheckResult, ProbeSnapshot } from '../../types.js';
+export declare function checkAgentManifest(snapshot: ProbeSnapshot): CheckResult;

package/dist/audit/checks/agent-manifest.js

@@ -0,0 +1,72 @@
+/**
+ * Check 5 — Agent manifest.
+ *
+ * The probe already attempted to call `*_agent_manifest`. We grade what
+ * came back:
+ *   10 — recommended_first_calls (length > 0) AND standard_tools (length > 0)
+ *    7 — has one of those two
+ *    3 — manifest tool exists but returned an unusable shape
+ *    0 — no manifest tool at all
+ */
+export function checkAgentManifest(snapshot) {
+    const hasManifestTool = snapshot.tools.some((t) => /(^|_)agent_manifest$/.test(t.name));
+    const manifest = snapshot.agentManifest;
+    if (!hasManifestTool) {
+        return {
+            id: 'agent_manifest',
+            label: 'Agent manifest',
+            score: 0,
+            status: 'fail',
+            summary: 'no agent_manifest tool',
+            details: [],
+            fixes: [
+                'Expose a `<prefix>_agent_manifest` tool that returns { recommended_first_calls, standard_tools, ... } so agents can self-onboard.'
+            ]
+        };
+    }
+    if (!manifest) {
+        return {
+            id: 'agent_manifest',
+            label: 'Agent manifest',
+            score: 3,
+            status: 'fail',
+            summary: 'agent_manifest tool present but call failed',
+            details: ['Calling the manifest tool did not return parseable JSON.'],
+            fixes: ['Ensure `<prefix>_agent_manifest` returns text content containing JSON with recommended_first_calls + standard_tools.']
+        };
+    }
+    const hasFC = manifest.has_recommended_first_calls && manifest.recommended_first_calls_count > 0;
+    const hasST = manifest.has_standard_tools && manifest.standard_tools_count > 0;
+    let score;
+    let summary;
+    if (hasFC && hasST) {
+        score = 10;
+        summary = `recommended_first_calls present (${manifest.recommended_first_calls_count} entries)`;
+    }
+    else if (hasFC || hasST) {
+        score = 7;
+        summary = hasFC
+            ? 'recommended_first_calls present; standard_tools missing'
+            : 'standard_tools present; recommended_first_calls missing';
+    }
+    else {
+        score = 3;
+        summary = 'agent_manifest returned object but no expected arrays';
+    }
+    const status = score >= 9 ? 'pass' : score >= 5 ? 'warn' : 'fail';
+    const fixes = [];
+    if (!hasFC)
+        fixes.push('Add `recommended_first_calls: [...]` to the manifest response.');
+    if (!hasST)
+        fixes.push('Add `standard_tools: [...]` to the manifest response.');
+    return {
+        id: 'agent_manifest',
+        label: 'Agent manifest',
+        score,
+        status,
+        summary,
+        details: [],
+        fixes
+    };
+}
+//# sourceMappingURL=agent-manifest.js.map

package/dist/audit/checks/agent-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-manifest.js","sourceRoot":"","sources":["../../../src/audit/checks/agent-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,UAAU,kBAAkB,CAAC,QAAuB;IACxD,MAAM,eAAe,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACxF,MAAM,QAAQ,GAAG,QAAQ,CAAC,aAAa,CAAC;IAExC,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,OAAO;YACL,EAAE,EAAE,gBAAgB;YACpB,KAAK,EAAE,gBAAgB;YACvB,KAAK,EAAE,CAAC;YACR,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,wBAAwB;YACjC,OAAO,EAAE,EAAE;YACX,KAAK,EAAE;gBACL,mIAAmI;aACpI;SACF,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,QAAQ,EAAE,CAAC;QACd,OAAO;YACL,EAAE,EAAE,gBAAgB;YACpB,KAAK,EAAE,gBAAgB;YACvB,KAAK,EAAE,CAAC;YACR,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,6CAA6C;YACtD,OAAO,EAAE,CAAC,0DAA0D,CAAC;YACrE,KAAK,EAAE,CAAC,sHAAsH,CAAC;SAChI,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,QAAQ,CAAC,2BAA2B,IAAI,QAAQ,CAAC,6BAA6B,GAAG,CAAC,CAAC;IACjG,MAAM,KAAK,GAAG,QAAQ,CAAC,kBAAkB,IAAI,QAAQ,CAAC,oBAAoB,GAAG,CAAC,CAAC;IAE/E,IAAI,KAAa,CAAC;IAClB,IAAI,OAAe,CAAC;IACpB,IAAI,KAAK,IAAI,KAAK,EAAE,CAAC;QACnB,KAAK,GAAG,EAAE,CAAC;QACX,OAAO,GAAG,oCAAoC,QAAQ,CAAC,6BAA6B,WAAW,CAAC;IAClG,CAAC;SAAM,IAAI,KAAK,IAAI,KAAK,EAAE,CAAC;QAC1B,KAAK,GAAG,CAAC,CAAC;QACV,OAAO,GAAG,KAAK;YACb,CAAC,CAAC,yDAAyD;YAC3D,CAAC,CAAC,yDAAyD,CAAC;IAChE,CAAC;SAAM,CAAC;QACN,KAAK,GAAG,CAAC,CAAC;QACV,OAAO,GAAG,uDAAuD,CAAC;IACpE,CAAC;IAED,MAAM,MAAM,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IAElE,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,gEAAgE,CAAC,CAAC;IACzF,IAAI,CAAC,KAAK;QAAE,KAAK,CAAC,IAAI,CAAC,uDAAuD,CAAC,CAAC;IAEhF,OAAO;QACL,EAAE,EAAE,gBAAgB;QACpB,KAAK,EAAE,gBAAgB;QACvB,KAAK;QACL,MAAM;QACN,OAAO;QACP,OAAO,EAAE,EAAE;QACX,KAAK;KACN,CAAC;AACJ,CAAC"}

package/dist/audit/checks/annotations.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Check 9 — Annotations.
+ *
+ * Counts what fraction of read tools (any non-mutation tool name) carry the
+ * MCP 1.20+ `annotations.readOnlyHint` field. Score = 10 * (annotated / read).
+ *
+ * If no read tools exist (rare — server is pure write) → score = 10 (n/a).
+ */
+import type { CheckResult, ProbeSnapshot } from '../../types.js';
+export declare function checkAnnotations(snapshot: ProbeSnapshot): CheckResult;

package/dist/audit/checks/annotations.js

@@ -0,0 +1,54 @@
+/**
+ * Check 9 — Annotations.
+ *
+ * Counts what fraction of read tools (any non-mutation tool name) carry the
+ * MCP 1.20+ `annotations.readOnlyHint` field. Score = 10 * (annotated / read).
+ *
+ * If no read tools exist (rare — server is pure write) → score = 10 (n/a).
+ */
+import { MUTATION_PATTERNS } from '../../constants.js';
+function isReadTool(name) {
+    return !MUTATION_PATTERNS.some((p) => p.test(name));
+}
+function hasReadOnlyHint(annotations) {
+    if (!annotations)
+        return false;
+    const v = annotations.readOnlyHint;
+    return v === true;
+}
+export function checkAnnotations(snapshot) {
+    const readTools = snapshot.tools.filter((t) => isReadTool(t.name));
+    if (readTools.length === 0) {
+        return {
+            id: 'annotations',
+            label: 'Annotations',
+            score: 10,
+            status: 'pass',
+            summary: 'no read tools — n/a',
+            details: [],
+            fixes: []
+        };
+    }
+    const annotated = readTools.filter((t) => hasReadOnlyHint(t.annotations));
+    const missing = readTools.filter((t) => !hasReadOnlyHint(t.annotations)).map((t) => t.name);
+    const score = Math.round((annotated.length / readTools.length) * 10);
+    const status = score >= 9 ? 'pass' : score >= 5 ? 'warn' : 'fail';
+    const details = [];
+    if (missing.length) {
+        details.push(`Missing readOnlyHint: ${missing.slice(0, 10).join(', ')}`);
+    }
+    const fixes = [];
+    if (score < 10) {
+        fixes.push('Add `annotations: { readOnlyHint: true, openWorldHint: false }` to every read tool definition.');
+    }
+    return {
+        id: 'annotations',
+        label: 'Annotations',
+        score,
+        status,
+        summary: `${annotated.length}/${readTools.length} read tools annotated`,
+        details,
+        fixes
+    };
+}
+//# sourceMappingURL=annotations.js.map

package/dist/audit/checks/annotations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../../../src/audit/checks/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAGvD,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AACtD,CAAC;AAED,SAAS,eAAe,CAAC,WAAgD;IACvE,IAAI,CAAC,WAAW;QAAE,OAAO,KAAK,CAAC;IAC/B,MAAM,CAAC,GAAG,WAAW,CAAC,YAAY,CAAC;IACnC,OAAO,CAAC,KAAK,IAAI,CAAC;AACpB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,QAAuB;IACtD,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IACnE,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO;YACL,EAAE,EAAE,aAAa;YACjB,KAAK,EAAE,aAAa;YACpB,KAAK,EAAE,EAAE;YACT,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,qBAAqB;YAC9B,OAAO,EAAE,EAAE;YACX,KAAK,EAAE,EAAE;SACV,CAAC;IACJ,CAAC;IAED,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,eAAe,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;IAC1E,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,eAAe,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IAC5F,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;IACrE,MAAM,MAAM,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IAElE,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,OAAO,CAAC,IAAI,CAAC,yBAAyB,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,KAAK,GAAG,EAAE,EAAE,CAAC;QACf,KAAK,CAAC,IAAI,CACR,gGAAgG,CACjG,CAAC;IACJ,CAAC;IAED,OAAO;QACL,EAAE,EAAE,aAAa;QACjB,KAAK,EAAE,aAAa;QACpB,KAAK;QACL,MAAM;QACN,OAAO,EAAE,GAAG,SAAS,CAAC,MAAM,IAAI,SAAS,CAAC,MAAM,uBAAuB;QACvE,OAAO;QACP,KAAK;KACN,CAAC;AACJ,CAAC"}

package/dist/audit/checks/manifest-discoverability.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Check 10 — Manifest discoverability.
+ *
+ * Server gets full credit if it exposes ANY of:
+ *   *_agent_manifest, *_data_inventory, *_capabilities, *_connection_status
+ *
+ * Score:
+ *   10 — has 2+ of these tools
+ *    7 — has exactly 1
+ *    0 — has none
+ */
+import type { CheckResult, ProbeSnapshot } from '../../types.js';
+export declare function checkManifestDiscoverability(snapshot: ProbeSnapshot): CheckResult;

package/dist/audit/checks/manifest-discoverability.js

@@ -0,0 +1,48 @@
+/**
+ * Check 10 — Manifest discoverability.
+ *
+ * Server gets full credit if it exposes ANY of:
+ *   *_agent_manifest, *_data_inventory, *_capabilities, *_connection_status
+ *
+ * Score:
+ *   10 — has 2+ of these tools
+ *    7 — has exactly 1
+ *    0 — has none
+ */
+import { DISCOVERY_TOOL_SUFFIXES } from '../../constants.js';
+function matchesSuffix(name, suffix) {
+    return name === suffix || name.endsWith(`_${suffix}`);
+}
+export function checkManifestDiscoverability(snapshot) {
+    const present = DISCOVERY_TOOL_SUFFIXES.filter((suf) => snapshot.tools.some((t) => matchesSuffix(t.name, suf)));
+    let score;
+    let status;
+    if (present.length >= 2) {
+        score = 10;
+        status = 'pass';
+    }
+    else if (present.length === 1) {
+        score = 7;
+        status = 'warn';
+    }
+    else {
+        score = 0;
+        status = 'fail';
+    }
+    const fixes = [];
+    if (score < 10) {
+        fixes.push('Expose discovery tools so agents can self-onboard: `*_agent_manifest`, `*_data_inventory`, `*_capabilities`, `*_connection_status`.');
+    }
+    return {
+        id: 'manifest_discoverability',
+        label: 'Manifest discoverability',
+        score,
+        status,
+        summary: present.length
+            ? `${present.length}/${DISCOVERY_TOOL_SUFFIXES.length} discovery tools present (${present.join(', ')})`
+            : 'no discovery tools',
+        details: [],
+        fixes
+    };
+}
+//# sourceMappingURL=manifest-discoverability.js.map

package/dist/audit/checks/manifest-discoverability.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-discoverability.js","sourceRoot":"","sources":["../../../src/audit/checks/manifest-discoverability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAG7D,SAAS,aAAa,CAAC,IAAY,EAAE,MAAc;IACjD,OAAO,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,MAAM,EAAE,CAAC,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,QAAuB;IAClE,MAAM,OAAO,GAAG,uBAAuB,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CACrD,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,CACvD,CAAC;IAEF,IAAI,KAAa,CAAC;IAClB,IAAI,MAA6B,CAAC;IAClC,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QACxB,KAAK,GAAG,EAAE,CAAC;QACX,MAAM,GAAG,MAAM,CAAC;IAClB,CAAC;SAAM,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChC,KAAK,GAAG,CAAC,CAAC;QACV,MAAM,GAAG,MAAM,CAAC;IAClB,CAAC;SAAM,CAAC;QACN,KAAK,GAAG,CAAC,CAAC;QACV,MAAM,GAAG,MAAM,CAAC;IAClB,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,KAAK,GAAG,EAAE,EAAE,CAAC;QACf,KAAK,CAAC,IAAI,CACR,qIAAqI,CACtI,CAAC;IACJ,CAAC;IAED,OAAO;QACL,EAAE,EAAE,0BAA0B;QAC9B,KAAK,EAAE,0BAA0B;QACjC,KAAK;QACL,MAAM;QACN,OAAO,EAAE,OAAO,CAAC,MAAM;YACrB,CAAC,CAAC,GAAG,OAAO,CAAC,MAAM,IAAI,uBAAuB,CAAC,MAAM,6BAA6B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;YACvG,CAAC,CAAC,oBAAoB;QACxB,OAAO,EAAE,EAAE;QACX,KAAK;KACN,CAAC;AACJ,CAAC"}

package/dist/audit/checks/mutation-gating.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Check 4 — Mutation gating.
+ *
+ * A tool is treated as mutating if its name matches MUTATION_PATTERNS (set,
+ * update, delete, create, pause, resume, enable, disable, cancel, publish,
+ * send, etc.). For each mutation tool, we check if the description mentions
+ * any MUTATION_GATE_HINTS phrase.
+ *
+ * Scoring:
+ *   - if NO mutation tools exist → 10 (vacuously gated)
+ *   - else: 10 * (gated / total_mutations)
+ */
+import type { CheckResult, ProbeSnapshot } from '../../types.js';
+export declare function checkMutationGating(snapshot: ProbeSnapshot): CheckResult;

package/dist/audit/checks/mutation-gating.js

@@ -0,0 +1,58 @@
+/**
+ * Check 4 — Mutation gating.
+ *
+ * A tool is treated as mutating if its name matches MUTATION_PATTERNS (set,
+ * update, delete, create, pause, resume, enable, disable, cancel, publish,
+ * send, etc.). For each mutation tool, we check if the description mentions
+ * any MUTATION_GATE_HINTS phrase.
+ *
+ * Scoring:
+ *   - if NO mutation tools exist → 10 (vacuously gated)
+ *   - else: 10 * (gated / total_mutations)
+ */
+import { MUTATION_GATE_HINTS, MUTATION_PATTERNS } from '../../constants.js';
+function isMutation(name) {
+    return MUTATION_PATTERNS.some((p) => p.test(name));
+}
+function descriptionMentionsGate(desc) {
+    if (!desc)
+        return false;
+    const lower = desc.toLowerCase();
+    return MUTATION_GATE_HINTS.some((hint) => lower.includes(hint));
+}
+export function checkMutationGating(snapshot) {
+    const mutations = snapshot.tools.filter((t) => isMutation(t.name));
+    if (mutations.length === 0) {
+        return {
+            id: 'mutation_gating',
+            label: 'Mutation gating',
+            score: 10,
+            status: 'pass',
+            summary: 'no write tools — n/a',
+            details: [],
+            fixes: []
+        };
+    }
+    const gated = mutations.filter((t) => descriptionMentionsGate(t.description));
+    const ungated = mutations.filter((t) => !descriptionMentionsGate(t.description));
+    const score = Math.round((gated.length / mutations.length) * 10);
+    const status = score >= 9 ? 'pass' : score >= 5 ? 'warn' : 'fail';
+    const details = [];
+    if (ungated.length) {
+        details.push(`Ungated mutations: ${ungated.slice(0, 10).map((t) => t.name).join(', ')}`);
+    }
+    const fixes = [];
+    if (ungated.length) {
+        fixes.push('Document the gating mechanism in each mutation tool description (e.g. "Gated by ALLOW_MUTATIONS=1" or "Requires explicit user intent").');
+    }
+    return {
+        id: 'mutation_gating',
+        label: 'Mutation gating',
+        score,
+        status,
+        summary: `${gated.length}/${mutations.length} mutation tools document gating`,
+        details,
+        fixes
+    };
+}
+//# sourceMappingURL=mutation-gating.js.map

package/dist/audit/checks/mutation-gating.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation-gating.js","sourceRoot":"","sources":["../../../src/audit/checks/mutation-gating.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAG5E,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AACrD,CAAC;AAED,SAAS,uBAAuB,CAAC,IAAwB;IACvD,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACxB,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACjC,OAAO,mBAAmB,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,QAAuB;IACzD,MAAM,SAAS,GAAG,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAEnE,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO;YACL,EAAE,EAAE,iBAAiB;YACrB,KAAK,EAAE,iBAAiB;YACxB,KAAK,EAAE,EAAE;YACT,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,sBAAsB;YAC/B,OAAO,EAAE,EAAE;YACX,KAAK,EAAE,EAAE;SACV,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,uBAAuB,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;IAC9E,MAAM,OAAO,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;IACjF,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC;IACjE,MAAM,MAAM,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IAElE,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,OAAO,CAAC,IAAI,CAAC,sBAAsB,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC3F,CAAC;IAED,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,KAAK,CAAC,IAAI,CACR,yIAAyI,CAC1I,CAAC;IACJ,CAAC;IAED,OAAO;QACL,EAAE,EAAE,iBAAiB;QACrB,KAAK,EAAE,iBAAiB;QACxB,KAAK;QACL,MAAM;QACN,OAAO,EAAE,GAAG,KAAK,CAAC,MAAM,IAAI,SAAS,CAAC,MAAM,iCAAiC;QAC7E,OAAO;QACP,KAAK;KACN,CAAC;AACJ,CAAC"}

package/dist/audit/checks/privacy-modes.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Check 3 — Privacy modes documented.
+ *
+ * Two signals:
+ *   1. any tool input schema has a `privacy_mode` property
+ *   2. any tool description mentions "summary|structured|raw" as modes
+ *
+ * Score:
+ *   10 — privacy_mode parameter is on >=1 tool
+ *    7 — >=3 tools mention summary/structured/raw in descriptions
+ *    4 — exactly 1-2 tools mention them
+ *    0 — no signal at all
+ *
+ * We look at the probe snapshot only — no source-file scraping needed.
+ */
+import type { CheckResult, ProbeSnapshot } from '../../types.js';
+export declare function checkPrivacyModes(snapshot: ProbeSnapshot): CheckResult;

package/dist/audit/checks/privacy-modes.js

@@ -0,0 +1,62 @@
+/**
+ * Check 3 — Privacy modes documented.
+ *
+ * Two signals:
+ *   1. any tool input schema has a `privacy_mode` property
+ *   2. any tool description mentions "summary|structured|raw" as modes
+ *
+ * Score:
+ *   10 — privacy_mode parameter is on >=1 tool
+ *    7 — >=3 tools mention summary/structured/raw in descriptions
+ *    4 — exactly 1-2 tools mention them
+ *    0 — no signal at all
+ *
+ * We look at the probe snapshot only — no source-file scraping needed.
+ */
+const MODE_RE = /\b(summary|structured|raw)\b/i;
+function hasPrivacyModeParam(inputSchema) {
+    if (!inputSchema || typeof inputSchema !== 'object')
+        return false;
+    const props = inputSchema.properties;
+    if (!props || typeof props !== 'object')
+        return false;
+    return 'privacy_mode' in props || 'privacyMode' in props;
+}
+export function checkPrivacyModes(snapshot) {
+    const tools = snapshot.tools;
+    const withParam = tools.filter((t) => hasPrivacyModeParam(t.inputSchema));
+    const mentioning = tools.filter((t) => t.description && MODE_RE.test(t.description));
+    let score;
+    let summary;
+    if (withParam.length >= 1) {
+        score = 10;
+        summary = `privacy_mode parameter on ${withParam.length} tool(s)`;
+    }
+    else if (mentioning.length >= 3) {
+        score = 7;
+        summary = `${mentioning.length} tools document summary/structured/raw modes`;
+    }
+    else if (mentioning.length >= 1) {
+        score = 4;
+        summary = `only ${mentioning.length} tool(s) mention privacy modes`;
+    }
+    else {
+        score = 0;
+        summary = 'no privacy modes documented';
+    }
+    const status = score >= 9 ? 'pass' : score >= 5 ? 'warn' : 'fail';
+    const fixes = [];
+    if (score < 10) {
+        fixes.push('Add a `privacy_mode` parameter (summary | structured | raw) on read tools so agents can request only what they need.');
+    }
+    return {
+        id: 'privacy_modes',
+        label: 'Privacy modes documented',
+        score,
+        status,
+        summary,
+        details: [],
+        fixes
+    };
+}
+//# sourceMappingURL=privacy-modes.js.map

package/dist/audit/checks/privacy-modes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"privacy-modes.js","sourceRoot":"","sources":["../../../src/audit/checks/privacy-modes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,OAAO,GAAG,+BAA+B,CAAC;AAEhD,SAAS,mBAAmB,CAAC,WAAoB;IAC/C,IAAI,CAAC,WAAW,IAAI,OAAO,WAAW,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAClE,MAAM,KAAK,GAAI,WAAuC,CAAC,UAAU,CAAC;IAClE,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACtD,OAAO,cAAc,IAAK,KAAgB,IAAI,aAAa,IAAK,KAAgB,CAAC;AACnF,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,QAAuB;IACvD,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC;IAC7B,MAAM,SAAS,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,mBAAmB,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;IAC1E,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;IAErF,IAAI,KAAa,CAAC;IAClB,IAAI,OAAe,CAAC;IACpB,IAAI,SAAS,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QAC1B,KAAK,GAAG,EAAE,CAAC;QACX,OAAO,GAAG,6BAA6B,SAAS,CAAC,MAAM,UAAU,CAAC;IACpE,CAAC;SAAM,IAAI,UAAU,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QAClC,KAAK,GAAG,CAAC,CAAC;QACV,OAAO,GAAG,GAAG,UAAU,CAAC,MAAM,8CAA8C,CAAC;IAC/E,CAAC;SAAM,IAAI,UAAU,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QAClC,KAAK,GAAG,CAAC,CAAC;QACV,OAAO,GAAG,QAAQ,UAAU,CAAC,MAAM,gCAAgC,CAAC;IACtE,CAAC;SAAM,CAAC;QACN,KAAK,GAAG,CAAC,CAAC;QACV,OAAO,GAAG,6BAA6B,CAAC;IAC1C,CAAC;IAED,MAAM,MAAM,GAAG,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;IAElE,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,KAAK,GAAG,EAAE,EAAE,CAAC;QACf,KAAK,CAAC,IAAI,CACR,sHAAsH,CACvH,CAAC;IACJ,CAAC;IAED,OAAO;QACL,EAAE,EAAE,eAAe;QACnB,KAAK,EAAE,0BAA0B;QACjC,KAAK;QACL,MAAM;QACN,OAAO;QACP,OAAO,EAAE,EAAE;QACX,KAAK;KACN,CAAC;AACJ,CAAC"}

package/dist/audit/checks/resources.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Check 7 — Resources advertised.
+ *
+ * Score from count of MCP resources returned by listResources():
+ *   0   resources → 0
+ *   1-2 resources → 5
+ *   3+  resources → 10
+ */
+import type { CheckResult, ProbeSnapshot } from '../../types.js';
+export declare function checkResources(snapshot: ProbeSnapshot): CheckResult;