@12-apps/mcp 3.15.0 → 3.17.0

package/dist/e2e/index.d.ts

@@ -0,0 +1,109 @@
+import { Page } from '@playwright/test';
+
+/** Every packaged `.feature`, for `defineBddConfig({ features })`. */
+declare const mcpFeatures: string;
+/**
+ * The base `defineBddConfig({ featuresRoot })` must be given, and it is NOT
+ * optional decoration.
+ *
+ * bddgen mirrors each feature's path RELATIVE TO `featuresRoot` under
+ * `outputDir`. Left unset it defaults to the config's own directory, so a
+ * feature living under `node_modules/...` compiles to a path Playwright then
+ * IGNORES, because its default `testIgnore` excludes `**\/node_modules/**`.
+ *
+ * The result is the worst kind of green: bddgen reports the features compiled,
+ * Playwright collects zero specs from them, and the run passes with the whole
+ * packaged suite silently absent.
+ *
+ * A host running SEVERAL packaged suites gives `featuresRoot` the directory they
+ * all sit under, since bddgen takes exactly one — and that is safe to do,
+ * because a feature outside it is a hard exit from bddgen, never a quiet
+ * omission.
+ */
+declare const mcpFeaturesRoot: string;
+/**
+ * Every packaged step definition, for `defineBddConfig({ steps })`.
+ *
+ * COMPILED JavaScript, and that is the reason this package has a build step at
+ * all while everything else it exports is raw `.ts` through the `exports` map.
+ * Those entries are consumed by an application's BUNDLER, which transpiles
+ * whatever it is pointed at. These are loaded by NODE — `playwright.config.ts`
+ * imports this module, and bddgen imports the step files — and Node refuses to
+ * strip types from anything under `node_modules`
+ * (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`). Playwright's own TS transform
+ * does not rescue them either; it skips `node_modules` by design.
+ *
+ * The host's own steps glob must ALSO be listed — that is where its
+ * `defineMcpConnectWorld` call lives, and playwright-bdd imports every step
+ * file before any scenario runs, which is what makes the registration land in
+ * time in every worker.
+ */
+declare const mcpSteps: string;
+
+/**
+ * The port a HOST implements to run the packaged AI-connect journeys.
+ *
+ * These journeys were written because the walkthrough they cover was tested
+ * NOWHERE. `./react` ships the whole flow — the landing, the assistant picker,
+ * the endpoint to copy, the configure and connect steps, the confirmation and
+ * its re-test — and twenty test ids go with it. Not one of them appeared in
+ * this package's own suite, and not one appeared in the origin host's specs
+ * either: that host's `ai.e2e.ts` drives its OWN plan lock and upsell modal,
+ * reaching only `ai-onboarding` and the status board on the way past.
+ *
+ * So the flow a store owner actually walks was covered by nothing, in either
+ * repo. That is the gap the `e2e` capability exists to convert into a
+ * declaration rather than an omission nobody can see.
+ *
+ * What stays the host's: how it signs an owner in, where it mounts the flow,
+ * and which assistant its `hosts` config offers — the guides are REQUIRED
+ * config (FUT-760), so the package has no assistant of its own to name.
+ */
+/** Facts about the host that the assertions have to name. */
+interface McpConnectFixtures {
+    /**
+     * The id of an assistant the host offers whose guide has NO `pluginUrl`.
+     *
+     * The flow BRANCHES on that field: a guide carrying one gets `InstallStep`
+     * (a single "open the install link" button), and a guide without one gets
+     * the three-step manual path — copy the endpoint, configure, connect. These
+     * journeys walk the MANUAL path, so the host has to point at a guide that
+     * takes it. Naming the branch here rather than guessing keeps the scenario
+     * from failing in a host whose first assistant happens to ship a plugin.
+     */
+    manualHostId: string;
+    /** The endpoint URL that host serves, as it is rendered for copying. */
+    endpointUrl: string;
+}
+/** What a host must be able to do for these journeys to run in it. */
+interface McpConnectWorld {
+    /**
+     * Put the browser in a known signed-in state as somebody who may connect an
+     * assistant, with the flow's progress RESET to its first run.
+     *
+     * The reset is load-bearing rather than hygiene: the wizard persists its step
+     * through `@12-apps/onboarding`, so a scenario that advanced it would hand
+     * the next one a flow resuming from the middle — and the landing step, which
+     * two of these scenarios assert, would never render.
+     */
+    signInAsOwner(page: Page): Promise<void>;
+    /** Land on the screen that mounts `AiIntegrationOnboarding`. */
+    openAiIntegrationScreen(page: Page): Promise<void>;
+    fixtures: McpConnectFixtures;
+}
+/**
+ * Install the host's implementation. Call this from a module inside the host's
+ * OWN steps glob — playwright-bdd imports every step file before any scenario
+ * runs, so a top-level call there is registered in time, in every worker.
+ */
+declare function defineMcpConnectWorld(world: McpConnectWorld): void;
+/**
+ * The installed world, or a refusal naming the fix.
+ *
+ * Throws rather than returning null: a step that ran against an absent world
+ * would fail on whatever it touched next, somewhere unrelated to the actual
+ * mistake, which is a diagnosis nobody should have to make twice.
+ */
+declare function mcpConnectWorld(): McpConnectWorld;
+
+export { type McpConnectFixtures, type McpConnectWorld, defineMcpConnectWorld, mcpConnectWorld, mcpFeatures, mcpFeaturesRoot, mcpSteps };

