@vantageos/mcp-boilerplate 0.6.3 → 0.8.0

package/dist/embedded.generated.d.ts

@@ -0,0 +1,225 @@
+export declare const EMBEDDED_LOCALES: {
+    readonly en: {
+        readonly Mcp: {
+            readonly auth: {
+                readonly unauthorized: "Unauthorized";
+                readonly originNotAllowed: "This origin is not allowed to call this endpoint";
+            };
+            readonly tenant: {
+                readonly permissionDenied: "permission denied: no tenant resolved for this caller";
+            };
+            readonly person: {
+                readonly identityNotConfigured: "permission denied: this tool needs the verified person, and this server resolves no person (identity is not configured)";
+                readonly noVerifiedSession: "permission denied: this tool needs the verified person, and this call carries no verified session";
+                readonly refused: "permission denied: the verified person behind this call could not be resolved";
+            };
+            readonly rateLimit: {
+                readonly exceeded: "too many tool calls: retry in {seconds} s";
+            };
+            readonly validation: {
+                readonly messageTooLong: "message exceeds the maximum length of 200 characters";
+            };
+            readonly oauth: {
+                readonly pickerTitle: "Connect {client}";
+                readonly pickerIntro: "{client} asks to act on your behalf. Choose the organisation it may reach, then approve or deny.";
+                readonly handoffTitle: "Returning to the application";
+                readonly handoffLink: "Continue to the application";
+                readonly pickerNoAllowedOrganisation: "None of your organisations is authorised on this server.";
+                readonly pickerDestination: "After approval you are sent to:";
+                readonly pickerScope: "Requested access:";
+                readonly pickerUnverified: "Unverified client: it registered itself automatically and nobody has vouched for it. Approve only if you recognise the address above.";
+                readonly pickerOrganisation: "Organisation";
+                readonly approve: "Approve";
+                readonly deny: "Deny";
+                readonly denied: "The request was denied; you can close this window.";
+                readonly unavailable: "Authorization is not configured on this server.";
+                readonly 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.";
+                readonly consentTokenRequired: "The consent token is missing: reload the page and try again.";
+                readonly registryFull: "Client registration is temporarily unavailable: the registry is full. Retry later.";
+                readonly 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\").";
+            };
+            readonly manifest: {
+                readonly unreadableField: "cannot read field \"{field}\" of {source} (expected: {expected})";
+                readonly expect: {
+                    readonly string: "a non-empty string";
+                    readonly semver: "a semantic version (x.y.z)";
+                    readonly object: "an object";
+                    readonly boolean: "true or false";
+                    readonly positiveInteger: "a positive whole number";
+                    readonly atLeastPerTool: "at least the perTool ceiling";
+                    readonly stringArray: "an array of non-empty strings";
+                };
+            };
+            readonly toolRoles: {
+                readonly identityMissing: "the identity stores are not injected (AppDeps.identity): on the OAuth tier a caller's role is decided for the organisation the identity layer resolves, so both are required";
+                readonly denied: "permission denied: your role does not grant the tool {tool} ({reason})";
+                readonly unresolved: "permission denied: your role could not be read, so no tool is granted";
+                readonly configMissing: "{variable} is not set: on the OAuth tier every tool is decided by the caller's role, read from that roles file";
+                readonly configInvalid: "{variable} ({path}) is not a valid roles file: {problem}";
+            };
+            readonly toolRecord: {
+                readonly unsound: "tool records or the context ceiling are unsound: {problems}";
+            };
+            readonly pagination: {
+                readonly invalidCursor: "invalid cursor: it was not issued by this tool or is no longer valid; start again without a cursor";
+            };
+            readonly lake: {
+                readonly unreadable: "the data source answered something this server cannot read; no row is shown rather than a partial or wrong page";
+            };
+            readonly buildIdentity: {
+                readonly unreadable: "cannot compute the build identity: {dir} is unreadable ({reason})";
+                readonly empty: "cannot compute the build identity: {dir} is empty (no file), nothing was built";
+                readonly commitUnreadable: "cannot read the build commit from {file} ({reason}): run npm run build, which writes it (scripts/write-build-info.mjs)";
+            };
+            readonly config: {
+                readonly refused: "configuration refused: {problems}";
+                readonly missing: "{env} is missing (expected: {expected})";
+                readonly invalid: "{env} is set but invalid (expected: {expected}; value not shown)";
+                readonly expect: {
+                    readonly string: "a non-empty string";
+                    readonly integer: "an integer from {min} to {max}";
+                    readonly integerAtLeast: "an integer of at least {min}";
+                    readonly boolean: "\"0\" or \"1\"";
+                    readonly url: "an https URL (http on loopback only)";
+                    readonly originList: "a comma-separated list of origins (scheme://host[:port], no path)";
+                    readonly enum: "one of: {values}";
+                    readonly json: "a JSON object or array";
+                };
+            };
+            readonly server: {
+                readonly instructions: "This server exposes three read-only example tools.\n1. Call whoami first. It returns who is calling on this connection (null on the public tier and on stdio), the caller's role, and grantedTools: the tools that role may call. Never ask the user for their identity and never pass one as an argument.\n2. ping proves the connection end to end; pass message to have it echoed back.\n3. list_items lists the items of the caller's organisation and renders them in an interactive widget where the client supports MCP Apps. It is paged: pass the returned nextCursor to read the next page; exhausted: true means the last page. Never invent a cursor.\n4. A result with isError and structuredContent.error.code is a refusal, not an empty result: rate_limited (wait retryAfterMs, then retry once), invalid_cursor (restart from the first page), lake_unreadable, TOOL_ROLE_DENIED or TOOL_ROLE_UNRESOLVED (the caller may not use this tool). Report it to the user; never read it as \"nothing exists\".\n5. Send the X-MCP-Locale header (en or fr) to receive messages in that language.";
+                readonly identityMissing: "the server identity has no {item}: set {variable}, or the \"{field}\" field of package.json";
+                readonly identityInvalid: "the server identity's {item} is not an https URL (http on a loopback host only): {source}";
+            };
+            readonly landing: {
+                readonly pageTitle: "{title} — MCP server";
+                readonly intro: "This address is a Model Context Protocol (MCP) server. Add it to your AI client as a remote MCP server:";
+                readonly claudeAi: "Claude.ai: add a custom connector with this URL, then Connect.";
+                readonly chatgpt: "ChatGPT: add a custom MCP server (developer mode) with this URL.";
+                readonly claudeCode: "Claude Code:";
+                readonly other: "Any other MCP client: a Streamable HTTP server at the URL above.";
+                readonly authOauth: "Your client then opens a sign-in page (OAuth 2.1). There is no token to copy.";
+                readonly authPublic: "This server runs without sign-in: connect directly.";
+                readonly website: "Website:";
+            };
+            readonly widget: {
+                readonly description: "Shows the example items returned by list_items as a list, with their name and status; read-only, it makes no request of its own.";
+            };
+        };
+    };
+    readonly fr: {
+        readonly Mcp: {
+            readonly auth: {
+                readonly unauthorized: "Non autorisé";
+                readonly originNotAllowed: "Cette origine n'est pas autorisée à appeler ce point d'accès";
+            };
+            readonly tenant: {
+                readonly permissionDenied: "permission refusée : aucun tenant résolu pour cet appelant";
+            };
+            readonly person: {
+                readonly identityNotConfigured: "permission refusée : cet outil exige la personne vérifiée, et ce serveur ne résout aucune personne (identité non configurée)";
+                readonly noVerifiedSession: "permission refusée : cet outil exige la personne vérifiée, et cet appel ne porte aucune session vérifiée";
+                readonly refused: "permission refusée : la personne vérifiée derrière cet appel n'a pas pu être résolue";
+            };
+            readonly rateLimit: {
+                readonly exceeded: "trop d’appels d’outils : réessayez dans {seconds} s";
+            };
+            readonly validation: {
+                readonly messageTooLong: "le message dépasse la longueur maximale de 200 caractères";
+            };
+            readonly oauth: {
+                readonly pickerTitle: "Connecter {client}";
+                readonly pickerIntro: "{client} demande à agir en votre nom. Choisissez l'organisation à laquelle il peut accéder, puis approuvez ou refusez.";
+                readonly handoffTitle: "Retour à l'application";
+                readonly handoffLink: "Continuer vers l'application";
+                readonly pickerNoAllowedOrganisation: "Aucune de vos organisations n'est autorisée sur ce serveur.";
+                readonly pickerDestination: "Redirection après validation vers :";
+                readonly pickerScope: "Accès demandé :";
+                readonly 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.";
+                readonly pickerOrganisation: "Organisation";
+                readonly approve: "Approuver";
+                readonly deny: "Refuser";
+                readonly denied: "La demande a été refusée ; vous pouvez fermer cette fenêtre.";
+                readonly unavailable: "L'autorisation n'est pas configurée sur ce serveur.";
+                readonly 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.";
+                readonly consentTokenRequired: "Le jeton de consentement est absent : rechargez la page et réessayez.";
+                readonly registryFull: "L'enregistrement de clients est temporairement indisponible : le registre est plein. Réessayez plus tard.";
+                readonly 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 »).";
+            };
+            readonly manifest: {
+                readonly unreadableField: "champ \"{field}\" illisible dans {source} (attendu : {expected})";
+                readonly expect: {
+                    readonly string: "une chaîne non vide";
+                    readonly semver: "une version sémantique (x.y.z)";
+                    readonly object: "un objet";
+                    readonly boolean: "true ou false";
+                    readonly positiveInteger: "un entier strictement positif";
+                    readonly atLeastPerTool: "au moins le plafond perTool";
+                    readonly stringArray: "un tableau de chaînes non vides";
+                };
+            };
+            readonly toolRoles: {
+                readonly identityMissing: "les stores d'identité ne sont pas injectés (AppDeps.identity) : sur le niveau OAuth, le rôle d'un appelant est décidé pour l'organisation que la couche d'identité résout, les deux sont donc requis";
+                readonly denied: "permission refusée : votre rôle n'accorde pas l'outil {tool} ({reason})";
+                readonly unresolved: "permission refusée : votre rôle n'a pas pu être lu, aucun outil n'est accordé";
+                readonly configMissing: "{variable} n'est pas défini : sur le niveau OAuth, chaque outil est décidé par le rôle de l'appelant, lu dans ce fichier de rôles";
+                readonly configInvalid: "{variable} ({path}) n'est pas un fichier de rôles valide : {problem}";
+            };
+            readonly toolRecord: {
+                readonly unsound: "fiches d'outils ou plafond de contexte invalides : {problems}";
+            };
+            readonly pagination: {
+                readonly invalidCursor: "curseur invalide : il n'a pas été émis par cet outil ou n'est plus valide ; recommencez sans curseur";
+            };
+            readonly lake: {
+                readonly 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";
+            };
+            readonly buildIdentity: {
+                readonly unreadable: "identité de build incalculable : {dir} est illisible ({reason})";
+                readonly empty: "identité de build incalculable : {dir} est vide (aucun fichier), rien n'a été construit";
+                readonly commitUnreadable: "impossible de lire le commit de build dans {file} ({reason}) : lancez npm run build, qui l'écrit (scripts/write-build-info.mjs)";
+            };
+            readonly config: {
+                readonly refused: "configuration refusée : {problems}";
+                readonly missing: "{env} est manquante (attendu : {expected})";
+                readonly invalid: "{env} est définie mais invalide (attendu : {expected} ; valeur non affichée)";
+                readonly expect: {
+                    readonly string: "une chaîne non vide";
+                    readonly integer: "un entier de {min} à {max}";
+                    readonly integerAtLeast: "un entier d'au moins {min}";
+                    readonly boolean: "\"0\" ou \"1\"";
+                    readonly url: "une URL https (http seulement sur la boucle locale)";
+                    readonly originList: "une liste d'origines séparées par des virgules (schéma://hôte[:port], sans chemin)";
+                    readonly enum: "une valeur parmi : {values}";
+                    readonly json: "un objet ou un tableau JSON";
+                };
+            };
+            readonly server: {
+                readonly instructions: "Ce serveur expose trois outils d'exemple en lecture seule.\n1. Appelez whoami d'abord. Il renvoie qui appelle sur cette connexion (null sur le niveau public et en stdio), le rôle de l'appelant et grantedTools : les outils que ce rôle peut appeler. Ne demandez jamais son identité à l'utilisateur et n'en passez jamais une en argument.\n2. ping prouve la connexion de bout en bout ; passez message pour qu'il soit renvoyé tel quel.\n3. list_items liste les éléments de l'organisation de l'appelant et les affiche dans un widget interactif quand le client prend en charge MCP Apps. Il est paginé : passez le nextCursor renvoyé pour lire la page suivante ; exhausted: true signale la dernière page. N'inventez jamais de curseur.\n4. Un résultat avec isError et structuredContent.error.code est un refus, pas un résultat vide : rate_limited (attendez retryAfterMs, puis réessayez une fois), invalid_cursor (repartez de la première page), lake_unreadable, TOOL_ROLE_DENIED ou TOOL_ROLE_UNRESOLVED (l'appelant ne peut pas utiliser cet outil). Signalez-le à l'utilisateur ; ne le lisez jamais comme « rien n'existe ».\n5. Envoyez l'en-tête X-MCP-Locale (en ou fr) pour recevoir les messages dans cette langue.";
+                readonly identityMissing: "l'identité du serveur n'a pas de {item} : définissez {variable}, ou le champ « {field} » de package.json";
+                readonly identityInvalid: "{item} de l'identité du serveur n'est pas une URL https (http sur un hôte de bouclage seulement) : {source}";
+            };
+            readonly landing: {
+                readonly pageTitle: "{title} — serveur MCP";
+                readonly intro: "Cette adresse est un serveur Model Context Protocol (MCP). Ajoutez-la à votre client IA comme serveur MCP distant :";
+                readonly claudeAi: "Claude.ai : ajoutez un connecteur personnalisé avec cette URL, puis Connecter.";
+                readonly chatgpt: "ChatGPT : ajoutez un serveur MCP personnalisé (mode développeur) avec cette URL.";
+                readonly claudeCode: "Claude Code :";
+                readonly other: "Tout autre client MCP : un serveur Streamable HTTP à l'URL ci-dessus.";
+                readonly authOauth: "Votre client ouvre ensuite une page de connexion (OAuth 2.1). Aucun jeton à copier.";
+                readonly authPublic: "Ce serveur fonctionne sans connexion : branchez-vous directement.";
+                readonly website: "Site :";
+            };
+            readonly widget: {
+                readonly description: "Affiche sous forme de liste les éléments d'exemple renvoyés par list_items, avec leur nom et leur statut ; en lecture seule, il ne fait aucune requête lui-même.";
+            };
+        };
+    };
+};
+export declare const EMBEDDED_PACKAGE_VERSION = "0.8.0";
+export declare const EMBEDDED_PACKAGE_IDENTITY: {
+    displayName: string;
+    description: string;
+    description_fr: string;
+    homepage: string;
+};

