evidence-report-mcp 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,41 @@
1
1
  # Changelog
2
2
 
3
+ ## [0.3.0](https://github.com/phun-ky/evidence-report-mcp/compare/0.2.0...0.3.0) (2026-11-20)
4
+
5
+ ### Tasks
6
+
7
+ * 🤖 add VitePress and TypeDoc ([4b3f79a](https://github.com/phun-ky/evidence-report-mcp/commit/4b3f79a575c64b71a0fd182a9ed4f3fdafc5a736))
8
+ * 🤖 generate the API docs with TypeDoc and override vite to 6.4.5 under VitePress ([e80daf3](https://github.com/phun-ky/evidence-report-mcp/commit/e80daf3e3eea473d043bec4446e805fc9d198554))
9
+ * 🤖 let lint pass before the API docs are generated ([6cf1dcb](https://github.com/phun-ky/evidence-report-mcp/commit/6cf1dcb2b2c5460bbf164b48f55b0b9e6ead415b))
10
+ * 🤖 point the npm homepage at the docs site ([56d93a9](https://github.com/phun-ky/evidence-report-mcp/commit/56d93a94a0aa7c778a875fd9e3d9bc4d64e72e43))
11
+
12
+ ### Documentation
13
+
14
+ * ✏️ add CONTRIBUTING, GOVERNANCE, ROADMAP and a Code of Conduct ([971aa49](https://github.com/phun-ky/evidence-report-mcp/commit/971aa49e127d5b1f2ed4497e18a62c9db02891cd)), closes [#16](https://github.com/phun-ky/evidence-report-mcp/issues/16), references [#16](https://github.com/phun-ky/evidence-report-mcp/issues/16)
15
+ * ✏️ add package, build and project badges to the README ([be53d40](https://github.com/phun-ky/evidence-report-mcp/commit/be53d4053aafc9d696525fa0688dadb0e6a4cd67))
16
+ * ✏️ add the docs site, and keep only getting started in the README ([40957cb](https://github.com/phun-ky/evidence-report-mcp/commit/40957cb02076934e1f073a19a34ed8394dee7bab))
17
+ * ✏️ answer the OpenSSF Best Practices criteria, with an assurance case and badges ([ca3b04b](https://github.com/phun-ky/evidence-report-mcp/commit/ca3b04b6eedf592ce67570c5bd142e7a30ed78d0)), closes [#17](https://github.com/phun-ky/evidence-report-mcp/issues/17), references [#17](https://github.com/phun-ky/evidence-report-mcp/issues/17)
18
+ * ✏️ answer the OSPS Baseline, with a VEX document and the badge ([1b9a20c](https://github.com/phun-ky/evidence-report-mcp/commit/1b9a20ca46a727dee963f522a9817eb4144b4cfe)), closes [#58](https://github.com/phun-ky/evidence-report-mcp/issues/58)
19
+ * ✏️ bring the roadmap up to date and link its issues ([c609861](https://github.com/phun-ky/evidence-report-mcp/commit/c60986117b67c51c97ac92eaa33f52cabb5df154)), closes [#65](https://github.com/phun-ky/evidence-report-mcp/issues/65)
20
+ * ✏️ move the docs site to direction C, the waterline ([00fbe08](https://github.com/phun-ky/evidence-report-mcp/commit/00fbe089f5c8b7146742c77e4b54ea8dc85a457e)), closes [#50](https://github.com/phun-ky/evidence-report-mcp/issues/50)
21
+ * ✏️ record the OpenSSF Best Practices passing badge ([8aa3810](https://github.com/phun-ky/evidence-report-mcp/commit/8aa3810d01d0ffc156a1f89f6a8d12e87b9d410a)), references [#17](https://github.com/phun-ky/evidence-report-mcp/issues/17)
22
+
23
+ ### Feature
24
+
25
+ * 🎸 limit the size of the verify tool's input ([eacd3e1](https://github.com/phun-ky/evidence-report-mcp/commit/eacd3e19ff1a861ca7a6c14b8af3afd0b4e4a595)), closes [#61](https://github.com/phun-ky/evidence-report-mcp/issues/61)
26
+
27
+ ### Bug
28
+
29
+ * 🐛 fill the home page board at every window height ([5167adc](https://github.com/phun-ky/evidence-report-mcp/commit/5167adc9634e5712dd3080de2824a9e290e28655)), references [#14](https://github.com/phun-ky/evidence-report-mcp/issues/14)
30
+ * 🐛 keep the wordmark inside the sidebar's column ([f601c1d](https://github.com/phun-ky/evidence-report-mcp/commit/f601c1d3a7b8c57bd0cf091a1e5cc0d6c685384a)), references [#50](https://github.com/phun-ky/evidence-report-mcp/issues/50)
31
+ * 🐛 make the docs site pass WCAG A and AA, and stop the home page scrolling sideways ([8dc1035](https://github.com/phun-ky/evidence-report-mcp/commit/8dc10354933e84de9fc72d22e992426a93fa67d5)), references [#24](https://github.com/phun-ky/evidence-report-mcp/issues/24) [#24](https://github.com/phun-ky/evidence-report-mcp/issues/24)
32
+ * 🐛 start headless Chrome without a guessed port, and wait longer for it ([e802545](https://github.com/phun-ky/evidence-report-mcp/commit/e80254547e11b4a7ea6f1d6f8eb3f5ab03dfade5)), references [#46](https://github.com/phun-ky/evidence-report-mcp/issues/46) [#24](https://github.com/phun-ky/evidence-report-mcp/issues/24)
33
+
34
+ ### Refactoring
35
+
36
+ * 💡 name the target schema TargetSchema and document the exported API ([a9e37f7](https://github.com/phun-ky/evidence-report-mcp/commit/a9e37f76e304a2c2e8ba0e6a0680ca57b7bb8bec))
37
+ * 💡 share the headless Chrome launch between scripts ([956fd10](https://github.com/phun-ky/evidence-report-mcp/commit/956fd107e870d2b6924d41b0c05491bd9d14eca4)), references [#24](https://github.com/phun-ky/evidence-report-mcp/issues/24)
38
+
3
39
  ## [0.2.0](https://github.com/phun-ky/evidence-report-mcp/compare/0.1.0...0.2.0) (2026-11-19)
4
40
 
5
41
  ### Tasks
package/README.md CHANGED
@@ -2,9 +2,22 @@
2
2
 
3
3
  <picture>
4
4
  <source media="(prefers-color-scheme: dark)" srcset="./docs/public/logo/banner-dark.png">
5
- <img alt="evidence-report-mcp: Evidence, not verdicts. Beside it, a report for lodash 4.17.20 that failed with two high findings from OSV.dev and lists what was not checked." src="./docs/public/logo/banner-light.png">
5
+ <img alt="evidence-report-mcp: Unknown is not pass. The headline is cut by a line: checked above it, not checked below. An MCP server that tells agents what was checked, where it came from, and what was not." src="./docs/public/logo/banner-light.png">
6
6
  </picture>
7
7
 
8
+ [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-green.svg)](./CONTRIBUTING.md)
9
+ [![SemVer 2.0](https://img.shields.io/badge/SemVer-2.0-green.svg)](https://semver.org/spec/v2.0.0.html)
10
+ [![npm version](https://img.shields.io/npm/v/evidence-report-mcp)](https://www.npmjs.com/package/evidence-report-mcp)
11
+ [![issues](https://img.shields.io/github/issues/phun-ky/evidence-report-mcp)](https://github.com/phun-ky/evidence-report-mcp/issues)
12
+ [![licence](https://img.shields.io/npm/l/evidence-report-mcp)](./LICENSE)
13
+ [![npm downloads](https://img.shields.io/npm/dm/evidence-report-mcp)](https://www.npmjs.com/package/evidence-report-mcp)
14
+ [![GitHub Repo stars](https://img.shields.io/github/stars/phun-ky/evidence-report-mcp)](https://github.com/phun-ky/evidence-report-mcp)
15
+ [![codecov](https://codecov.io/gh/phun-ky/evidence-report-mcp/graph/badge.svg)](https://codecov.io/gh/phun-ky/evidence-report-mcp)
16
+ [![build](https://github.com/phun-ky/evidence-report-mcp/actions/workflows/check.yml/badge.svg)](https://github.com/phun-ky/evidence-report-mcp/actions/workflows/check.yml)
17
+ [![OpenSSF Best Practices](https://www.bestpractices.dev/projects/16929/badge)](https://www.bestpractices.dev/projects/16929)
18
+ [![OpenSSF Baseline](https://www.bestpractices.dev/projects/16929/baseline)](https://www.bestpractices.dev/projects/16929)
19
+ [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/phun-ky/evidence-report-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/phun-ky/evidence-report-mcp)
20
+
8
21
  A "trust layer" MCP server: one `verify` tool an agent calls _before_ acting on
9
22
  data it did not produce, such as a package, a dataset, a media file or a claim.
10
23
  It returns an evidence report, not a checkmark: what was checked, where each
@@ -13,25 +26,49 @@ result came from and when, and what was not checked.
13
26
  Companion to the talk
14
27
  [_Invisible Data: Building Trust in the Age of AI_](https://slides.com/phun-ky/invisible-data-building-trust-in-the-age-of-ai).
15
28
 
16
- ## Install
29
+ **Documentation:**
30
+ [phun-ky.net/evidence-report-mcp](https://phun-ky.net/evidence-report-mcp/)
31
+
32
+ ## Getting started
17
33
 
18
- Needs Node.js 22.12.0 or later.
34
+ Needs Node.js 22.12.0 or later. Add it to Claude Code:
19
35
 
20
36
  ```sh
21
37
  claude mcp add evidence-report -- npx -y evidence-report-mcp
22
38
  ```
23
39
 
24
- From a clone instead:
40
+ Then ask your agent to verify before it acts, for example: "Before you add
41
+ lodash 4.17.20, verify it, and tell me what was not checked." The answer is an
42
+ evidence report:
25
43
 
26
- ```sh
27
- npm install
28
- npm run build
29
- claude mcp add evidence-report -- node /path/to/evidence-report-mcp/dist/cli.js
44
+ ```json
45
+ {
46
+ "verdict": "fail",
47
+ "summary": "Failed: 1/1 checks completed, 4 finding(s).",
48
+ "checks": [
49
+ {
50
+ "id": "osv.vulnerabilities",
51
+ "status": "fail",
52
+ "source": {
53
+ "name": "OSV.dev",
54
+ "retrievedAt": "2026-11-19T11:17:18.524Z"
55
+ },
56
+ "findings": [
57
+ {
58
+ "severity": "high",
59
+ "message": "Command Injection in lodash",
60
+ "ref": "GHSA-35jh-r3h4-6jhm"
61
+ }
62
+ ]
63
+ }
64
+ ],
65
+ "notChecked": ["Unpublished or zero-day vulnerabilities", "..."]
66
+ }
30
67
  ```
31
68
 
32
- The package also exports `verify`, `aggregate` and `createServer`, for use
33
- without MCP, and the types of the report and its input (`EvidenceReport`,
34
- `CheckResult`, `Finding`, `Verdict`, `CheckKind`, `CheckStatus` and `Target`):
69
+ A verdict of `unknown` means not verified, never safe.
70
+
71
+ The package also works without MCP, and exports the report's types:
35
72
 
36
73
  ```ts
37
74
  import { verify, type EvidenceReport } from 'evidence-report-mcp';
@@ -39,89 +76,32 @@ import { verify, type EvidenceReport } from 'evidence-report-mcp';
39
76
  const report: EvidenceReport = await verify({
40
77
  kind: 'package',
41
78
  ecosystem: 'npm',
42
- name: 'left-pad',
43
- version: '1.3.0'
79
+ name: 'lodash',
80
+ version: '4.17.20'
44
81
  });
45
- ```
46
-
47
- ## The tool
48
-
49
- ```ts
50
- verify({ target });
51
- ```
52
-
53
- `target` is one of:
54
-
55
- | kind | example input | checks |
56
- | --------- | ------------------------------------- | ------------------------------------------------------------ |
57
- | `package` | `{ ecosystem: "npm", name, version }` | OSV.dev advisories |
58
- | `dataset` | `{ schema, records, assetId? }` | JSON Schema contract (incl. `x-unit`), observability adapter |
59
- | `file` | `{ path }` | C2PA manifest (c2patool) |
60
- | `claim` | `{ text, sources: [url, …] }` | independent-source corroboration (heuristic) |
61
-
62
- ### Units: `x-unit`
63
-
64
- A property with `"x-unit": "N*s"` must be sent as
65
- `{ "value": 4.45, "unit": "N*s" }`. A different unit (`lbf*s`) or a bare number
66
- is a `high` finding. Only separators are normalised (`N·s` = `N*s` = `N s`);
67
- there are no aliases and no conversion.
68
82
 
69
- Schemas are compiled in Ajv strict mode: an unknown or misspelled keyword makes
70
- the check `error` instead of silently passing. `x-*` keys are allowed as
71
- annotations.
72
-
73
- ### C2PA: `c2patool`
74
-
75
- Install [c2patool](https://github.com/contentauth/c2pa-rs/releases) (tested with
76
- 0.27.23, verify the release checksum) and point the server at it:
77
-
78
- ```sh
79
- claude mcp add evidence-report \
80
- -e EVIDENCE_REPORT_MCP_C2PATOOL=/path/to/c2patool \
81
- -e C2PATOOL_TRUST_ANCHORS=/path/to/anchors.pem \
82
- -- npx -y evidence-report-mcp
83
+ console.log(report.verdict); // fail
84
+ console.log(report.summary); // Failed: 1/1 checks completed, 4 finding(s).
83
85
  ```
84
86
 
85
- `C2PATOOL_TRUST_ANCHORS`, `C2PATOOL_TRUST_CONFIG` and `C2PATOOL_ALLOWED_LIST`
86
- are c2patool's own settings. Only a `Trusted` manifest passes; `Invalid` fails;
87
- a manifest from an untrusted signer, or no manifest at all, is `skipped`, so the
88
- verdict stays `unknown`.
89
-
90
- ## The report
91
-
92
- ```jsonc
93
- {
94
- "verdict": "pass" | "fail" | "unknown",
95
- "summary": "Failed: 1/2 checks completed, 2 finding(s).",
96
- "checks": [{ "id", "kind", "status", "source": { "name", "retrievedAt" }, "findings", "reason" }],
97
- "notChecked": ["Whether values are true, only whether they are well-formed", "…"],
98
- "generatedAt": "…",
99
- "verifier": { "name": "evidence-report-mcp", "version": "0.1.0" }
100
- }
101
- ```
102
-
103
- ## Rules baked in
104
-
105
- 1. **Evidence, not verdicts.** Every check lists its source and timestamp.
106
- `notChecked` is always present, so limits are never silent.
107
- 2. **Deterministic first.** Checks are labelled `deterministic` or `heuristic`.
108
- Heuristics can fail a target but can never pass it alone.
109
- 3. **Independent checks.** No LLM "plausibility" scoring. The verifier never
110
- asks the generator to grade itself.
111
- 4. **Unknown ≠ verified.** A required check that errors or is skipped makes the
112
- verdict `unknown`. Exceptions become `error`, never a crash or a pass.
113
- 5. **Verify the verifier.** This server is a dependency too: pin it, scan it,
114
- and keep it read-only (`readOnlyHint: true`).
115
-
116
- ## What's stubbed
117
-
118
- - `checkObservability`: wire to Monte Carlo, Soda, Elementary, etc. (their API,
119
- or act as an MCP client to their MCP server).
120
- - `checkCorroboration`: fetches nothing yet; only enforces two distinct source
121
- domains.
122
-
123
- ## Ideas
124
-
125
- - `verify` over a lockfile or SBOM (OSV batch API).
126
- - A signed report (Sigstore) so downstream systems can trust the verifier's
127
- output, not just the agent's summary of it.
87
+ ## Learn more
88
+
89
+ - [Getting started](https://phun-ky.net/evidence-report-mcp/guide/), including
90
+ other MCP clients
91
+ - [The evidence report](https://phun-ky.net/evidence-report-mcp/guide/report):
92
+ every field, and how the verdict is worked out
93
+ - The checks:
94
+ [packages](https://phun-ky.net/evidence-report-mcp/guide/checks/package),
95
+ [datasets](https://phun-ky.net/evidence-report-mcp/guide/checks/dataset),
96
+ [media files](https://phun-ky.net/evidence-report-mcp/guide/checks/file) and
97
+ [claims](https://phun-ky.net/evidence-report-mcp/guide/checks/claim)
98
+ - [Configuration](https://phun-ky.net/evidence-report-mcp/guide/configuration),
99
+ including `c2patool` for media files
100
+ - [API reference](https://phun-ky.net/evidence-report-mcp/api/)
101
+ - [Security policy](./SECURITY.md) and [assurance case](./ASSURANCE.md)
102
+ - [Contributing](./CONTRIBUTING.md), [governance](./GOVERNANCE.md),
103
+ [roadmap](./ROADMAP.md) and [Code of Conduct](./CODE_OF_CONDUCT.md)
104
+
105
+ ## Licence
106
+
107
+ [MIT](./LICENSE)
package/dist/server.d.ts CHANGED
@@ -1,14 +1,37 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
- import { Target, type CheckResult, type EvidenceReport, type Verdict } from './types.js';
2
+ import { type CheckResult, type EvidenceReport, type Target, type Verdict } from './types.js';
3
3
  export type { CheckKind, CheckResult, CheckStatus, EvidenceReport, Finding, Target, Verdict } from './types.js';
4
4
  /**
5
- * Fail closed:
6
- * 1. Any failed check -> "fail"
7
- * 2. Any required check not run -> "unknown" (unknown is not zero)
8
- * 3. Only heuristics passed -> "unknown" (judgment can't certify)
9
- * 4. Otherwise -> "pass"
5
+ * Combines check results into one verdict, failing closed, in this order:
6
+ *
7
+ * 1. Any check that failed makes the verdict `fail`, even a heuristic one or
8
+ * one that is not required.
9
+ * 2. A required check that is missing, errored or was skipped makes it
10
+ * `unknown`: unknown is not zero.
11
+ * 3. If only heuristic checks are required and passed, it is `unknown`:
12
+ * judgement can't certify.
13
+ * 4. Otherwise it is `pass`.
14
+ *
15
+ * @param checks - The results of the checks that ran.
16
+ * @param required - The ids of the checks that must pass for a `pass`.
17
+ * @returns The verdict.
10
18
  */
11
19
  export declare function aggregate(checks: CheckResult[], required: string[]): Verdict;
20
+ /**
21
+ * Runs every check for a target and returns the evidence report. Checks never
22
+ * throw: a check that fails to run is reported with status `error`.
23
+ *
24
+ * @param target - What to verify: a package, a dataset, a file or a claim.
25
+ * @returns The report, with the verdict, each check's evidence and what was
26
+ * not checked.
27
+ */
12
28
  export declare function verify(target: Target): Promise<EvidenceReport>;
29
+ /**
30
+ * Creates the MCP server with its one tool, `verify`, which is read-only. It
31
+ * is not connected to a transport; the `evidence-report-mcp` command connects
32
+ * it to stdio.
33
+ *
34
+ * @returns The server, ready to connect.
35
+ */
13
36
  export declare function createServer(): McpServer;
14
37
  //# sourceMappingURL=server.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE,OAAO,EACL,MAAM,EACN,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,OAAO,EACb,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,SAAS,EACT,WAAW,EACX,WAAW,EACX,cAAc,EACd,OAAO,EACP,MAAM,EACN,OAAO,EACR,MAAM,YAAY,CAAC;AAUpB;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAW5E;AAcD,wBAAsB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAcpE;AAED,wBAAgB,YAAY,IAAI,SAAS,CA0BxC"}
1
+ {"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAKpE,OAAO,EAEL,KAAK,WAAW,EAChB,KAAK,cAAc,EACnB,KAAK,MAAM,EACX,KAAK,OAAO,EACb,MAAM,YAAY,CAAC;AAGpB,YAAY,EACV,SAAS,EACT,WAAW,EACX,WAAW,EACX,cAAc,EACd,OAAO,EACP,MAAM,EACN,OAAO,EACR,MAAM,YAAY,CAAC;AAUpB;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,WAAW,EAAE,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CAW5E;AAcD;;;;;;;GAOG;AACH,wBAAsB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAcpE;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,IAAI,SAAS,CA0BxC"}
package/dist/server.js CHANGED
@@ -1,15 +1,23 @@
1
1
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
2
2
  import { readFileSync } from 'node:fs';
3
3
  import { plan } from './checkers.js';
4
- import { Target } from './types.js';
4
+ import { TargetSchema } from './types.js';
5
5
  const { name, version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
6
6
  const VERIFIER = { name, version };
7
7
  /**
8
- * Fail closed:
9
- * 1. Any failed check -> "fail"
10
- * 2. Any required check not run -> "unknown" (unknown is not zero)
11
- * 3. Only heuristics passed -> "unknown" (judgment can't certify)
12
- * 4. Otherwise -> "pass"
8
+ * Combines check results into one verdict, failing closed, in this order:
9
+ *
10
+ * 1. Any check that failed makes the verdict `fail`, even a heuristic one or
11
+ * one that is not required.
12
+ * 2. A required check that is missing, errored or was skipped makes it
13
+ * `unknown`: unknown is not zero.
14
+ * 3. If only heuristic checks are required and passed, it is `unknown`:
15
+ * judgement can't certify.
16
+ * 4. Otherwise it is `pass`.
17
+ *
18
+ * @param checks - The results of the checks that ran.
19
+ * @param required - The ids of the checks that must pass for a `pass`.
20
+ * @returns The verdict.
13
21
  */
14
22
  export function aggregate(checks, required) {
15
23
  if (checks.some((c) => c.status === 'fail'))
@@ -27,6 +35,14 @@ function summarise(verdict, checks) {
27
35
  const label = { pass: 'Passed', fail: 'Failed', unknown: 'Could not verify' }[verdict];
28
36
  return `${label}: ${ran}/${checks.length} checks completed, ${findings} finding(s).`;
29
37
  }
38
+ /**
39
+ * Runs every check for a target and returns the evidence report. Checks never
40
+ * throw: a check that fails to run is reported with status `error`.
41
+ *
42
+ * @param target - What to verify: a package, a dataset, a file or a claim.
43
+ * @returns The report, with the verdict, each check's evidence and what was
44
+ * not checked.
45
+ */
30
46
  export async function verify(target) {
31
47
  const p = plan(target);
32
48
  const checks = await Promise.all(p.checks);
@@ -41,6 +57,13 @@ export async function verify(target) {
41
57
  verifier: VERIFIER
42
58
  };
43
59
  }
60
+ /**
61
+ * Creates the MCP server with its one tool, `verify`, which is read-only. It
62
+ * is not connected to a transport; the `evidence-report-mcp` command connects
63
+ * it to stdio.
64
+ *
65
+ * @returns The server, ready to connect.
66
+ */
44
67
  export function createServer() {
45
68
  const server = new McpServer(VERIFIER);
46
69
  server.registerTool('verify', {
@@ -50,7 +73,7 @@ export function createServer() {
50
73
  'Call this BEFORE acting on data you did not produce.',
51
74
  "Treat verdict 'unknown' as 'not verified'. Read 'notChecked' before telling a user something is safe or true."
52
75
  ].join(' '),
53
- inputSchema: { target: Target },
76
+ inputSchema: { target: TargetSchema },
54
77
  annotations: { readOnlyHint: true, openWorldHint: true }
55
78
  }, async ({ target }) => {
56
79
  const report = await verify(target);
@@ -1 +1 @@
1
- {"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}
package/dist/types.d.ts CHANGED
@@ -28,7 +28,8 @@ export declare const ClaimTarget: z.ZodObject<{
28
28
  text: z.ZodString;
29
29
  sources: z.ZodDefault<z.ZodArray<z.ZodString>>;
30
30
  }, z.core.$strip>;
31
- export declare const Target: z.ZodDiscriminatedUnion<[z.ZodObject<{
31
+ /** The zod schema for a target: the `verify` tool's input. */
32
+ export declare const TargetSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
32
33
  kind: z.ZodLiteral<"package">;
33
34
  ecosystem: z.ZodEnum<{
34
35
  npm: "npm";
@@ -54,46 +55,71 @@ export declare const Target: z.ZodDiscriminatedUnion<[z.ZodObject<{
54
55
  text: z.ZodString;
55
56
  sources: z.ZodDefault<z.ZodArray<z.ZodString>>;
56
57
  }, z.core.$strip>], "kind">;
57
- export type Target = z.infer<typeof Target>;
58
58
  /**
59
- * deterministic: reproducible given the same input and source state
60
- * (schema validation, signature checks, CVE lookups).
61
- * heuristic: judgment-based (corroboration, model scoring). Can lower
62
- * a verdict, never raise it to "pass" on its own.
59
+ * What to verify, by `kind`: a `package` (ecosystem, name and version), a
60
+ * `dataset` (a JSON Schema and records), a `file` (a path) or a `claim` (text
61
+ * and the sources it relies on).
62
+ */
63
+ export type Target = z.infer<typeof TargetSchema>;
64
+ /**
65
+ * How a check reaches its result.
66
+ *
67
+ * - `deterministic`: reproducible given the same input and source state, such
68
+ * as schema validation, signature checks and advisory lookups.
69
+ * - `heuristic`: a judgement, such as corroboration. It can fail a target but
70
+ * never make it pass on its own.
63
71
  */
64
72
  export type CheckKind = 'deterministic' | 'heuristic';
65
- /** "error" and "skipped" mean the check did NOT run to completion. */
73
+ /**
74
+ * The outcome of one check. `error` and `skipped` mean the check did not run
75
+ * to completion, so a required check with either makes the verdict `unknown`.
76
+ */
66
77
  export type CheckStatus = 'pass' | 'fail' | 'error' | 'skipped';
78
+ /** One thing a check found. */
67
79
  export interface Finding {
80
+ /** How serious it is, on the CVSS qualitative scale. */
68
81
  severity: 'info' | 'low' | 'medium' | 'high' | 'critical';
82
+ /** What was found, in words. */
69
83
  message: string;
70
84
  /** Where the finding points: JSON pointer, advisory id, manifest field. */
71
85
  ref?: string;
72
86
  }
87
+ /** The evidence from one check. */
73
88
  export interface CheckResult {
89
+ /** The check, for example `osv.vulnerabilities`. */
74
90
  id: string;
75
91
  kind: CheckKind;
76
92
  status: CheckStatus;
93
+ /** Where the evidence came from, and when. */
77
94
  source: {
95
+ /** For example `OSV.dev`. */
78
96
  name: string;
79
97
  url?: string;
98
+ /** ISO 8601 time of the lookup: evidence goes stale. */
80
99
  retrievedAt: string;
81
100
  };
82
101
  findings: Finding[];
83
102
  /** Why a check errored or was skipped. Required for those statuses. */
84
103
  reason?: string;
104
+ /** How long the check took, in milliseconds. */
85
105
  durationMs: number;
86
106
  }
107
+ /** The overall answer. `unknown` means not verified, never safe. */
87
108
  export type Verdict = 'pass' | 'fail' | 'unknown';
109
+ /** What `verify` returns: the verdict and the evidence behind it. */
88
110
  export interface EvidenceReport {
89
111
  verdict: Verdict;
90
112
  /** One line a human can read. The checks array is the actual answer. */
91
113
  summary: string;
114
+ /** The target as it was checked. */
92
115
  target: Target;
116
+ /** One result for each check that was planned for this kind of target. */
93
117
  checks: CheckResult[];
94
118
  /** Things this verifier cannot or did not check. Always present, never empty. */
95
119
  notChecked: string[];
120
+ /** ISO 8601 time the report was made. */
96
121
  generatedAt: string;
122
+ /** The package and version that made the report. */
97
123
  verifier: {
98
124
  name: string;
99
125
  version: string;
@@ -1 +1 @@
1
- {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAMxB,eAAO,MAAM,aAAa;;;;;;;;;;;;;iBAaxB,CAAC;AAEH,eAAO,MAAM,aAAa;;;;;iBAQxB,CAAC;AAEH,eAAO,MAAM,UAAU;;;iBAIrB,CAAC;AAEH,eAAO,MAAM,WAAW;;;;iBAKtB,CAAC;AAEH,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;2BAKjB,CAAC;AAEH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,MAAM,CAAC,CAAC;AAM5C;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,WAAW,CAAC;AAEtD,sEAAsE;AACtE,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAEhE,MAAM,WAAW,OAAO;IACtB,QAAQ,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IAC1D,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,WAAW,CAAC;IACpB,MAAM,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAElD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,iFAAiF;IACjF,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C"}
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAmBxB,eAAO,MAAM,aAAa;;;;;;;;;;;;;iBAaxB,CAAC;AAEH,eAAO,MAAM,aAAa;;;;;iBAuBxB,CAAC;AAEH,eAAO,MAAM,UAAU;;;iBAIrB,CAAC;AAEH,eAAO,MAAM,WAAW;;;;iBAKtB,CAAC;AAEH,8DAA8D;AAC9D,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;2BAKvB,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAMlD;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG,eAAe,GAAG,WAAW,CAAC;AAEtD;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;AAEhE,+BAA+B;AAC/B,MAAM,WAAW,OAAO;IACtB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IAC1D,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,mCAAmC;AACnC,MAAM,WAAW,WAAW;IAC1B,oDAAoD;IACpD,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,WAAW,CAAC;IACpB,8CAA8C;IAC9C,MAAM,EAAE;QACN,6BAA6B;QAC7B,IAAI,EAAE,MAAM,CAAC;QACb,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,wDAAwD;QACxD,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,uEAAuE;IACvE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,oEAAoE;AACpE,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAElD,qEAAqE;AACrE,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,iFAAiF;IACjF,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,oDAAoD;IACpD,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C"}
package/dist/types.js CHANGED
@@ -2,6 +2,16 @@ import { z } from 'zod';
2
2
  /* ------------------------------------------------------------------ */
3
3
  /* Input: what the agent asks us to verify */
4
4
  /* ------------------------------------------------------------------ */
5
+ /* Limits, so one call can't hold the server for long (#61). */
6
+ const MAX_DEPTH = 32;
7
+ const KB = 1024;
8
+ /** Whether a JSON value nests objects and arrays at most `max` deep. Stops early, so deep input can't overflow the stack. */
9
+ function withinDepth(v, max) {
10
+ if (typeof v !== 'object' || v === null)
11
+ return true;
12
+ return max > 0 && Object.values(v).every((c) => withinDepth(c, max - 1));
13
+ }
14
+ const jsonBytes = (v) => Buffer.byteLength(JSON.stringify(v));
5
15
  export const PackageTarget = z.object({
6
16
  kind: z.literal('package'),
7
17
  ecosystem: z.enum([
@@ -13,30 +23,42 @@ export const PackageTarget = z.object({
13
23
  'NuGet',
14
24
  'RubyGems'
15
25
  ]),
16
- name: z.string().min(1),
17
- version: z.string().min(1)
26
+ name: z.string().min(1).max(256),
27
+ version: z.string().min(1).max(256)
18
28
  });
19
29
  export const DatasetTarget = z.object({
20
30
  kind: z.literal('dataset'),
21
31
  /** Inline JSON Schema the data must satisfy (the "contract"). */
22
- schema: z.record(z.string(), z.unknown()),
32
+ schema: z
33
+ .record(z.string(), z.unknown())
34
+ .refine((s) => withinDepth(s, MAX_DEPTH) && jsonBytes(s) <= 100 * KB, {
35
+ message: `must nest at most ${MAX_DEPTH} deep and be at most 100 KB as JSON`
36
+ }),
23
37
  /** Records to validate. Keep samples small; this is not a warehouse scan. */
24
- records: z.array(z.unknown()).min(1).max(1000),
38
+ records: z
39
+ .array(z.unknown())
40
+ .min(1)
41
+ .max(1000)
42
+ .refine((r) => r.every((rec) => withinDepth(rec, MAX_DEPTH)) &&
43
+ jsonBytes(r) <= 1024 * KB, {
44
+ message: `each record must nest at most ${MAX_DEPTH} deep, and all records be at most 1 MB as JSON`
45
+ }),
25
46
  /** Optional asset id in an observability tool (freshness, volume, lineage). */
26
- assetId: z.string().optional()
47
+ assetId: z.string().max(256).optional()
27
48
  });
28
49
  export const FileTarget = z.object({
29
50
  kind: z.literal('file'),
30
51
  /** Local path of an image/video/audio file to check for C2PA credentials. */
31
- path: z.string().min(1)
52
+ path: z.string().min(1).max(4096)
32
53
  });
33
54
  export const ClaimTarget = z.object({
34
55
  kind: z.literal('claim'),
35
- text: z.string().min(1),
56
+ text: z.string().min(1).max(10_000),
36
57
  /** Sources the agent is relying on. Never verified against the agent's own output. */
37
- sources: z.array(z.string().url()).default([])
58
+ sources: z.array(z.string().url().max(2048)).max(20).default([])
38
59
  });
39
- export const Target = z.discriminatedUnion('kind', [
60
+ /** The zod schema for a target: the `verify` tool's input. */
61
+ export const TargetSchema = z.discriminatedUnion('kind', [
40
62
  PackageTarget,
41
63
  DatasetTarget,
42
64
  FileTarget,
package/dist/types.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,wEAAwE;AACxE,wEAAwE;AACxE,wEAAwE;AAExE,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IAC1B,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC;QAChB,KAAK;QACL,MAAM;QACN,IAAI;QACJ,OAAO;QACP,WAAW;QACX,OAAO;QACP,UAAU;KACX,CAAC;IACF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CAC3B,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IAC1B,iEAAiE;IACjE,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;IACzC,6EAA6E;IAC7E,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;IAC9C,+EAA+E;IAC/E,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAC/B,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IACvB,6EAA6E;IAC7E,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACxB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IACxB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IACvB,sFAAsF;IACtF,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CAC/C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IACjD,aAAa;IACb,aAAa;IACb,UAAU;IACV,WAAW;CACZ,CAAC,CAAC"}
1
+ {"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,wEAAwE;AACxE,wEAAwE;AACxE,wEAAwE;AAExE,+DAA+D;AAC/D,MAAM,SAAS,GAAG,EAAE,CAAC;AACrB,MAAM,EAAE,GAAG,IAAI,CAAC;AAEhB,6HAA6H;AAC7H,SAAS,WAAW,CAAC,CAAU,EAAE,GAAW;IAC1C,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAErD,OAAO,GAAG,GAAG,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC;AAC3E,CAAC;AAED,MAAM,SAAS,GAAG,CAAC,CAAU,EAAE,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;AAEvE,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IAC1B,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC;QAChB,KAAK;QACL,MAAM;QACN,IAAI;QACJ,OAAO;QACP,WAAW;QACX,OAAO;QACP,UAAU;KACX,CAAC;IACF,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;IAChC,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;CACpC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC;IAC1B,iEAAiE;IACjE,MAAM,EAAE,CAAC;SACN,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,WAAW,CAAC,CAAC,EAAE,SAAS,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,IAAI,GAAG,GAAG,EAAE,EAAE;QACpE,OAAO,EAAE,qBAAqB,SAAS,qCAAqC;KAC7E,CAAC;IACJ,6EAA6E;IAC7E,OAAO,EAAE,CAAC;SACP,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC;SAClB,GAAG,CAAC,CAAC,CAAC;SACN,GAAG,CAAC,IAAI,CAAC;SACT,MAAM,CACL,CAAC,CAAC,EAAE,EAAE,CACJ,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC;QAC7C,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,EAAE,EAC3B;QACE,OAAO,EAAE,iCAAiC,SAAS,gDAAgD;KACpG,CACF;IACH,+EAA+E;IAC/E,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;CACxC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,MAAM,CAAC;IACjC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC;IACvB,6EAA6E;IAC7E,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;CAClC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC;IACxB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC;IACnC,sFAAsF;IACtF,OAAO,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CACjE,CAAC,CAAC;AAEH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,CAAC,kBAAkB,CAAC,MAAM,EAAE;IACvD,aAAa;IACb,aAAa;IACb,UAAU;IACV,WAAW;CACZ,CAAC,CAAC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "evidence-report-mcp",
3
- "version": "0.2.0",
3
+ "version": "0.3.0",
4
4
  "description": "An MCP server with one verify tool: agents call it before acting on data they did not produce, and get an evidence report back, not a yes or no.",
5
5
  "keywords": [
6
6
  "mcp",
@@ -13,7 +13,7 @@
13
13
  "provenance",
14
14
  "agents"
15
15
  ],
16
- "homepage": "https://github.com/phun-ky/evidence-report-mcp#readme",
16
+ "homepage": "https://phun-ky.net/evidence-report-mcp/",
17
17
  "bugs": {
18
18
  "url": "https://github.com/phun-ky/evidence-report-mcp/issues"
19
19
  },
@@ -55,10 +55,23 @@
55
55
  "lint:fix": "eslint . --fix",
56
56
  "format": "prettier --write .",
57
57
  "format:check": "prettier --check .",
58
- "test:ci": "node --import tsx --test --enable-source-maps --experimental-test-coverage --test-coverage-include='src/**/*.ts' --test-coverage-exclude='src/**/__tests__/**' --test-coverage-exclude='src/test/**' --test-coverage-lines=98 --test-coverage-branches=100 --test-coverage-functions=100 'src/**/__tests__/**/*.spec.ts'",
58
+ "pretest:ci": "mkdir -p coverage",
59
+ "test:ci": "node --import tsx --test --enable-source-maps --experimental-test-coverage --test-coverage-include='src/**/*.ts' --test-coverage-exclude='src/**/__tests__/**' --test-coverage-exclude='src/test/**' --test-coverage-lines=96 --test-coverage-branches=100 --test-coverage-functions=100 --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage/lcov.info 'src/**/__tests__/**/*.spec.ts'",
59
60
  "prepare": "git config core.hooksPath .githooks || true",
60
61
  "test:hooks": "node --test scripts/__tests__/commit-msg.test.mjs",
62
+ "test:readme": "node --test scripts/__tests__/readme-examples.test.mjs",
61
63
  "check:pack": "node scripts/check-pack.mjs",
64
+ "check:bestpractices": "node scripts/check-bestpractices.mjs",
65
+ "bestpractices:url": "node scripts/bestpractices-url.mjs",
66
+ "docs:gen": "typedoc",
67
+ "docs:check": "typedoc --emit none --treatWarningsAsErrors",
68
+ "predocs:dev": "npm run docs:gen",
69
+ "docs:dev": "vitepress dev docs",
70
+ "predocs:build": "npm run docs:gen",
71
+ "docs:build": "vitepress build docs",
72
+ "docs:preview": "vitepress preview docs",
73
+ "check:site": "node scripts/check-site.mjs",
74
+ "test:site": "node --test scripts/__tests__/check-site.test.mjs",
62
75
  "render:logo": "node scripts/render-logo.mjs",
63
76
  "release": "release-it",
64
77
  "release:dry-run": ".github/scripts/should-release.sh && release-it --ci --dry-run --github.release=false --no-git.requireCleanWorkingDir --no-git.requireUpstream"
@@ -70,15 +83,26 @@
70
83
  },
71
84
  "devDependencies": {
72
85
  "@arethetypeswrong/cli": "0.18.5",
73
- "@fontsource/work-sans": "5.3.0",
86
+ "@fontsource/big-shoulders": "5.3.0",
87
+ "@fontsource/public-sans": "5.3.0",
74
88
  "@release-it/conventional-changelog": "12.0.2",
75
89
  "@types/node": "22.20.5",
90
+ "axe-core": "4.14.1",
76
91
  "eslint": "10.15.0",
77
92
  "eslint-config-phun-ky": "3.0.0",
78
93
  "prettier": "3.9.10",
79
94
  "publint": "0.3.25",
80
95
  "release-it": "21.1.2",
81
96
  "tsx": "4.23.15",
82
- "typescript": "6.0.3"
97
+ "typedoc": "0.28.20",
98
+ "typedoc-plugin-markdown": "4.14.1",
99
+ "typedoc-vitepress-theme": "1.1.4",
100
+ "typescript": "6.0.3",
101
+ "vitepress": "1.6.4"
102
+ },
103
+ "overrides": {
104
+ "vitepress": {
105
+ "vite": "6.4.5"
106
+ }
83
107
  }
84
108
  }
package/src/server.ts CHANGED
@@ -4,9 +4,10 @@ import { readFileSync } from 'node:fs';
4
4
 
5
5
  import { plan } from './checkers.js';
6
6
  import {
7
- Target,
7
+ TargetSchema,
8
8
  type CheckResult,
9
9
  type EvidenceReport,
10
+ type Target,
10
11
  type Verdict
11
12
  } from './types.js';
12
13
 
@@ -30,11 +31,19 @@ const { name, version } = JSON.parse(
30
31
  const VERIFIER = { name, version };
31
32
 
32
33
  /**
33
- * Fail closed:
34
- * 1. Any failed check -> "fail"
35
- * 2. Any required check not run -> "unknown" (unknown is not zero)
36
- * 3. Only heuristics passed -> "unknown" (judgment can't certify)
37
- * 4. Otherwise -> "pass"
34
+ * Combines check results into one verdict, failing closed, in this order:
35
+ *
36
+ * 1. Any check that failed makes the verdict `fail`, even a heuristic one or
37
+ * one that is not required.
38
+ * 2. A required check that is missing, errored or was skipped makes it
39
+ * `unknown`: unknown is not zero.
40
+ * 3. If only heuristic checks are required and passed, it is `unknown`:
41
+ * judgement can't certify.
42
+ * 4. Otherwise it is `pass`.
43
+ *
44
+ * @param checks - The results of the checks that ran.
45
+ * @param required - The ids of the checks that must pass for a `pass`.
46
+ * @returns The verdict.
38
47
  */
39
48
  export function aggregate(checks: CheckResult[], required: string[]): Verdict {
40
49
  if (checks.some((c) => c.status === 'fail')) return 'fail';
@@ -61,6 +70,14 @@ function summarise(verdict: Verdict, checks: CheckResult[]): string {
61
70
  return `${label}: ${ran}/${checks.length} checks completed, ${findings} finding(s).`;
62
71
  }
63
72
 
73
+ /**
74
+ * Runs every check for a target and returns the evidence report. Checks never
75
+ * throw: a check that fails to run is reported with status `error`.
76
+ *
77
+ * @param target - What to verify: a package, a dataset, a file or a claim.
78
+ * @returns The report, with the verdict, each check's evidence and what was
79
+ * not checked.
80
+ */
64
81
  export async function verify(target: Target): Promise<EvidenceReport> {
65
82
  const p = plan(target);
66
83
  const checks = await Promise.all(p.checks);
@@ -77,6 +94,13 @@ export async function verify(target: Target): Promise<EvidenceReport> {
77
94
  };
78
95
  }
79
96
 
97
+ /**
98
+ * Creates the MCP server with its one tool, `verify`, which is read-only. It
99
+ * is not connected to a transport; the `evidence-report-mcp` command connects
100
+ * it to stdio.
101
+ *
102
+ * @returns The server, ready to connect.
103
+ */
80
104
  export function createServer(): McpServer {
81
105
  const server = new McpServer(VERIFIER);
82
106
 
@@ -89,7 +113,7 @@ export function createServer(): McpServer {
89
113
  'Call this BEFORE acting on data you did not produce.',
90
114
  "Treat verdict 'unknown' as 'not verified'. Read 'notChecked' before telling a user something is safe or true."
91
115
  ].join(' '),
92
- inputSchema: { target: Target },
116
+ inputSchema: { target: TargetSchema },
93
117
  annotations: { readOnlyHint: true, openWorldHint: true }
94
118
  },
95
119
  async ({ target }) => {
package/src/types.ts CHANGED
@@ -4,6 +4,19 @@ import { z } from 'zod';
4
4
  /* Input: what the agent asks us to verify */
5
5
  /* ------------------------------------------------------------------ */
6
6
 
7
+ /* Limits, so one call can't hold the server for long (#61). */
8
+ const MAX_DEPTH = 32;
9
+ const KB = 1024;
10
+
11
+ /** Whether a JSON value nests objects and arrays at most `max` deep. Stops early, so deep input can't overflow the stack. */
12
+ function withinDepth(v: unknown, max: number): boolean {
13
+ if (typeof v !== 'object' || v === null) return true;
14
+
15
+ return max > 0 && Object.values(v).every((c) => withinDepth(c, max - 1));
16
+ }
17
+
18
+ const jsonBytes = (v: unknown) => Buffer.byteLength(JSON.stringify(v));
19
+
7
20
  export const PackageTarget = z.object({
8
21
  kind: z.literal('package'),
9
22
  ecosystem: z.enum([
@@ -15,89 +28,130 @@ export const PackageTarget = z.object({
15
28
  'NuGet',
16
29
  'RubyGems'
17
30
  ]),
18
- name: z.string().min(1),
19
- version: z.string().min(1)
31
+ name: z.string().min(1).max(256),
32
+ version: z.string().min(1).max(256)
20
33
  });
21
34
 
22
35
  export const DatasetTarget = z.object({
23
36
  kind: z.literal('dataset'),
24
37
  /** Inline JSON Schema the data must satisfy (the "contract"). */
25
- schema: z.record(z.string(), z.unknown()),
38
+ schema: z
39
+ .record(z.string(), z.unknown())
40
+ .refine((s) => withinDepth(s, MAX_DEPTH) && jsonBytes(s) <= 100 * KB, {
41
+ message: `must nest at most ${MAX_DEPTH} deep and be at most 100 KB as JSON`
42
+ }),
26
43
  /** Records to validate. Keep samples small; this is not a warehouse scan. */
27
- records: z.array(z.unknown()).min(1).max(1000),
44
+ records: z
45
+ .array(z.unknown())
46
+ .min(1)
47
+ .max(1000)
48
+ .refine(
49
+ (r) =>
50
+ r.every((rec) => withinDepth(rec, MAX_DEPTH)) &&
51
+ jsonBytes(r) <= 1024 * KB,
52
+ {
53
+ message: `each record must nest at most ${MAX_DEPTH} deep, and all records be at most 1 MB as JSON`
54
+ }
55
+ ),
28
56
  /** Optional asset id in an observability tool (freshness, volume, lineage). */
29
- assetId: z.string().optional()
57
+ assetId: z.string().max(256).optional()
30
58
  });
31
59
 
32
60
  export const FileTarget = z.object({
33
61
  kind: z.literal('file'),
34
62
  /** Local path of an image/video/audio file to check for C2PA credentials. */
35
- path: z.string().min(1)
63
+ path: z.string().min(1).max(4096)
36
64
  });
37
65
 
38
66
  export const ClaimTarget = z.object({
39
67
  kind: z.literal('claim'),
40
- text: z.string().min(1),
68
+ text: z.string().min(1).max(10_000),
41
69
  /** Sources the agent is relying on. Never verified against the agent's own output. */
42
- sources: z.array(z.string().url()).default([])
70
+ sources: z.array(z.string().url().max(2048)).max(20).default([])
43
71
  });
44
72
 
45
- export const Target = z.discriminatedUnion('kind', [
73
+ /** The zod schema for a target: the `verify` tool's input. */
74
+ export const TargetSchema = z.discriminatedUnion('kind', [
46
75
  PackageTarget,
47
76
  DatasetTarget,
48
77
  FileTarget,
49
78
  ClaimTarget
50
79
  ]);
51
80
 
52
- export type Target = z.infer<typeof Target>;
81
+ /**
82
+ * What to verify, by `kind`: a `package` (ecosystem, name and version), a
83
+ * `dataset` (a JSON Schema and records), a `file` (a path) or a `claim` (text
84
+ * and the sources it relies on).
85
+ */
86
+ export type Target = z.infer<typeof TargetSchema>;
53
87
 
54
88
  /* ------------------------------------------------------------------ */
55
89
  /* Output: evidence, not verdicts */
56
90
  /* ------------------------------------------------------------------ */
57
91
 
58
92
  /**
59
- * deterministic: reproducible given the same input and source state
60
- * (schema validation, signature checks, CVE lookups).
61
- * heuristic: judgment-based (corroboration, model scoring). Can lower
62
- * a verdict, never raise it to "pass" on its own.
93
+ * How a check reaches its result.
94
+ *
95
+ * - `deterministic`: reproducible given the same input and source state, such
96
+ * as schema validation, signature checks and advisory lookups.
97
+ * - `heuristic`: a judgement, such as corroboration. It can fail a target but
98
+ * never make it pass on its own.
63
99
  */
64
100
  export type CheckKind = 'deterministic' | 'heuristic';
65
101
 
66
- /** "error" and "skipped" mean the check did NOT run to completion. */
102
+ /**
103
+ * The outcome of one check. `error` and `skipped` mean the check did not run
104
+ * to completion, so a required check with either makes the verdict `unknown`.
105
+ */
67
106
  export type CheckStatus = 'pass' | 'fail' | 'error' | 'skipped';
68
107
 
108
+ /** One thing a check found. */
69
109
  export interface Finding {
110
+ /** How serious it is, on the CVSS qualitative scale. */
70
111
  severity: 'info' | 'low' | 'medium' | 'high' | 'critical';
112
+ /** What was found, in words. */
71
113
  message: string;
72
114
  /** Where the finding points: JSON pointer, advisory id, manifest field. */
73
115
  ref?: string;
74
116
  }
75
117
 
118
+ /** The evidence from one check. */
76
119
  export interface CheckResult {
77
- id: string; // e.g. "osv.vulnerabilities"
120
+ /** The check, for example `osv.vulnerabilities`. */
121
+ id: string;
78
122
  kind: CheckKind;
79
123
  status: CheckStatus;
124
+ /** Where the evidence came from, and when. */
80
125
  source: {
81
- name: string; // e.g. "OSV.dev"
126
+ /** For example `OSV.dev`. */
127
+ name: string;
82
128
  url?: string;
83
- retrievedAt: string; // ISO timestamp: evidence goes stale
129
+ /** ISO 8601 time of the lookup: evidence goes stale. */
130
+ retrievedAt: string;
84
131
  };
85
132
  findings: Finding[];
86
133
  /** Why a check errored or was skipped. Required for those statuses. */
87
134
  reason?: string;
135
+ /** How long the check took, in milliseconds. */
88
136
  durationMs: number;
89
137
  }
90
138
 
139
+ /** The overall answer. `unknown` means not verified, never safe. */
91
140
  export type Verdict = 'pass' | 'fail' | 'unknown';
92
141
 
142
+ /** What `verify` returns: the verdict and the evidence behind it. */
93
143
  export interface EvidenceReport {
94
144
  verdict: Verdict;
95
145
  /** One line a human can read. The checks array is the actual answer. */
96
146
  summary: string;
147
+ /** The target as it was checked. */
97
148
  target: Target;
149
+ /** One result for each check that was planned for this kind of target. */
98
150
  checks: CheckResult[];
99
151
  /** Things this verifier cannot or did not check. Always present, never empty. */
100
152
  notChecked: string[];
153
+ /** ISO 8601 time the report was made. */
101
154
  generatedAt: string;
155
+ /** The package and version that made the report. */
102
156
  verifier: { name: string; version: string };
103
157
  }