package/dist/e2e/index.js

@@ -0,0 +1,27 @@
+import {
+  defineMcpConnectWorld,
+  mcpConnectWorld
+} from "../chunk-F3LMK6OL.js";
+import {
+  __name
+} from "../chunk-7QVYU63E.js";
+
+// src/e2e/globs.ts
+import { createRequire } from "module";
+import { dirname, join } from "path";
+var require_ = createRequire(import.meta.url);
+function packageRoot() {
+  return dirname(require_.resolve("@12-apps/mcp/package.json"));
+}
+__name(packageRoot, "packageRoot");
+var mcpFeatures = join(packageRoot(), "features/**/*.feature");
+var mcpFeaturesRoot = join(packageRoot(), "features");
+var mcpSteps = join(packageRoot(), "dist/e2e/steps/**/*.js");
+export {
+  defineMcpConnectWorld,
+  mcpConnectWorld,
+  mcpFeatures,
+  mcpFeaturesRoot,
+  mcpSteps
+};
+//# sourceMappingURL=index.js.map

package/dist/e2e/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/e2e/globs.ts"],"sourcesContent":["import { createRequire } from 'node:module';\nimport { dirname, join } from 'node:path';\n\n/**\n * Where this package's journeys and their steps live, ON DISK, in the consumer's\n * `node_modules`.\n *\n * `defineBddConfig` takes filesystem globs, not module specifiers — it hands\n * them to a glob matcher, so `'@12-apps/mcp/features/**'` matches\n * nothing and, worse, matches nothing SILENTLY: bddgen compiles the features it\n * found, finds none, and the run is green with zero journeys.\n *\n * So the paths are RESOLVED here instead of written down by every consumer. A\n * host that hard-codes `node_modules/@12-apps/mcp/...` is broken by\n * pnpm's nested store, by a workspace link, and by this package's own layout\n * changing; resolving from the package's own entry point is correct under all\n * three.\n */\nconst require_ = createRequire(import.meta.url);\n\n/**\n * The package root, found from a file this package definitely exports.\n * `./package.json` is exported precisely so this lookup needs no guess about\n * directory depth.\n */\nfunction packageRoot(): string {\n  return dirname(require_.resolve('@12-apps/mcp/package.json'));\n}\n\n/** Every packaged `.feature`, for `defineBddConfig({ features })`. */\nexport const mcpFeatures: string = join(packageRoot(), 'features/**/*.feature');\n\n/**\n * The base `defineBddConfig({ featuresRoot })` must be given, and it is NOT\n * optional decoration.\n *\n * bddgen mirrors each feature's path RELATIVE TO `featuresRoot` under\n * `outputDir`. Left unset it defaults to the config's own directory, so a\n * feature living under `node_modules/...` compiles to a path Playwright then\n * IGNORES, because its default `testIgnore` excludes `**\\/node_modules/**`.\n *\n * The result is the worst kind of green: bddgen reports the features compiled,\n * Playwright collects zero specs from them, and the run passes with the whole\n * packaged suite silently absent.\n *\n * A host running SEVERAL packaged suites gives `featuresRoot` the directory they\n * all sit under, since bddgen takes exactly one — and that is safe to do,\n * because a feature outside it is a hard exit from bddgen, never a quiet\n * omission.\n */\nexport const mcpFeaturesRoot: string = join(packageRoot(), 'features');\n\n/**\n * Every packaged step definition, for `defineBddConfig({ steps })`.\n *\n * COMPILED JavaScript, and that is the reason this package has a build step at\n * all while everything else it exports is raw `.ts` through the `exports` map.\n * Those entries are consumed by an application's BUNDLER, which transpiles\n * whatever it is pointed at. These are loaded by NODE — `playwright.config.ts`\n * imports this module, and bddgen imports the step files — and Node refuses to\n * strip types from anything under `node_modules`\n * (`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`). Playwright's own TS transform\n * does not rescue them either; it skips `node_modules` by design.\n *\n * The host's own steps glob must ALSO be listed — that is where its\n * `defineMcpConnectWorld` call lives, and playwright-bdd imports every step\n * file before any scenario runs, which is what makes the registration land in\n * time in every worker.\n */\nexport const mcpSteps: string = join(packageRoot(), 'dist/e2e/steps/**/*.js');\n"],"mappings":";;;;;;;;;AAAA,SAAS,qBAAqB;AAC9B,SAAS,SAAS,YAAY;AAiB9B,IAAM,WAAW,cAAc,YAAY,GAAG;AAO9C,SAAS,cAAsB;AAC7B,SAAO,QAAQ,SAAS,QAAQ,2BAA2B,CAAC;AAC9D;AAFS;AAKF,IAAM,cAAsB,KAAK,YAAY,GAAG,uBAAuB;AAoBvE,IAAM,kBAA0B,KAAK,YAAY,GAAG,UAAU;AAmB9D,IAAM,WAAmB,KAAK,YAAY,GAAG,wBAAwB;","names":[]}