package/dist/embedded.generated.js

@@ -0,0 +1,8 @@
+// GENERATED by scripts/embed-static.mjs from src/locales/{en,fr}.json and package.json. Do not edit:
+// `node scripts/embed-static.mjs --check` refuses any difference (tests/embedded-static.test.ts).
+export const EMBEDDED_LOCALES = {
+    en: { "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" }, "rateLimit": { "exceeded": "too many tool calls: retry in {seconds} s" }, "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", "stringArray": "an array of non-empty strings" } }, "toolRoles": { "identityMissing": "the identity stores are not injected (AppDeps.identity): on the OAuth tier a caller's role is decided for the organisation the identity layer resolves, so both are required", "denied": "permission denied: your role does not grant the tool {tool} ({reason})", "unresolved": "permission denied: your role could not be read, so no tool is granted", "configMissing": "{variable} is not set: on the OAuth tier every tool is decided by the caller's role, read from that roles file", "configInvalid": "{variable} ({path}) is not a valid roles file: {problem}" }, "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", "commitUnreadable": "cannot read the build commit from {file} ({reason}): run npm run build, which writes it (scripts/write-build-info.mjs)" }, "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" } }, "server": { "instructions": "This server exposes three read-only example tools.\n1. Call whoami first. It returns who is calling on this connection (null on the public tier and on stdio), the caller's role, and grantedTools: the tools that role may call. Never ask the user for their identity and never pass one as an argument.\n2. ping proves the connection end to end; pass message to have it echoed back.\n3. list_items lists the items of the caller's organisation and renders them in an interactive widget where the client supports MCP Apps. It is paged: pass the returned nextCursor to read the next page; exhausted: true means the last page. Never invent a cursor.\n4. A result with isError and structuredContent.error.code is a refusal, not an empty result: rate_limited (wait retryAfterMs, then retry once), invalid_cursor (restart from the first page), lake_unreadable, TOOL_ROLE_DENIED or TOOL_ROLE_UNRESOLVED (the caller may not use this tool). Report it to the user; never read it as \"nothing exists\".\n5. Send the X-MCP-Locale header (en or fr) to receive messages in that language.", "identityMissing": "the server identity has no {item}: set {variable}, or the \"{field}\" field of package.json", "identityInvalid": "the server identity's {item} is not an https URL (http on a loopback host only): {source}" }, "landing": { "pageTitle": "{title} — MCP server", "intro": "This address is a Model Context Protocol (MCP) server. Add it to your AI client as a remote MCP server:", "claudeAi": "Claude.ai: add a custom connector with this URL, then Connect.", "chatgpt": "ChatGPT: add a custom MCP server (developer mode) with this URL.", "claudeCode": "Claude Code:", "other": "Any other MCP client: a Streamable HTTP server at the URL above.", "authOauth": "Your client then opens a sign-in page (OAuth 2.1). There is no token to copy.", "authPublic": "This server runs without sign-in: connect directly.", "website": "Website:" }, "widget": { "description": "Shows the example items returned by list_items as a list, with their name and status; read-only, it makes no request of its own." } } },
+    fr: { "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" }, "rateLimit": { "exceeded": "trop d’appels d’outils : réessayez dans {seconds} s" }, "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", "stringArray": "un tableau de chaînes non vides" } }, "toolRoles": { "identityMissing": "les stores d'identité ne sont pas injectés (AppDeps.identity) : sur le niveau OAuth, le rôle d'un appelant est décidé pour l'organisation que la couche d'identité résout, les deux sont donc requis", "denied": "permission refusée : votre rôle n'accorde pas l'outil {tool} ({reason})", "unresolved": "permission refusée : votre rôle n'a pas pu être lu, aucun outil n'est accordé", "configMissing": "{variable} n'est pas défini : sur le niveau OAuth, chaque outil est décidé par le rôle de l'appelant, lu dans ce fichier de rôles", "configInvalid": "{variable} ({path}) n'est pas un fichier de rôles valide : {problem}" }, "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", "commitUnreadable": "impossible de lire le commit de build dans {file} ({reason}) : lancez npm run build, qui l'écrit (scripts/write-build-info.mjs)" }, "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" } }, "server": { "instructions": "Ce serveur expose trois outils d'exemple en lecture seule.\n1. Appelez whoami d'abord. Il renvoie qui appelle sur cette connexion (null sur le niveau public et en stdio), le rôle de l'appelant et grantedTools : les outils que ce rôle peut appeler. Ne demandez jamais son identité à l'utilisateur et n'en passez jamais une en argument.\n2. ping prouve la connexion de bout en bout ; passez message pour qu'il soit renvoyé tel quel.\n3. list_items liste les éléments de l'organisation de l'appelant et les affiche dans un widget interactif quand le client prend en charge MCP Apps. Il est paginé : passez le nextCursor renvoyé pour lire la page suivante ; exhausted: true signale la dernière page. N'inventez jamais de curseur.\n4. Un résultat avec isError et structuredContent.error.code est un refus, pas un résultat vide : rate_limited (attendez retryAfterMs, puis réessayez une fois), invalid_cursor (repartez de la première page), lake_unreadable, TOOL_ROLE_DENIED ou TOOL_ROLE_UNRESOLVED (l'appelant ne peut pas utiliser cet outil). Signalez-le à l'utilisateur ; ne le lisez jamais comme « rien n'existe ».\n5. Envoyez l'en-tête X-MCP-Locale (en ou fr) pour recevoir les messages dans cette langue.", "identityMissing": "l'identité du serveur n'a pas de {item} : définissez {variable}, ou le champ « {field} » de package.json", "identityInvalid": "{item} de l'identité du serveur n'est pas une URL https (http sur un hôte de bouclage seulement) : {source}" }, "landing": { "pageTitle": "{title} — serveur MCP", "intro": "Cette adresse est un serveur Model Context Protocol (MCP). Ajoutez-la à votre client IA comme serveur MCP distant :", "claudeAi": "Claude.ai : ajoutez un connecteur personnalisé avec cette URL, puis Connecter.", "chatgpt": "ChatGPT : ajoutez un serveur MCP personnalisé (mode développeur) avec cette URL.", "claudeCode": "Claude Code :", "other": "Tout autre client MCP : un serveur Streamable HTTP à l'URL ci-dessus.", "authOauth": "Votre client ouvre ensuite une page de connexion (OAuth 2.1). Aucun jeton à copier.", "authPublic": "Ce serveur fonctionne sans connexion : branchez-vous directement.", "website": "Site :" }, "widget": { "description": "Affiche sous forme de liste les éléments d'exemple renvoyés par list_items, avec leur nom et leur statut ; en lecture seule, il ne fait aucune requête lui-même." } } },
+};
+export const EMBEDDED_PACKAGE_VERSION = "0.8.0";
+export const EMBEDDED_PACKAGE_IDENTITY = { "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.", "homepage": "https://github.com/elpiarthera/vantage-mcp-boilerplate#readme" };

