@oomol-lab/open-connector 1.6.4 → 1.7.0

package/src/providers/moneyforward_mcp/runtime.js

@@ -0,0 +1,296 @@
+import { sha256Hex } from "../../core/aws-sigv4.js";
+import { compactObject, looseArray, optionalNumber, optionalRecord, optionalString } from "../../core/cast.js";
+import { callMcpTool, listMcpTools } from "../mcp-tools.js";
+import { createProviderTimeout, ProviderRequestError, providerInputError, providerResponseError, } from "../provider-runtime.js";
+import { canonicalOfficeName, currentOfficeToolName, moneyforwardMcpEndpoint, moneyforwardService, moneyforwardTools, officeCodePattern, schemaDigest, } from "./manifest.js";
+const defaultOptions = { deadlineMs: 90_000, closeGraceMs: 5_000 };
+const defaultWritesPerMinute = 30;
+const rateWindowMs = 60_000;
+const maxResponseBytes = 8 * 1024 * 1024;
+const officeCodeRegExp = new RegExp(officeCodePattern, "u");
+// A Money Forward API 4xx relayed by the MCP server. Enough to call a read invalid input, but not
+// proof that a write did nothing: batch writes can fail part-way and retries can hide a success.
+const apiClientErrorPattern = /^API request failed: client error\b/u;
+// The only answers that prove the tool handler never ran: the arguments failed the tool's input
+// schema, or the tool does not exist. Output validation runs after the handler, so it is excluded.
+const notExecutedPattern = /^(?:MCP error -32602: )?Input validation error\b|^MCP error -32601\b/u;
+export function createMoneyforwardMcpHandlers(timing = defaultOptions) {
+    const takeWriteSlot = createWriteLimiter(timing.writesPerMinute ?? defaultWritesPerMinute);
+    const toolHandlers = moneyforwardTools.map((entry) => [
+        entry.actionName,
+        entry.isWrite
+            ? async (input, context) => {
+                takeWriteSlot(context.apiKey);
+                return runWrite(entry, input, context, timing);
+            }
+            : (input, context) => runRead(entry, input, context, timing),
+    ]);
+    const listTools = (_input, context) => withDeadline(context.signal, timing, async (signal) => ({
+        tools: await listMcpTools(toolOptions(context, signal, timing), { includeAnnotations: true }),
+    }));
+    return Object.fromEntries([...toolHandlers, ["list_tools", listTools]]);
+}
+export const moneyforwardMcpActionHandlers = createMoneyforwardMcpHandlers();
+/** Accept the key when the server exposes every captured tool; report schema drift without refusing. */
+export async function validateMoneyforwardMcpCredential(apiKey, fetcher, signal, schemaDigests) {
+    const tools = await withDeadline(signal, defaultOptions, (deadlineSignal) => listMcpTools(toolOptions({ apiKey, fetcher }, deadlineSignal, defaultOptions)));
+    const byName = new Map(tools.map((tool) => [tool.name, tool]));
+    const missing = moneyforwardTools.filter((entry) => !byName.has(entry.toolName)).map((entry) => entry.toolName);
+    if (missing.length > 0) {
+        throw providerInputError(`Money Forward MCP does not expose these tools for this key: ${missing.join(", ")}`);
+    }
+    const schemaDrift = moneyforwardTools
+        .filter((entry) => schemaDigest(byName.get(entry.toolName)?.inputSchema) !== expectedDigest(entry, schemaDigests))
+        .map((entry) => entry.toolName);
+    const keyHash = sha256Hex(apiKey).slice(0, 16);
+    return {
+        profile: {
+            accountId: `${moneyforwardService}:${keyHash}`,
+            displayName: `Money Forward MCP · ${keyHash.slice(-6)}`,
+        },
+        grantedScopes: [],
+        metadata: { mcpEndpoint: moneyforwardMcpEndpoint, schemaDrift },
+    };
+}
+async function runRead(entry, input, context, timing) {
+    const args = toolArguments(entry, input);
+    return withDeadline(context.signal, timing, async (signal) => {
+        const result = await callToolWithoutWaitingForClose({
+            ...toolOptions(context, signal, timing),
+            toolName: entry.toolName,
+            arguments: args,
+        });
+        return readPayload(entry.toolName, result);
+    });
+}
+async function runWrite(entry, input, context, timing) {
+    const args = toolArguments(entry, input);
+    const expectedName = optionalString(input.expected_office_name);
+    if (!expectedName)
+        throw writeError(providerInputError("expected_office_name is required"), "definitely_not_sent");
+    // Flipped by the authorizeTool hook, the last step before callMcpTool sends tools/call.
+    const phase = { dispatched: false };
+    try {
+        return await withDeadline(context.signal, timing, async (signal) => {
+            const options = toolOptions(context, signal, timing);
+            await confirmOffice(String(args.office_code), expectedName, options);
+            const result = await callToolWithoutWaitingForClose({
+                ...options,
+                toolName: entry.toolName,
+                arguments: args,
+                authorizeTool(tool) {
+                    // A late tools/list must not dispatch after the backstop has already reported definitely_not_sent.
+                    if (signal.aborted) {
+                        throw providerResponseError("The Money Forward write was cancelled before it was sent; nothing was written.");
+                    }
+                    assertSchemaUnchanged(entry, tool, expectedDigest(entry, timing.schemaDigests));
+                    phase.dispatched = true;
+                },
+            });
+            return readPayload(entry.toolName, result);
+        });
+    }
+    catch (error) {
+        throw classifyWriteFailure(entry, args, phase.dispatched, error);
+    }
+}
+async function confirmOffice(officeCode, expectedName, options) {
+    const office = await callToolWithoutWaitingForClose({
+        ...options,
+        toolName: currentOfficeToolName,
+        arguments: { office_code: officeCode },
+    });
+    const payload = optionalRecord(readPayload(currentOfficeToolName, office));
+    const actualName = optionalString(payload?.name);
+    if (payload?.code !== officeCode || !actualName) {
+        throw providerInputError(`Money Forward did not confirm office ${officeCode}; nothing was written.`);
+    }
+    if (canonicalOfficeName(actualName) !== canonicalOfficeName(expectedName)) {
+        throw providerInputError(`Office ${officeCode} is "${actualName}" in Money Forward, not "${expectedName}"; nothing was written.`);
+    }
+}
+function expectedDigest(entry, overrides) {
+    return overrides?.[entry.toolName] ?? entry.schemaDigest;
+}
+function assertSchemaUnchanged(entry, tool, expected) {
+    if (!tool) {
+        throw providerResponseError(`Money Forward MCP no longer exposes ${entry.toolName}; nothing was written.`);
+    }
+    if (schemaDigest(tool.inputSchema) !== expected) {
+        throw providerResponseError(`Money Forward changed the ${entry.toolName} input schema; writes stay blocked until the change is reviewed and the provider is updated. Nothing was written.`);
+    }
+}
+function classifyWriteFailure(entry, args, dispatched, error) {
+    const cause = error instanceof ProviderRequestError ? error : providerResponseError("Money Forward request failed");
+    if (readWriteOutcome(cause) !== undefined)
+        return cause;
+    if (!dispatched)
+        return writeError(cause, "definitely_not_sent");
+    const submitted = summarizeSubmission(entry, args);
+    if (optionalRecord(cause.details)?.notExecuted === true) {
+        // The pattern proves the MCP layer refused the call; a batch is still worth checking by hand.
+        const batchNote = Object.values(args).some(Array.isArray)
+            ? " This was a batch write: confirm that no item was applied before resubmitting."
+            : "";
+        const rejected = new ProviderRequestError(cause.status, `${cause.message}${batchNote}`, cause.details, cause.code);
+        return writeError(rejected, "rejected", submitted);
+    }
+    return new ProviderRequestError(502, `OUTCOME UNKNOWN: ${entry.toolName} may have been applied. Check the ledger with get_journals / get_transactions for the submitted content before retrying. Cause: ${cause.message}`, { writeOutcome: "outcome_unknown", submitted }, "provider_error");
+}
+function writeError(error, outcome, submitted) {
+    const details = { ...optionalRecord(error.details), writeOutcome: outcome, submitted };
+    return new ProviderRequestError(error.status, error.message, details, error.code);
+}
+/** What was submitted, so an unknown outcome can be reconciled by hand. Never includes credentials. */
+function summarizeSubmission(entry, args) {
+    const journal = optionalRecord(args.journal);
+    const branches = Array.isArray(journal?.branches) ? journal.branches : undefined;
+    const arrayCounts = Object.fromEntries(Object.entries(args)
+        .filter(([, value]) => Array.isArray(value))
+        .map(([key, value]) => [`${key}_count`, value.length]));
+    return compactObject({
+        tool: entry.toolName,
+        office_code: args.office_code,
+        id: args.id,
+        transaction_id: args.transaction_id,
+        transaction_date: journal?.transaction_date,
+        branch_count: branches?.length,
+        debit_total: branches ? sumDebits(branches) : undefined,
+        ...arrayCounts,
+    });
+}
+function sumDebits(branches) {
+    return branches.reduce((total, branch) => total + (optionalNumber(optionalRecord(optionalRecord(branch)?.debitor)?.value) ?? 0), 0);
+}
+/**
+ * Validate office_code and drop the guard-only field before it reaches Money Forward. The action
+ * schema already requires both, but executors can be invoked without schema validation (tests, direct
+ * loader callers), and these checks are what keep a write from going to an unnamed office.
+ */
+function toolArguments(entry, input) {
+    const { expected_office_name: _guard, ...args } = input;
+    if (entry.requiresOfficeCode && !(typeof args.office_code === "string" && officeCodeRegExp.test(args.office_code))) {
+        throw entry.isWrite
+            ? writeError(providerInputError("office_code is required in the form XXXX-XXXX"), "definitely_not_sent")
+            : providerInputError("office_code is required in the form XXXX-XXXX");
+    }
+    return args;
+}
+/**
+ * Rolling one-minute write budget per key (hashed, so the map never holds the key itself). Best-effort:
+ * it counts within one process, so separate processes or isolates each keep their own budget.
+ */
+function createWriteLimiter(writesPerMinute) {
+    const recent = new Map();
+    return (apiKey) => {
+        const now = Date.now();
+        // Timestamps are appended in order, so a bucket is idle once its newest one has aged out.
+        for (const [key, times] of recent) {
+            if (now - (times.at(-1) ?? 0) >= rateWindowMs)
+                recent.delete(key);
+        }
+        const bucket = sha256Hex(apiKey);
+        const inWindow = (recent.get(bucket) ?? []).filter((at) => now - at < rateWindowMs);
+        if (inWindow.length >= writesPerMinute) {
+            throw new ProviderRequestError(429, `More than ${writesPerMinute} Money Forward writes in a minute; nothing was written. Wait and confirm with the user before continuing.`, { writeOutcome: "definitely_not_sent" }, "rate_limited");
+        }
+        recent.set(bucket, [...inWindow, now]);
+    };
+}
+// protocolVersion is deliberately left unset (legacy): in modern mode the SDK re-sends tools/call
+// on a SEP-2243 header mismatch, which would be a silent write retry.
+function toolOptions(context, signal, timing) {
+    return {
+        endpoint: moneyforwardMcpEndpoint,
+        service: "Money Forward",
+        fetcher: context.fetcher,
+        headers: { "mf-api-key": context.apiKey },
+        // Never follow a redirect: a cross-origin hop drops the key but would replay the ledger payload.
+        redirect: "manual",
+        signal,
+        terminateSession: true,
+        requestTimeoutMs: timing.deadlineMs,
+        maxResponseBytes,
+        toolListMaxBytes: 1024 * 1024,
+        toolListMaxPages: 5,
+        toolListMaxTools: 200,
+    };
+}
+/**
+ * Resolve as soon as the tool result arrives instead of after the SDK closes the session:
+ * the upstream cleanup awaits close() without a timeout, and a finished write must not be
+ * reported as unknown because a DELETE hung. Later cleanup errors are ignored.
+ */
+function callToolWithoutWaitingForClose(input) {
+    return new Promise((resolve, reject) => {
+        callMcpTool({
+            ...input,
+            transformToolResult(result) {
+                resolve(result);
+                return result;
+            },
+        }).then(() => undefined, (error) => reject(error));
+    });
+}
+function readPayload(toolName, result) {
+    const text = readText(result);
+    if ("isError" in result && result.isError) {
+        const notExecuted = notExecutedPattern.test(text);
+        const isClientError = notExecuted || apiClientErrorPattern.test(text);
+        throw new ProviderRequestError(isClientError ? 400 : 502, `Money Forward ${toolName} failed: ${text.slice(0, 500)}`, { notExecuted }, isClientError ? "invalid_input" : "provider_error");
+    }
+    if ("structuredContent" in result && result.structuredContent !== undefined)
+        return result.structuredContent;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { text };
+    }
+}
+function readText(result) {
+    return looseArray(optionalRecord(result)?.content)
+        .map((item) => {
+        const content = optionalRecord(item);
+        return content?.type === "text" && typeof content.text === "string" ? content.text : "";
+    })
+        .join("")
+        .trim();
+}
+/**
+ * Run with one deadline shared by every step. The grace timer is a backstop for SDK cleanup
+ * that ignores the abort; the losing promise is caught so it cannot become an unhandled rejection.
+ * Every Money Forward call goes through here, so auth failures are normalized in this one place.
+ */
+async function withDeadline(parentSignal, timing, run) {
+    if (parentSignal?.aborted) {
+        throw new ProviderRequestError(504, "The Money Forward request was cancelled before it was sent", undefined, "provider_error");
+    }
+    const deadline = createProviderTimeout(parentSignal, timing.deadlineMs);
+    let grace;
+    const work = run(deadline.signal);
+    work.catch(() => undefined);
+    const backstop = new Promise((_resolve, reject) => {
+        grace = setTimeout(() => reject(new ProviderRequestError(504, "The Money Forward request timed out", undefined, "provider_error")), timing.deadlineMs + timing.closeGraceMs);
+    });
+    try {
+        return await Promise.race([work, backstop]);
+    }
+    catch (error) {
+        throw withAuthorizationCode(error);
+    }
+    finally {
+        deadline.cleanup();
+        clearTimeout(grace);
+    }
+}
+// The shared MCP error mapper reports 401/403 as provider_error; surface them as auth failures.
+function withAuthorizationCode(error) {
+    if (error instanceof ProviderRequestError && (error.status === 401 || error.status === 403)) {
+        return new ProviderRequestError(error.status, error.message, error.details, "authorization_failed");
+    }
+    return error;
+}
+function readWriteOutcome(error) {
+    return optionalRecord(error.details)?.writeOutcome;
+}