package/dist/e2e/steps/journey.steps.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/e2e/steps/journey.steps.js

@@ -0,0 +1,79 @@
+import {
+  mcpConnectWorld
+} from "../../chunk-F3LMK6OL.js";
+import {
+  __name
+} from "../../chunk-7QVYU63E.js";
+
+// src/e2e/steps/journey.steps.ts
+import { expect } from "@playwright/test";
+import { createBdd } from "playwright-bdd";
+var { Given, When, Then } = createBdd();
+Given("I am signed in as somebody who may connect an assistant", async ({ page }) => {
+  await mcpConnectWorld().signInAsOwner(page);
+});
+When("I open the AI integration screen", async ({ page }) => {
+  await mcpConnectWorld().openAiIntegrationScreen(page);
+  await expect(page.getByTestId("ai-onboarding")).toBeVisible();
+});
+Then("the landing explains the permission model before anything is connected", async ({ page }) => {
+  await expect(page.getByTestId("ai-landing")).toBeVisible();
+  await expect(page.getByTestId("ai-permission-callout")).toBeVisible();
+});
+Then("it shows examples of what an assistant can be asked", async ({ page }) => {
+  await expect(page.getByTestId("ai-capability-examples")).toBeVisible();
+});
+When("I start the walkthrough", async ({ page }) => {
+  await page.getByTestId("ai-landing-start").click();
+  await expect(page.getByTestId("ai-host-select")).toBeVisible();
+});
+When("I choose an assistant that has no one-click install", async ({ page }) => {
+  await page.getByTestId(`ai-host-card-${mcpConnectWorld().fixtures.manualHostId}`).click();
+});
+Then("I am asked to copy the store's endpoint", async ({ page }) => {
+  await expect(page.getByTestId("ai-copy-step")).toBeVisible();
+  await expect(page.getByTestId("mcp-endpoint-url")).toContainText(
+    mcpConnectWorld().fixtures.endpointUrl
+  );
+});
+async function copyEndpoint(page) {
+  await page.getByTestId("ai-copy-endpoint").click();
+}
+__name(copyEndpoint, "copyEndpoint");
+async function openConnectorPage(page) {
+  await page.getByTestId(`ai-host-link-${mcpConnectWorld().fixtures.manualHostId}`).click();
+}
+__name(openConnectorPage, "openConnectorPage");
+When("I copy the endpoint", async ({ page }) => {
+  await copyEndpoint(page);
+});
+Then("the walkthrough has moved on to configuring the connector", async ({ page }) => {
+  await expect(page.getByTestId("ai-configure-step")).toBeVisible();
+  await expect(page.getByTestId("ai-copy-step")).toHaveCount(0);
+});
+Then("continuing is refused until I open the connector page", async ({ page }) => {
+  await expect(page.getByTestId("ai-configure-next")).toBeDisabled();
+});
+Then("once opened, continuing reaches the connect step", async ({ page }) => {
+  await openConnectorPage(page);
+  await expect(page.getByTestId("ai-configure-next")).toBeEnabled();
+  await page.getByTestId("ai-configure-next").click();
+  await expect(page.getByTestId("ai-connect-step")).toBeVisible();
+});
+When("I go back a step", async ({ page }) => {
+  await page.getByTestId("ai-step-back").click();
+});
+When("I work through configuring and connecting", async ({ page }) => {
+  await openConnectorPage(page);
+  await page.getByTestId("ai-configure-next").click();
+  await expect(page.getByTestId("ai-connect-step")).toBeVisible();
+  await page.getByTestId("ai-connect-done").click();
+});
+Then("the confirmation is still waiting for the assistant", async ({ page }) => {
+  await expect(page.getByTestId("ai-confirm-waiting")).toBeVisible();
+  await expect(page.getByTestId("ai-confirm-connected")).toHaveCount(0);
+});
+Then("it offers to test the connection again", async ({ page }) => {
+  await expect(page.getByTestId("ai-confirm-retest")).toBeVisible();
+});
+//# sourceMappingURL=journey.steps.js.map

