@vantageos/mcp-doctor 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -3,13 +3,122 @@
 All notable changes to `@vantageos/mcp-doctor` are documented here.
 This project adheres to [Semantic Versioning](https://semver.org/).
 
-## Unreleased
+## 0.6.0 — 2026-10-10
 
-### Changed
+Rebased onto 0.5.0 (S-28, PR #53); this release ships as 0.6.0.
+
+Measured on `vantage-mcp-boilerplate` @ `577c6e0b` (`--mode=static`: 14 non-conforming, 3
+could-not-judge under 0.4.0) and against the standard as merged in ElPi-Corp #241 (`572a8835`) +
+fix-forward #242. Every changed reading below has a RED test committed before its fix and a bite
+mutation on foreign material (`scripts/v050-foreign-bite-probe.sh`).
+
+### Fixed (false positives and blind spots)
+- **C15 reads `annotations: TOOL_ANNOTATIONS`.** An `annotations:` value that is not an inline
+  object is resolved to a `const X = { ... }` in the same file (or the only such definition in the
+  tree; `...SPREAD` entries are followed). Unresolvable (imported from a package, a call, a member
+  access) is `could-not-judge` naming the expression, never "missing hint". The same abstention
+  now protects C-8, C-9, C-10, C-11 and C-13, which read the same annotations window.
+- **DServer14 Element 1 recognises the delegated challenge.** A call to `unauthorizedChallenge(` or
+  `verifyMcpAccessToken(` imported from `@vantageos/cloud-identity` (or its `/resource-server`
+  subpath, multi-line and aliased imports included) with the result's `status` and `WWW-Authenticate`
+  header forwarded — in the same module or another — is the 401 challenge. A delegation call whose
+  forwarding is not readable is `could-not-judge`. The kit's verifier also counts as the RS256/JWKS
+  verification (Element 4). A same-named function imported from another package is not a delegation.
+- **DServer14 Element 2 reads a PRM route registered through a constant**
+  (`for (const path of PRM_PATHS) app.get(path, ...)`), a blind spot that Element 1 had been masking.
+- **C19 reads the description forms servers actually write:** a `+` concatenation of literals across
+  lines, a template literal without expressions, and a string holding the other quote character
+  (`"the caller's org"` ended the literal at the apostrophe). A `description:` whose value is not
+  readable (a call, an interpolated template) is `could-not-judge` naming it. A tool's window now
+  stops at the previous tool's call, so a neighbour's description is never claimed.
+- **D10 reads `description_fr:` with the literal on the next line,** a `+` concatenation, or an
+  identifier bound to a same-tree `const X = "..."`. Any other value (`t(locale, ...)`, a call) stays
+  `could-not-judge` and the reason now names the form.
+- **The code mask lexes JSX/TSX.** In `.tsx`/`.jsx` files a `<` at an expression position opens an
+  element; the text between tags is not code, `/>` is not a regex, an apostrophe in JSX text is not a
+  string. `src/ui/entry.tsx` no longer reads "brackets never balance". A file that ends inside an
+  unterminated JSX element, template literal or block comment is now unreadable (fail closed) instead
+  of having its tail swallowed.
+- **D16 recognises the SDK v2 server construction.** `new McpServer({ name, version })` whose
+  `version` is read from `package.json` (directly, or through a `const` bound to a statement that
+  reads `package.json`'s `.version`, in any file) is the observable version: the SDK serves it on
+  `server/discover` and `initialize`. The verdict is `[static read]` and declares the residual
+  (pre-auth reachability of the SDK transport is the dynamic half). A literal version, or an
+  identifier bound to anything else, is not credited.
+
+### Fixed (measured on vantage-peers `mcp-server` @ `2f0e5469`, Sigma's triage)
+- **D2 stateless: a header NAME in a CORS list is not session keying.** Every `mcp-session-id` mention
+  is classified: a keying form (a `sessionIdGenerator` other than `undefined`, the header read or
+  written by call or index, sent as an object key, or a store keyed by a session id) is
+  `non-conforming`; a CORS `allowHeaders` / `exposeHeaders` entry is inert and named in the verdict;
+  anything else is `could-not-judge` naming the site. The old oracle fixture, which was only CORS
+  lists, now carries a real generator.
+- **DServer6 reports every site and resolves literal values.** It returned on its first match; it now
+  lists all sites (Forms A, B, C, D). A name match whose value is proven a literal constant
+  (`HOSTNAME = "0.0.0.0"` reached through `server.hostname`) is not a finding and is named as not
+  counted; an unresolved value is kept and says "identifier-name match, value unresolved". A call is
+  never resolved.
+- **C17 reads the repository-root workflows.** For a package scanned as a subdirectory the check
+  walks from the scan root up to the git root (the nearest `.git`) and reads that
+  `.github/workflows`; it never reads above the git root and never leaves the scanned tree when
+  there is no `.git`.
+- **C25 recognises a build identity on `/health`.** A `/health` handler that serves `version` and a
+  derived `commit` (or any C25 identity key) beside it is the build identity of the tree served; a
+  hand-written literal there is red.
+- **Registration wrappers (`defineTool(...)`).** A function whose body calls `registerTool` / `.tool`
+  (directly or through a local alias) with one of its own parameters as the tool name is a
+  registration wrapper; the parameter index is derived, and the literal at that index of every call
+  is a tool name (a constant bound to a string literal is resolved; anything else is an unresolved
+  site, as before). The tool's annotations are read from its call, its description from the argument
+  the wrapper forwards, and the wrapper's own internal `registerTool(name, ...)` is no longer
+  reported as an unresolved tool. C8-C13, C15, C19 and DServer2 judge those tools instead of
+  abstaining.
+
+### Corrected after review (PR #54)
+- **C17 reads a publish step, nothing else.** Provenance is an actual package-manager `publish`
+  invocation carrying `--provenance` (YAML/shell comments stripped, `\` continuations joined) or
+  `publishConfig.provenance: true`. A comment that names the flag and the `id-token: write`
+  permission (necessary for OIDC, attests nothing) are no longer a claim.
+- **C15: a one-line constant closes on its own line.** `const PING_ANN = { title: "x" };` no longer
+  reads on into the next constant and borrows its hints. A tool whose own `annotations: X` is an
+  expression reads only X; the sibling-attribution fix now has a test that fails without it.
+- **C15 reads spreads in order.** In `annotations: { ...CONST, key: value }` a later member
+  overrides the spread (`key: undefined` un-declares a hint, a boolean keeps it); a spread that
+  cannot be resolved is `could-not-judge` naming it.
+- **C25 resolves a constant.** `commit: GIT_SHA` with `const GIT_SHA = "deadbeef"` is the same
+  hand-written literal and stays red.
+
+### Changed (rule changes from the merged standard)
+- **D7:** conformant when the tree depends on `@modelcontextprotocol/server` >= 2 and no result
+  builder is written by hand (`resultType` / `ttlMs` / `cacheScope` spelled in source, outside the
+  SDK's `cacheHints` option). The protocol-kit requirement applies only to hand-rolled builders:
+  SDK v2 plus a hand-rolled builder and no kit is `non-conforming` at the builder. A dependency range
+  that is a tag (`latest`) is `could-not-judge`. SDK v1 / no SDK keeps the 0.4.0 `absent`.
+- **C-17 non-CI path.** A package published without CI has no npm provenance; the standard accepts the
+  `npm pack` shasum the reviewer reproduced and read back at the registry. **Proposed evidence form —
+  the reviewer rules:** one line `Provenance: <pkg>@<version> npm-pack shasum <40-hex> reproduced by
+  <who>, read back from the registry <date>` in `PROVENANCE`, `PROVENANCE.md`, `CHANGELOG.md` or
+  `README.md`, naming `<pkg>@<version>` equal to `package.json`'s `name@version`. A record for another version or
+  another package, one that names only a version, or one with no 40-hex shasum, is
+  `non-conforming` and says why. Without `--provenance` and without a record it is
+  still `non-conforming`. Whether the shasum equals the registry's `dist.shasum` stays the gate.
+- **C-18 identifies the server manifest by content.** A root `mcp.json` carrying `mcpServers` is the
+  OpenAI plugin config, not the server manifest; the server manifest is the root file (`mcp.json` or
+  `mcp-server.json`) carrying capabilities + transport + version. `non-conforming` when no root file
+  qualifies (the verdict says why `mcp.json` did not count) and when two root files each qualify.
+- **S-5 package rule (DServer14):** `non-conforming` on a shipped dependency (`dependencies`,
+  `peerDependencies`, `optionalDependencies`) on `@vantageos/mcp-auth-kit`, or on
+  `@vantageos/cloud-identity` whose lowest admissible version is below 0.15.0; a range whose floor
+  cannot be read (`latest`) is `could-not-judge`. The import-subpath half of S-5 is not read.
+- **DLocalIdentity: minting is not resolving the caller.** Sites that sign or mint (`new SignJWT`,
+  `jwt.sign`, `importPKCS8`, `createPrivateKey`, `importJWK` of a private key) and the claims written
+  into a signing chain's payload are listed under `MINTING/SIGNING` and never counted. Local signature
+  verification (`jwtVerify`, `createLocalJWKSet`, ...) and raw claim reads that identify the caller
+  stay violations whoever issued the token: there is no issuer carve-out.
+
+### Also
 - **DLocalIdentity exemption marker renamed** `local-identity-exempt:` -> `allow-local-identity:`
   (standard R-57), reason of 8 characters or more (was 10). The old spelling no longer exempts.
-
-### Added
 - **DLocalIdentity, third REVISE (PR #52):** reported now are `claimedName` (and any
   `caller*`/`actor*`/`acting*`/`claimed*` property) compared to an agent's `.name`;
   `switch (row.createdBy) { case caller: }`; `[caller].includes(row.createdBy)` and
@@ -17,6 +126,15 @@ This project adheres to [Semantic Versioning](https://semver.org/).
   imported or destructured under an alias (`import { createHash as h }`). Implemented as regex
   matchers, not an AST: `typescript` is a devDependency only and the report contract is line-based.
 
+## 0.5.0 — unreleased
+
+### Added — S-28, a tool forwards the verified claim of its caller (standard `bacc54a`)
+- **`S-28 claim-forwarded`** (`src/detectors/s28-claim-forwarded.ts`), the MCP half of the door audit's cause 1: every MCP caller reaches the backend as one service account, so a tool that does not forward the claim it holds leaves the door nothing to confine to. For each `<client>.query|mutation|action("<module>:<fn>", args)` it reads the call's argument text, the helpers it spreads or attaches (resolved in the tree), the refusal that precedes the call in the same handler, and the backend door list. Red: a call to a door that is not an exit and resolves its caller, with no `verifiedOrg` / `verifiedPerson` in it (a `verifiedActor` added by a wrapped client covers only a bearer that resolved an agent), or one forwarded only through an optional helper with no refusal before the call. Green: the claim is forwarded (and refused-without through an optional helper), or the door is service-account-only / `fleet-wide:` (read from the door). Could-not-judge: no backend found, a door the backend does not define, a door named by an expression, a door whose own source shows no caller resolution. Absent: no Convex client imported at all.
+- **New option `--backend=<convex-dir>`** (and `RunDoctorOptions.backend`, `Tree.backendRoot`, `loadTree(root, backendRoot?)`): the backend source whose door list S-28 reads. Default: the nearest `convex/` (holding a `schema.ts`) above the scanned tree.
+- **Pin.** ElPi-Corp `bacc54a53d5f6f9f20e5254908e2b46807902faa` on `main`, `resources/references/mcp-server-standard.md` blob `fe30518`: the merged S-28 text of ElPi-Corp #239. Its merge commit `7d7df89` was left off `main` by the 2026-10-10 history rewrite; `bacc54a` is its rewritten counterpart and carries the same file blob (as do `7d7df89` and the PR head `6f7794e`, the former pin). Later `main` commits amend other rules and leave S-28 unchanged.
+- Tests: `tests/s28-claim-forwarded.test.ts`. Real material: vantage-peers `16f09070ffd49488ad65b12ec2f8026865d4ab5d` (the commit the door audit measured), `tools.ts` + `verifiedActor.ts` and ten `convex/` modules vendored byte-exact in `fixtures/s28-vp-16f0907/`.
+- Version 0.5.0 (0.4.0 shipped DLocalIdentity, PR #52). The registry has one more detector (47); the oracle snapshot gains one `absent` row, no existing row changed.
+
 ## 0.4.0 — 2026-10-09
 
 ### Added
@@ -46,10 +164,20 @@ This project adheres to [Semantic Versioning](https://semver.org/).
   stylesheet, `authorize.ts:373`) is not reported. A keyed `createHmac`, and any digest of a value the
   caller supplied, stay sites.
 - Measured on vantage-peers `mcp-server/src` at `8fb7c12`: 33 sites, exit 1.
+- **DLocalIdentity, third REVISE (PR #52):** reported now are `claimedName` (and any
+  `caller*`/`actor*`/`acting*`/`claimed*` property) compared to an agent's `.name`;
+  `switch (row.createdBy) { case caller: }`; `[caller].includes(row.createdBy)` and
+  `new Set([caller]).has(...)`; `a.localeCompare(b) === 0` on names or tenants; a primitive
+  imported or destructured under an alias (`import { createHash as h }`). Implemented as regex
+  matchers, not an AST: `typescript` is a devDependency only and the report contract is line-based.
 
 ### Changed
 - The registry has one more detector (46). `tests/__oracle__/oracle-complete-server.static.json`
   gains one `present` row; no existing row changed.
+- **DLocalIdentity exemption marker renamed** `local-identity-exempt:` -> `allow-local-identity:`
+  (standard R-57), reason of 8 characters or more (was 10). The old spelling no longer exempts.
+- Fix-forward (0.5.0): the third-REVISE items above and the marker rename were first logged under
+  `Unreleased`, but shipped in 0.4.0 (npm `@vantageos/mcp-doctor@0.4.0`, gitHead `16a7531`); moved here.
 
 ---
 

package/README.md

@@ -46,7 +46,7 @@ The path is the root of the MCP server sources (the folder holding `server.ts` /
 The binary's own `--help` is the authority; this is what it prints:
 
 ```
-usage: mcp-doctor <source-tree-path> [--mode=static|dynamic|both]
+usage: mcp-doctor <source-tree-path> [--mode=static|dynamic|both] [--backend=<convex-dir>]
 
   --mode=static   read the tree only (default)
   --mode=dynamic  launch the server and judge what it serves
@@ -54,6 +54,8 @@ usage: mcp-doctor <source-tree-path> [--mode=static|dynamic|both]
   --local-identity-ceiling=N
                   local identity primitives tolerated before DLocalIdentity
                   fails (default 0)
+  --backend=DIR   the backend source (a convex/ dir) whose door list S-28 reads;
+                  default: the nearest convex/ above the tree
   --version       print the version and exit
   --help          print this and exit
 
@@ -117,10 +119,11 @@ Each detector maps one standard item and is proven **bipolar** on real material:
 | **D4** CacheableResult | `ttlMs` / `cacheScope` on the list/read result types | present / absent |
 | **D5** server/discover | a `server/discover` handler is registered (absence-based, with a positive control) | present / absent |
 | **D6** mcp-apps ui-key | MCP Apps UI key is the GA nested `_meta.ui.resourceUri` — not flat `ui/resourceUri`, not community `io.modelcontextprotocol/ui` | GA-nested / flat-deprecated / community-nonGA / none |
-| **D7** protocol-kit | `@vantageos/mcp-protocol-kit` listed in `package.json` **and actually called** (builder invoked, not merely declared) | listed+called / listed-not-called / hand-rolled |
+| **D7** protocol-kit | `@vantageos/mcp-protocol-kit` listed in `package.json` **and actually called** (builder invoked, not merely declared) | listed+called / listed-not-called / hand-rolled. Conformant too on `@modelcontextprotocol/server` >= 2 with no hand-rolled result builder (the kit is required only where builders are written by hand) |
 | **D15** cache-coherence | Server Rule 15 — every tool-set mutation (RegisteredTool `.enable/.disable/.update/.remove`, `unregisterTool`) is correlated with a `notifications/tools/list_changed` emission | present / absent / non-conforming / could-not-judge |
-| **D16** version-observable | Server Rule 16 — `server/discover` (or an HTTP `/health` route) exposes a `version` field sourced from `package.json`, reachable pre-auth | present / absent / non-conforming / could-not-judge |
-| **DLocalIdentity** no-local-identity | No MCP server defines its own identity primitive: resolving a caller to a tenant or agent (local JWT verify, a populated allow-list attached to a bearer), asserting org membership or role, filtering rows by caller scope (`fromAllowList`, a name allow-list, a row's `orgId` or acting-name field such as `createdBy` / `assignedTo` compared to the caller's, by `===`, `==`, `Object.is` or after `toLowerCase()`), or validating a credential (local `timingSafeEqual`, a digest of a presented value, HMAC; a hash over a static literal is not a site). A call to a binding imported from `@vantageos/cloud-identity` is not a site. | present (0, or EXEMPT) / non-conforming (count > ceiling, default 0) / could-not-judge |
+| **D16** version-observable | Server Rule 16 — `server/discover` (or an HTTP `/health` route) exposes a `version` field sourced from `package.json`, reachable pre-auth; an SDK v2 `new McpServer({ name, version })` carrying a `package.json`-derived version counts (pre-auth reach is the dynamic half) | present / absent / non-conforming / could-not-judge |
+| **DLocalIdentity** no-local-identity | No MCP server defines its own identity primitive: resolving a caller to a tenant or agent (local JWT verify, a populated allow-list attached to a bearer), asserting org membership or role, filtering rows by caller scope (`fromAllowList`, a name allow-list, a row's `orgId` or acting-name field such as `createdBy` / `assignedTo` compared to the caller's, by `===`, `==`, `Object.is` or after `toLowerCase()`), or validating a credential (local `timingSafeEqual`, a digest of a presented value, HMAC; a hash over a static literal is not a site). A call to a binding imported from `@vantageos/cloud-identity` is not a site. Minting/signing sites (`new SignJWT`, `jwt.sign`, a private-key import) are listed as `MINTING/SIGNING` and not counted; verification and claim reads stay violations whoever issued the token (no issuer carve-out). | present (0, or EXEMPT) / non-conforming (count > ceiling, default 0) / could-not-judge |
+| **S-28** claim-forwarded | Server complement S-28 (standard `bacc54a`) — a tool forwards the verified claim of its caller (`verifiedOrg` / `verifiedPerson`) to every backend door it calls and refuses when it holds none. Reads each `<client>.query\|mutation\|action` call, the helpers it spreads, the refusal before it, and the backend source's door list (`--backend=<convex-dir>`, else the nearest `convex/` above the tree). A door that is service-account-only or declared `fleet-wide:` needs no claim; no backend found, an unknown door, a computed door name are could-not-judge. | present / non-conforming / could-not-judge / absent (no Convex client imported) |
 
 **DLocalIdentity exemptions.** Two, both reported as `EXEMPT` rather than hidden: the
 `@vantageos/cloud-identity` package itself (read from the target's `package.json` name), and a site
@@ -131,6 +134,25 @@ not UTF-8 text, is `could-not-judge`. To adopt the rule on a tree that still hol
 `--local-identity-ceiling=<current count>` as a ratchet; the row then reads `present` and still lists
 every site.
 
+**Reading rules, 0.6.0** (each changed detector; details and rationale in [CHANGELOG.md](./CHANGELOG.md)).
+- **C15 / C8 / C9 / C10 / C11 / C13** resolve `annotations: SOME_CONST` to a same-tree `const` object; an
+  unresolvable value is `could-not-judge`, never "missing".
+- **C19** counts `"a" + "b"`, an expression-free template literal and apostrophe-bearing strings as a
+  declared description; **D10** reads `description_fr:` with the literal on the next line or a const.
+- **DServer14** accepts a 401 challenge delegated to `@vantageos/cloud-identity`
+  (`unauthorizedChallenge` / `verifyMcpAccessToken`, status + header forwarded), a PRM route registered
+  through a path constant, and is red on `@vantageos/mcp-auth-kit` or `cloud-identity` below 0.15.0.
+- **C17** accepts, without CI, a `Provenance: <pkg>@<version> npm-pack shasum <40-hex> ...` record naming the
+  published version (**proposed evidence form, reviewer rules**); **C18** identifies the server manifest by
+  content (`mcpServers` = OpenAI plugin config; the manifest is `mcp-server.json` then) and is red on two.
+- **D2** names `mcp-session-id` in a CORS list as inert and flags only real session keying;
+  **DServer6** reports every site and does not count a name whose value is a literal constant;
+  **C17** reads the repository-root `.github/workflows` for a subpackage; **C25** accepts a derived
+  `commit` served on `/health` beside `version`; a project-local registration wrapper
+  (`defineTool(...)`) is derived from the function that forwards a parameter to `registerTool`, so its
+  tools are judged.
+- **TSX/JSX files** are lexed; a file that ends inside an unterminated JSX element is unreadable, not skipped.
+
 **This table is a sample, not the inventory.** Every registered detector runs on every invocation,
 so the authoritative list is simply the output of a run — one row per detector. The registered set
 lives in `src/detectors/index.ts`. No count is written here on purpose: a number typed into a README

package/dist/doctor.d.ts

@@ -43,6 +43,13 @@ interface Tree {
      * configured list: the report states what was walked past, not what could be.
      */
     skippedDirs: SkippedDir[];
+    /**
+     * The backend source root (a `convex/` directory) a detector may read the
+     * backend's door list from. Set by the caller (`--backend=<dir>`); when unset a
+     * detector that needs it looks for the nearest `convex/` above `root` and says
+     * so when it finds none. Unset means "not supplied", never "no backend".
+     */
+    backendRoot?: string;
 }
 
 type State = "present" | "absent" | "non-conforming" | "could-not-judge";
@@ -217,6 +224,8 @@ declare function isLiveDetector(d: Detector | LiveDetector): d is LiveDetector;
 type RunMode = "static" | "dynamic" | "both";
 interface RunDoctorOptions {
     mode?: RunMode;
+    /** The backend source root (`convex/`) a detector reads the backend's door list from (S-28). */
+    backend?: string;
 }
 /**
  * Run every detector against the target.