package/dist/hostVerification.d.ts

@@ -0,0 +1,15 @@
+import type { Env, Hono } from "hono";
+/**
+ * The verification path each host reads to confirm we own the origin (mcp-server-standard S-45), served for every
+ * DECLARED target (`mcp-server.json` `distribution.targets`) from configuration — never a token written in source.
+ * A host with no verification path (claude, cursor, vscode, …) needs no route. One explicit route per host that has
+ * one, each reading `process.env` in its own handler, so a reader (and mcp-doctor) sees both the path and where its
+ * value comes from; a fork sets the value in its environment.
+ */
+export declare const HOST_VERIFICATION: ReadonlyArray<{
+    host: string;
+    path: string;
+    env: string;
+}>;
+/** Registers the verification route of every declared target that has one; returns the paths registered. */
+export declare function registerHostVerification<E extends Env>(app: Hono<E>, targets: readonly string[]): string[];

package/dist/hostVerification.js

@@ -0,0 +1,32 @@
+/**
+ * The verification path each host reads to confirm we own the origin (mcp-server-standard S-45), served for every
+ * DECLARED target (`mcp-server.json` `distribution.targets`) from configuration — never a token written in source.
+ * A host with no verification path (claude, cursor, vscode, …) needs no route. One explicit route per host that has
+ * one, each reading `process.env` in its own handler, so a reader (and mcp-doctor) sees both the path and where its
+ * value comes from; a fork sets the value in its environment.
+ */
+export const HOST_VERIFICATION = [
+    { host: "chatgpt", path: "/.well-known/openai-apps-challenge", env: "OPENAI_APPS_CHALLENGE" },
+    {
+        host: "google-connected-apps",
+        path: "/.well-known/google-connected-apps",
+        env: "GOOGLE_CONNECTED_APPS_VERIFICATION",
+    },
+];
+/** The configured value, read at request time; unset, 404 naming the variable (the host's check fails visibly). */
+function answer(c, value, variable) {
+    return value ? c.text(value) : c.text(`${variable} is not configured`, 404);
+}
+/** Registers the verification route of every declared target that has one; returns the paths registered. */
+export function registerHostVerification(app, targets) {
+    const registered = [];
+    if (targets.includes("chatgpt")) {
+        app.get("/.well-known/openai-apps-challenge", (c) => answer(c, process.env.OPENAI_APPS_CHALLENGE, "OPENAI_APPS_CHALLENGE"));
+        registered.push("/.well-known/openai-apps-challenge");
+    }
+    if (targets.includes("google-connected-apps")) {
+        app.get("/.well-known/google-connected-apps", (c) => answer(c, process.env.GOOGLE_CONNECTED_APPS_VERIFICATION, "GOOGLE_CONNECTED_APPS_VERIFICATION"));
+        registered.push("/.well-known/google-connected-apps");
+    }
+    return registered;
+}