package/dist/e2e/steps/journey.steps.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../src/e2e/steps/journey.steps.ts"],"sourcesContent":["import { expect, type Page } from '@playwright/test';\nimport { createBdd } from 'playwright-bdd';\n\nimport { mcpConnectWorld } from '../world.js';\n\n/**\n * The packaged AI-connect journeys' step definitions.\n *\n * Every locator is a test id THIS package's own components render —\n * `ai-landing`, `ai-host-select`, `ai-copy-step`, `ai-configure-step`,\n * `ai-connect-step`, `ai-confirm-waiting`, `mcp-endpoint-url` — which is what\n * makes the scenarios portable: they mean the same thing in any app mounting\n * `AiIntegrationOnboarding`. Everything a host owns (sign-in, where the flow is\n * mounted, which assistants it offers) arrives through the world port.\n *\n * ## Why `package.json` declares this file under `sideEffects`\n *\n * Every Given/When/Then below runs at IMPORT time — registering a step is the\n * whole point of the module, and it exports nothing anybody imports by name. To\n * a bundler doing tree-shaking that reads as dead weight, and dropping it is\n * licensed: the result is a suite where bddgen reports the features compiled\n * and every scenario then fails on an undefined step.\n *\n * Not one step asserts a SENTENCE. The assistants' names, the button words and\n * the permission prose are REQUIRED host config (FUT-760) — this package ships\n * no assistant and no copy of its own — so a spec written against them could\n * only ever have run in one adopter.\n */\nconst { Given, When, Then } = createBdd();\n\nGiven('I am signed in as somebody who may connect an assistant', async ({ page }) => {\n  await mcpConnectWorld().signInAsOwner(page);\n});\n\nWhen('I open the AI integration screen', async ({ page }) => {\n  await mcpConnectWorld().openAiIntegrationScreen(page);\n  await expect(page.getByTestId('ai-onboarding')).toBeVisible();\n});\n\nThen('the landing explains the permission model before anything is connected', async ({ page }) => {\n  await expect(page.getByTestId('ai-landing')).toBeVisible();\n  // The callout is the point of the landing: an owner is about to hand a third\n  // party a key to their store, and this is the screen that says what the key\n  // opens. It renders BEFORE any assistant is chosen, which is the only moment\n  // the answer is still \"nothing\".\n  await expect(page.getByTestId('ai-permission-callout')).toBeVisible();\n});\n\nThen('it shows examples of what an assistant can be asked', async ({ page }) => {\n  await expect(page.getByTestId('ai-capability-examples')).toBeVisible();\n});\n\nWhen('I start the walkthrough', async ({ page }) => {\n  await page.getByTestId('ai-landing-start').click();\n  await expect(page.getByTestId('ai-host-select')).toBeVisible();\n});\n\nWhen('I choose an assistant that has no one-click install', async ({ page }) => {\n  // The flow BRANCHES on the guide's `pluginUrl`: with one it becomes\n  // Escolher → Instalar → Confirmar and there is no endpoint to copy at all.\n  // The host names a guide that takes the manual path, because which\n  // assistants exist is its configuration and not this package's.\n  await page.getByTestId(`ai-host-card-${mcpConnectWorld().fixtures.manualHostId}`).click();\n});\n\nThen(\"I am asked to copy the store's endpoint\", async ({ page }) => {\n  await expect(page.getByTestId('ai-copy-step')).toBeVisible();\n  await expect(page.getByTestId('mcp-endpoint-url')).toContainText(\n    mcpConnectWorld().fixtures.endpointUrl,\n  );\n});\n\n/** Copying is the ACTION that advances this step — there is no next button. */\nasync function copyEndpoint(page: Page): Promise<void> {\n  await page.getByTestId('ai-copy-endpoint').click();\n}\n\n/**\n * Open the assistant's connector page — the one action that unlocks \"next\".\n *\n * By its OWN id, not `getByRole('link')`: this control is a Button calling\n * `window.open`, and the only real `<a>` in the step is the DOCS link, which\n * deliberately does not unlock anything. A role query would have taken the\n * docs link and then failed on an assertion about the button.\n */\nasync function openConnectorPage(page: Page): Promise<void> {\n  await page.getByTestId(`ai-host-link-${mcpConnectWorld().fixtures.manualHostId}`).click();\n}\n\nWhen('I copy the endpoint', async ({ page }) => {\n  await copyEndpoint(page);\n});\n\nThen('the walkthrough has moved on to configuring the connector', async ({ page }) => {\n  // The claim is that COPYING advanced it. The copy step offers no \"next\", so\n  // reaching the configure step at all proves the copy handler drove the\n  // wizard rather than some button the operator happened to press.\n  await expect(page.getByTestId('ai-configure-step')).toBeVisible();\n  await expect(page.getByTestId('ai-copy-step')).toHaveCount(0);\n});\n\nThen('continuing is refused until I open the connector page', async ({ page }) => {\n  // The guard that stops an owner walking past the one step that does the\n  // actual work: the connector page has to be opened before \"next\" unlocks.\n  await expect(page.getByTestId('ai-configure-next')).toBeDisabled();\n});\n\nThen('once opened, continuing reaches the connect step', async ({ page }) => {\n  await openConnectorPage(page);\n  await expect(page.getByTestId('ai-configure-next')).toBeEnabled();\n  await page.getByTestId('ai-configure-next').click();\n  await expect(page.getByTestId('ai-connect-step')).toBeVisible();\n});\n\nWhen('I go back a step', async ({ page }) => {\n  await page.getByTestId('ai-step-back').click();\n});\n\nWhen('I work through configuring and connecting', async ({ page }) => {\n  await openConnectorPage(page);\n  await page.getByTestId('ai-configure-next').click();\n  await expect(page.getByTestId('ai-connect-step')).toBeVisible();\n  await page.getByTestId('ai-connect-done').click();\n});\n\nThen('the confirmation is still waiting for the assistant', async ({ page }) => {\n  // Waiting rather than connected, because nothing has actually connected: the\n  // wizard reaching its last step is not evidence of a live connection, and\n  // this is the step that refuses to claim otherwise.\n  await expect(page.getByTestId('ai-confirm-waiting')).toBeVisible();\n  await expect(page.getByTestId('ai-confirm-connected')).toHaveCount(0);\n});\n\nThen('it offers to test the connection again', async ({ page }) => {\n  await expect(page.getByTestId('ai-confirm-retest')).toBeVisible();\n});\n"],"mappings":"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","names":[]}

package/dist/{guide-KQNcXlMG.d.ts → guide-CrzdsdNf.d.ts}

@@ -147,4 +147,4 @@ interface AiConnectPromptCopy {
  */
 declare function aiConnectPrompt(spec: AiConnectPromptSpec, copy: AiConnectPromptCopy): string;
 
-export { type AiCapability as A, type AiConnectPromptCopy as a, type AiConnectPromptSpec as b, type AiHostBrand as c, type AiHostConfigureStage as d, type AiHostGuide as e, type AiHostLink as f, type AiProvider as g, aiConnectPrompt as h, type AiPermissionModel as i, providerForHostId as p };
+export { type AiConnectPromptSpec as A, type AiHostGuide as a, type AiCapability as b, type AiPermissionModel as c, type AiProvider as d, type AiConnectPromptCopy as e, type AiHostBrand as f, type AiHostConfigureStage as g, type AiHostLink as h, aiConnectPrompt as i, providerForHostId as p };

package/dist/hono/index.d.ts

@@ -1,5 +1,5 @@
 import { Hono } from 'hono';
-import { A as ApiMcpOauth, M as McpOauthConfig } from '../create-api-mcp-oauth-CsC0jlH7.js';
+import { A as ApiMcpOauth, M as McpOauthConfig } from '../create-api-mcp-oauth-BEvYLRBV.js';
 import 'jose';
 
 /**

package/dist/hono/index.js

@@ -1,6 +1,6 @@
 import {
   createApiMcpOauth
-} from "../chunk-UIILEGAC.js";
+} from "../chunk-WCZC4TPX.js";
 import "../chunk-WJJNKKNS.js";
 import {
   __name

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { J as JsonSchema, a as ToolAnnotations, G as GeneratedTool, D as DispatchConfig, b as DispatchResult, R as RequestAuth, T as ToolManifest } from './generate-BCDqBUjZ.js';
 export { A as AuthResolver, c as GenerateOptions, O as OpenApiDocument, d as OpenApiOperation, e as OpenApiParameter, f as OpenApiRequestBody, g as OpenApiResponse, P as ParameterLocation, h as ToolParameter, i as generateTools } from './generate-BCDqBUjZ.js';
-export { A as AiCapability, a as AiConnectPromptCopy, b as AiConnectPromptSpec, c as AiHostBrand, d as AiHostConfigureStage, e as AiHostGuide, f as AiHostLink, g as AiProvider, h as aiConnectPrompt, p as providerForHostId } from './guide-KQNcXlMG.js';
+export { b as AiCapability, e as AiConnectPromptCopy, A as AiConnectPromptSpec, f as AiHostBrand, g as AiHostConfigureStage, a as AiHostGuide, h as AiHostLink, d as AiProvider, i as aiConnectPrompt, p as providerForHostId } from './guide-CrzdsdNf.js';
 import { z } from 'zod';
-export { A as AI_CAPABILITIES, a as AI_CONNECT_PROMPT, b as AI_HOST_GUIDES, c as AI_PERMISSION_MODEL, E as EN_US_AI_CAPABILITIES, d as EN_US_AI_CONNECT_PROMPT, e as EN_US_AI_HOST_GUIDES, f as EN_US_AI_PERMISSION_MODEL, P as PT_BR_AI_CAPABILITIES, g as PT_BR_AI_CONNECT_PROMPT, h as PT_BR_AI_HOST_GUIDES, i as PT_BR_AI_PERMISSION_MODEL } from './locales-eKE_OJw4.js';
+export { A as AI_CAPABILITIES, a as AI_CONNECT_PROMPT, b as AI_HOST_GUIDES, c as AI_PERMISSION_MODEL, E as EN_US_AI_CAPABILITIES, d as EN_US_AI_CONNECT_PROMPT, e as EN_US_AI_HOST_GUIDES, f as EN_US_AI_PERMISSION_MODEL, P as PT_BR_AI_CAPABILITIES, g as PT_BR_AI_CONNECT_PROMPT, h as PT_BR_AI_HOST_GUIDES, i as PT_BR_AI_PERMISSION_MODEL } from './locales-Cv0Pecvu.js';
 
 /**
  * Raised when a JSON Schema cannot be turned into a flat, self-contained tool
@@ -275,6 +275,93 @@ interface RegistryOptions {
 }
 declare function createToolRegistry(options: RegistryOptions): ToolRegistry;
 
+/**
+ * What an unauthorized MCP call is TOLD, as opposed to what it is refused with.
+ *
+ * ## The failure this module exists to remove
+ *
+ * A resource server has three RFC 6750 challenge codes and a boolean's worth of
+ * expressiveness, so every way a bearer can fail arrives at the agent as one
+ * opaque refusal. `Authentication required` is what a lapsed connection, a token
+ * minted for a different origin, a surface an operator never switched on, and a
+ * missing scope all look like — identical, and none of them actionable.
+ *
+ * The cost is not cosmetic. An agent that cannot tell those apart cannot tell the
+ * user anything useful either: every tool call fails, the connector still reports
+ * itself connected, and the one thing that would fix the common case — reconnect
+ * it — is the one thing nobody is told to do. Reported from a live deployment as
+ * "every tool call failing, even the ones that read nothing".
+ *
+ * ## The shape of the answer
+ *
+ * Each reason resolves to three things, and they are deliberately separate:
+ *
+ *   - `challenge` — the RFC 6750 code for the `WWW-Authenticate` header. Only
+ *     ever one of the two the spec defines for this situation, because a host's
+ *     OAuth machinery keys off it;
+ *   - `action` — what would actually fix it, for a client that automates;
+ *   - `message` — one sentence an agent can relay to a person. English, like
+ *     everything else a developer or a model reads here; a host that wants its
+ *     own wording supplies it.
+ *
+ * Nothing here narrows `unverified`. Signature, issuer and audience stay
+ * collapsed into one answer on purpose — see `../oauth/access-token.ts` for why
+ * expiry is the single documented exception.
+ */
+/** Why a call was refused, across both the transport and the token verifier. */
+type McpAuthFailureReason = 
+/** No `Authorization` header at all — the client has not connected yet. */
+"no_token"
+/** The token was fine until its `exp` passed. The common one, and recoverable. */
+ | "expired"
+/** Signature, issuer or audience did not hold. Deliberately not narrowed. */
+ | "unverified"
+/** Verified, but carrying no usable identity. */
+ | "incomplete"
+/** The operator has not provisioned signing material, so nothing can verify. */
+ | "not_provisioned"
+/** The whole MCP surface is switched off for this deployment. */
+ | "surface_disabled"
+/** A valid token that lacks the scope this particular call needs. */
+ | "insufficient_scope";
+/** What a client should do about it. */
+type McpAuthRecovery = 
+/** Exchange the refresh token for a new access token, then retry. */
+"refresh"
+/** Re-run the authorization flow — a human has to approve it again. */
+ | "reconnect"
+/** Nothing the client can do; the deployment has to change. */
+ | "contact_operator";
+/** The resolved answer for one refusal. */
+interface McpAuthFailure {
+    reason: McpAuthFailureReason;
+    /** The RFC 6750 code for the `WWW-Authenticate` challenge. */
+    challenge: "invalid_token" | "insufficient_scope";
+    action: McpAuthRecovery;
+    /** One sentence, written to be relayed to a person by an agent. */
+    message: string;
+}
+/** Resolve a reason to its challenge code, recovery and human-relayable message. */
+declare function describeAuthFailure(reason: McpAuthFailureReason): McpAuthFailure;
+/**
+ * The machine-readable half, carried in the JSON-RPC error's `data` member.
+ *
+ * A model reads `message`; a host that automates its connection lifecycle reads
+ * this. Both travel together so neither has to be inferred from the other.
+ */
+interface McpAuthFailureData {
+    reason: McpAuthFailureReason;
+    action: McpAuthRecovery;
+    /**
+     * Whether presenting a NEW token could succeed. `false` means the deployment
+     * itself is the problem, so a client that retries forever is wasting its time
+     * and the user's — and should say so rather than loop.
+     */
+    recoverable: boolean;
+}
+/** Build the `data` payload for a refusal. */
+declare function authFailureData(failure: McpAuthFailure): McpAuthFailureData;
+
 /**
  * The MCP JSON-RPC 2.0 request half of the Streamable HTTP transport.
  *
@@ -312,9 +399,15 @@ interface JsonRpcResponse {
     jsonrpc: "2.0";
     id: string | number | null;
     result?: unknown;
+    /**
+     * `data` is the JSON-RPC 2.0 optional member, and it is what carries the
+     * machine-readable half of a refusal ({@link McpAuthFailureData}) while
+     * `message` carries the half a model relays to a person.
+     */
     error?: {
         code: number;
         message: string;
+        data?: unknown;
     };
 }
 /** What a client is told it connected to, in `initialize`'s `serverInfo`. */
@@ -355,8 +448,13 @@ interface McpJsonRpcOptions {
  * `tools/call` then returns {@link UNAUTHORIZED_CODE}, which the host surfaces as
  * HTTP 401. Discovery (`initialize`, `ping`, `tools/list`) stays open, so a client
  * can read the surface before it has a token.
+ *
+ * `failure` is WHY `auth` is null, which only the host's verifier knows. It is
+ * optional so an existing caller keeps compiling, and passing it is what turns a
+ * refusal an agent can only report into one it can act on — see
+ * `./auth-failure.ts`.
  */
-declare function handleMcpJsonRpc(request: JsonRpcRequest, registry: ToolRegistry, auth: RequestAuth | null, options: McpJsonRpcOptions): Promise<JsonRpcResponse | null>;
+declare function handleMcpJsonRpc(request: JsonRpcRequest, registry: ToolRegistry, auth: RequestAuth | null, options: McpJsonRpcOptions, failure?: McpAuthFailureReason): Promise<JsonRpcResponse | null>;
 
 /**
  * The manifest is the committed source-of-truth artifact the CI drift gate
@@ -561,4 +659,4 @@ interface AuthorizationServerMetadata {
  */
 declare function buildAuthorizationServerMetadata(input: AuthorizationServerMetadataInput): AuthorizationServerMetadata;
 
-export { type AuthorizationServerMetadata, type AuthorizationServerMetadataInput, type AuthorizationServerPaths, type BuildManifestOptions, DispatchConfig, DispatchInputError, DispatchResult, GeneratedTool, HTTP_STATUS_META_KEY, type HttpMethod, type JsonRpcRequest, type JsonRpcResponse, JsonSchema, MCP_PROTOCOL_VERSION, type McpAnnotationDefaults, type McpEndpoint, type McpJsonRpcOptions, type McpServerInfo, type McpToolDescriptor, type McpToolResult, PROTECTED_RESOURCE_METADATA_PATH, type ProtectedResourceMetadata, type ProtectedResourceMetadataInput, type RegistryOptions, RequestAuth, type SurfaceLock, type SurfaceLockCheck, type ToolAnnotationOverrides, ToolAnnotations, ToolManifest, type ToolRegistry, UNAUTHORIZED_CODE, UnsupportedSchemaError, bearerChallenge, buildAuthorizationServerMetadata, buildManifest, buildProtectedResourceMetadata, createToolRegistry, dispatchTool, handleMcpJsonRpc, inlineSchemaRefs, redactResponseBody, redactResponseSchema, resolveToolAnnotations, serializeManifest, serializeSurfaceLock, surfaceDigest, surfaceLockProblem };
+export { type AuthorizationServerMetadata, type AuthorizationServerMetadataInput, type AuthorizationServerPaths, type BuildManifestOptions, DispatchConfig, DispatchInputError, DispatchResult, GeneratedTool, HTTP_STATUS_META_KEY, type HttpMethod, type JsonRpcRequest, type JsonRpcResponse, JsonSchema, MCP_PROTOCOL_VERSION, type McpAnnotationDefaults, type McpAuthFailure, type McpAuthFailureData, type McpAuthFailureReason, type McpAuthRecovery, type McpEndpoint, type McpJsonRpcOptions, type McpServerInfo, type McpToolDescriptor, type McpToolResult, PROTECTED_RESOURCE_METADATA_PATH, type ProtectedResourceMetadata, type ProtectedResourceMetadataInput, type RegistryOptions, RequestAuth, type SurfaceLock, type SurfaceLockCheck, type ToolAnnotationOverrides, ToolAnnotations, ToolManifest, type ToolRegistry, UNAUTHORIZED_CODE, UnsupportedSchemaError, authFailureData, bearerChallenge, buildAuthorizationServerMetadata, buildManifest, buildProtectedResourceMetadata, createToolRegistry, describeAuthFailure, dispatchTool, handleMcpJsonRpc, inlineSchemaRefs, redactResponseBody, redactResponseSchema, resolveToolAnnotations, serializeManifest, serializeSurfaceLock, surfaceDigest, surfaceLockProblem };

package/dist/index.js

@@ -338,6 +338,57 @@ function createToolRegistry(options) {
 }
 __name(createToolRegistry, "createToolRegistry");
 
+// src/server/auth-failure.ts
+var FAILURES = {
+  no_token: {
+    challenge: "invalid_token",
+    action: "reconnect",
+    message: "This request carried no access token. Ask the user to connect this MCP server in their assistant's connector settings, then retry."
+  },
+  expired: {
+    challenge: "invalid_token",
+    action: "refresh",
+    message: "The access token has expired. A client that holds a refresh token should renew it and retry; if renewal also fails, ask the user to reconnect this MCP server in their assistant's connector settings."
+  },
+  unverified: {
+    challenge: "invalid_token",
+    action: "reconnect",
+    message: "The access token could not be verified for this server. Ask the user to reconnect this MCP server in their assistant's connector settings \u2014 a token issued for a different deployment will never verify here."
+  },
+  incomplete: {
+    challenge: "invalid_token",
+    action: "reconnect",
+    message: "The access token verified but carries no usable identity. Ask the user to reconnect this MCP server in their assistant's connector settings."
+  },
+  not_provisioned: {
+    challenge: "invalid_token",
+    action: "contact_operator",
+    message: "This server has no signing key provisioned, so no access token can be verified. Reconnecting will not help; the deployment's operator has to configure it."
+  },
+  surface_disabled: {
+    challenge: "invalid_token",
+    action: "contact_operator",
+    message: "The MCP surface is switched off on this deployment. Reconnecting will not help; the deployment's operator has to enable it."
+  },
+  insufficient_scope: {
+    challenge: "insufficient_scope",
+    action: "reconnect",
+    message: "The access token does not grant the scope this tool needs. Ask the user to reconnect this MCP server and approve the wider scope."
+  }
+};
+function describeAuthFailure(reason) {
+  return { reason, ...FAILURES[reason] };
+}
+__name(describeAuthFailure, "describeAuthFailure");
+function authFailureData(failure) {
+  return {
+    reason: failure.reason,
+    action: failure.action,
+    recoverable: failure.action !== "contact_operator"
+  };
+}
+__name(authFailureData, "authFailureData");
+
 // src/server/jsonrpc.ts
 var MCP_PROTOCOL_VERSION = "2025-06-18";
 var UNAUTHORIZED_CODE = -32001;
@@ -348,16 +399,28 @@ function ok(id, result) {
   return { jsonrpc: "2.0", id: id ?? null, result };
 }
 __name(ok, "ok");
-function fail(id, code, message) {
-  return { jsonrpc: "2.0", id: id ?? null, error: { code, message } };
+function fail(id, code, message, data) {
+  return {
+    jsonrpc: "2.0",
+    id: id ?? null,
+    error: { code, message, ...data === void 0 ? {} : { data } }
+  };
 }
 __name(fail, "fail");
 function isWellFormed(request) {
   return request != null && typeof request === "object" && typeof request.method === "string";
 }
 __name(isWellFormed, "isWellFormed");
-async function handleToolsCall(request, registry, auth) {
-  if (!auth) return fail(request.id, UNAUTHORIZED_CODE, "Authentication required");
+async function handleToolsCall(request, registry, auth, failure) {
+  if (!auth) {
+    const described = describeAuthFailure(failure ?? "no_token");
+    return fail(
+      request.id,
+      UNAUTHORIZED_CODE,
+      described.message,
+      authFailureData(described)
+    );
+  }
   const params = request.params ?? {};
   if (!params.name) return fail(request.id, INVALID_PARAMS_CODE, "Missing tool name");
   const result = await registry.callTool(params.name, params.arguments ?? {}, auth);
@@ -376,7 +439,7 @@ function handleInitialize(request, options) {
   });
 }
 __name(handleInitialize, "handleInitialize");
-async function handleMcpJsonRpc(request, registry, auth, options) {
+async function handleMcpJsonRpc(request, registry, auth, options, failure) {
   if (!isWellFormed(request)) {
     return fail(request?.id ?? null, INVALID_REQUEST_CODE, "Invalid Request");
   }
@@ -388,7 +451,7 @@ async function handleMcpJsonRpc(request, registry, auth, options) {
     case "tools/list":
       return ok(request.id, { tools: registry.listTools(auth ?? void 0) });
     case "tools/call":
-      return handleToolsCall(request, registry, auth);
+      return handleToolsCall(request, registry, auth, failure);
     default:
       if (request.method.startsWith("notifications/")) return null;
       return fail(request.id, METHOD_NOT_FOUND_CODE, `Method not found: ${request.method}`);
@@ -415,11 +478,13 @@ export {
   UNAUTHORIZED_CODE,
   UnsupportedSchemaError,
   aiConnectPrompt,
+  authFailureData,
   bearerChallenge,
   buildAuthorizationServerMetadata,
   buildManifest,
   buildProtectedResourceMetadata,
   createToolRegistry,
+  describeAuthFailure,
   dispatchTool,
   generateTools,
   handleMcpJsonRpc,