@vantageos/mcp-boilerplate 0.6.3 → 0.8.0

package/dist/upstream/paginatedClient.js

@@ -133,6 +133,7 @@ function canonicalJson(value) {
     }
     return JSON.stringify(value) ?? "null";
 }
+// allow-local-identity: cache key of an upstream request (path + params); no credential, caller or tenant
 function fingerprint(path, params) {
     return createHash("sha256")
         .update(canonicalJson({ path, params }))

package/dist/verifiedPerson.d.ts

@@ -77,6 +77,12 @@ export interface PersonContext {
 export type PersonRefusalResult = CallToolResult & {
     isError: true;
 };
+/**
+ * The identity layer's refusal for a caller it did not resolve (no resolution in the context = no_verified_session),
+ * or undefined when the caller is resolved. The agent-roles gate answers with it before deciding a role, so an
+ * unresolved caller gets the precise, stable identity code rather than a generic role denial — a refusal either way.
+ */
+export declare function callerRefusal(caller: CallerResolution | undefined, locale: McpLocale): PersonRefusalResult | undefined;
 /**
  * Declares that a tool needs the verified person: the handler runs only with one, and receives it
  * as its second argument. No caller resolution in the context (stdio) is `no_verified_session`.

package/dist/verifiedPerson.js

@@ -98,6 +98,15 @@ function personRefusal(caller, locale) {
         isError: true,
     };
 }
+/**
+ * The identity layer's refusal for a caller it did not resolve (no resolution in the context = no_verified_session),
+ * or undefined when the caller is resolved. The agent-roles gate answers with it before deciding a role, so an
+ * unresolved caller gets the precise, stable identity code rather than a generic role denial — a refusal either way.
+ */
+export function callerRefusal(caller, locale) {
+    const resolution = caller ?? unresolved("no_verified_session");
+    return resolution.ok ? undefined : personRefusal(resolution, locale);
+}
 /**
  * Declares that a tool needs the verified person: the handler runs only with one, and receives it
  * as its second argument. No caller resolution in the context (stdio) is `no_verified_session`.

package/dist/version.js

@@ -1,8 +1,9 @@
 /**
- * The advertised server version is DERIVED from package.json (never a literal).
- * `src/version.ts` and `dist/version.js` both sit one level under the package root,
- * so the same relative URL resolves in source mode (vitest) and in the built output.
+ * The advertised server version is DERIVED from package.json (never a literal): scripts/embed-static.mjs writes
+ * it into src/embedded.generated.ts at build, and `--check` (tests/embedded-static.test.ts) refuses a stale copy.
+ * It is a module value, not a file read at import: a bundled consumer carries no package.json beside this module
+ * (task k17aj33ks3ndyxgt7jch68rpwx8hz9x5).
  */
-import { readFileSync } from "node:fs";
+import { EMBEDDED_PACKAGE_VERSION } from "./embedded.generated.js";
 export const SERVER_NAME = "mcp-boilerplate";
-export const SERVER_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+export const SERVER_VERSION = EMBEDDED_PACKAGE_VERSION;

package/docs/manufact-gap.md

@@ -0,0 +1,200 @@
+# Manufact quality score — gap list of this boilerplate
+
+Every check Manufact runs for its MCP quality score, the verdict this boilerplate gets on it today, the
+`mcp-doctor` rule that measures the same property, the evidence, and the boilerplate file that owns the fix.
+
+| | |
+|---|---|
+| Boilerplate | `elpiarthera/vantage-mcp-boilerplate` `main` @ `a772895e836422973a5d8bd60277d62e511f629b` (package `0.7.0`) |
+| Scanner (primary) | `mcp-doctor` 0.19.0 at PR #139 head `0b2f29e1d0222e09e47b8485154d237c4f98e223` (carries the S-49, S-50, C-37, C-38, A-13 detectors) |
+| Scanner (comparison) | `npx -y @vantageos/mcp-doctor@0.19.0` (npm `latest`) |
+| Served targets | the local server (`AUTH_MODE=public PORT=8787 npm run start:http`, `http://127.0.0.1:8787/mcp`) and the public instance `https://vantage-mcp-boilerplate-production.up.railway.app/mcp` (Railway, `AUTH_MODE=public`). Both serve `buildId` `e1db86666c3c032b` and the same 3 tools (`tools/list` byte-equal), so they run the same `dist/` |
+| Check list | the 31 check ids of the Manufact report on vantage-peers (fixture `mcp-doctor/fixtures/manufact-vantage-peers-2026-11-08/manufact-report.json`), its 8 Server Metadata sub-checks, its Discoverability block, the policy review, and the domain/TLS publishing checks |
+| Rule mapping | `ElPi-Corp/resources/references/mcp-manufact-gap.md` @ `7e5513eff22c0e2174c100d26e0aa40f642a562f` |
+| Date | 2026-11-08 |
+
+## Limits of this measurement
+
+- **Manufact's engine is closed.** The open `mcp-use` code holds none of Manufact's checks. The only exact
+  value it publishes is the CLI score weighting, error 3 / warning 2 / info 1
+  (`mcp-use/mcp-use@ac0b6a53` `libraries/typescript/packages/cli/src/cloud/checklist/output.ts:85-105`).
+  Every verdict below is therefore our reading of the check's name, message and fix text, measured with
+  `mcp-doctor` or a raw wire read. It is never Manufact's own output.
+- **Served checks ran twice**: on the local public-mode server and on the public Railway instance
+  (`https://vantage-mcp-boilerplate-production.up.railway.app/mcp`). Every `mcp-doctor` served verdict is identical on both, and so is every raw read
+  quoted below. The host-level checks (TLS, redirect, server card at the origin, setup page at the MCP URL)
+  were read on the public instance. The instance runs on Railway's `*.up.railway.app` hostname, which is not
+  an owned domain, and no directory submission has been made yet. No row is left `needs-public-instance`.
+- A check passes only when a scanner output or a raw read-back proves it. `could-not-judge` means the property
+  is measured but Manufact's closed reading of it is ambiguous. The reason is stated on the row.
+
+## Verdicts
+
+Verdict values: `pass`, `fail`, `could-not-judge`, `needs-public-instance`. The `Sev.` column gives
+Manufact's severity (error / warning / info) where the report states one.
+
+### The 31 Manufact checks
+
+| Check id | Name | Sev. | Verdict | mcp-doctor rule -> verdict | Evidence | Owning file (non-pass) |
+|---|---|---|---|---|---|---|
+| server-responds | MCP negotiation succeeds (v1/v2) | error | pass | S23 -> present (served); D3/D4 -> could-not-judge (the doctor obtained only a 2025-06-18 session) | `server/discover` at 2026-07-28 -> `supportedVersions:["2026-07-28"]`, `resultType:"complete"`, `ttlMs:300000`; `initialize` at 2025-11-25 -> HTTP 200, `protocolVersion:"2025-11-25"` | — |
+| tools-list-responds | Tools list returns results | warning | pass | S12 -> present (served) | S12: "tools/list served 3 entries in one page with no nextCursor"; modern `tools/list` -> `ping`, `list_items`, `whoami` | — |
+| skills-over-mcp-readable | Skills over MCP resources are readable | error | could-not-judge | C29 -> absent | Manufact answers `skip` when the extension is not declared. C29: "the extension io.modelcontextprotocol/skills is not declared … 1 SKILL.md file(s) sit in the tree (skills/connect-mcp-server/SKILL.md) and are not served". Whether a `skip` costs score is not public | `src/mcpServerFactory.ts` (declare `io.modelcontextprotocol/skills` and serve `skills/connect-mcp-server/SKILL.md`), if the skip is scored |
+| tool-description-present | All tools have descriptions | warning | pass | C19 -> present (served) | C19: "3 served tool description(s) are bilingual, under the declared per-tool budget (700), and carry their trigger phrase" | — |
+| tool-hints-present | All tools have OpenAI behavior hints | error | pass | C15 -> present (static) | C15: "3 tool(s) each declare all four behavioral annotations"; served, all 3 tools: `readOnlyHint:true`, `destructiveHint:false`, `openWorldHint:false`, all booleans | — |
+| resources-list-responds | Resources list responds | info | pass | S12 -> present (served) | S12: "resources/list served 1 entries"; modern `resources/list` -> `ui://mcp-boilerplate/items-widget.html` | — |
+| claude-code-metadata-length | Claude Code metadata fits its 2 KB fields | warning | pass | C38 -> present (served) | C38: "every budgeted field at or under its cap for claude-code (4 field(s) measured over 3 served tool(s), max 710 bytes)"; served `instructions` = 49 UTF-8 bytes | — |
+| tool-title-present | All tools have a display title | error | pass | C35 -> present (served) | served `title`: `Ping`, `List items`, `Who am I`; C35: "titles and hints equal to the served ones" | — |
+| claude-tool-hints-present | Claude tools declare applicable behavior hints | error | pass | C15 -> present (static) | served `readOnlyHint` and `destructiveHint` on all 3 tools | — |
+| tool-input-header-annotations-valid | Tool input header annotations are valid | error | pass | no rule | no served tool carries `x-mcp-header`: nothing to invalidate (raw read of the 3 served tools) | — |
+| openai-file-params-schema-valid | OpenAI file parameters use valid schemas | error | pass | no rule | no served tool declares an OpenAI file parameter. The `_meta` keys served are `ui`, `openai/outputTemplate`, `openai/toolInvocation/invoking`, `openai/toolInvocation/invoked`, `description_fr` on `list_items`, none on the other two | — |
+| tool-name-protocol-length | Tool names follow the MCP 1–128 character range | warning | pass | DServer2 -> present (served) | served name lengths 4 / 10 / 6 | — |
+| tool-input-schema-type | Tool input schemas have a valid object structure | error | pass | S43 -> present (served inputSchema read) | served `inputSchema.type` = `"object"` on all 3 tools | — |
+| tool-name-format | Tool names use valid characters | warning | pass | DServer2 -> present (served) | each served name matches `[A-Za-z0-9_.-]{1,128}`; DServer2: "3 runtime tool name(s) snake_case" | — |
+| tool-name-length | Claude tool names are within 64 characters | error | pass | DServer2 -> present (served) | longest served name `list_items`, 10 characters | — |
+| cursor-tool-name-budget | Cursor tool-name budget advisory | warning | pass | no rule | longest served name 10 characters, against the 60-character combined budget | — |
+| tool-names-protocol-unique | Tool names follow MCP uniqueness guidance | warning | pass | C12 -> present (static) | 3 served names, 3 distinct | — |
+| tool-names-unique | ChatGPT tool names are unique | error | pass | C12 -> present (static) | 3 served names, 3 distinct | — |
+| tool-output-schema-valid | Declared output schemas have a valid basic structure | error | pass | S44 -> present (served) | S44: "3 output schema(s) read (served tools/list outputSchema)"; each `type:"object"` | — |
+| server-tools-capability-declared | Server declares tools capability | error | pass | S49 -> capabilities found (served) | `server/discover` -> `capabilities:{"tools":{"listChanged":true},"resources":{"listChanged":true}}` | — |
+| tool-text-hidden-characters | Tool text has no hidden control characters | warning | pass | no rule | raw scan of the served name, title, description, inputSchema and annotations of the 3 tools for C0/C1 controls (tab, LF, CR excepted), U+200B–U+200F, U+202A–U+202E, U+2060–U+2064, U+FEFF, U+00AD: 0 hits | — |
+| tool-resource-metadata-complete | View resource metadata complete | warning | fail | no rule | served resource `_meta.ui` = `{csp, prefersBorder}`. No `_meta.ui.widgetDescription` and no `_meta["openai/widgetDescription"]`, on the resource contents or on the linked tool `list_items`. Manufact's fix text reads exactly those two keys | `src/ui/uiResource.ts:71` (`buildItemsUiResourceMeta`) and `src/ui/uiResource.ts:103` (`ITEMS_TOOL_META`) |
+| view-resource-coverage | All discovered view resources were inspected | warning | pass | D6 -> present (static) | 1 `ui://` resource listed, 1 read with HTTP 200 and a non-empty `contents[0]` | — |
+| resource-content-valid | View resource envelope is valid | error | pass | D6 -> present (static) | `resources/read` -> `uri:"ui://mcp-boilerplate/items-widget.html"`, `mimeType:"text/html;profile=mcp-app"`, `text` 191777 characters | — |
+| tool-resource-uri-readable | Tool-linked resource URI is readable | error | pass | D6 -> present (static) | `list_items._meta.ui.resourceUri` = `ui://mcp-boilerplate/items-widget.html`, read OK | — |
+| tool-invocation-metadata-present | Tool invocation metadata present | warning | could-not-judge | A13 -> present (served) | A13 accepts the flat or the nested form: "1 App entry tool(s), each declaring invoking and invoked: list_items". The boilerplate serves only the flat keys `openai/toolInvocation/invoking` / `…/invoked`. Manufact's fix text names an `openai/toolInvocation` object "with string fields invoking and invoked". Which form the closed engine reads is unknown | `src/ui/uiResource.ts:103` (`ITEMS_TOOL_META`: serve the nested object beside the flat keys) |
+| tool-visibility-valid | Tool visibility metadata is valid | error | pass | no rule | served `list_items._meta.ui.visibility` = `["model","app"]` | — |
+| view-domain-present | View resources declare a domain | error | fail | A11 -> could-not-judge (static) | Locally (`PUBLIC_BASE_URL` unset), no `_meta.ui.domain`. With `PUBLIC_BASE_URL=https://mcp.example.com` the server serves `domain:"7a930d27a3f5c4643da88c1794444840.claudemcpcontent.com"`, which is Claude's sandbox hostname. That is not the exact HTTPS origin ChatGPT requires ("one exact HTTPS origin such as https://app.example.com … via _meta.ui.domain (or openai/widgetDomain)"), and no `openai/widgetDomain` is served. The public instance serves no domain either: its `resources/list` `_meta.ui` = `{csp, prefersBorder}`, because `PUBLIC_BASE_URL` is not set there | `src/ui/uiResource.ts:71` (add `openai/widgetDomain` = the owned HTTPS origin, keep `ui.domain` for Claude); `src/http.ts:10` (derive it from `PUBLIC_BASE_URL`); the Railway service env (`PUBLIC_BASE_URL` = the owned origin) |
+| view-csp-origin-coverage | CSP metadata covers literal external origins | warning | could-not-judge | A2 -> present (static) | A2: "0 network/frame target(s) in the UI code". The served widget text holds 2 literal origins, both vendored React strings and neither fetched: `https://react.dev/errors/` (the error-URL builder) and `http://www.w3.org/2000/svg` (the `createElementNS` namespace). All CSP lists are empty. Whether Manufact's static detector counts vendored literals is unknown | `src/ui/uiResource.ts:71` (CSP lists), only if Manufact flags the vendored literals |
+| view-frame-domains-absent | Views do not request nested iframe domains | warning | pass | A2 -> present (static, frame 0) | served `csp.frameDomains` = `[]`, so no frame domain is requested. If the closed engine treats the presence of the empty key as a request, drop the key in `src/ui/uiResource.ts:71` | — |
+| view-domain-responds | Declared domains respond | warning | pass | — | No domain is declared, locally or on the public instance, so nothing can fail to respond. Manufact passed this check on vantage-peers in the same state ("All declared domains are reachable" next to view-domain-present "missing domain"). The row must be re-read once view-domain-present is fixed | — |
+
+### Server Metadata sub-checks (Manufact `protocolMetadata.metadataScore`, points in brackets)
+
+| Check id | Name | Sev. | Verdict | mcp-doctor rule -> verdict | Evidence | Owning file (non-pass) |
+|---|---|---|---|---|---|---|
+| metadata:identity | Stable server name [10] | — | pass | S49 -> found (served) | S49: `found: name "mcp-boilerplate"` | — |
+| metadata:title | Human-readable title [10] | — | fail | S49 -> non-conforming (served) | S49: "title absent" | `src/mcpServerFactory.ts:207` (`serverInfo` passed to `new McpServer`) |
+| metadata:description | Useful description [20] | — | fail | S49 -> non-conforming (served) | S49: "description absent" | `src/mcpServerFactory.ts:207` |
+| metadata:version | Server version [10] | — | pass | S49 -> found; D16 -> present (served) | D16: `running server serves version "0.7.0" pre-auth on initialize, matching package.json` | — |
+| metadata:website | Public website [10] | — | fail | S49 -> non-conforming (served) | S49: "websiteUrl absent" | `src/mcpServerFactory.ts:207` |
+| metadata:icon | Scalable or high-resolution icon [10] | — | fail | S49 -> non-conforming (served) | S49: "icons absent" | `src/mcpServerFactory.ts:207` (`icons`, plus an SVG or 128px asset served by `src/httpApp.ts`) |
+| metadata:instructions | Server instructions [20] | — | could-not-judge | S49 -> found (served) | S49: "instructions 49 bytes". The served text is `Clonable MCP server boilerplate — see README.md`: it is present, but it only points to the README. Manufact scores whether the instructions are useful ("explain how an agent should use the server"), and that judgement is closed | `src/mcpServerFactory.ts:216` |
+| metadata:capabilities | Declared capabilities [10] | — | pass | S49 -> found (served) | S49: `capabilities tools, resources` | — |
+
+### Discoverability (Manufact `discoverability`)
+
+| Check id | Name | Sev. | Verdict | mcp-doctor rule -> verdict | Evidence | Owning file (non-pass) |
+|---|---|---|---|---|---|---|
+| discoverability:manifest | `mcp.json` or MCP Server Card served | — | fail | S50 -> non-conforming (served) | S50: "no server card served (/mcp.json 404, /.well-known/mcp.json 404, /mcp/server-card 404, /.well-known/mcp-server-card 404, /.well-known/mcp/server-card.json 404)"; raw `GET /.well-known/ai-catalog.json` -> 404. Public instance: all 7 paths -> 404 (S50 and raw read) | `src/httpApp.ts` (serve the card before the `/mcp` gate, built from `mcp-server.json` through `src/serverManifest.ts`) |
+| discoverability:landingPage | Setup instructions at the MCP URL | — | fail | S50 -> non-conforming (served) | S50: "the MCP base URL http://127.0.0.1:8787/mcp answers HTTP 405: no setup instructions"; raw `GET /mcp` (Accept text/html) -> 405 `{"code":-32000,"message":"Method not allowed."}`. Public instance: `GET https://vantage-mcp-boilerplate-production.up.railway.app/mcp` -> 405, and S50 reads the same. On the OAuth tier the same GET would hit the auth gate (Manufact read HTTP 401 on vantage-peers) | `src/httpApp.ts:267` (answer an unauthenticated `GET /mcp` with `Accept: text/html` with a bilingual setup page, ahead of the auth middleware at `src/httpApp.ts:174`/`:216`) |
+| discoverability:chatgpt | Listed on ChatGPT | — | fail | C37 -> non-conforming (static) | C37: "no listing proof for chatgpt (the ChatGPT app directory)". Not submitted, so not listed | `mcp-server.json` (`distribution.listings.chatgpt`, after the submission) |
+| discoverability:claude | Listed on Claude (Verified by Anthropic) | — | fail | C37 -> non-conforming (static) | C37: "no listing proof for claude (the Claude connector directory)". Not submitted, so not listed | `mcp-server.json` (`distribution.listings.claude`, after the submission) |
+| discoverability:cursor | Cursor marketplace | — | fail | C37 -> non-conforming (static) | C37: "no listing proof for cursor (the Cursor marketplace)". Not submitted, so not listed | `mcp-server.json` (`distribution.listings.cursor`, after the submission) |
+| discoverability:muse | Listed on Muse | — | fail | no rule (Muse is not a declared target) | Not submitted, so not listed. `mcp-server.json` `distribution.targets` = `["claude","claude-code","vscode","cursor","chatgpt"]`: Muse is not declared, so C37 does not read it | `mcp-server.json` (`distribution.targets` + `listings`, if Muse is targeted) |
+
+### Policy review and domain checks
+
+| Check id | Name | Sev. | Verdict | mcp-doctor rule -> verdict | Evidence | Owning file (non-pass) |
+|---|---|---|---|---|---|---|
+| policy-review | Directory-policy directives in tool descriptions (Manufact "Security & Policy": instruction-like tool copy) | — | could-not-judge | C16 -> absent (n/a); C19 -> present (served, requires the trigger phrase) | The served descriptions say "Use this whenever you need to check that this server answers, even if they don't say 'ping'." (`ping`), "Use this whenever the user asks to list, see or render the items, even if they don't say 'list'." (`list_items`), and the same pattern on `whoami`. The Anthropic Software Directory Policy (Instructional Software) says (A) tools are defined "through narrow, unambiguous natural language", and (D) descriptions "must not be written in a way that intentionally leads to other Software extraneously calling them". The "even if they don't say X" widening is the copy a policy agent can flag. C-19 currently REQUIRES that trigger phrase, so removing it needs a standard ruling first | `src/mcpServerFactory.ts:261`, `:321`, `:390` (the three bilingual descriptions); the C-19 trigger-phrase clause in the standard |
+| domain-tls | Widgets resolve from an owned domain: hostname, TLS, redirects (Manufact "The Domain is Set") | — | fail | S45 -> could-not-judge (static) | TLS and redirect hold on the public instance: TLSv1.3, certificate `CN=*.up.railway.app` issued by Let's Encrypt and expiring 2026-12-26; `http://…/health` -> 301 to `https://…/health`. The hostname is Railway's, though, not an owned one. S45: "the public origin is not declared: only a development default (localhost at src/config.ts:39)", and the widget serves no domain | the Railway service (an owned custom domain); `mcp-server.json` / `.env.example` (`PUBLIC_BASE_URL` = that origin) |
+
+## Non-pass rows — the fix list
+
+`fail`, fixable in the tree now:
+
+1. `tool-resource-metadata-complete`: `src/ui/uiResource.ts:71`, `:103`.
+2. `view-domain-present`: `src/ui/uiResource.ts:71`, `src/http.ts:10`, and `PUBLIC_BASE_URL` set on the Railway service.
+3. `metadata:title`, `metadata:description`, `metadata:website`, `metadata:icon`: `src/mcpServerFactory.ts:207` (and an icon asset served by `src/httpApp.ts`).
+4. `discoverability:manifest`: `src/httpApp.ts`, `src/serverManifest.ts`.
+5. `discoverability:landingPage`: `src/httpApp.ts:267` (before the gates at `:174` / `:216`).
+6. `domain-tls`: an owned custom domain on the Railway service, declared as `PUBLIC_BASE_URL` (`mcp-server.json` / `.env.example`). This is infrastructure, not code.
+7. `discoverability:chatgpt`, `:claude`, `:cursor`, `:muse`: submit to each directory, then record the proof in `mcp-server.json` `distribution.listings` (C-37). This needs the owned domain and the fixes above first.
+
+`could-not-judge`, where a defensive fix settles the ambiguity:
+
+8. `tool-invocation-metadata-present`: `src/ui/uiResource.ts:103` (add the nested `openai/toolInvocation` object).
+9. `metadata:instructions`: `src/mcpServerFactory.ts:216` (actionable instructions, not a README pointer).
+10. `policy-review`: `src/mcpServerFactory.ts:261`, `:321`, `:390`. This needs a ruling on the C-19 trigger phrase first.
+11. `skills-over-mcp-readable`: `src/mcpServerFactory.ts` (serve the Skills extension), only if a skip is scored.
+12. `view-csp-origin-coverage`: `src/ui/uiResource.ts:71`, only if the vendored React literals are flagged.
+
+## What the scanners could not read
+
+- **`mcp-doctor --url` never opens a 2026-07-28 session.** D3 and D4 are could-not-judge: "the session
+  negotiated 2025-06-18 … the doctor could not obtain a 2026-07-28 session". The raw read shows the server
+  does serve 2026-07-28. `server/discover` with the per-request envelope (`_meta` protocolVersion +
+  clientCapabilities, `Mcp-Method` header) answers `resultType:"complete"`, `ttlMs`, `cacheScope`.
+- **C25 is non-conforming in both served runs** (not a Manufact check): `served build-identity "buildId"="e1db86666c3c032b" DIFFERS from the expected commit "a772895e…"`.
+  The boilerplate's `buildId` is a content hash of `dist/` by design (`src/buildIdentity.ts`), while
+  `--source` makes the doctor expect the git commit. The two contracts disagree, and that disagreement is
+  traced separately from this list.
+- **No `mcp-doctor` rule reads** `tool-resource-metadata-complete` (widgetDescription),
+  `tool-input-header-annotations-valid`, `openai-file-params-schema-valid`, `cursor-tool-name-budget`,
+  `tool-visibility-valid` or `tool-text-hidden-characters`. Those rows rest on a raw wire read, cited on each
+  row.
+- **Static could-not-judge rows that bear on these checks**: A11 (the domain derivation exists, but its value
+  is judged only when served), S45 (no public origin declared), S49 and S50 (judged on the served half, which
+  is above), and C38 (judged served, above).
+- **The public-instance runs** (`--url https://vantage-mcp-boilerplate-production.up.railway.app/mcp`, PR #139 and npm 0.19.0) return the same states as the
+  local runs: PR #139 gives present 13 / non-conforming 3 (C25, S49, S50) / could-not-judge 6, and npm gives
+  present 11 / non-conforming 1 / could-not-judge 6.
+- **npm `latest` 0.19.0 does not carry** A13, C37, C38, S49 or S50. Its static run has 118 rows against 123
+  for PR #139, and its served run has 18 against 22. Every row the two versions share has the same verdict.
+
+## How to reproduce
+
+```bash
+git clone https://github.com/elpiarthera/vantage-mcp-boilerplate.git bp && cd bp
+git checkout a772895e836422973a5d8bd60277d62e511f629b
+npm ci && npm run build && npm run build:ui
+AUTH_MODE=public PORT=8787 npm run start:http &
+
+# mcp-doctor at PR #139 head (0b2f29e1), built in ../md
+node ../md/dist/doctor.js . --mode=static --json > static.json
+node ../md/dist/doctor.js --url http://127.0.0.1:8787/mcp --source . --json > served.json
+npx -y @vantageos/mcp-doctor@0.19.0 . --mode=static --json > static-npm.json
+npx -y @vantageos/mcp-doctor@0.19.0 --url http://127.0.0.1:8787/mcp --source . --json > served-npm.json
+
+# raw 2026-07-28 reads (server/discover, tools/list, resources/list, resources/read)
+M='"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"probe","version":"0"},"io.modelcontextprotocol/clientCapabilities":{}}'
+for m in server/discover tools/list resources/list; do
+  curl -s -X POST http://127.0.0.1:8787/mcp -H 'content-type: application/json' \
+    -H 'accept: application/json, text/event-stream' -H 'mcp-protocol-version: 2026-07-28' \
+    -H "mcp-method: $m" -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"$m\",\"params\":{$M}}"; echo
+done
+curl -s -X POST http://127.0.0.1:8787/mcp -H 'content-type: application/json' \
+  -H 'accept: application/json, text/event-stream' -H 'mcp-protocol-version: 2026-07-28' \
+  -H 'mcp-method: resources/read' -H 'mcp-name: ui://mcp-boilerplate/items-widget.html' \
+  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"resources/read\",\"params\":{\"uri\":\"ui://mcp-boilerplate/items-widget.html\",$M}}"
+curl -s -o /dev/null -w '%{http_code}\n' -H 'accept: text/html' http://127.0.0.1:8787/mcp   # 405
+
+# public instance: the same doctor and raw reads with U=https://vantage-mcp-boilerplate-production.up.railway.app
+node ../md/dist/doctor.js --url "$U/mcp" --source . --json > served-public.json
+curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' "http://${U#https://}/health"   # 301 -> https
+curl -sv -o /dev/null "$U/health" 2>&1 | grep -E 'SSL connection|subject:|issuer:|expire date'
+
+# the domain served once a public origin is set
+AUTH_MODE=public PORT=8788 PUBLIC_BASE_URL=https://mcp.example.com node dist/http.js &
+```
+
+Count the verdicts on this file (verdict = 5th `|`-separated field of a check row):
+
+```bash
+awk -F'|' '$2 ~ /^ (metadata:|discoverability:|policy-review|domain-tls|[a-z]+-[a-z-]+ )/ && $5 ~ /pass|fail|could-not-judge|needs-public-instance/ {gsub(/ /,"",$5); n[$5]++} END {for (v in n) print v, n[v]}' docs/manufact-gap.md
+```
+
+## Résumé (FR)
+
+Ce document relève l'écart entre le boilerplate (`main` @ `a772895e`) et chacun des contrôles du score
+qualité Manufact : les 31 contrôles du rapport, les 8 sous-contrôles « Server Metadata », la
+découvrabilité, la revue de politique et les contrôles de domaine. Chaque ligne donne le verdict, la règle
+`mcp-doctor` (PR #139 @ `0b2f29e1`), la preuve et le fichier propriétaire du correctif. Les échecs
+corrigeables tout de suite portent sur les métadonnées serveur (title, description, websiteUrl, icons dans
+`src/mcpServerFactory.ts`), la description et le domaine du widget (`src/ui/uiResource.ts`), la carte
+serveur et la page d'installation à l'URL MCP (`src/httpApp.ts`). Les contrôles servis ont été lus sur le
+serveur local et sur l'instance publique Railway, avec des verdicts identiques. TLS et la redirection vers
+HTTPS tiennent, mais le nom d'hôte appartient à Railway et non à nous : il manque un domaine possédé. Aucune
+inscription en annuaire n'a encore été faite. La revue de politique signale la formule « even if they don't say X » des descriptions, que la
+règle C-19 impose aujourd'hui. La retirer demande d'abord un arbitrage sur la norme.

package/docs/releasing.md

@@ -0,0 +1,19 @@
+# Releasing
+
+A release is cut from `main`, in one pull request, after every change in it has merged.
+
+1. **Fold the changelog.** `npm run changelog:release -- --version <x.y.z>` (optionally `--date YYYY-MM-DD`)
+   inserts `## [x.y.z] - <date>` below `## [Unreleased]`, with every fragment of `changelog.d/` grouped by
+   section, and deletes the folded fragments. `## [Unreleased]` stays, empty. Then add the version's link line
+   at the bottom of `CHANGELOG.md` (`[x.y.z]: <url>`, the npm page of the version when it is published without
+   a git tag); `tests/changelogLinks.test.ts` refuses a version heading with no link line.
+2. **Bump the version** in `package.json` and `mcp-server.json` (they must be equal; `npm run build` refuses
+   a difference), then `npm install --package-lock-only` so the lockfile carries it.
+3. **Build and test**: `npm run build && npm run build:ui && npm test`. `prepublishOnly` runs the same chain,
+   plus the evals, before any publish.
+4. **Open the release PR** through the review flow. Publication happens only from the merged `main`, after
+   the reviewer's npm verdict, and is proven at the registry (full and abbreviated documents, then a fresh
+   consumer install), never by the publish command's output.
+
+Between releases, every pull request adds one fragment to `changelog.d/` (see `changelog.d/README.md`) and
+never touches `CHANGELOG.md`, so parallel pull requests do not conflict on it.

package/mcp-server.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-boilerplate",
-  "version": "0.6.3",
+  "version": "0.8.0",
   "capabilities": {
     "tools": {},
     "resources": {}
@@ -10,5 +10,6 @@
     "streamableHttp": { "path": "/mcp", "stateless": true }
   },
   "features": {},
-  "contextCeiling": { "global": 1200, "perTool": 700 }
+  "contextCeiling": { "global": 1400, "perTool": 700 },
+  "distribution": { "targets": ["claude", "claude-code", "vscode", "cursor", "chatgpt"] }
 }

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@vantageos/mcp-boilerplate",
-  "version": "0.6.3",
+  "version": "0.8.0",
+  "displayName": "MCP Boilerplate",
   "description": "Clonable MCP server skeleton on the official @modelcontextprotocol/server SDK v2 (protocol 2026-07-28 + 2025 legacy, stdio + stateless Streamable HTTP), with its own OAuth 2.1 authorization server (Clerk person + organisation, cloud-identity), MCP Apps UI, tenant scoping, FR/EN i18n and a declarative eval harness.",
   "description_fr": "Squelette de serveur MCP clonable sur le SDK officiel @modelcontextprotocol/server v2 (protocole 2026-07-28 + héritage 2025, stdio + Streamable HTTP sans état), avec son propre serveur d'autorisation OAuth 2.1 (personne + organisation Clerk, cloud-identity), UI MCP Apps, scoping tenant, i18n FR/EN et un harnais d'évaluations déclaratif.",
   "type": "module",
@@ -53,11 +54,15 @@
   "homepage": "https://github.com/elpiarthera/vantage-mcp-boilerplate#readme",
   "author": "ElPi Corp / Laurent Perello",
   "scripts": {
-    "build": "node scripts/clean-dist.mjs && tsc && mkdir -p dist/locales && cp src/locales/en.json src/locales/fr.json dist/locales/ && node scripts/sync-plugin-version.mjs",
+    "build": "node scripts/clean-dist.mjs && node scripts/embed-static.mjs && tsc && node scripts/write-build-info.mjs && node scripts/sync-plugin-version.mjs && node scripts/listing-kit.mjs --check",
+    "listing:write": "node scripts/listing-kit.mjs",
+    "changelog:check": "node scripts/changelog-assemble.mjs --check",
+    "changelog:release": "node scripts/changelog-assemble.mjs",
     "prepack": "node scripts/check-dist-orphans.mjs",
     "build:ui": "vite build && mv dist/ui-bundle/index.html dist/ui-bundle/widget.html",
     "pretest": "npm run build && npm run build:ui",
     "test": "vitest run",
+    "test:a11y": "vitest run tests/widgetAxe.test.ts",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "start:http": "node dist/http.js",
@@ -83,7 +88,7 @@
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^2.0.3",
     "@modelcontextprotocol/server": "^2.3.1",
-    "@vantageos/cloud-identity": "^0.20.2",
+    "@vantageos/cloud-identity": "^0.34.1",
     "@vantageos/mosaic-i18n": "^0.1.1",
     "hono": "^4.13.13",
     "jose": "^6.2.7",
@@ -100,11 +105,14 @@
   "devDependencies": {
     "@biomejs/biome": "1.9.4",
     "@modelcontextprotocol/client": "^2.3.1",
+    "@types/jsdom": "^30.0.0",
     "@types/node": "^20.14.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^4.3.0",
+    "axe-core": "^4.14.0",
     "convex": "1.46.0",
+    "jsdom": "^30.1.3",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "typescript": "^5.7.2",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "vantage-mcp-boilerplate",
-  "version": "0.6.3",
+  "version": "0.8.0",
   "description": "Clonable MCP server template: SDK v2 on protocol 2026-07-28 (stdio + stateless Streamable HTTP), its own OAuth 2.1 authorization server (Clerk person + organisation), MCP Apps UI, FR/EN i18n and a declarative eval harness. Scaffold, extend, publish.",
   "author": {
     "name": "ElPi Corp / Laurent Perello"
@@ -34,9 +34,7 @@
         "longDescription": "Clonable MCP server template: SDK v2 on protocol 2026-07-28 (stdio + stateless Streamable HTTP), its own OAuth 2.1 authorization server (Clerk person + organisation), MCP Apps UI, FR/EN i18n and a declarative eval harness. Scaffold, extend, publish.",
         "developerName": "ElPi Corp / Laurent Perello",
         "websiteURL": "https://github.com/elpiarthera/vantage-mcp-boilerplate#readme",
-        "capabilities": [
-          "Read"
-        ]
+        "capabilities": ["Read"]
       }
     }
   }

package/scripts/plugin-manifest.source.json

@@ -31,5 +31,24 @@
   "openai": {
     "auth": { "type": "oauth", "client": { "mode": "cimd" } },
     "capabilities": ["Read"]
+  },
+  "listing": {
+    "testPrompts": {
+      "positive": [
+        "tools-call-ping-happy-path",
+        "tools-call-ping-default",
+        "tools-call-list-items-public-tier-unscoped",
+        "tools-call-list-items-page-truncated",
+        "tools-call-list-items-ui-link"
+      ],
+      "negative": [
+        "tools-call-ping-message-too-long-failure",
+        "tools-call-list-items-requires-tenant-refusal-failure",
+        "tools-call-list-items-invalid-cursor-failure"
+      ]
+    },
+    "reviewerAccount": {
+      "howToObtain": "Sign in at the server's /authorize page with any Clerk account; a reviewer organisation is created on request to the maintainers (README, 'Own authorization server'). No credential is stored in this repository."
+    }
   }
 }

package/scripts/readme-fr.mjs

@@ -27,7 +27,9 @@ import { fileURLToPath } from "node:url";
 export const BANNER =
   "<!-- Généré depuis README.md par mcp-readme-fr (@vantageos/mcp-boilerplate) : ne pas modifier à la main. -->";
 
-const MARKER = /^\s*<!--\s*(lang:([A-Za-z-]+)|\/lang)\s*-->\s*$/;
+// A marker sits at the start of a line with at most 3 spaces of indent (CommonMark): 4 or more spaces, or a tab, make
+// the line an indented code block, so such a "marker" is text, copied with the part it sits in, like a fenced one.
+const MARKER = /^ {0,3}<!--\s*(lang:([A-Za-z-]+)|\/lang)\s*-->\s*$/;
 const FENCE = /^ {0,3}(`{3,}|~{3,})(.*)$/;
 
 /** README.md text -> { fr, errors }. `fr` is the README.fr.md content (banner first). */
@@ -83,19 +85,24 @@ export function generate(text) {
       return;
     }
     // lang === "fr"
-    if (state === "shared")
+    if (state === "shared") {
       errors.push(
         `line ${n}: lang:fr opens a region before its English part (<!-- lang:en --> first)`
       );
-    else if (state === "fr")
+      // The region it opens is reported from this line, never from a stale or zero opening line.
+      openedAt = n;
+    } else if (state === "fr")
       errors.push(`line ${n}: a second lang:fr in the region opened at line ${openedAt}`);
     state = "fr";
   });
   if (fence !== null)
     errors.push(`line ${fence.at}: unclosed code fence (${fence.char.repeat(fence.len)})`);
+  // Every line number printed is 1-based. The last line of a file ending with a newline is the one before the empty
+  // string that split() leaves after it.
+  const lastLine = text.endsWith("\n") ? lines.length - 1 : lines.length;
   if (state !== "shared")
     errors.push(
-      `line ${lines.length}: the region opened at line ${openedAt} is unclosed (<!-- /lang -->)`
+      `line ${lastLine}: the region opened at line ${openedAt} is unclosed (<!-- /lang -->)`
     );
   return { fr: out.join("\n"), errors };
 }

package/dist/locales/en.json

@@ -1,77 +0,0 @@
-{
-  "Mcp": {
-    "auth": {
-      "unauthorized": "Unauthorized",
-      "originNotAllowed": "This origin is not allowed to call this endpoint"
-    },
-    "tenant": {
-      "permissionDenied": "permission denied: no tenant resolved for this caller"
-    },
-    "person": {
-      "identityNotConfigured": "permission denied: this tool needs the verified person, and this server resolves no person (identity is not configured)",
-      "noVerifiedSession": "permission denied: this tool needs the verified person, and this call carries no verified session",
-      "refused": "permission denied: the verified person behind this call could not be resolved"
-    },
-    "validation": {
-      "messageTooLong": "message exceeds the maximum length of 200 characters"
-    },
-    "oauth": {
-      "pickerTitle": "Connect {client}",
-      "pickerIntro": "{client} asks to act on your behalf. Choose the organisation it may reach, then approve or deny.",
-      "handoffTitle": "Returning to the application",
-      "handoffLink": "Continue to the application",
-      "pickerNoAllowedOrganisation": "None of your organisations is authorised on this server.",
-      "pickerDestination": "After approval you are sent to:",
-      "pickerScope": "Requested access:",
-      "pickerUnverified": "Unverified client: it registered itself automatically and nobody has vouched for it. Approve only if you recognise the address above.",
-      "pickerOrganisation": "Organisation",
-      "approve": "Approve",
-      "deny": "Deny",
-      "denied": "The request was denied; you can close this window.",
-      "unavailable": "Authorization is not configured on this server.",
-      "inMemoryWarning": "Running on in-memory OAuth stores: codes and registered clients are lost on restart and not shared between instances. Fine for development; set {knob}=1 to acknowledge, or inject durable adapters.",
-      "consentTokenRequired": "The consent token is missing: reload the page and try again.",
-      "registryFull": "Client registration is temporarily unavailable: the registry is full. Retry later.",
-      "devInstanceRemote": "Development Clerk instance on a remote server: its hosted sign-in page redirects only to localhost or to the instance Home URL. Set the development instance's Home URL (development origin) to this server's origin for a remote test and revert it afterwards, or use a Clerk production instance (see README, \"Sign-in with ChatGPT and Claude\")."
-    },
-    "manifest": {
-      "unreadableField": "cannot read field \"{field}\" of {source} (expected: {expected})",
-      "expect": {
-        "string": "a non-empty string",
-        "semver": "a semantic version (x.y.z)",
-        "object": "an object",
-        "boolean": "true or false",
-        "positiveInteger": "a positive whole number",
-        "atLeastPerTool": "at least the perTool ceiling"
-      }
-    },
-    "toolRecord": {
-      "unsound": "tool records or the context ceiling are unsound: {problems}"
-    },
-    "pagination": {
-      "invalidCursor": "invalid cursor: it was not issued by this tool or is no longer valid; start again without a cursor"
-    },
-    "lake": {
-      "unreadable": "the data source answered something this server cannot read; no row is shown rather than a partial or wrong page"
-    },
-    "buildIdentity": {
-      "unreadable": "cannot compute the build identity: {dir} is unreadable ({reason})",
-      "empty": "cannot compute the build identity: {dir} is empty (no file), nothing was built"
-    },
-    "config": {
-      "refused": "configuration refused: {problems}",
-      "missing": "{env} is missing (expected: {expected})",
-      "invalid": "{env} is set but invalid (expected: {expected}; value not shown)",
-      "expect": {
-        "string": "a non-empty string",
-        "integer": "an integer from {min} to {max}",
-        "integerAtLeast": "an integer of at least {min}",
-        "boolean": "\"0\" or \"1\"",
-        "url": "an https URL (http on loopback only)",
-        "originList": "a comma-separated list of origins (scheme://host[:port], no path)",
-        "enum": "one of: {values}",
-        "json": "a JSON object or array"
-      }
-    }
-  }
-}

package/dist/locales/fr.json

@@ -1,77 +0,0 @@
-{
-  "Mcp": {
-    "auth": {
-      "unauthorized": "Non autorisé",
-      "originNotAllowed": "Cette origine n'est pas autorisée à appeler ce point d'accès"
-    },
-    "tenant": {
-      "permissionDenied": "permission refusée : aucun tenant résolu pour cet appelant"
-    },
-    "person": {
-      "identityNotConfigured": "permission refusée : cet outil exige la personne vérifiée, et ce serveur ne résout aucune personne (identité non configurée)",
-      "noVerifiedSession": "permission refusée : cet outil exige la personne vérifiée, et cet appel ne porte aucune session vérifiée",
-      "refused": "permission refusée : la personne vérifiée derrière cet appel n'a pas pu être résolue"
-    },
-    "validation": {
-      "messageTooLong": "le message dépasse la longueur maximale de 200 caractères"
-    },
-    "oauth": {
-      "pickerTitle": "Connecter {client}",
-      "pickerIntro": "{client} demande à agir en votre nom. Choisissez l'organisation à laquelle il peut accéder, puis approuvez ou refusez.",
-      "handoffTitle": "Retour à l'application",
-      "handoffLink": "Continuer vers l'application",
-      "pickerNoAllowedOrganisation": "Aucune de vos organisations n'est autorisée sur ce serveur.",
-      "pickerDestination": "Redirection après validation vers :",
-      "pickerScope": "Accès demandé :",
-      "pickerUnverified": "Client non vérifié : il s'est enregistré automatiquement et personne ne s'en porte garant. N'approuvez que si vous reconnaissez l'adresse ci-dessus.",
-      "pickerOrganisation": "Organisation",
-      "approve": "Approuver",
-      "deny": "Refuser",
-      "denied": "La demande a été refusée ; vous pouvez fermer cette fenêtre.",
-      "unavailable": "L'autorisation n'est pas configurée sur ce serveur.",
-      "inMemoryWarning": "Stores OAuth en mémoire : les codes et les clients enregistrés sont perdus au redémarrage et non partagés entre instances. Acceptable en développement ; définissez {knob}=1 pour l'accepter, ou injectez des adaptateurs durables.",
-      "consentTokenRequired": "Le jeton de consentement est absent : rechargez la page et réessayez.",
-      "registryFull": "L'enregistrement de clients est temporairement indisponible : le registre est plein. Réessayez plus tard.",
-      "devInstanceRemote": "Instance Clerk de développement sur un serveur distant : sa page de connexion hébergée ne redirige que vers localhost ou vers l'URL d'accueil (Home URL) de l'instance. Pour un test distant, réglez l'URL d'accueil (origine de développement) de l'instance sur l'origine de ce serveur, puis rétablissez-la ; sinon utilisez une instance Clerk de production (voir README, « Connexion avec ChatGPT et Claude »)."
-    },
-    "manifest": {
-      "unreadableField": "champ \"{field}\" illisible dans {source} (attendu : {expected})",
-      "expect": {
-        "string": "une chaîne non vide",
-        "semver": "une version sémantique (x.y.z)",
-        "object": "un objet",
-        "boolean": "true ou false",
-        "positiveInteger": "un entier strictement positif",
-        "atLeastPerTool": "au moins le plafond perTool"
-      }
-    },
-    "toolRecord": {
-      "unsound": "fiches d'outils ou plafond de contexte invalides : {problems}"
-    },
-    "pagination": {
-      "invalidCursor": "curseur invalide : il n'a pas été émis par cet outil ou n'est plus valide ; recommencez sans curseur"
-    },
-    "lake": {
-      "unreadable": "la source de données a renvoyé une réponse illisible pour ce serveur ; aucune ligne n'est affichée plutôt qu'une page partielle ou fausse"
-    },
-    "buildIdentity": {
-      "unreadable": "identité de build incalculable : {dir} est illisible ({reason})",
-      "empty": "identité de build incalculable : {dir} est vide (aucun fichier), rien n'a été construit"
-    },
-    "config": {
-      "refused": "configuration refusée : {problems}",
-      "missing": "{env} est manquante (attendu : {expected})",
-      "invalid": "{env} est définie mais invalide (attendu : {expected} ; valeur non affichée)",
-      "expect": {
-        "string": "une chaîne non vide",
-        "integer": "un entier de {min} à {max}",
-        "integerAtLeast": "un entier d'au moins {min}",
-        "boolean": "\"0\" ou \"1\"",
-        "url": "une URL https (http seulement sur la boucle locale)",
-        "originList": "une liste d'origines séparées par des virgules (schéma://hôte[:port], sans chemin)",
-        "enum": "une valeur parmi : {values}",
-        "json": "un objet ou un tableau JSON"
-      }
-    }
-  }
-}