package/dist/http.js

@@ -2,8 +2,11 @@ import { loadAuthConfig, loadAuthMode } from "./config.js";
 import { buildHttpApp } from "./httpApp.js";
 import { createNodeListener, maxBodyBytesFrom } from "./nodeAdapter.js";
 import { loadHttpSettings } from "./settings.js";
+import { claudeSandboxDomain, servedMcpUrl } from "./ui/sandboxDomain.js";
 const authMode = loadAuthMode();
-const uiDomain = process.env.MCP_UI_DOMAIN || undefined;
+// A-11: the widget's Claude sandbox domain is derived from the served MCP URL, never configured as a literal.
+const mcpUrl = servedMcpUrl(process.env);
+const uiDomain = mcpUrl ? claudeSandboxDomain(mcpUrl) : undefined;
 // S-22: MCP_ALLOWED_ORIGINS, declared in src/settings.ts. A wildcard or a path stops the server
 // here with a ConfigurationError naming the variable.
 const { allowedOrigins } = loadHttpSettings();
@@ -12,11 +15,13 @@ const { allowedOrigins } = loadHttpSettings();
 // settings from the environment per request — a missing value answers 503, see
 // src/oauth/settings.ts.
 const externalIssuer = Boolean(process.env.MCP_OAUTH_ISSUER && process.env.MCP_OAUTH_AUDIENCE);