package/src/providers/notion/executors.js

@@ -1,5 +1,5 @@
 import { compactObject } from "../../core/cast.js";
-import { createProviderFetch, createProviderProxyUrl, defineProviderExecutors, normalizeProviderProxyHeaders, ProviderRequestError, providerUserAgent, readProviderProxyErrorMessage, readProviderProxyResponse, requireBearerCredential, toProviderProxyError, } from "../provider-runtime.js";
+import { createProviderFetch, createProviderProxyUrl, defineProviderExecutors, normalizeProviderProxyHeaders, providerInputError, ProviderRequestError, providerUserAgent, readProviderProxyErrorMessage, readProviderProxyResponse, requireBearerCredential, toProviderProxyError, withRetryAfterSeconds, } from "../provider-runtime.js";
 const service = "notion";
 const notionApiBaseUrl = "https://api.notion.com/v1";
 const notionFetch = createProviderFetch({ skipDnsValidation: true });
@@ -83,6 +83,12 @@ export const notionActionHandlers = {
     list_data_source_templates(input, context) {
         return notionListDataSourceTemplates(input, context.accessToken, context.fetcher);
     },
+    list_comments(input, context) {
+        return notionListComments(input, context.accessToken, context.fetcher);
+    },
+    create_comment(input, context) {
+        return notionCreateComment(input, context.accessToken, context.fetcher);
+    },
 };
 export const executors = defineProviderExecutors({
     service,
@@ -121,7 +127,7 @@ export const proxy = async (input, context) => {
         const response = await notionFetch(url, init);
         if (!response.ok) {
             const text = await readProviderProxyErrorMessage(response, "");
-            throw new ProviderRequestError(response.status, text || `Notion request failed with HTTP ${response.status}`);
+            throw new ProviderRequestError(response.status, text || `Notion request failed with HTTP ${response.status}`, withRetryAfterSeconds(response));
         }
         return { ok: true, response: await readProviderProxyResponse(response) };
     }
@@ -595,6 +601,36 @@ async function notionListDataSourceTemplates(input, accessToken, fetcher) {
     }, fetcher);
     return payload ?? {};
 }
