@frihet/mcp-server 1.16.6 → 2.0.0

package/dist/openai-review-oauth.d.ts

@@ -3,6 +3,47 @@
  * freeze gate. Values in this module are public protocol metadata, not secrets.
  */
 export declare const OPENAI_REVIEW_ORIGIN = "https://openai-mcp.frihet.io";
+export declare const FULL_MCP_ORIGIN = "https://mcp.frihet.io";
+export declare const FRIHET_CONNECTOR_SCOPE = "frihet:workspace.manage";
+export declare const OPENAI_REVIEW_OAUTH_SCOPES: readonly string[];
+/**
+ * RFC 8707 resource identifier of the reviewed MCP endpoint. Claude's
+ * connector guide requires protected-resource metadata to name the connector
+ * URL a user enters, including its path; OpenAI documents that ChatGPT takes
+ * the `resource` value it sends from that metadata.
+ */
+export declare const OPENAI_REVIEW_MCP_RESOURCE = "https://openai-mcp.frihet.io/mcp";
+/** RFC 9728 section 3.1 path-inserted location of the metadata for
+ * OPENAI_REVIEW_MCP_RESOURCE. The 401 challenge points here. */
+export declare const OPENAI_REVIEW_MCP_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource/mcp";
+/**
+ * The only RFC 8707 resource values the reviewed authorization boundary
+ * accepts. The canonical MCP URL comes first; the bare origin is the value the
+ * root metadata document still publishes (and the only one it published before
+ * the path-inserted document existed), so clients using it keep working. Both
+ * name this Worker only: the pinned provider matches a token audience by exact
+ * origin plus path prefix, so neither value can authorize the full host.
+ * The runtime checks that use this set are validateOAuthBoundary (below) and
+ * the /token rotation guard in workers/remote-mcp/src/oauth-token-family.ts.
+ * The inventory test in workers/remote-mcp/src/__tests__/openai-review-oauth.test.ts
+ * lists every runtime line that reads a field named `resource` or `audience`
+ * (dot access, string-literal bracket access, or single-line destructuring)
+ * and fails on any new such line, whatever it compares or calls. It does not
+ * follow a value after it is copied into another variable, multi-line
+ * destructuring, or computed property names.
+ * Grant props keep `oauthResource: OPENAI_REVIEW_ORIGIN` as the host-binding
+ * identity checked at session init and API-key provisioning; that field is not
+ * the RFC 8707 value, which the provider stores on the grant itself.
+ */
+export declare const OPENAI_REVIEW_OAUTH_RESOURCES: readonly string[];
+/** RFC 7636 S256 challenges are the 32-byte SHA-256 digest encoded as
+ * unpadded base64url, which is always exactly 43 characters. */
+export declare function isValidS256CodeChallenge(value: string): boolean;
+/** RFC 7636 code_verifier ABNF: 43–128 unreserved URI characters. */
+export declare function isValidPKCECodeVerifier(value: string): boolean;
+export type FrihetAccessProfile = "openai" | "full";
+/** Fail closed if a Worker deploy omits or mistypes its profile binding. */
+export declare function resolveFrihetAccessProfile(value: string | undefined): FrihetAccessProfile;
 /**
  * Byte-compatible extraction of the options previously inlined in the Worker.
  * index.ts spreads this object into the real OAuthProvider constructor.
@@ -16,11 +57,60 @@ export declare const OAUTH_PROVIDER_REVIEW_OPTIONS: {
     accessTokenTTL: number;
     refreshTokenTTL: number;
     allowPlainPKCE: false;
+    resourceMetadata: {
+        resource: string;
+        authorization_servers: string[];
+        scopes_supported: string[];
+        bearer_methods_supported: string[];
+        resource_name: string;
+    };
+};
+export type OAuthBoundaryError = "invalid_target" | "invalid_scope";
+export type OAuthBoundaryResult = {
+    ok: true;
+} | {
+    ok: false;
+    error: OAuthBoundaryError;
+    description: string;
+};
+interface OAuthBoundaryParameters {
+    resource?: string | string[];
+    scope?: string | string[];
+    /** The authorization request creates the grant and must carry the canonical
+     * resource. Later token/refresh requests may omit it because the provider
+     * inherits the already-validated value stored on that grant. */
+    requireResource: boolean;
+    /** Authorization requests must include the advertised scope. Token refresh
+     * requests may omit it because the provider reuses the validated grant. */
+    requireScope: boolean;
+}
+export declare function hasExactOpenAIReviewScopes(value: unknown): value is string[];
+/**
+ * Validate the two OAuth values that form the reviewed-host authorization
+ * boundary. RFC 8707 resource comparison is exact string membership by design:
+ * accepting an arbitrary absolute URI would let a token minted by one Frihet
+ * Worker target the other Worker. Unknown or empty scopes are rejected instead
+ * of silently downscoping to an empty token.
+ */
+export declare function validateOAuthBoundary(parameters: OAuthBoundaryParameters, acceptedResources: readonly string[]): OAuthBoundaryResult;
+export declare function buildOpenAIUnauthorizedChallenge(origin?: string): string;
+/**
+ * Path-inserted protected-resource metadata for the reviewed MCP endpoint,
+ * served by the Worker itself (the pinned provider only serves the root
+ * document). It differs from the root document only in `resource`.
+ */
+export declare function buildReviewedMcpProtectedResourceMetadata(origin?: string): {
+    resource: string;
+    authorization_servers: string[];
+    scopes_supported: string[];
+    bearer_methods_supported: string[];
+    resource_name: string;
 };
 /**
  * Materialize the public metadata generated by workers-oauth-provider 0.3.0
- * from the same options used by the Worker. The dependency version is pinned
- * separately in the canonical descriptor snapshot.
+ * from the same options used by the Worker, plus the path-inserted document
+ * the Worker serves itself. The dependency version is pinned separately in
+ * the canonical descriptor snapshot.
  */
 export declare function buildOpenAIReviewOAuthContract(origin?: string): {
     authorizationServer: {
@@ -42,10 +132,67 @@ export declare function buildOpenAIReviewOAuthContract(origin?: string): {
         authorization_servers: string[];
         scopes_supported: string[];
         bearer_methods_supported: string[];
+        resource_name: string;
+    };
+    protectedResourceMcp: {
+        resource: string;
+        authorization_servers: string[];
+        scopes_supported: string[];
+        bearer_methods_supported: string[];
+        resource_name: string;
+    };
+    openidConfiguration: {
+        issuer: string;
+        authorization_endpoint: string;
+        token_endpoint: string;
+        userinfo_endpoint: string;
+        registration_endpoint: string;
+        scopes_supported: string[];
+        response_types_supported: string[];
+        response_modes_supported: string[];
+        grant_types_supported: string[];
+        subject_types_supported: string[];
+        token_endpoint_auth_methods_supported: string[];
+        code_challenge_methods_supported: string[];
     };
     wwwAuthenticate: {
         resourceMetadataUrl: string;
         missingTokenHeader: string;
     };
 };
+interface ReviewedAccessTokenSummary {
+    userId?: unknown;
+    expiresAt?: unknown;
+    audience?: unknown;
+    scope?: unknown;
+    grant?: {
+        scope?: unknown;
+        props?: unknown;
+    };
+}
+export declare function isVerifiedOpenAIIdentity(value: {
+    uid?: unknown;
+    email?: unknown;
+    emailVerified?: unknown;
+}): value is {
+    uid: string;
+    email: string;
+    emailVerified: true;
+};
+export type OpenAIUserInfo = {
+    sub: string;
+    email: string;
+    email_verified: true;
+};
+/**
+ * Validate the provider's opaque access-token summary before serving OIDC
+ * UserInfo. The provider already verifies the encrypted token and KV expiry;
+ * this second boundary deliberately rechecks every OpenAI-specific binding.
+ */
+export declare function buildOpenAIUserInfo(token: ReviewedAccessTokenSummary | null, nowEpochSeconds?: number, boundary?: Readonly<{
+    accessProfile: "openai" | "claude";
+    origin: string;
+    acceptedResources: readonly string[];
+}>): OpenAIUserInfo | undefined;
+export {};
 //# sourceMappingURL=openai-review-oauth.d.ts.map

package/dist/openai-review-oauth.js

@@ -3,6 +3,63 @@
  * freeze gate. Values in this module are public protocol metadata, not secrets.
  */
 export const OPENAI_REVIEW_ORIGIN = "https://openai-mcp.frihet.io";
+export const FULL_MCP_ORIGIN = "https://mcp.frihet.io";
+export const FRIHET_CONNECTOR_SCOPE = "frihet:workspace.manage";
+export const OPENAI_REVIEW_OAUTH_SCOPES = Object.freeze([
+    "openid",
+    "email",
+    FRIHET_CONNECTOR_SCOPE,
+]);
+/**
+ * RFC 8707 resource identifier of the reviewed MCP endpoint. Claude's
+ * connector guide requires protected-resource metadata to name the connector
+ * URL a user enters, including its path; OpenAI documents that ChatGPT takes
+ * the `resource` value it sends from that metadata.
+ */
+export const OPENAI_REVIEW_MCP_RESOURCE = `${OPENAI_REVIEW_ORIGIN}/mcp`;
+/** RFC 9728 section 3.1 path-inserted location of the metadata for
+ * OPENAI_REVIEW_MCP_RESOURCE. The 401 challenge points here. */
+export const OPENAI_REVIEW_MCP_RESOURCE_METADATA_PATH = "/.well-known/oauth-protected-resource/mcp";
+/**
+ * The only RFC 8707 resource values the reviewed authorization boundary
+ * accepts. The canonical MCP URL comes first; the bare origin is the value the
+ * root metadata document still publishes (and the only one it published before
+ * the path-inserted document existed), so clients using it keep working. Both
+ * name this Worker only: the pinned provider matches a token audience by exact
+ * origin plus path prefix, so neither value can authorize the full host.
+ * The runtime checks that use this set are validateOAuthBoundary (below) and
+ * the /token rotation guard in workers/remote-mcp/src/oauth-token-family.ts.
+ * The inventory test in workers/remote-mcp/src/__tests__/openai-review-oauth.test.ts
+ * lists every runtime line that reads a field named `resource` or `audience`
+ * (dot access, string-literal bracket access, or single-line destructuring)
+ * and fails on any new such line, whatever it compares or calls. It does not
+ * follow a value after it is copied into another variable, multi-line
+ * destructuring, or computed property names.
+ * Grant props keep `oauthResource: OPENAI_REVIEW_ORIGIN` as the host-binding
+ * identity checked at session init and API-key provisioning; that field is not
+ * the RFC 8707 value, which the provider stores on the grant itself.
+ */
+export const OPENAI_REVIEW_OAUTH_RESOURCES = Object.freeze([
+    OPENAI_REVIEW_MCP_RESOURCE,
+    OPENAI_REVIEW_ORIGIN,
+]);
+/** RFC 7636 S256 challenges are the 32-byte SHA-256 digest encoded as
+ * unpadded base64url, which is always exactly 43 characters. */
+export function isValidS256CodeChallenge(value) {
+    return /^[A-Za-z0-9_-]{43}$/u.test(value);
+}
+/** RFC 7636 code_verifier ABNF: 43–128 unreserved URI characters. */
+export function isValidPKCECodeVerifier(value) {
+    return /^[A-Za-z0-9._~-]{43,128}$/u.test(value);
+}
+/** Fail closed if a Worker deploy omits or mistypes its profile binding. */
+export function resolveFrihetAccessProfile(value) {
+    if (value === "true")
+        return "openai";
+    if (value === "false")
+        return "full";
+    throw new Error("FRIHET_OPENAI_MODE must be explicitly set to true or false");
+}
 /**
  * Byte-compatible extraction of the options previously inlined in the Worker.
  * index.ts spreads this object into the real OAuthProvider constructor.
@@ -12,25 +69,101 @@ export const OAUTH_PROVIDER_REVIEW_OPTIONS = {
     authorizeEndpoint: "/authorize",
     tokenEndpoint: "/token",
     clientRegistrationEndpoint: "/register",
-    scopesSupported: ["read", "write"],
+    // This provider does not implement per-tool OAuth authorization. Advertise
+    // one honest connector-wide scope instead of implying that `read` prevents
+    // writes. Where a profile requires confirm=true, that is a client interlock,
+    // not an authorization boundary.
+    scopesSupported: [...OPENAI_REVIEW_OAUTH_SCOPES],
     accessTokenTTL: 3600,
     refreshTokenTTL: 2592000,
     allowPlainPKCE: false,
+    resourceMetadata: {
+        resource: OPENAI_REVIEW_ORIGIN,
+        authorization_servers: [OPENAI_REVIEW_ORIGIN],
+        scopes_supported: [...OPENAI_REVIEW_OAUTH_SCOPES],
+        bearer_methods_supported: ["header"],
+        resource_name: "Frihet reviewed connector",
+    },
 };
+export function hasExactOpenAIReviewScopes(value) {
+    if (!Array.isArray(value) || value.length !== OPENAI_REVIEW_OAUTH_SCOPES.length) {
+        return false;
+    }
+    const scopes = new Set(value);
+    return scopes.size === OPENAI_REVIEW_OAUTH_SCOPES.length
+        && OPENAI_REVIEW_OAUTH_SCOPES.every((scope) => scopes.has(scope));
+}
+/**
+ * Validate the two OAuth values that form the reviewed-host authorization
+ * boundary. RFC 8707 resource comparison is exact string membership by design:
+ * accepting an arbitrary absolute URI would let a token minted by one Frihet
+ * Worker target the other Worker. Unknown or empty scopes are rejected instead
+ * of silently downscoping to an empty token.
+ */
+export function validateOAuthBoundary(parameters, acceptedResources) {
+    if (parameters.resource === undefined && !parameters.requireResource) {
+        // The provider will inherit the exact resource stored on the grant.
+    }
+    else if (typeof parameters.resource !== "string"
+        || !acceptedResources.includes(parameters.resource)) {
+        return {
+            ok: false,
+            error: "invalid_target",
+            description: "The OAuth resource must exactly match this Frihet MCP server.",
+        };
+    }
+    if (parameters.scope === undefined && !parameters.requireScope)
+        return { ok: true };
+    const scopes = Array.isArray(parameters.scope)
+        ? parameters.scope
+        : typeof parameters.scope === "string"
+            ? parameters.scope.split(/\s+/u).filter(Boolean)
+            : [];
+    if (!hasExactOpenAIReviewScopes(scopes)) {
+        return {
+            ok: false,
+            error: "invalid_scope",
+            description: `The required OAuth scopes are ${OPENAI_REVIEW_OAUTH_SCOPES.join(" ")}.`,
+        };
+    }
+    return { ok: true };
+}
 function endpoint(origin, path) {
     return new URL(path, new URL(origin).origin).toString();
 }
+export function buildOpenAIUnauthorizedChallenge(origin = OPENAI_REVIEW_ORIGIN) {
+    const resourceMetadataUrl = endpoint(new URL(origin).origin, OPENAI_REVIEW_MCP_RESOURCE_METADATA_PATH);
+    return `Bearer realm="OAuth", resource_metadata="${resourceMetadataUrl}", ` +
+        `scope="${OPENAI_REVIEW_OAUTH_SCOPES.join(" ")}", error="invalid_token", ` +
+        'error_description="Missing or invalid access token"';
+}
+/**
+ * Path-inserted protected-resource metadata for the reviewed MCP endpoint,
+ * served by the Worker itself (the pinned provider only serves the root
+ * document). It differs from the root document only in `resource`.
+ */
+export function buildReviewedMcpProtectedResourceMetadata(origin = OPENAI_REVIEW_ORIGIN) {
+    const normalizedOrigin = new URL(origin).origin;
+    return {
+        resource: endpoint(normalizedOrigin, OAUTH_PROVIDER_REVIEW_OPTIONS.apiRoute),
+        authorization_servers: [normalizedOrigin],
+        scopes_supported: [...OAUTH_PROVIDER_REVIEW_OPTIONS.scopesSupported],
+        bearer_methods_supported: ["header"],
+        resource_name: OAUTH_PROVIDER_REVIEW_OPTIONS.resourceMetadata.resource_name,
+    };
+}
 /**
  * Materialize the public metadata generated by workers-oauth-provider 0.3.0
- * from the same options used by the Worker. The dependency version is pinned
- * separately in the canonical descriptor snapshot.
+ * from the same options used by the Worker, plus the path-inserted document
+ * the Worker serves itself. The dependency version is pinned separately in
+ * the canonical descriptor snapshot.
  */
 export function buildOpenAIReviewOAuthContract(origin = OPENAI_REVIEW_ORIGIN) {
     const normalizedOrigin = new URL(origin).origin;
     const authorizationEndpoint = endpoint(normalizedOrigin, OAUTH_PROVIDER_REVIEW_OPTIONS.authorizeEndpoint);
     const tokenEndpoint = endpoint(normalizedOrigin, OAUTH_PROVIDER_REVIEW_OPTIONS.tokenEndpoint);
     const registrationEndpoint = endpoint(normalizedOrigin, OAUTH_PROVIDER_REVIEW_OPTIONS.clientRegistrationEndpoint);
-    const resourceMetadataUrl = endpoint(normalizedOrigin, "/.well-known/oauth-protected-resource");
+    const resourceMetadataUrl = endpoint(normalizedOrigin, OPENAI_REVIEW_MCP_RESOURCE_METADATA_PATH);
     return {
         authorizationServer: {
             issuer: normalizedOrigin,
@@ -55,12 +188,93 @@ export function buildOpenAIReviewOAuthContract(origin = OPENAI_REVIEW_ORIGIN) {
             authorization_servers: [normalizedOrigin],
             scopes_supported: [...OAUTH_PROVIDER_REVIEW_OPTIONS.scopesSupported],
             bearer_methods_supported: ["header"],
+            resource_name: OAUTH_PROVIDER_REVIEW_OPTIONS.resourceMetadata.resource_name,
+        },
+        protectedResourceMcp: buildReviewedMcpProtectedResourceMetadata(normalizedOrigin),
+        openidConfiguration: {
+            issuer: normalizedOrigin,
+            authorization_endpoint: authorizationEndpoint,
+            token_endpoint: tokenEndpoint,
+            userinfo_endpoint: endpoint(normalizedOrigin, "/userinfo"),
+            registration_endpoint: registrationEndpoint,
+            scopes_supported: [...OPENAI_REVIEW_OAUTH_SCOPES],
+            response_types_supported: ["code"],
+            response_modes_supported: ["query"],
+            grant_types_supported: ["authorization_code", "refresh_token"],
+            subject_types_supported: ["public"],
+            token_endpoint_auth_methods_supported: [
+                "client_secret_basic",
+                "client_secret_post",
+                "none",
+            ],
+            code_challenge_methods_supported: ["S256"],
         },
         wwwAuthenticate: {
             resourceMetadataUrl,
-            missingTokenHeader: `Bearer realm="OAuth", resource_metadata="${resourceMetadataUrl}", ` +
-                'error="invalid_token", error_description="Missing or invalid access token"',
+            missingTokenHeader: buildOpenAIUnauthorizedChallenge(normalizedOrigin),
         },
     };
 }
+function isRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function isVerifiedEmail(email, verified) {
+    return verified === true
+        && typeof email === "string"
+        && email.length >= 3
+        && email.length <= 320
+        && email === email.trim()
+        && !/[\u0000-\u001f\u007f]/u.test(email)
+        && /^[^@\s]+@[^@\s]+$/u.test(email);
+}
+export function isVerifiedOpenAIIdentity(value) {
+    return typeof value.uid === "string"
+        && value.uid.length > 0
+        && value.uid.length <= 128
+        && isVerifiedEmail(value.email, value.emailVerified);
+}
+/**
+ * Validate the provider's opaque access-token summary before serving OIDC
+ * UserInfo. The provider already verifies the encrypted token and KV expiry;
+ * this second boundary deliberately rechecks every OpenAI-specific binding.
+ */
+export function buildOpenAIUserInfo(token, nowEpochSeconds = Math.floor(Date.now() / 1000), boundary = {
+    accessProfile: "openai",
+    origin: OPENAI_REVIEW_ORIGIN,
+    acceptedResources: OPENAI_REVIEW_OAUTH_RESOURCES,
+}) {
+    const audience = token?.audience;
+    if (!token
+        || !Number.isSafeInteger(token.expiresAt)
+        || token.expiresAt <= nowEpochSeconds
+        || typeof audience !== "string"
+        || !boundary.acceptedResources.includes(audience)
+        || !hasExactOpenAIReviewScopes(token.scope)
+        || !hasExactOpenAIReviewScopes(token.grant?.scope)
+        || !isRecord(token.grant?.props)) {
+        return undefined;
+    }
+    const props = token.grant.props;
+    const identity = {
+        uid: props.userId,
+        email: props.email,
+        emailVerified: props.emailVerified,
+    };
+    if (props.accessProfile !== boundary.accessProfile
+        || props.authMethod !== "oauth"
+        || props.oauthIssuer !== boundary.origin
+        || props.oauthResource !== boundary.origin
+        || props.oauthAudience !== audience
+        || props.oauthScope !== FRIHET_CONNECTOR_SCOPE
+        || !hasExactOpenAIReviewScopes(props.oauthScopes)
+        || token.userId !== props.userId
+        || !isVerifiedOpenAIIdentity(identity)) {
+        return undefined;
+    }
+    return {
+        sub: identity.uid,
+        email: identity.email,
+        email_verified: true,
+    };
+}
 //# sourceMappingURL=openai-review-oauth.js.map

package/dist/prompts/register-all.d.ts

@@ -6,5 +6,7 @@
  * using the available Frihet tools to complete each action.
  */
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/** Exact prompt registrations below; runtime capture gates this value. */
+export declare const MCP_PROMPT_COUNT = 10;
 export declare function registerAllPrompts(server: McpServer): void;
 //# sourceMappingURL=register-all.d.ts.map

package/dist/prompts/register-all.js

@@ -6,6 +6,8 @@
  * using the available Frihet tools to complete each action.
  */
 import { z } from "zod/v4";
+/** Exact prompt registrations below; runtime capture gates this value. */
+export const MCP_PROMPT_COUNT = 10;
 export function registerAllPrompts(server) {
     // -- monthly-close --
     server.registerPrompt("monthly-close", {
@@ -184,34 +186,21 @@ export function registerAllPrompts(server) {
                 role: "user",
                 content: {
                     type: "text",
-                    text: `Help me follow up on overdue invoices.\n\n` +
-                        `Follow these steps:\n\n` +
-                        `1. FIND OVERDUE INVOICES\n` +
-                        `   - Use list_invoices to find all invoices with status "overdue" or "sent" past their due date\n` +
-                        `   - For each, note: invoice ID, client name, amount, due date, days overdue\n` +
-                        `   - Sort by days overdue (most overdue first)\n\n` +
-                        `2. GROUP BY CLIENT\n` +
-                        `   - Group overdue invoices by client\n` +
-                        `   - Calculate total outstanding per client\n` +
-                        `   - Use get_client to get contact details for each client\n\n` +
-                        `3. DRAFT FOLLOW-UP MESSAGES\n` +
-                        `   For each client, draft a professional payment reminder:\n` +
-                        `   - Tone: Firm but polite. Maintain the business relationship.\n` +
-                        `   - Include: Invoice number(s), amount(s), original due date(s)\n` +
-                        `   - 1-15 days overdue: Friendly reminder, assume it was overlooked\n` +
-                        `   - 16-30 days overdue: Firmer tone, request confirmation of payment date\n` +
-                        `   - 31-60 days overdue: Escalation notice, mention potential late fees\n` +
-                        `   - 60+ days overdue: Final notice, mention potential debt collection\n` +
-                        `   - Provide both English and Spanish versions\n\n` +
-                        `4. SUGGEST ACTIONS\n` +
-                        `   - Recommend which invoices to update to "overdue" status if still "sent"\n` +
-                        `   - Suggest setting up webhook notifications for future overdue invoices\n` +
-                        `   - Flag any clients with multiple overdue invoices (potential bad debt risk)\n\n` +
-                        `5. SUMMARY\n` +
-                        `   - Total overdue amount\n` +
-                        `   - Number of clients affected\n` +
-                        `   - Oldest unpaid invoice\n` +
-                        `   - Recommended priority order for follow-up`,
+                    text: `Help me prepare overdue invoice follow-ups for review.
+
+1. GATHER RECORDS
+   - Call list_invoices without a status filter (it has no partial status) and select sent, partial and overdue records client-side from each returned status. Paginate every result set using the returned pagination fields until exhausted; deduplicate by invoice ID. If a page fails or results are incomplete, disclose that limitation.
+   - Use get_invoice when detail is missing. Record invoice ID/number, client, currency, due date and remaining unpaid balance after recorded payments and credits. Do not count full invoice totals as outstanding for partially paid records. If balance cannot be verified, flag it as unknown instead of assuming it.
+   - Confirm the as-of date and workspace timezone. Separate not-yet-due and due-today invoices from overdue invoices. Missing or invalid due dates need review, not an invented age. Invoice status alone does not prove delivery.
+
+2. GROUP AND DRAFT
+   - Group verified positive overdue balances by client and currency; never sum different currencies or infer conversion rates. Show the source invoices, balances and days overdue.
+   - Use get_client to verify contact details. Draft a neutral, professional reminder in English and Spanish, listing invoice numbers, due dates, remaining balances and currencies. Do not assume why payment is late or that a debt is undisputed.
+
+3. USER REVIEW
+   - Present drafts, recipients and supporting records for user approval before any actions, including sending messages, changing records or setting reminders.
+   - Do not automatically impose late fees, write off balances, stop work, threaten collection, assign collectible probabilities or make business decisions based on age alone. Ask the user to review disputes and their agreed terms.
+   - Summarize overdue balances per currency, clients affected, oldest verified overdue invoice and any missing evidence. Keep not-yet-due balances separate.`,
                 },
             },
         ],
@@ -458,7 +447,7 @@ export function registerAllPrompts(server) {
     // -- invoice-aging-review --
     server.registerPrompt("invoice-aging-review", {
         title: "Invoice Aging Review",
-        description: "Accounts receivable aging analysis: group unpaid invoices by aging bucket (0-30, 31-60, 61-90, 90+ days), " +
+        description: "Accounts receivable aging analysis: separate not-yet-due balances from overdue buckets by currency, " +
             "identify top debtors, and suggest collection actions. " +
             "/ Análisis de antigüedad de cuentas por cobrar: agrupar facturas impagadas por tramos, " +
             "identificar mayores deudores y sugerir acciones de cobro.",
@@ -468,55 +457,22 @@ export function registerAllPrompts(server) {
                 role: "user",
                 content: {
                     type: "text",
-                    text: `Perform an accounts receivable aging analysis. Follow these steps:\n\n` +
-                        `1. GATHER UNPAID INVOICES\n` +
-                        `   - Use list_invoices to find all invoices with status "sent" or "overdue"\n` +
-                        `   - For each invoice, note: invoice ID/number, client name, amount (with tax),\n` +
-                        `     issue date, due date, and days since due date\n` +
-                        `   - If due date is in the future, calculate days until due (negative = not yet due)\n\n` +
-                        `2. AGING BUCKETS\n` +
-                        `   Group all unpaid invoices into these buckets:\n` +
-                        `   - CURRENT (0-30 days): Not yet due or less than 30 days overdue\n` +
-                        `   - 31-60 DAYS: Between 31 and 60 days overdue\n` +
-                        `   - 61-90 DAYS: Between 61 and 90 days overdue\n` +
-                        `   - 90+ DAYS: More than 90 days overdue (high risk)\n` +
-                        `   For each bucket, show:\n` +
-                        `   - Number of invoices\n` +
-                        `   - Total amount\n` +
-                        `   - Percentage of total outstanding receivables\n` +
-                        `   - List of invoices in that bucket\n\n` +
-                        `3. TOP DEBTORS\n` +
-                        `   - Use get_client for each client with unpaid invoices to get their details\n` +
-                        `   - Rank clients by total outstanding amount (highest first)\n` +
-                        `   - For each top debtor, show:\n` +
-                        `     - Client name and contact info\n` +
-                        `     - Number of unpaid invoices\n` +
-                        `     - Total outstanding amount\n` +
-                        `     - Oldest unpaid invoice date\n` +
-                        `     - Average days overdue\n\n` +
-                        `4. COLLECTION ACTIONS\n` +
-                        `   Suggest specific actions for each bucket:\n` +
-                        `   - CURRENT (0-30 days): No action needed, monitor normally\n` +
-                        `   - 31-60 DAYS: Send a friendly payment reminder (use overdue-followup prompt pattern)\n` +
-                        `   - 61-90 DAYS: Escalate — phone call + formal written reminder,\n` +
-                        `     consider pausing new work for this client\n` +
-                        `   - 90+ DAYS: Final notice before debt collection,\n` +
-                        `     evaluate write-off vs collection agency cost,\n` +
-                        `     stop all new work for this client\n\n` +
-                        `5. WRITE-OFF CANDIDATES\n` +
-                        `   - Flag any invoices 90+ days overdue with amounts under €100 — likely not worth pursuing\n` +
-                        `   - For larger amounts 90+ days, suggest formal demand letter before write-off\n` +
-                        `   - Note: written-off invoices may still be tax-deductible as bad debt\n` +
-                        `     (requires documentation of collection attempts)\n\n` +
-                        `6. SUMMARY DASHBOARD\n` +
-                        `   Present a clear overview:\n` +
-                        `   - Total accounts receivable (all unpaid invoices)\n` +
-                        `   - Breakdown by aging bucket (amount and % of total)\n` +
-                        `   - Weighted collection estimate:\n` +
-                        `     Current: 95% collectible, 31-60: 80%, 61-90: 50%, 90+: 20%\n` +
-                        `   - Expected collectible amount vs total outstanding\n` +
-                        `   - Number of clients with overdue invoices\n` +
-                        `   - Most urgent actions to take (prioritized list)`,
+                    text: `Prepare an accounts receivable aging review.
+
+1. VERIFY THE DATA
+   - Call list_invoices without a status filter (it has no partial status) and select sent, partial and overdue records client-side from each returned status. Paginate every result set using the returned pagination fields until exhausted; deduplicate by invoice ID. Report any failed page or incomplete coverage.
+   - Use get_invoice when needed to verify currency, due date and remaining unpaid balance after recorded payments and credits. Do not count full invoice totals as outstanding for partially paid invoices. Mark unverifiable balances as unknown; do not invent totals.
+   - Confirm the as-of date and workspace timezone. Exclude settled, draft and cancelled records from receivables. Status alone does not establish delivery or an undisputed debt.
+
+2. AGE VERIFIED BALANCES
+   - Keep separate buckets: not-yet-due; due today; 1-30 days overdue; 31-60 days overdue; 61-90 days overdue; more than 90 days overdue. Missing or invalid due dates form an unknown-age bucket.
+   - Group by currency. For each bucket, show invoice IDs, count, remaining unpaid balance and percentage of that currency's verified receivables (only when the denominator is positive). Never combine currencies without a user-supplied conversion basis.
+   - Use get_client for client details and summarize positive balances by client within each currency, showing oldest due dates and missing evidence.
+
+3. REVIEW BEFORE ACTING
+   - Present the per-currency report and possible follow-up drafts using overdue-followup for user approval before any actions. A report is not permission to send, change status or create charges.
+   - Do not assign arbitrary collectible probabilities, automatically write off balances, impose late fees, stop work or make business decisions from age or amount alone. Ask for the user's terms, dispute context and decision before proposing an action.
+   - Keep not-yet-due amounts separate from overdue exposure and disclose unknown balances and incomplete pagination.`,
                 },
             },
         ],

package/dist/public-capability-contract.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Generated public-surface contract captured through the real MCP SDK.
+ *
+ * This is the mechanical source for catalogue, alias, discovery, resource, and
+ * prompt truth across the npm/full, remote/grouped, and OpenAI/full profiles.
+ */
+import { type PublicCapabilityTruth } from "./capability-truth.js";
+export declare const PUBLIC_CAPABILITY_CONTRACT_VERSION = 2;
+export interface CompactPublicTool {
+    name: string;
+    annotations?: Record<string, boolean>;
+    capability?: PublicCapabilityTruth;
+}
+export interface CompactPublicSurface {
+    tools: CompactPublicTool[];
+    resources: string[];
+    prompts: string[];
+    discovery?: {
+        searchTools: CompactPublicTool;
+        describeTool: CompactPublicTool;
+    };
+}
+export interface PublicCapabilityContract {
+    contractVersion: number;
+    catalogue: {
+        canonicalOperations: number;
+        aliasNames: number;
+        discoveryNames: number;
+    };
+    surfaces: {
+        localFull: CompactPublicSurface;
+        remoteGrouped: CompactPublicSurface;
+        openaiFull: CompactPublicSurface;
+    };
+}
+export declare function capturePublicCapabilityContract(): Promise<PublicCapabilityContract>;
+export declare function serializePublicCapabilityContract(contract: PublicCapabilityContract): string;
+export declare function assertPublicCapabilityContract(actual: PublicCapabilityContract, expected: PublicCapabilityContract): void;
+//# sourceMappingURL=public-capability-contract.d.ts.map