+// S-50: the server card, the setup page and the icon name the public origin when it is set.
+const publicBaseUrl = process.env.PUBLIC_BASE_URL || undefined;
 const app = buildHttpApp(authMode === "oauth"
     ? externalIssuer
-        ? { authMode, auth: loadAuthConfig(), uiDomain, allowedOrigins }
-        : { authMode, authorizationServer: {}, uiDomain, allowedOrigins }
-    : { authMode, uiDomain, allowedOrigins });
+        ? { authMode, auth: loadAuthConfig(), uiDomain, allowedOrigins, publicBaseUrl }
+        : { authMode, authorizationServer: {}, uiDomain, allowedOrigins, publicBaseUrl }
+    : { authMode, uiDomain, allowedOrigins, publicBaseUrl });
 const port = Number(process.env.PORT ?? 8787);
 // Hono's fetch handler adapted onto Node's http server, with the request-body cap
 // (MCP_MAX_BODY_BYTES, default 1 MiB) enforced while the body streams in: src/nodeAdapter.ts.

package/dist/httpApp.d.ts

@@ -28,15 +28,25 @@ import type { AuthMode } from "./config.js";
 import type { ExampleItem } from "./exampleItems.js";
 import type { LakeReader } from "./lake/reader.js";
 import { type AuthorizationServerDeps } from "./oauth/authorizationServer.js";