+async function notionListComments(input, accessToken, fetcher) {
+    const payload = await notionRequest(accessToken, {
+        path: "/comments",
+        query: compactQuery({
+            block_id: String(input.blockId),
+            page_size: asNumber(input.pageSize),
+            start_cursor: asNonEmptyString(input.startCursor),
+        }),
+    }, fetcher);
+    return payload ?? {};
+}
+async function notionCreateComment(input, accessToken, fetcher) {
+    const parent = asObject(input.parent);
+    const discussionId = asNonEmptyString(input.discussion_id);
+    if (!parent === !discussionId) {
+        throw providerInputError("exactly one of parent or discussion_id is required");
+    }
+    const payload = await notionRequest(accessToken, {
+        method: "POST",
+        path: "/comments",
+        body: compactObject({
+            parent,
+            discussion_id: discussionId,
+            rich_text: Array.isArray(input.rich_text) ? input.rich_text : [],
+            attachments: Array.isArray(input.attachments) ? input.attachments : undefined,
+            display_name: asObject(input.display_name),
+        }),
+    }, fetcher);
+    return payload ?? {};
+}
 async function notionRequest(accessToken, input, fetcher) {
     const url = new URL(`https://api.notion.com/v1${input.path}`);
     for (const [key, value] of Object.entries(input.query ?? {})) {
@@ -653,7 +689,7 @@ async function assertNotionResponse(response) {
         throw new ProviderRequestError(403, message);
     }
     if (response.status === 429) {
-        throw new ProviderRequestError(429, message);
+        throw new ProviderRequestError(429, message, withRetryAfterSeconds(response));
     }
     throw new ProviderRequestError(response.status, message);
 }

package/src/providers/notion_mcp/endpoints.d.ts

@@ -0,0 +1,3 @@
+/** Notion's official remote MCP server, which its own OAuth authorization server protects (RFC 9728). */
+export declare const notionMcpEndpoint = "https://mcp.notion.com/mcp";
+export declare const notionMcpIssuer = "https://mcp.notion.com";

package/src/providers/notion_mcp/endpoints.js

@@ -0,0 +1,3 @@
+/** Notion's official remote MCP server, which its own OAuth authorization server protects (RFC 9728). */
+export const notionMcpEndpoint = "https://mcp.notion.com/mcp";
+export const notionMcpIssuer = "https://mcp.notion.com";

package/src/providers/notion_mcp/executors.d.ts

@@ -0,0 +1,3 @@
+import type { CredentialValidators, ProviderExecutors } from "../../core/types.ts";
+export declare const executors: ProviderExecutors;
+export declare const credentialValidators: CredentialValidators;

package/src/providers/notion_mcp/executors.js

@@ -0,0 +1,176 @@
+import { ProtocolError, SdkHttpError, UnauthorizedError } from "@modelcontextprotocol/client";
+import { compactObject, looseArray, optionalBoolean, optionalInteger, optionalNumber, optionalRawString, optionalRecord, optionalString, optionalStringArray, requiredRawString, } from "../../core/cast.js";
+import { withMcpClient } from "../mcp-client.js";
+import { defineOAuthProviderExecutors, mapProviderActionSources, providerResponseError, providerUserAgent, ProviderRequestError, requiredInputString, requiredResponseRecord, runProviderRequest, } from "../provider-runtime.js";
+import { notionMcpEndpoint } from "./endpoints.js";
+import { decodeNotionToolText, parseNotionComments, parseNotionPage, parseNotionSearch, parseNotionSelf, parseNotionToolAccess, } from "./mcp-response.js";
+const service = "notion_mcp";
+const selfUserId = "self";
+const toolsByAction = {
+    get_self: {
+        tool: "notion-get-users",
+        arguments: () => ({ user_id: selfUserId }),
+        parse: (value) => compactObject({ user: parseNotionSelf(value) }),
+    },
+    search: {
+        tool: "notion-search",
+        arguments: searchArguments,
+        parse: (value) => ({ ...parseNotionSearch(value) }),
+    },
+    fetch_page: {
+        tool: "notion-fetch",
+        arguments: (input) => ({ id: requiredInputString(input.id, "id") }),
+        parse: (value, input) => ({ id: requiredInputString(input.id, "id"), ...parseNotionPage(value) }),
+    },
+    list_comments: {
+        tool: "notion-get-comments",
+        arguments: (input) => ({
+            page_id: requiredInputString(input.page_id, "page_id"),
+            include_all_blocks: optionalBoolean(input.include_all_blocks) ?? true,
+            include_resolved: optionalBoolean(input.include_resolved) ?? true,
+        }),
+        parse: (value) => ({ comments: parseNotionComments(value) }),
+    },
+    tool_access: {
+        tool: "notion-get-tool-access",
+        arguments: () => ({}),
+        parse: (value) => ({ tools: parseNotionToolAccess(value) }),
+    },
+};
+const handlers = mapProviderActionSources(service, toolsByAction, (_actionName, source) => async (input, context) => {
+    const result = await callNotionTool(context, source.tool, source.arguments(input));
+    return { ...source.parse(result.value, input), raw: result.raw };
+});
+export const executors = defineOAuthProviderExecutors(service, handlers, {
+    skipDnsValidation: true,
+});
+export const credentialValidators = {
+    /** Require every tool the actions map, then identify the user so the account key is the Notion user ID. */
+    async oauth2(input, { fetcher, signal }) {
+        const context = { accessToken: input.accessToken, fetcher, signal };
+        const { toolCount, self } = await withNotionMcpClient(context, "validate", async (client, signal) => {
+            const tools = await listNotionTools(client, signal);
+            const available = new Set(tools.map((tool) => tool.name));
+            const missing = Object.values(toolsByAction)
+                .map((source) => source.tool)
+                .filter((tool) => !available.has(tool));
+            if (missing.length > 0) {
+                throw new ProviderRequestError(502, `Notion MCP did not expose the tools this connector needs: ${[...new Set(missing)].join(", ")}.`);
+            }
+            const result = await client.callTool({ name: toolsByAction.get_self.tool, arguments: toolsByAction.get_self.arguments({}) }, { signal });
+            return {
+                toolCount: tools.length,
+                self: parseNotionSelf(readNotionToolResult(toolsByAction.get_self.tool, result).value),
+            };
+        });
+        const accountId = self?.id;
+        if (!accountId)
+            throw providerResponseError("Notion MCP did not identify the connected user.");
+        return {
+            profile: { accountId, displayName: self.name ?? self.email ?? accountId },
+            grantedScopes: optionalString(input.metadata.scope)?.split(" ") ?? [],
+            metadata: { mcpEndpoint: notionMcpEndpoint, discoveredToolCount: toolCount },
+        };
+    },
+};
+/** The recorded notion-search arguments: typed filters nest under `filters`; extra ones pass through beneath them. */
+function searchArguments(input) {
+    const filters = compactObject({
+        ...optionalRecord(input.filters),
+        last_edited_date_range: optionalRecord(input.last_edited_date_range),
+        created_date_range: optionalRecord(input.created_date_range),
+        created_by_user_ids: optionalStringArray(input.created_by_user_ids),
+        edited_by_user_ids: optionalStringArray(input.edited_by_user_ids),
+    });
+    return compactObject({
+        query: optionalRawString(input.query) ?? "",
+        sort: optionalString(input.sort),
+        page_size: optionalInteger(input.page_size),
+        max_highlight_length: optionalInteger(input.max_highlight_length),
+        filters: Object.keys(filters).length > 0 ? filters : undefined,
+    });
+}
+async function listNotionTools(client, signal) {
+    const tools = [];
+    const cursors = new Set();
+    let cursor;
+    do {
+        const page = await client.listTools(cursor === undefined ? {} : { cursor }, { signal });
+        tools.push(...page.tools);
+        cursor = page.nextCursor;
+        if (cursor !== undefined) {
+            if (cursors.has(cursor))
+                throw providerResponseError("Notion MCP tools/list returned a repeated cursor.");
+            cursors.add(cursor);
+        }
+    } while (cursor !== undefined);
+    return tools;
+}
+async function callNotionTool(context, name, input) {
+    const result = await withNotionMcpClient(context, "execute", (client, signal) => client.callTool({ name, arguments: input }, { signal }));
+    return readNotionToolResult(name, result);
+}
+/** The text blocks joined are the raw answer; structured content, when the server sends it, is the value. */
+function readNotionToolResult(name, result) {
+    const record = requiredResponseRecord(result, "Notion MCP result");
+    if (record.isError === true)
+        throw notionToolError(name, record);
+    const texts = looseArray(record.content).flatMap((block) => {
+        const item = optionalRecord(block);
+        return item?.type === "text" ? [requiredRawString(item.text, "Notion MCP text", providerResponseError)] : [];
+    });
+    const structured = optionalRecord(record.structuredContent);
+    if (texts.length === 0 && structured === undefined)
+        throw providerResponseError("Notion MCP returned no content.");
+    const raw = texts.length > 0 ? texts.join("\n") : JSON.stringify(structured);
+    return { raw, value: structured ?? decodeNotionToolText(raw) };
+}
+/**
+ * A tool error. Notion returns a rate limit it does not wait out as a tool error whose `structuredContent.error`
+ * carries `code: "rate_limited"` and, when known, `retry_after_seconds`; that one is a 429, the rest a 502.
+ */
+function notionToolError(name, record) {
+    const error = optionalRecord(optionalRecord(record.structuredContent)?.error);
+    if (error?.code === "rate_limited") {
+        const retryAfter = optionalNumber(error.retry_after_seconds);
+        const wait = retryAfter === undefined ? "" : `; retry after ${retryAfter} seconds`;
+        return new ProviderRequestError(429, `Notion MCP tool ${name} was rate limited${wait}.`, record);
+    }
+    return new ProviderRequestError(502, `Notion MCP tool ${name} failed.`, record);
+}
+function withNotionMcpClient(context, phase, run) {
+    return runProviderRequest({ signal: context.signal, label: "Notion MCP" }, (signal) => withMcpClient({
+        endpoint: new URL(notionMcpEndpoint),
+        transport: "streamable_http",
+        fetcher: context.fetcher,
+        headers: { authorization: `Bearer ${context.accessToken}`, "user-agent": providerUserAgent },
+        redirect: "manual",
+        signal,
+        mapError: (error) => mapNotionMcpError(error, phase),
+    }, (client) => run(client, signal)));
+}
+/**
+ * Sign-in reports a rejected token as invalid input (400); a run reports it as an expired authorization (401).
+ * Anything unrecognized is left to runProviderRequest, which tells a timeout (504) from a failure (502).
+ */
+function mapNotionMcpError(error, phase) {
+    if (error instanceof ProviderRequestError)
+        return error;
+    const credentialStatus = phase === "validate" ? 400 : 401;
+    if (error instanceof UnauthorizedError) {
+        return new ProviderRequestError(credentialStatus, "Notion MCP credential is invalid or expired.");
+    }
+    if (error instanceof SdkHttpError) {
+        const status = error.status;
+        if (status === 401 || status === 403) {
+            return new ProviderRequestError(credentialStatus, "Notion MCP credential is invalid or expired.");
+        }
+        // The SDK error carries the response body; only the status is reported so a token echoed in it never is.
+        const providerStatus = 400 <= status && status < 500 ? status : 502;
+        return new ProviderRequestError(providerStatus, `Notion MCP request failed with HTTP ${status}.`);
+    }
+    if (error instanceof ProtocolError) {
+        return new ProviderRequestError(502, `Notion MCP request failed: ${error.message}`);
+    }
+    return error;
+}

package/src/providers/notion_mcp/mcp-response.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Readers for the text envelopes Notion's beta MCP tools answer in, as they were recorded live. Every reader is
+ * defensive: a field the server omits is absent from the typed result, an unrecognized shape yields an empty
+ * result, and nothing here throws, because the caller keeps the raw text beside the typed fields.
+ */
+interface NotionMcpUser {
+    id?: string;
+    name?: string;
+    email?: string;
+    type?: string;
+}
+interface NotionMcpSearchResult {
+    id?: string;
+    title?: string;
+    url?: string;
+    type?: string;
+    timestamp?: string;
+    path?: string;
+}
+interface NotionMcpSearch {
+    type: string | undefined;
+    results: NotionMcpSearchResult[];
+    notices: string[];
+}
+interface NotionMcpPage {
+    title?: string;
+    url?: string;
+    page_last_edited_at?: string;
+    properties?: string;
+    content?: string;
+    truncated: boolean;
+}
+interface NotionMcpComment {
+    id?: string;
+    discussion_id?: string;
+    plain_text?: string;
+    created_time?: string;
+    created_by?: NotionMcpUser;
+}
+interface NotionMcpToolRestriction {
+    parameter: string;
+    reason: string;
+}
+interface NotionMcpToolAccess {
+    tool: string;
+    status: string | undefined;
+    restricted_parameters: NotionMcpToolRestriction[];
+    upgrade_url: string | undefined;
+    full_version_url: string | undefined;
+    landing_page_url: string | undefined;
+    landing_page_action: string | undefined;
+}
+/** Notion's tools answer JSON in a text block on most calls and prose or XML fragments on the rest. */
+export declare function decodeNotionToolText(text: string): unknown;
+/**
+ * The connected user as notion-get-users answers `user_id: "self"`: the first listed user of
+ * `{results: [{type, id, name, email}], has_more}` that carries an ID or an email, or the answer itself when it is a
+ * single user.
+ */
+export declare function parseNotionSelf(value: unknown): NotionMcpUser | undefined;
+/**
+ * Search results plus the server's notices, such as a filter dropped on the connected plan, and the search `type`
+ * the server reports: `workspace_search`, or `ai_search` when it routed a keyword query to Notion AI search.
+ */
+export declare function parseNotionSearch(value: unknown): NotionMcpSearch;
+/**
+ * The page envelope notion-fetch answers: a preamble line, then
+ * `<page url="..."><properties>...</properties><content>MARKDOWN</content></page>`, either bare in the text block or
+ * under `text` of a `{title, url, page_last_edited_at, text}` object. A page the server cut says so with a
+ * `truncated` flag on the object or on the tag.
+ */
+export declare function parseNotionPage(value: unknown): NotionMcpPage;
+/**
+ * Comments as notion-get-comments answers them, in both recorded shapes: the structured
+ * `{discussions: [{id, comments: [{id, plain_text, created_time, created_by}]}]}` (or a flat `{comments: [...]}`),
+ * or the XML twin `<discussion id><comment id author author_id created_time>text</comment></discussion>`.
+ */
+export declare function parseNotionComments(value: unknown): NotionMcpComment[];
+/**
+ * The plan report notion-get-tool-access answers: `{current_tool_access: {<tool>: {status, restricted_parameters?,
+ * upgrade_url?, full_version_url?, landing_page_url?, landing_page_action?}}}`, keyed by each tool's base name
+ * (`search`, `ai_search`), where `restricted_parameters` maps a parameter path such as `filters.title_only` to the
+ * reason it is unavailable. The reason is kept as text and never interpreted.
+ */
+export declare function parseNotionToolAccess(value: unknown): NotionMcpToolAccess[];
+export {};