+import type { RateLimiter } from "./rateLimit.js";
 import type { CursorSigner } from "./signedCursor.js";
 import { type ResolvedTenant } from "./tenancy.js";
+import { type ToolRolesConfig } from "./toolRoles.js";
 import { type CallerResolution, type IdentityDeps } from "./verifiedPerson.js";
 export interface AppDeps {
     authMode?: AuthMode;
+    /** The tool invocation limiter (S-24); default the process-wide one. A test injects its own. */
+    rateLimiter?: RateLimiter;
     /** External-issuer resource-server configuration (no authorization server mounted). */
     auth?: AuthConfig;
     /** Own authorization server (R1). Takes precedence over `auth`. */
     authorizationServer?: AuthorizationServerDeps;
+    /**
+     * The public base URL (`PUBLIC_BASE_URL`, src/http.ts): the server card, the setup page and the
+     * serverInfo icon name `<base>/mcp` and `<base>/icon.svg`. Absent (development), they name the
+     * origin the request was addressed to, and those answers are sent `no-store`.
+     */
+    publicBaseUrl?: string;
     /** Dedicated sandbox origin for the MCP Apps widget (`_meta.ui.domain`). */
     uiDomain?: string;
     /**
@@ -47,6 +57,11 @@ export interface AppDeps {
      * (`identity_not_configured`).
      */
     identity?: IdentityDeps;
+    /**
+     * Agent tool roles (src/toolRoles.ts). Default: read at start by `loadToolRoles` — on the OAuth tier `MCP_ROLES_FILE`
+     * is required; elsewhere roles are not applicable. A test or a deployment with another store injects its own.
+     */
+    toolRoles?: ToolRolesConfig;
     /**
      * The data-lake reader `list_items` reads through (src/lake/reader.ts), read-only by design.
      * Injected by the deployment like `identity`; absent, the in-memory seed is read.

package/dist/httpApp.js

@@ -26,36 +26,133 @@ import { createMcpHandler } from "@modelcontextprotocol/server";
 import { unauthorizedChallenge } from "@vantageos/cloud-identity";
 import { Hono } from "hono";
 import { authenticateRequest, protectedResourceMetadataDocument } from "./auth.js";
-import { getBuildIdentity } from "./buildIdentity.js";
-import { detectLocale, t } from "./i18n.js";
-import { createBoilerplateMcpServer } from "./mcpServerFactory.js";
+import { getBuildCommit, getBuildIdentity } from "./buildIdentity.js";
+import { registerHostVerification } from "./hostVerification.js";
+import { detectLocale, t, tBoth } from "./i18n.js";
+import { isBrowserLandingRequest, landingPageResponse } from "./landingPage.js";
+import { createBoilerplateMcpServer, registeredToolSummaries } from "./mcpServerFactory.js";
 import { createAuthorizationServer, } from "./oauth/authorizationServer.js";
 import { MCP_SCOPE } from "./oauth/settings.js";
+import { SERVER_CARD_PATHS, buildServerCard, serverCardResponse } from "./serverCard.js";
+import { SERVER_ICON_MIME_TYPE, SERVER_ICON_PATH, SERVER_ICON_SVG } from "./serverIcon.js";
+import { getServerIdentity } from "./serverIdentity.js";
 import { loadServerManifest } from "./serverManifest.js";
 import { resolveTenantFromJwtPayload } from "./tenancy.js";
+import { callerScopeOf } from "./toolRoleGate.js";
+import { ToolRolesConfigError, loadToolRoles } from "./toolRoles.js";
+import { servedMcpUrl } from "./ui/sandboxDomain.js";
 import { assertIdentityDeps, resolveVerifiedPerson, } from "./verifiedPerson.js";
 import { SERVER_VERSION } from "./version.js";
+function servedLocation(publicBaseUrl, requestUrl) {
+    const configured = publicBaseUrl ? servedMcpUrl({ PUBLIC_BASE_URL: publicBaseUrl }) : undefined;
+    const mcpUrl = configured ?? new URL("/mcp", requestUrl).href;
+    return { mcpUrl, baseUrl: new URL("./", mcpUrl).href, configured: configured !== undefined };
+}
 const PRM_PATHS = [
     "/.well-known/oauth-protected-resource",
     "/.well-known/oauth-protected-resource/mcp",
 ];
+/**
+ * The per-request role context: the caller's member scope (from the person the identity layer resolved) and the role
+ * the provider returns for it. No resolved person -> no lookup and a null scope, so every gated tool is denied
+ * (caller-not-resolved). A provider that throws is a failed read -> TOOL_ROLE_UNRESOLVED, never "all tools".
+ */
+async function toolRolesFor(config, caller) {
+    if (!config.applicable)
+        return { applicable: false };
+    const person = caller?.ok ? caller.person : undefined;
+    const scope = callerScopeOf(person);
+    let lookup = { status: "absent", cause: "unassigned" };
+    if (person && scope?.orgClerkId) {
+        try {
+            lookup = await config.provider({ subject: person.subject, orgClerkId: scope.orgClerkId });
+        }
+        catch {
+            lookup = { status: "unresolved" };
+        }
+    }
+    return { applicable: true, lookup, caller: scope, resolution: caller, roleName: config.roleName };
+}
 export function buildHttpApp(deps = {}) {
     const app = new Hono();
     const authMode = deps.authMode ?? "public";
     // Refuses at start, naming the field, a manifest without a readable context ceiling (G6).
-    loadServerManifest();
+    const manifest = loadServerManifest();
     if (deps.identity)
         assertIdentityDeps(deps.identity);
-    // Unauthenticated (S-7): the version AND the identity of the tree being served (C-25), so a
-    // deployment is proven from what the server returns, not from what the deploy printed.
-    app.get("/health", (c) => c.json({ status: "ok", version: SERVER_VERSION, buildId: getBuildIdentity() }));
+    // Agent tool roles (Pi's rulings on task k17103j933e6en0aqyws2v1twx8hc0s3): on the OAuth tier every tool is decided
+    // by the caller's role, which needs BOTH a role store and the identity stores that resolve the caller to an
+    // organisation. The start refuses, naming each piece that is missing; an absent store never widens access.
+    const toolRoles = authMode === "oauth"
+        ? (() => {
+            const missing = [];
+            let config = deps.toolRoles;
+            if (!config) {
+                try {
+                    config = loadToolRoles("oauth");
+                }
+                catch (e) {
+                    if (!(e instanceof ToolRolesConfigError))
+                        throw e;
+                    missing.push(e.message);
+                }
+            }
+            if (!deps.identity)
+                missing.push(tBoth("toolRoles.identityMissing"));
+            if (missing.length > 0)
+                throw new ToolRolesConfigError(missing.join("; "));
+            return config;
+        })()
+        : { applicable: false };
+    // The public identity (S-49), read once at start: a value neither the environment nor
+    // package.json carries stops the server here, naming it, instead of serving a placeholder.
+    const identity = getServerIdentity();
+    // Unauthenticated (S-7): the version AND the identity of the tree being served (C-25): buildId is
+    // the git commit the tree was built from, buildHash the hash of the files this process runs
+    // from, so a deployment is proven from what the server returns, not from what the deploy printed.
+    app.get("/health", (c) => c.json({
+        status: "ok",
+        version: SERVER_VERSION,
+        buildId: getBuildCommit(),
+        buildHash: getBuildIdentity(),
+    }));
+    // Discoverability (S-49 icon, S-50), public and registered BEFORE the auth gate below: a route
+    // that answers ends the chain, so none of them is ever gated. They read no credential and grant
+    // nothing. The setup page at /mcp sits after the Origin check (S-22 holds on every /mcp method).
+    //  - the serverInfo icon, as SVG, under a CSP that forbids script and external references;
+    app.get(`/${SERVER_ICON_PATH}`, (c) => c.body(SERVER_ICON_SVG, 200, {
+        "content-type": `${SERVER_ICON_MIME_TYPE}; charset=utf-8`,
+        "cache-control": "public, max-age=86400",
+        "content-security-policy": "default-src 'none'; style-src 'unsafe-inline'",
+        "x-content-type-options": "nosniff",
+    }));
+    //  - the MCP Server Card at every path a scanner probes (src/serverCard.ts), its tool summary
+    //    read from the tools a server built by the factory registers (computed once, on first read);
+    let cardTools;
+    for (const path of SERVER_CARD_PATHS) {
+        app.get(path, (c) => {
+            cardTools ??= registeredToolSummaries(createBoilerplateMcpServer({ locale: "en" }));
+            const where = servedLocation(deps.publicBaseUrl, c.req.url);
+            const card = buildServerCard({
+                identity,
+                mcpUrl: where.mcpUrl,
+                baseUrl: where.baseUrl,
+                capabilities: manifest.capabilities,
+                tools: [...cardTools],
+            });
+            return serverCardResponse(c.req.raw, card, where.configured);
+        });
+    }
+    // S-45: the verification path of every declared target host, served from configuration.
+    registerHostVerification(app, manifest.distribution.targets);
     // S-22 Origin validation, on /mcp ONLY and registered BEFORE the auth gate: a request that carries
     // an Origin header (a browser) must name an allowed origin (exact full-origin match, case-
     // insensitive), else 403 before any token is looked at. No Origin header (server-to-server, Claude
     // Code, a connector backend) passes as before. `null`, an empty value and near-misses such as
     // `https://claude.ai.evil.example` are not in the list, so they are refused.
-    // Declared divergence: /health and the OAuth/discovery routes (/.well-known/*, /authorize, /token,
-    // /register) are NOT covered — they are browser navigations or CORS calls of the sign-in flow
+    // Declared divergence: /health, the icon, the server card paths (/mcp/server-card included, served
+    // above) and the OAuth/discovery routes (/.well-known/*, /authorize, /token, /register) are NOT
+    // covered — they are public metadata, browser navigations or CORS calls of the sign-in flow
     // (/register has its own MCP_REGISTER_CORS_ORIGINS allowlist) and S-22 guards the MCP endpoint.
     const allowedOrigins = new Set((deps.allowedOrigins ?? []).map((o) => o.toLowerCase()));
     app.use("/mcp", async (c, next) => {
@@ -68,6 +165,15 @@ export function buildHttpApp(deps = {}) {
             message_fr: t("fr", "auth.originNotAllowed"),
         }, 403);
     });
+    // S-50 setup page at the MCP URL, after the Origin check and BEFORE the auth gate: a request that
+    // cannot be an MCP request (a browser GET: no Authorization, no text/event-stream) gets the
+    // public page (src/landingPage.ts); every other request continues to the gate unchanged.
+    app.get("/mcp", async (c, next) => {
+        if (!isBrowserLandingRequest(c.req.raw))
+            return next();
+        const where = servedLocation(deps.publicBaseUrl, c.req.url);
+        return landingPageResponse(identity, where.mcpUrl, authMode, where.configured);
+    });
     if (authMode === "oauth") {
         // Resolves the resource-server configuration per request: the own-AS tier reads its
         // environment lazily, so a missing value is a 503 on the request, not a crash at boot.
@@ -154,14 +260,18 @@ export function buildHttpApp(deps = {}) {
             ? c.get("caller")
             : await resolveVerifiedPerson(undefined, deps.identity);
         const locale = detectLocale(c.req.header("X-MCP-Locale"));
+        const roles = await toolRolesFor(toolRoles, caller);
         const handler = createMcpHandler(() => createBoilerplateMcpServer({
             tenant,
             requireTenant: authMode === "oauth",
             caller,
             locale,
             uiDomain: deps.uiDomain,
+            baseUrl: servedLocation(deps.publicBaseUrl, c.req.url).baseUrl,
             lake: deps.lake,
             cursorSigner: deps.cursorSigner,
+            rateLimiter: deps.rateLimiter,
+            toolRoles: roles,
         }));
         return handler.fetch(c.req.raw);
     });

package/dist/i18n.js

@@ -18,23 +18,13 @@
  * (§Bilingual, l.234): "fr" selects the French resource, anything else
  * (including a missing header) defaults to English.
  */
-import { readFileSync } from "node:fs";
-import { fileURLToPath } from "node:url";
-// Loaded via fs + JSON.parse, not a JSON module import: Node's ESM loader
-// (the runtime the compiled dist/stdio.js and dist/http.js run under)
-// requires an explicit import attribute for a JSON module import, which the
-// project's current `tsconfig.json` `module` target does not emit. This
-// project's `resolveJsonModule` + a plain JSON import already work for
-// bundler-processed code (e.g. src/ui/Widget.tsx, inlined by Vite at build
-// time and never hitting Node's loader at all) but not for tsc's own Node
-// ESM output, so the two resources here are read as plain files instead.
-function loadLocaleResource(fileName) {
-    const path = fileURLToPath(new URL(`./locales/${fileName}`, import.meta.url));
-    return JSON.parse(readFileSync(path, "utf8"));
-}
+import { EMBEDDED_LOCALES } from "./embedded.generated.js";
+// The two resources are module values (src/embedded.generated.ts, generated from src/locales/{en,fr}.json by
+// scripts/embed-static.mjs at build), never a file read at import: a bundled consumer (the Convex bundler,
+// esbuild) carries this module and no `locales/` folder beside it (task k17aj33ks3ndyxgt7jch68rpwx8hz9x5).
 const RESOURCES = {
-    en: loadLocaleResource("en.json"),
-    fr: loadLocaleResource("fr.json"),
+    en: EMBEDDED_LOCALES.en,
+    fr: EMBEDDED_LOCALES.fr,
 };
 /**
  * Resolves the caller's locale from the `X-MCP-Locale` request header.