@withone/mcp 1.2.3 → 1.3.0

package/README.md

@@ -20,7 +20,7 @@
   <a href="https://npmjs.com/package/@withone/mcp"><img src="https://img.shields.io/npm/v/%40withone%2Fmcp" alt="npm version"></a>
 </p>
 
-Connect your AI agents to 500+ apps through a single [MCP](https://modelcontextprotocol.io) server. Search for actions, read documentation, and execute API calls across platforms, without having to manage OAuth tokens or API keys.
+Connect your AI agents to 700+ apps through a single [MCP](https://modelcontextprotocol.io) server. Search for actions, read documentation, and execute API calls across platforms, without having to manage OAuth tokens or API keys.
 
 ```bash
 npm install -g @withone/cli
@@ -31,7 +31,7 @@ That's it. The [One CLI](https://www.npmjs.com/package/@withone/cli) will prompt
 
 ## Capabilities
 
-- **500+ platforms.** Gmail, Slack, Shopify, HubSpot, Stripe, Linear, QuickBooks, and [more](https://app.withone.ai/tools).
+- **700+ platforms.** Gmail, Slack, Shopify, HubSpot, Stripe, Linear, QuickBooks, and [more](https://app.withone.ai/tools).
 - **Natural language execution.** "read my last gmail email", "send a message to #general on Slack"
 - **Code generation.** "build a form to send emails using Gmail", "create a dashboard that lists my Linear projects"
 - **No tool bloat.** Only 4 tools exposed regardless of how many platforms or actions you connect. Actions are search-based, so your agent's context window stays clean.
@@ -89,6 +89,9 @@ One-click install:
 [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_One-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=one&config=%7B%22type%22%3A%20%22http%22%2C%20%22url%22%3A%20%22https%3A%2F%2Fmcp.withone.ai%2Fmcp%22%7D)
 [![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_One-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=one&config=%7B%22type%22%3A%20%22http%22%2C%20%22url%22%3A%20%22https%3A%2F%2Fmcp.withone.ai%2Fmcp%22%7D)
 [![Add to Cursor](https://img.shields.io/badge/Cursor-Add_One-000000?style=flat-square)](https://cursor.com/en/install-mcp?name=one&config=eyJ1cmwiOiAiaHR0cHM6Ly9tY3Aud2l0aG9uZS5haS9tY3AifQ==)
+[![Open in Windsurf](https://img.shields.io/badge/Windsurf-Open_One-09B6A2?style=flat-square)](windsurf://windsurf-mcp-registry?serverName=ai.withone/mcp)
+
+The Windsurf link opens One's page in the editor's MCP marketplace, which is served from the official MCP registry where One is published as `ai.withone/mcp`. Windsurf handles the OAuth sign-in itself once you install from that page.
 
 ## Manual Installation
 

package/build/client.js

@@ -22,6 +22,11 @@ export class OneClient {
     connectors = [];
     isInitialized = false;
     allowedActionsCache = null;
+    // Short-lived cache of fetched action details, keyed by action ID. The
+    // knowledge digest and a follow-up section/toc/full call both need the same
+    // document, so this lets the follow-up reuse it instead of re-fetching.
+    static ACTION_DETAILS_TTL_MS = 5 * 60_000;
+    actionDetailsCache = new Map();
     constructor(optionsOrSecret, baseUrl = "https://api.withone.ai") {
         if (typeof optionsOrSecret === 'string') {
             // Legacy constructor: (secret, baseUrl)
@@ -174,6 +179,10 @@ export class OneClient {
         if (!actionId?.trim()) {
             throw new Error("Action ID is required");
         }
+        const cached = this.actionDetailsCache.get(actionId);
+        if (cached && cached.expiresAt > Date.now()) {
+            return cached.details;
+        }
         try {
             const headers = this.generateHeaders();
             const url = `${this.baseUrl}/v1/knowledge`;
@@ -188,6 +197,10 @@ export class OneClient {
             if (actions.length === 0) {
                 throw new Error(`Action with ID ${actionId} not found`);
             }
+            this.actionDetailsCache.set(actionId, {
+                details: actions[0],
+                expiresAt: Date.now() + OneClient.ACTION_DETAILS_TTL_MS
+            });
             return actions[0];
         }
         catch (error) {

package/build/helpers.js

@@ -7,6 +7,7 @@
  * @author One
  */
 import axios from 'axios';
+import { parseSections, buildDigest, renderDigestBanner, renderDigestNotice, selectSections, flattenSections, parseSectionFlag, collapseSections, omittedSections, } from './knowledge-sections.js';
 /**
  * Paginates through API results by repeatedly calling a fetch function until all data is retrieved.
  * @param fetchFn - Function that fetches paginated data, takes skip and limit parameters
@@ -60,6 +61,110 @@ export async function fetchPaginatedData(baseUrl, headers, additionalParams) {
     };
     return paginateResults(fetchFn);
 }
+/**
+ * Reduce an action's knowledge document to what the agent asked for, returning
+ * both the text to read and a machine-readable envelope.
+ *
+ * By default a large doc is handed back as a digest (request-building sections
+ * in full, plus a trailer and a `sections` list naming what was omitted); a
+ * small doc is returned whole. `section` selects named section(s), `toc`
+ * returns the full table of contents, and `full` (or `section: "all"`) returns
+ * the document verbatim. Only the digest and full cases carry the API request
+ * guidance, so `wrap` is set for those.
+ *
+ * @param knowledge - The raw knowledge markdown for the action
+ * @param method - The action's HTTP method (echoed into the envelope)
+ * @param platform - The kebab-case platform identifier (for the load-more hint)
+ * @param actionId - The action ID (for the load-more hint)
+ * @param options - `section`/`toc`/`full` select what to return
+ */
+export function buildKnowledgeResponse(knowledge, method, platform, actionId, options = {}) {
+    const doc = parseSections(knowledge);
+    const fullToc = flattenSections(doc.sections).map((s) => ({
+        id: s.id,
+        heading: s.heading,
+        level: s.level,
+        chars: s.chars,
+    }));
+    const sectionNames = parseSectionFlag(options.section);
+    const specificSections = sectionNames.filter((n) => n.toLowerCase() !== 'all');
+    // `full: true`, or a `section` value that is only "all", asks for the whole doc.
+    const wantFull = options.full === true || (sectionNames.length > 0 && specificSections.length === 0);
+    // A specific named section takes precedence over `toc` and `full`.
+    if (specificSections.length > 0) {
+        const picked = selectSections(doc, specificSections);
+        if (!picked.ok) {
+            // Collapse candidates the same way the digest does: a not-found on a
+            // 400-heading doc must not answer with tens of KB of names.
+            const toc = collapseSections(picked.candidates);
+            const listing = toc.sections
+                .map((c) => `${c.heading} [${c.id}] (${c.chars} chars${c.children ? `, +${c.children} nested` : ''})`)
+                .join('\n');
+            const lead = picked.reason === 'ambiguous'
+                ? `Section "${picked.query}" matches several sections; pick one by id or full heading.`
+                : `No section named "${picked.query}". Use one of the names below, or full: true.`;
+            return {
+                wrap: false,
+                text: `${lead}\n\n${listing}`,
+                structured: {
+                    error: lead,
+                    query: picked.query,
+                    reason: picked.reason,
+                    sections: toc.sections,
+                    ...(toc.collapsed ? { sectionsCollapsed: true, sectionCount: picked.candidates.length } : {}),
+                },
+            };
+        }
+        return {
+            wrap: false,
+            text: picked.markdown,
+            structured: {
+                title: doc.title,
+                method,
+                truncated: false,
+                requested: specificSections,
+                resolved: picked.sections.map((s) => ({ id: s.id, heading: s.heading, chars: s.chars })),
+                sectionCount: fullToc.length,
+            },
+        };
+    }
+    if (options.toc) {
+        const listing = fullToc.length
+            ? fullToc.map((t) => `${'  '.repeat(Math.max(0, t.level - 1))}${t.heading} [${t.id}] (${t.chars} chars)`).join('\n')
+            : '(this document has no sections)';
+        return {
+            wrap: false,
+            text: `Table of contents. Load any by name with section: "<id or heading>", or the whole document with full: true.\n\n${listing}`,
+            structured: { title: doc.title, method, chars: doc.chars, sections: fullToc },
+        };
+    }
+    // `full`, and any document small enough to keep whole, are returned verbatim
+    // rather than reconstructed from the parsed tree, so nothing is reformatted.
+    if (wantFull) {
+        return { wrap: true, text: knowledge, structured: { title: doc.title, method, truncated: false } };
+    }
+    const digest = buildDigest(doc);
+    if (!digest.truncated) {
+        return { wrap: true, text: knowledge, structured: { title: doc.title, method, truncated: false } };
+    }
+    const toc = omittedSections(digest);
+    const text = [renderDigestBanner(digest), digest.markdown, renderDigestNotice(digest, platform, actionId)]
+        .filter(Boolean)
+        .join('\n\n');
+    return {
+        wrap: true,
+        text,
+        structured: {
+            title: doc.title,
+            method,
+            truncated: true,
+            omitted: digest.omitted,
+            omittedChars: digest.omittedChars,
+            sections: toc.sections,
+            ...(toc.collapsed ? { sectionsCollapsed: true, sectionCount: digest.sections.length } : {}),
+        },
+    };
+}
 /**
  * Builds action knowledge with API request structure guidance.
  * @param knowledge - The raw knowledge content for the action

package/build/index.js

@@ -11,7 +11,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
 import { OneClient } from './client.js';
-import { buildActionKnowledgeWithGuidance, buildKnowledgeModeGuidance, filterByPermissions, isMethodAllowed, isActionAllowed, computeConnectionAccess, } from './helpers.js';
+import { buildActionKnowledgeWithGuidance, buildKnowledgeModeGuidance, buildKnowledgeResponse, filterByPermissions, isMethodAllowed, isActionAllowed, computeConnectionAccess, } from './helpers.js';
 import { listOneIntegrationsToolConfig, searchOnePlatformActionsToolConfig, getOneActionKnowledgeToolConfig, executeOneActionToolConfig } from './schemas.js';
 const SERVER_NAME = "one-mcp-server";
 const SERVER_VERSION = "1.0.0";
@@ -212,6 +212,11 @@ async function handleGetActionKnowledge(args) {
             }
         }
         if (ONE_KNOWLEDGE_AGENT) {
+            // Knowledge/code-gen mode returns the full document: the appended
+            // Integration Code Guide tells the agent to reproduce the complete
+            // input and output structure, which the digest would defer. Digesting
+            // is for the execute flow below, where the agent only needs to build
+            // one request.
             const details = await oneClient.getActionDetails(actionId);
             const knowledgeWithGuide = buildKnowledgeModeGuidance(details, args.platform, oneClient.getBaseUrl());
             return {
@@ -224,14 +229,22 @@ async function handleGetActionKnowledge(args) {
             };
         }
         const { knowledge, method } = await oneClient.getActionKnowledge(actionId);
-        const knowledgeWithGuidance = buildActionKnowledgeWithGuidance(knowledge, method, oneClient.getBaseUrl(), args.platform, actionId);
+        const response = buildKnowledgeResponse(knowledge, method, args.platform, actionId, {
+            section: args.section,
+            full: args.full,
+            toc: args.toc,
+        });
+        const text = response.wrap
+            ? buildActionKnowledgeWithGuidance(response.text, method, oneClient.getBaseUrl(), args.platform, actionId)
+            : response.text;
         return {
             content: [
                 {
                     type: "text",
-                    text: knowledgeWithGuidance,
+                    text,
                 },
             ],
+            structuredContent: response.structured,
         };
     }
     catch (error) {

package/build/knowledge-response.test.js

@@ -0,0 +1,73 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { buildKnowledgeResponse } from './helpers.js';
+// Pure: string in, response out. No network, no home-directory access.
+const bigSection = (label) => `## ${label}\n` +
+    Array.from({ length: 120 }, (_, i) => `- ${label} field ${i}: descriptive text adding length to the section body.`).join('\n');
+const LARGE = [
+    '# Send Email',
+    '## Method\nPOST',
+    '## URL\n/gmail/v1/messages/send',
+    '## Headers\n- Authorization: Bearer',
+    '## Request Body\n### Required Request Body Fields\n- to: string\n- subject: string',
+    bigSection('Response Fields'),
+    bigSection('Success Response'),
+    bigSection('Optional Request Body Fields'),
+].join('\n\n');
+const SMALL = '# Tiny\n\n## Method\nGET\n\n## URL\n/x';
+describe('buildKnowledgeResponse', () => {
+    it('digests a large doc: request-building sections in full, omitted ones named in the envelope', () => {
+        const r = buildKnowledgeResponse(LARGE, 'POST', 'gmail', 'act_1', {});
+        assert.equal(r.wrap, true);
+        assert.equal(r.structured.truncated, true);
+        assert.ok(r.structured.omitted >= 1);
+        assert.ok(Array.isArray(r.structured.sections) && r.structured.sections.length >= 1);
+        assert.ok(r.text.includes('**Digest.**'));
+        assert.ok(r.text.includes('get_one_action_knowledge'));
+        // A deferred body is not inlined into the digest text.
+        assert.ok(!r.text.includes('Response Fields field 100'));
+        // No CLI-flag phrasing leaks into agent-visible text.
+        assert.ok(!/--section|one --agent|--full|--toc/.test(r.text));
+    });
+    it('returns the whole table of contents for toc, with no bodies', () => {
+        const r = buildKnowledgeResponse(LARGE, 'POST', 'gmail', 'act_1', { toc: true });
+        assert.equal(r.wrap, false);
+        assert.ok(r.structured.sections.length >= 5);
+        assert.ok(r.text.includes('[response-fields]'));
+        assert.ok(!r.text.includes('Response Fields field 100'));
+    });
+    it('returns a named section with its body and what it resolved to', () => {
+        const r = buildKnowledgeResponse(LARGE, 'POST', 'gmail', 'act_1', { section: 'Response Fields' });
+        assert.equal(r.wrap, false);
+        assert.deepEqual(r.structured.resolved.map((s) => s.heading), ['Response Fields']);
+        assert.ok(r.text.includes('Response Fields field 100'));
+    });
+    it('reports a not-found section with a bounded candidate list', () => {
+        const r = buildKnowledgeResponse(LARGE, 'POST', 'gmail', 'act_1', { section: 'nope' });
+        assert.equal(r.wrap, false);
+        assert.ok(r.structured.error);
+        assert.equal(r.structured.reason, 'not-found');
+        assert.ok(r.structured.sections.length >= 1);
+        assert.ok(r.text.startsWith('No section named "nope"'));
+    });
+    it('treats section: "all" and full: true as the verbatim whole document', () => {
+        for (const opts of [{ section: 'all' }, { full: true }]) {
+            const r = buildKnowledgeResponse(LARGE, 'POST', 'gmail', 'act_1', opts);
+            assert.equal(r.wrap, true);
+            assert.equal(r.text, LARGE);
+            assert.equal(r.structured.truncated, false);
+        }
+    });
+    it('returns a small doc verbatim with no digest', () => {
+        const r = buildKnowledgeResponse(SMALL, 'GET', 'gmail', 'act_1', {});
+        assert.equal(r.wrap, true);
+        assert.equal(r.text, SMALL);
+        assert.equal(r.structured.truncated, false);
+    });
+    it('section wins over full when both are set', () => {
+        const r = buildKnowledgeResponse(LARGE, 'POST', 'gmail', 'act_1', { section: 'Response Fields', full: true });
+        assert.equal(r.wrap, false);
+        assert.notEqual(r.text, LARGE);
+        assert.ok(r.text.includes('Response Fields field 100'));
+    });
+});

package/build/knowledge-sections.js

@@ -0,0 +1,558 @@
+/**
+ * Header-based sectioning for action knowledge markdown.
+ *
+ * The backend returns one markdown document per action. Half of them are under
+ * ~8k chars, but the tail is long (p90 ~17k, max ~370k) and the bulk of every
+ * large doc sits in three sections — `Success Response`, `Response Fields`, and
+ * `Optional Request Body Fields`. Agents pay per token, so
+ * `get_one_action_knowledge` hands back a *digest*: the sections needed to
+ * build a correct request in full, plus a table of contents for everything
+ * else. The agent asks for the rest by name (`section: "Response Fields"`) or
+ * for the whole document (`full: true`) on a follow-up call.
+ *
+ * Ported from withoneai/cli (`src/lib/knowledge-sections.ts`, PR #197). The
+ * parsing/classification/digest engine is identical; only the user-facing
+ * "how to load more" strings are adapted for the MCP tool. Keep the engine in
+ * sync when the cli module changes.
+ *
+ * Everything in this module is pure: string in, structure out. No I/O.
+ */
+export const DEFAULT_WHOLE_DOC_THRESHOLD = 8_000;
+export const DEFAULT_DIGEST_BUDGET = 8_000;
+export const DEFAULT_SECTION_CAP = 6_000;
+// ---------------------------------------------------------------------------
+// Parsing
+// ---------------------------------------------------------------------------
+const HEADING_RE = /^(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/;
+const FENCE_RE = /^\s*(```|~~~)/;
+export function slugify(heading) {
+    return heading
+        .toLowerCase()
+        .replace(/`/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'section';
+}
+/**
+ * Split markdown into a section tree keyed by ATX headings. Headings inside
+ * fenced code blocks are ignored. Setext (underlined) headings are not
+ * recognised — the backend never emits them.
+ */
+export function parseSections(markdown) {
+    // Normalise line endings up front: a CRLF document would otherwise leave a
+    // trailing `\r` on every line, which defeats the heading regex (`$` will not
+    // match before it) so nothing is recognised as a heading. Windows checkouts
+    // and some scraped docs carry CRLF, so this is a correctness fix, not just a
+    // test convenience.
+    const normalized = markdown.replace(/\r\n?/g, '\n');
+    const lines = normalized.split('\n');
+    const prefaceLines = [];
+    const blocks = [];
+    let inFence = false;
+    let fenceMarker = '';
+    for (const line of lines) {
+        const fence = FENCE_RE.exec(line);
+        if (fence) {
+            if (!inFence) {
+                inFence = true;
+                fenceMarker = fence[1];
+            }
+            else if (fence[1] === fenceMarker) {
+                inFence = false;
+            }
+        }
+        const m = !inFence ? HEADING_RE.exec(line) : null;
+        if (m) {
+            blocks.push({ level: m[1].length, heading: m[2].trim(), lines: [line] });
+            continue;
+        }
+        if (blocks.length === 0)
+            prefaceLines.push(line);
+        else
+            blocks[blocks.length - 1].lines.push(line);
+    }
+    const usedIds = new Set();
+    const nodes = blocks.map((b) => {
+        const base = slugify(b.heading);
+        let id = base;
+        for (let n = 2; usedIds.has(id); n++)
+            id = `${base}-${n}`;
+        usedIds.add(id);
+        return {
+            id,
+            heading: b.heading,
+            level: b.level,
+            text: b.lines.join('\n'),
+            chars: 0,
+            tier: classifyHeading(b.heading),
+            children: [],
+        };
+    });
+    // Build the tree by level. The first heading, when it is an H1, is the title;
+    // its children are promoted so the document's H2s are the top-level sections.
+    const root = [];
+    const stack = [];
+    let title = '';
+    let titleNode = null;
+    for (const node of nodes) {
+        while (stack.length && stack[stack.length - 1].level >= node.level)
+            stack.pop();
+        if (stack.length)
+            stack[stack.length - 1].children.push(node);
+        else
+            root.push(node);
+        stack.push(node);
+    }
+    if (root.length && nodes[0].level === 1 && root[0] === nodes[0]) {
+        titleNode = root.shift();
+        title = titleNode.heading;
+        root.unshift(...titleNode.children);
+        titleNode.children = [];
+    }
+    // Any text under the title heading itself (before the first H2) becomes preface.
+    let preface = prefaceLines.join('\n').trim();
+    if (titleNode) {
+        const own = titleNode.text.split('\n').slice(1).join('\n').trim();
+        if (own)
+            preface = preface ? `${preface}\n\n${own}` : own;
+    }
+    const measure = (n) => {
+        n.chars = n.text.length + n.children.reduce((sum, c) => sum + measure(c), 0);
+        return n.chars;
+    };
+    root.forEach(measure);
+    return { title, preface, sections: root, chars: normalized.length };
+}
+/** Full markdown for a section including its nested children. */
+export function sectionText(section) {
+    const parts = [section.text, ...section.children.map(sectionText)];
+    return parts.join('\n').replace(/\n+$/, '');
+}
+export function flattenSections(sections) {
+    const out = [];
+    const walk = (list) => {
+        for (const s of list) {
+            out.push(s);
+            walk(s.children);
+        }
+    };
+    walk(sections);
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Classification
+// ---------------------------------------------------------------------------
+/** Lower-case, strip a trailing parenthetical like "(200 OK)" or "(application/json)". */
+export function canonicalHeading(heading) {
+    return heading
+        .toLowerCase()
+        .replace(/\s*\([^)]*\)\s*$/, '')
+        .replace(/[`*_]/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+const ESSENTIAL_EXACT = new Set([
+    'prerequisites',
+    'method',
+    'url',
+    'endpoint',
+    'headers',
+    'description',
+    'enforcement rules',
+    'valid examples',
+    'invalid examples',
+    'request body',
+    'sample request',
+    'gotchas',
+    'error handling',
+    'graphql operation',
+    'graphql arguments',
+    'request variables',
+    'variables',
+    'path parameters',
+    'query parameters',
+    'parameters',
+    'arguments',
+]);
+const ESSENTIAL_PREFIX = ['required '];
+/**
+ * Essential sections are what an agent needs to build a correct request.
+ * Everything else — response shapes, optional fields, worked examples, prose —
+ * is deferred and listed in the table of contents.
+ */
+export function classifyHeading(heading) {
+    const c = canonicalHeading(heading);
+    if (ESSENTIAL_EXACT.has(c))
+        return 'essential';
+    if (ESSENTIAL_PREFIX.some((p) => c.startsWith(p)))
+        return 'essential';
+    return 'deferred';
+}
+/** Priority for back-filling deferred sections into spare budget (lower = sooner). */
+function deferredPriority(heading) {
+    const c = canonicalHeading(heading);
+    if (c.startsWith('optional '))
+        return 0;
+    if (c === 'behavior' || c === 'behaviour')
+        return 1;
+    if (c === 'notes')
+        return 2;
+    if (c === 'example usage' || c.startsWith('example'))
+        return 3;
+    if (c === 'response fields')
+        return 5;
+    if (c === 'response' || c.startsWith('success response') || c.startsWith('error response'))
+        return 6;
+    return 4;
+}
+function truncateText(text, cap, id) {
+    const cut = text.slice(0, cap);
+    // Back up to a line boundary so we never split a table row or code fence mid-way.
+    const nl = cut.lastIndexOf('\n');
+    const head = nl > cap * 0.5 ? cut.slice(0, nl) : cut;
+    const remaining = text.length - head.length;
+    return `${head}\n\n_[truncated — ${remaining.toLocaleString('en-US')} more chars. Load the full section by calling get_one_action_knowledge again with section: "${id}"]_`;
+}
+/**
+ * Build the digest: essential sections in full (capped), then deferred
+ * sections back-filled in priority order while they fit the budget, then a
+ * table of contents for what was left out.
+ */
+export function buildDigest(doc, opts = {}) {
+    const wholeThreshold = opts.wholeDocThreshold ?? DEFAULT_WHOLE_DOC_THRESHOLD;
+    const budget = opts.budget ?? DEFAULT_DIGEST_BUDGET;
+    const cap = opts.sectionCap ?? DEFAULT_SECTION_CAP;
+    const flat = flattenSections(doc.sections);
+    const whole = () => ({
+        markdown: renderWhole(doc),
+        truncated: false,
+        sections: flat.map((s) => summary(s, true)),
+        omitted: 0,
+        omittedChars: 0,
+    });
+    // Nothing to section on, or small enough that a second round trip costs more than it saves.
+    if (flat.length === 0 || doc.chars <= wholeThreshold)
+        return whole();
+    const decisions = new Map();
+    let used = doc.title ? doc.title.length + 4 : 0;
+    used += doc.preface.length;
+    // Pass 1: essentials. A deferred child of an essential parent (e.g. Optional
+    // fields under a custom action's `Request Body`) stays deferred — unless it is
+    // a sub-section (H3+) that itself contains essentials, such as Notion's
+    // `Request Body > Option B > Required Request Body Fields`. Then its own text
+    // is kept as scaffolding and its children are decided individually. H1/H2
+    // deferred nodes (appended schema chunks, companion endpoints) go wholesale.
+    const hasEssentialDescendant = (n) => n.children.some((c) => c.tier === 'essential' || hasEssentialDescendant(c));
+    const walk = (list) => {
+        for (const node of list) {
+            if (node.tier === 'essential' || (node.level >= 3 && hasEssentialDescendant(node))) {
+                const own = node.text;
+                if (own.length > cap) {
+                    const render = truncateText(own, cap, node.id);
+                    decisions.set(node.id, { node, included: 'partial', render });
+                    used += render.length;
+                }
+                else {
+                    decisions.set(node.id, { node, included: true, render: own });
+                    used += own.length;
+                }
+                walk(node.children);
+            }
+            else {
+                decisions.set(node.id, { node, included: false, render: '' });
+                // Children of a deferred node are deferred wholesale.
+                for (const c of flattenSections(node.children))
+                    decisions.set(c.id, { node: c, included: false, render: '' });
+            }
+        }
+    };
+    walk(doc.sections);
+    // Pass 2: back-fill deferred subtrees whose *parent* is included or top-level,
+    // smallest priority first, while they fit whole. Extra H1s (appended schema
+    // chunks, companion endpoints) are never back-filled: pulling three random
+    // schema types into the digest would mislead more than it helps.
+    const candidates = flat
+        .filter((s) => decisions.get(s.id)?.included === false)
+        .filter((s) => s.level >= 2)
+        .filter((s) => {
+        const parent = parentOf(doc.sections, s);
+        return !parent || decisions.get(parent.id)?.included !== false;
+    })
+        .sort((a, b) => deferredPriority(a.heading) - deferredPriority(b.heading) || a.chars - b.chars);
+    for (const s of candidates) {
+        if (used + s.chars > budget)
+            continue;
+        for (const n of [s, ...flattenSections(s.children)]) {
+            decisions.set(n.id, { node: n, included: true, render: n.text });
+        }
+        used += s.chars;
+    }
+    // If everything ended up included, the doc fits — return it whole.
+    const allIn = flat.every((s) => decisions.get(s.id)?.included === true);
+    if (allIn)
+        return whole();
+    // Render in document order.
+    const out = [];
+    if (doc.title)
+        out.push(`# ${doc.title}`);
+    if (doc.preface)
+        out.push(doc.preface);
+    for (const s of flat) {
+        const d = decisions.get(s.id);
+        if (d.included !== false)
+            out.push(d.render.replace(/\n+$/, ''));
+    }
+    const sections = flat.map((s) => summary(s, decisions.get(s.id).included));
+    // Chars the agent has not seen: whole omitted subtrees (counted once, at the
+    // top-most omitted node) plus the cut tail of every partial section.
+    const topOmitted = flat.filter((s) => {
+        if (decisions.get(s.id).included !== false)
+            return false;
+        const parent = parentOf(doc.sections, s);
+        return !parent || decisions.get(parent.id).included !== false;
+    });
+    const omittedChars = topOmitted.reduce((sum, s) => sum + s.chars, 0) +
+        flat
+            .filter((s) => decisions.get(s.id).included === 'partial')
+            .reduce((sum, s) => sum + (s.text.length - decisions.get(s.id).render.length), 0);
+    return {
+        markdown: out.join('\n\n'),
+        truncated: true,
+        sections,
+        omitted: topOmitted.length + flat.filter((s) => decisions.get(s.id).included === 'partial').length,
+        omittedChars: Math.max(0, omittedChars),
+    };
+}
+function summary(s, included) {
+    return { id: s.id, heading: s.heading, level: s.level, chars: s.chars, included };
+}
+function parentOf(roots, target) {
+    const find = (list, parent) => {
+        for (const n of list) {
+            if (n === target)
+                return parent;
+            const r = find(n.children, n);
+            if (r !== undefined)
+                return r;
+        }
+        return undefined;
+    };
+    return find(roots, null) ?? null;
+}
+export function renderWhole(doc) {
+    const out = [];
+    if (doc.title)
+        out.push(`# ${doc.title}`);
+    if (doc.preface)
+        out.push(doc.preface);
+    for (const s of doc.sections)
+        out.push(sectionText(s));
+    return out.join('\n\n');
+}
+export const DEFAULT_TOC_MAX_ENTRIES = 60;
+/**
+ * Shrink a table of contents for the JSON envelope. Scraped mega-docs can
+ * carry 400+ headings (45 KB of metadata — more than the digest itself), so
+ * the list is cut to the shallowest heading depth that fits `max` entries.
+ * Hidden descendants are counted on their nearest surviving ancestor; the
+ * full list is one `--toc` call away.
+ */
+export function collapseSections(sections, max = DEFAULT_TOC_MAX_ENTRIES) {
+    if (sections.length <= max)
+        return { sections, collapsed: false };
+    // The action doc proper is everything before the first extra H1; what
+    // follows is appended scrape chunks / companion endpoints. The canonical
+    // part keeps its H2s (and H3s when they fit); the appendix collapses to
+    // its H1s no matter what — those are the entries nobody needs to see.
+    const firstH1 = sections.findIndex((s) => s.level === 1);
+    const canonEnd = firstH1 === -1 ? sections.length : firstH1;
+    for (const depth of [3, 2]) {
+        const keep = (s, i) => (i < canonEnd ? s.level <= depth : s.level <= 1);
+        const count = sections.filter(keep).length;
+        if (count > max && depth !== 2)
+            continue;
+        const out = [];
+        let owner = null;
+        sections.forEach((s, i) => {
+            if (keep(s, i)) {
+                owner = { ...s };
+                out.push(owner);
+            }
+            else if (owner) {
+                owner.children = (owner.children ?? 0) + 1;
+            }
+        });
+        return { sections: out, collapsed: true };
+    }
+    return { sections, collapsed: false };
+}
+/**
+ * The table of contents for the JSON envelope: only what the digest left
+ * out. Included sections are already visible as headings in the markdown, so
+ * listing them again cost ~1.9k chars per response — enough to make the
+ * median (small) doc *larger* than before. Collapsed for mega-docs.
+ */
+export function omittedSections(digest, max = DEFAULT_TOC_MAX_ENTRIES) {
+    return collapseSections(digest.sections.filter((s) => s.included !== true), max);
+}
+/**
+ * The trailer appended to a digest so an agent that only reads the markdown
+ * (and never looks at the JSON envelope) still knows the document continues.
+ */
+export function renderDigestNotice(digest, platform, actionId) {
+    if (!digest.truncated)
+        return '';
+    // List only the top-most omitted sections: in document order the nearest
+    // preceding section with a lower level is the parent, and children of an
+    // omitted parent are implied by it.
+    const topMost = digest.sections.filter((s, idx) => {
+        if (s.included === true)
+            return false;
+        for (let i = idx - 1; i >= 0; i--) {
+            const prev = digest.sections[i];
+            if (prev.level < s.level)
+                return prev.included !== false;
+        }
+        return true;
+    });
+    // Extra H1s are appended scrape chunks or companion endpoints, not part of
+    // the action doc proper — say so, or "Append Block Children" showing up as
+    // omitted reads as if the core doc itself were missing.
+    const names = topMost.map((s) => {
+        if (s.included === 'partial')
+            return `${s.heading} (partial)`;
+        if (s.level === 1)
+            return `${s.heading} (appendix)`;
+        return s.heading;
+    });
+    // A scraped mega-doc can omit 30+ sections; naming a dozen is enough to
+    // orient the agent, the rest are reachable by name on a follow-up call.
+    const MAX_NAMES = 12;
+    const shown = names.slice(0, MAX_NAMES);
+    const rest = names.length - shown.length;
+    const nameList = rest > 0 ? `${shown.join(', ')}, and ${rest} more` : shown.join(', ');
+    return [
+        '---',
+        `**This is a digest, not the full document.** ${topMost.length} section${topMost.length === 1 ? '' : 's'} omitted (${digest.omittedChars.toLocaleString('en-US')} chars): ${nameList}.`,
+        `Load one or more by calling get_one_action_knowledge again for ${platform} / ${actionId} with section: "${topMost[0]?.heading ?? 'Response'}" (comma-separate several).`,
+        `Load the whole document with full: true.`,
+    ].join('\n');
+}
+/**
+ * One line for the *top* of a digest, so an agent that reads the beginning of
+ * the markdown and stops early still learns the document continues.
+ */
+export function renderDigestBanner(digest) {
+    if (!digest.truncated)
+        return '';
+    return `> **Digest.** ${digest.omitted} section${digest.omitted === 1 ? '' : 's'} (${digest.omittedChars.toLocaleString('en-US')} chars) omitted: response shapes, reference schemas, or worked examples. The notice at the end names them and shows how to load them.`;
+}
+/** Short names agents are likely to type. Each maps to a predicate over the canonical heading. */
+const ALIASES = {
+    response: (c) => c === 'response',
+    responses: (c) => c === 'response',
+    'response fields': (c) => c === 'response fields',
+    fields: (c) => c === 'response fields',
+    optional: (c) => c.startsWith('optional '),
+    required: (c) => c.startsWith('required '),
+    examples: (c) => c === 'example usage' || c === 'examples',
+    example: (c) => c === 'example usage' || c === 'examples',
+    errors: (c) => c.startsWith('error response') || c === 'error handling',
+    success: (c) => c.startsWith('success response'),
+    body: (c) => c === 'request body' || c.endsWith('request body fields'),
+    query: (c) => c.endsWith('query parameters'),
+    path: (c) => c.endsWith('path parameters'),
+    notes: (c) => c === 'notes',
+    behavior: (c) => c === 'behavior' || c === 'behaviour',
+    gotchas: (c) => c === 'gotchas',
+};
+function normalizeQuery(q) {
+    return q.trim().replace(/^["'`]+|["'`]+$/g, '').toLowerCase().replace(/\s+/g, ' ');
+}
+/**
+ * Resolve one user-supplied name to sections. Match order: exact id, exact
+ * heading, alias, slug prefix / heading prefix, substring. Prefix and
+ * substring matches must be unique; aliases may return several.
+ */
+export function findSections(doc, query) {
+    const flat = flattenSections(doc.sections);
+    const q = normalizeQuery(query);
+    const qSlug = slugify(q);
+    const miss = (reason, candidates) => ({
+        ok: false,
+        reason,
+        query,
+        candidates: candidates.map((s) => summary(s, false)),
+    });
+    if (!q)
+        return miss('not-found', flat);
+    // Exact id and exact heading together: a doc with two `## Response`
+    // headings (id `response` and `response-2`) should return both, not
+    // silently the first.
+    const exact = flat.filter((s) => s.id === qSlug || canonicalHeading(s.heading) === q || s.heading.toLowerCase() === q);
+    if (exact.length)
+        return { ok: true, sections: exact };
+    const alias = ALIASES[q];
+    if (alias) {
+        const hits = flat.filter((s) => alias(canonicalHeading(s.heading)));
+        if (hits.length)
+            return { ok: true, sections: dropNested(hits) };
+    }
+    const byPrefix = flat.filter((s) => s.id.startsWith(qSlug) || canonicalHeading(s.heading).startsWith(q));
+    if (byPrefix.length === 1)
+        return { ok: true, sections: byPrefix };
+    if (byPrefix.length > 1) {
+        // "error response" should match every error response block, not be ambiguous.
+        const sameCanon = new Set(byPrefix.map((s) => canonicalHeading(s.heading).replace(/\s*\d.*$/, '')));
+        if (sameCanon.size === 1)
+            return { ok: true, sections: dropNested(byPrefix) };
+        return miss('ambiguous', byPrefix);
+    }
+    const bySubstring = flat.filter((s) => s.id.includes(qSlug) || canonicalHeading(s.heading).includes(q));
+    if (bySubstring.length === 1)
+        return { ok: true, sections: bySubstring };
+    if (bySubstring.length > 1)
+        return miss('ambiguous', bySubstring);
+    return miss('not-found', flat);
+}
+/** If a hit's ancestor is also a hit, drop the descendant — its text is already inside the ancestor. */
+function dropNested(hits) {
+    const inside = new Set();
+    for (const h of hits)
+        for (const c of flattenSections(h.children))
+            inside.add(c.id);
+    return hits.filter((h) => !inside.has(h.id));
+}
+/**
+ * Resolve a comma-separated `--section` value. Every name must resolve; the
+ * first failure is returned so the agent can correct it.
+ */
+export function selectSections(doc, names) {
+    const picked = [];
+    const seen = new Set();
+    for (const name of names) {
+        const r = findSections(doc, name);
+        if (!r.ok)
+            return r;
+        for (const s of dropNested(r.sections)) {
+            if (!seen.has(s.id)) {
+                seen.add(s.id);
+                picked.push(s);
+            }
+        }
+    }
+    // Document order, and drop anything nested inside another pick.
+    const order = new Map(flattenSections(doc.sections).map((s, i) => [s.id, i]));
+    const final = dropNested(picked).sort((a, b) => order.get(a.id) - order.get(b.id));
+    const parts = [doc.title ? `# ${doc.title}` : '', ...final.map(sectionText)].filter(Boolean);
+    return { ok: true, sections: final, markdown: parts.join('\n\n') };
+}
+/** Split a `--section` flag value (repeatable, comma-separated) into names. */
+export function parseSectionFlag(value) {
+    if (!value)
+        return [];
+    const raw = Array.isArray(value) ? value : [value];
+    return raw
+        .flatMap((v) => v.split(','))
+        .map((v) => v.trim())
+        .filter(Boolean);
+}

package/build/knowledge-sections.test.js

@@ -0,0 +1,359 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseSections, buildDigest, renderWhole, renderDigestNotice, renderDigestBanner, collapseSections, omittedSections, findSections, selectSections, parseSectionFlag, classifyHeading, flattenSections, sectionText, slugify, } from './knowledge-sections.js';
+// Pure string-in/structure-out module: no home-directory access, no sandbox needed.
+const fixturesDir = path.join(path.dirname(fileURLToPath(import.meta.url)), 'test-support', 'fixtures');
+const fixture = (name) => fs.readFileSync(path.join(fixturesDir, name), 'utf-8');
+const GITHUB = fixture('knowledge-github-create-issue.md'); // ~25k, canonical template
+const STRIPE = fixture('knowledge-stripe-create-customer.md'); // ~10k, canonical template
+const GMAIL = fixture('knowledge-gmail-send-email.md'); // ~10k, custom-action template
+describe('parseSections', () => {
+    it('takes the first H1 as the title and promotes its H2s to top level', () => {
+        const doc = parseSections(GITHUB);
+        assert.equal(doc.title, 'Create an Issue for a Repository');
+        assert.equal(doc.preface, '');
+        assert.deepEqual(doc.sections.map((s) => s.heading).slice(0, 6), ['Prerequisites', 'Method', 'URL', 'Headers', 'Description', 'Enforcement Rules']);
+        assert.ok(doc.sections.every((s) => s.level === 2));
+    });
+    it('parses a CRLF document identically to LF (Windows checkouts, scraped docs)', () => {
+        const lf = GITHUB.replace(/\r\n?/g, '\n');
+        const crlf = lf.replace(/\n/g, '\r\n');
+        // Without normalisation the trailing \r defeats the heading regex, so the
+        // title is empty and nothing is sectioned.
+        assert.equal(parseSections(crlf).title, 'Create an Issue for a Repository');
+        assert.deepEqual(parseSections(crlf), parseSections(lf));
+    });
+    it('nests H3s under their H2', () => {
+        const doc = parseSections(GITHUB);
+        const response = doc.sections.find((s) => s.heading === 'Response');
+        assert.equal(response.children.length, 7);
+        assert.equal(response.children[0].heading, 'Success Response (201 Created)');
+        assert.ok(response.children.slice(1).every((c) => c.heading.startsWith('Error Response')));
+    });
+    it('handles the custom-action template (Endpoint + Request Body with H3 children)', () => {
+        const doc = parseSections(GMAIL);
+        assert.equal(doc.title, 'Send Email');
+        const body = doc.sections.find((s) => s.heading === 'Request Body');
+        assert.deepEqual(body.children.map((c) => c.heading), ['Required Request Body Fields', 'Optional Request Body Fields']);
+    });
+    it('round-trips: rendering the whole tree reproduces the source text', () => {
+        for (const src of [GITHUB, STRIPE, GMAIL]) {
+            const doc = parseSections(src);
+            // Rendering joins blocks with a blank line and parseSections normalises
+            // CRLF to LF, so compare modulo blank-line runs and line-ending style.
+            const norm = (s) => s.replace(/\r\n?/g, '\n').replace(/\n{2,}/g, '\n').trim();
+            assert.equal(norm(renderWhole(doc)), norm(src));
+        }
+    });
+    it('ignores # lines inside fenced code blocks', () => {
+        const md = ['# T', '', '## Real', '```bash', '# not a heading', '~~~ still inside', '```', 'after', '## Next', ''].join('\n');
+        const doc = parseSections(md);
+        assert.deepEqual(doc.sections.map((s) => s.heading), ['Real', 'Next']);
+        assert.ok(doc.sections[0].text.includes('# not a heading'));
+    });
+    it('keeps a second H1 as a top-level section rather than a new title', () => {
+        const md = '# One\n\n## A\ntext\n\n# Two\n\n## B\nmore\n';
+        const doc = parseSections(md);
+        assert.equal(doc.title, 'One');
+        assert.deepEqual(doc.sections.map((s) => `${s.level}:${s.heading}`), ['2:A', '1:Two']);
+        assert.equal(doc.sections[1].children[0].heading, 'B');
+    });
+    it('returns no sections and an empty title for text without headings', () => {
+        const doc = parseSections('just prose\nno headings');
+        assert.equal(doc.title, '');
+        assert.equal(doc.sections.length, 0);
+        assert.equal(doc.preface, 'just prose\nno headings');
+    });
+    it('de-duplicates ids and slugs headings predictably', () => {
+        assert.equal(slugify('Success Response (201 Created)'), 'success-response-201-created');
+        assert.equal(slugify('Optional Request Body Fields (application/x-www-form-urlencoded)'), 'optional-request-body-fields-application-x-www-form-urlencoded');
+        const doc = parseSections('# T\n## Notes\n## Notes\n## Notes\n');
+        assert.deepEqual(doc.sections.map((s) => s.id), ['notes', 'notes-2', 'notes-3']);
+    });
+    it('measures chars including children', () => {
+        const doc = parseSections(GITHUB);
+        const response = doc.sections.find((s) => s.heading === 'Response');
+        assert.equal(response.chars, sectionText(response).length + 0 || response.chars);
+        assert.ok(response.chars > 15_000, `response subtree is ${response.chars}`);
+        const total = doc.sections.reduce((n, s) => n + s.chars, 0);
+        assert.ok(total <= GITHUB.length && total > GITHUB.length * 0.95);
+    });
+});
+describe('classifyHeading', () => {
+    it('marks request-building sections essential and the size drivers deferred', () => {
+        const essential = ['Method', 'URL', 'Endpoint', 'Headers', 'Description', 'Prerequisites', 'Enforcement Rules',
+            'Required Path Parameters', 'Required Request Body Fields', 'Required Query Parameters', 'Request Body',
+            'Sample Request', 'Gotchas', 'Error Handling'];
+        const deferred = ['Response', 'Success Response (201 Created)', 'Error Response (404 Not Found)', 'Response Fields',
+            'Optional Request Body Fields', 'Optional Request Body Fields (application/x-www-form-urlencoded)',
+            'Optional Query Parameters', 'Example Usage', 'Example 1: Simple Message', 'Behavior', 'Notes', 'Document.footnotes'];
+        for (const h of essential)
+            assert.equal(classifyHeading(h), 'essential', h);
+        for (const h of deferred)
+            assert.equal(classifyHeading(h), 'deferred', h);
+    });
+});
+describe('buildDigest', () => {
+    it('returns small documents whole, untruncated, with every section flagged included', () => {
+        const doc = parseSections(STRIPE);
+        const d = buildDigest(doc, { wholeDocThreshold: 20_000 });
+        assert.equal(d.truncated, false);
+        assert.equal(d.omitted, 0);
+        assert.equal(d.omittedChars, 0);
+        assert.ok(d.sections.every((s) => s.included === true));
+        assert.equal(d.sections.length, flattenSections(doc.sections).length);
+        assert.ok(d.markdown.includes('## Optional Request Body Fields'));
+    });
+    it('returns a document with no headings whole', () => {
+        const d = buildDigest(parseSections('a'.repeat(50_000)));
+        assert.equal(d.truncated, false);
+        assert.equal(d.markdown.length, 50_000);
+    });
+    it('keeps essentials, defers the big Response block, and lists everything omitted', () => {
+        const doc = parseSections(GITHUB);
+        const d = buildDigest(doc);
+        assert.equal(d.truncated, true);
+        assert.ok(d.markdown.length < GITHUB.length / 2, `digest is ${d.markdown.length} of ${GITHUB.length}`);
+        const status = Object.fromEntries(d.sections.map((s) => [s.heading, s.included]));
+        for (const h of ['Prerequisites', 'Method', 'URL', 'Headers', 'Description', 'Enforcement Rules',
+            'Required Path Parameters', 'Required Request Body Fields', 'Sample Request', 'Gotchas', 'Error Handling']) {
+            assert.equal(status[h], true, h);
+        }
+        assert.equal(status['Success Response (201 Created)'], false);
+        assert.equal(status['Response Fields'], false);
+        assert.ok(!d.markdown.includes('### Success Response (201 Created)'));
+        assert.ok(d.markdown.includes('## Required Request Body Fields'));
+        // The TOC covers every section, not just the omitted ones.
+        assert.equal(d.sections.length, flattenSections(doc.sections).length);
+        assert.ok(d.omitted > 0);
+        assert.ok(d.omittedChars > 15_000);
+    });
+    it('back-fills deferred sections in priority order while they fit the budget', () => {
+        const doc = parseSections(GITHUB);
+        const d = buildDigest(doc, { wholeDocThreshold: 0, budget: 8_000 });
+        const status = Object.fromEntries(d.sections.map((s) => [s.heading, s.included]));
+        // Optional fields (~1k) fit and are the first to be pulled back in.
+        assert.equal(status['Optional Request Body Fields'], true);
+        // The 15k success response never fits an 8k budget.
+        assert.equal(status['Success Response (201 Created)'], false);
+        const tight = buildDigest(doc, { wholeDocThreshold: 0, budget: 0 });
+        const tightStatus = Object.fromEntries(tight.sections.map((s) => [s.heading, s.included]));
+        assert.equal(tightStatus['Optional Request Body Fields'], false);
+        assert.equal(tightStatus['Method'], true, 'essentials survive a zero budget');
+    });
+    it('cuts an oversized essential section and marks it partial', () => {
+        const big = '# T\n\n## Method\nPOST\n\n## Required Request Body Fields\n' + '| a | b |\n'.repeat(2_000) + '\n## Notes\nn\n';
+        const doc = parseSections(big);
+        const d = buildDigest(doc, { wholeDocThreshold: 0, sectionCap: 500, budget: 0 });
+        const req = d.sections.find((s) => s.heading === 'Required Request Body Fields');
+        assert.equal(req.included, 'partial');
+        assert.ok(d.markdown.includes('_[truncated'));
+        assert.ok(d.markdown.includes('section: "required-request-body-fields"'));
+        assert.ok(d.truncated);
+        assert.ok(d.omittedChars > 15_000);
+    });
+    it('keeps essential children of an essential parent but defers deferred children (custom template)', () => {
+        const doc = parseSections(GMAIL);
+        const d = buildDigest(doc, { wholeDocThreshold: 0, budget: 0 });
+        const status = Object.fromEntries(d.sections.map((s) => [s.heading, s.included]));
+        assert.equal(status['Request Body'], true);
+        assert.equal(status['Required Request Body Fields'], true);
+        assert.equal(status['Optional Request Body Fields'], false);
+        assert.ok(d.markdown.includes('### Required Request Body Fields'));
+        assert.ok(!d.markdown.includes('### Optional Request Body Fields'));
+    });
+    it('keeps required fields nested under a deferred sub-heading (Notion option layout)', () => {
+        const md = [
+            '# Update Page', '', '## Method', 'PATCH', '', '## Request Body', 'Pick one option.', '',
+            '### Option A: Replace everything', '#### Required Request Body Fields (Replace)', '| a |', '#### Optional Fields (Replace)', '| opt |',
+            '### Option B: Search and replace', 'intro b', '#### Required Fields inside `update_content`', '| b |', '#### Examples for B', 'ex',
+            '## Response', 'x'.repeat(9_000), '',
+        ].join('\n');
+        const d = buildDigest(parseSections(md), { wholeDocThreshold: 0, budget: 0 });
+        const st = Object.fromEntries(d.sections.map((s) => [s.heading, s.included]));
+        assert.equal(st['Option A: Replace everything'], true, 'scaffolding kept');
+        assert.equal(st['Required Request Body Fields (Replace)'], true);
+        assert.equal(st['Optional Fields (Replace)'], false);
+        assert.equal(st['Option B: Search and replace'], true);
+        assert.equal(st['Required Fields inside `update_content`'], true);
+        assert.equal(st['Examples for B'], false);
+        assert.equal(st['Response'], false);
+        assert.ok(d.markdown.includes('intro b'));
+        assert.ok(!d.markdown.includes('| opt |'));
+    });
+    it('never back-fills appended H1 chunks even when they would fit the budget', () => {
+        const md = [
+            '# Action', '', '## Method', 'POST', '', '## Response', 'r'.repeat(9_000), '',
+            '# Data Models — Chunk 2/7', '', '# TinyType', '## Description', 'small', '## Fields', '| f |', '',
+        ].join('\n');
+        const d = buildDigest(parseSections(md), { wholeDocThreshold: 0, budget: 100_000 });
+        const st = Object.fromEntries(d.sections.map((s) => [s.heading, s.included]));
+        assert.equal(st['Response'], true, 'H2 deferred sections are back-filled');
+        assert.equal(st['TinyType'], false, 'appendix H1s are not');
+        assert.equal(st['Data Models — Chunk 2/7'], false);
+        assert.ok(d.truncated);
+    });
+    it('treats GraphQL request-building headings as essential', () => {
+        for (const h of ['GraphQL Operation', 'Request Variables', 'Path Parameters', 'Query Parameters']) {
+            assert.equal(classifyHeading(h), 'essential', h);
+        }
+        assert.equal(classifyHeading('Type'), 'deferred');
+    });
+    it('falls back to the whole document when the digest would include everything anyway', () => {
+        const doc = parseSections(STRIPE);
+        const d = buildDigest(doc, { wholeDocThreshold: 0, budget: 1_000_000 });
+        assert.equal(d.truncated, false);
+        assert.equal(d.markdown, renderWhole(doc));
+    });
+});
+describe('renderDigestNotice', () => {
+    it('is empty for an untruncated digest', () => {
+        const d = buildDigest(parseSections(STRIPE), { wholeDocThreshold: 1_000_000 });
+        assert.equal(renderDigestNotice(d, 'stripe', 'id'), '');
+    });
+    it('names only top-most omitted sections and shows both load commands', () => {
+        const d = buildDigest(parseSections(GITHUB), { wholeDocThreshold: 0, budget: 0 });
+        const notice = renderDigestNotice(d, 'github', 'conn_mod_def::X::Y');
+        assert.match(notice, /This is a digest, not the full document/);
+        assert.match(notice, /get_one_action_knowledge again for github \/ conn_mod_def::X::Y with section: "/);
+        assert.match(notice, /full: true/);
+        assert.ok(notice.includes('Response,') || notice.includes('Response.'), 'lists the omitted Response parent');
+        assert.ok(!notice.includes('Success Response (201 Created)'), 'children of an omitted parent are implied');
+        assert.ok(notice.includes('Response Fields'));
+    });
+});
+describe('renderDigestBanner', () => {
+    it('is empty when nothing was omitted and one line otherwise', () => {
+        assert.equal(renderDigestBanner(buildDigest(parseSections(STRIPE), { wholeDocThreshold: 1_000_000 })), '');
+        const b = renderDigestBanner(buildDigest(parseSections(GITHUB), { wholeDocThreshold: 0, budget: 0 }));
+        assert.match(b, /^> \*\*Digest\.\*\* \d+ sections \([\d,]+ chars\) omitted/);
+        assert.ok(!b.includes('\n'));
+    });
+});
+describe('collapseSections', () => {
+    const mk = (level, i) => ({ id: `s${i}`, heading: `H${i}`, level, chars: 10, included: false });
+    it('leaves a short list alone', () => {
+        const list = [mk(2, 1), mk(3, 2), mk(2, 3)];
+        const r = collapseSections(list, 60);
+        assert.equal(r.collapsed, false);
+        assert.equal(r.sections, list);
+    });
+    it('drops the deepest levels first and counts hidden descendants on the surviving ancestor', () => {
+        // 5 H2s, each with 20 H3s = 105 entries
+        const list = [];
+        let i = 0;
+        for (let a = 0; a < 5; a++) {
+            list.push(mk(2, i++));
+            for (let b = 0; b < 20; b++)
+                list.push(mk(3, i++));
+        }
+        const r = collapseSections(list, 60);
+        assert.equal(r.collapsed, true);
+        assert.equal(r.sections.length, 5);
+        assert.ok(r.sections.every((s) => s.level === 2 && s.children === 20));
+    });
+    it('collapses the real 400-heading Notion-style tree to a manageable size', () => {
+        // Synthesise: canonical doc + 40 appended H1 chunks each with 10 H2s.
+        const parts = ['# Big', '## Method', 'POST', '## Response', 'r'];
+        for (let c = 0; c < 40; c++) {
+            parts.push(`# Chunk ${c}`);
+            for (let h = 0; h < 10; h++)
+                parts.push(`## Type ${c}-${h}`, 'x');
+        }
+        const d = buildDigest(parseSections(parts.join('\n')), { wholeDocThreshold: 0 });
+        assert.equal(d.sections.length, 442);
+        const r = collapseSections(d.sections);
+        assert.ok(r.collapsed);
+        assert.equal(r.sections.length, 42, 'title-level H2s and the 40 chunk H1s');
+        const chunk = r.sections.find((s) => s.heading === 'Chunk 3');
+        assert.equal(chunk.children, 10);
+    });
+});
+describe('omittedSections', () => {
+    it('lists only what the digest left out', () => {
+        const d = buildDigest(parseSections(GITHUB), { wholeDocThreshold: 0, budget: 0 });
+        const o = omittedSections(d);
+        assert.equal(o.collapsed, false);
+        assert.ok(o.sections.length > 0 && o.sections.length < d.sections.length);
+        assert.ok(o.sections.every((s) => s.included !== true));
+        assert.ok(o.sections.some((s) => s.id === 'response-fields'));
+        assert.ok(!o.sections.some((s) => s.id === 'method'));
+    });
+    it('is empty for an untruncated digest', () => {
+        assert.deepEqual(omittedSections(buildDigest(parseSections(STRIPE), { wholeDocThreshold: 1_000_000 })).sections, []);
+    });
+});
+describe('findSections / selectSections', () => {
+    const doc = parseSections(GITHUB);
+    const headings = (r) => (r.ok ? r.sections.map((s) => s.heading) : r);
+    it('matches by id, exact heading, and case-insensitive heading', () => {
+        assert.deepEqual(headings(findSections(doc, 'response-fields')), ['Response Fields']);
+        assert.deepEqual(headings(findSections(doc, 'Response Fields')), ['Response Fields']);
+        assert.deepEqual(headings(findSections(doc, '"response fields"')), ['Response Fields']);
+        assert.deepEqual(headings(findSections(doc, 'success response')), ['Success Response (201 Created)']);
+    });
+    it('resolves aliases to groups', () => {
+        assert.deepEqual(headings(findSections(doc, 'optional')), ['Optional Request Body Fields']);
+        assert.deepEqual(headings(findSections(doc, 'required')), ['Required Path Parameters', 'Required Request Body Fields']);
+        assert.deepEqual(headings(findSections(doc, 'examples')), ['Example Usage']);
+        const errors = headings(findSections(doc, 'errors'));
+        assert.ok(errors.length >= 6 && errors.includes('Error Handling'));
+    });
+    it('returns every copy when a heading is duplicated', () => {
+        const dup = parseSections('# T\n## Response\nnot included\n## Notes\nn\n# T again\n## Response\nthe real one\n');
+        const r = findSections(dup, 'Response');
+        assert.ok(r.ok);
+        assert.deepEqual(r.sections.map((s) => s.id), ['response', 'response-2']);
+        const byId = findSections(dup, 'response-2');
+        assert.ok(byId.ok && byId.sections.length === 1);
+    });
+    it('labels appended H1 chunks as appendix in the notice', () => {
+        const d = buildDigest(parseSections('# T\n## Method\nPOST\n## Response\n' + 'x'.repeat(9000) + '\n# T\n## Response\nagain\n'), { wholeDocThreshold: 0, budget: 0 });
+        const n = renderDigestNotice(d, 'p', 'id');
+        assert.ok(n.includes('T (appendix)'), n);
+    });
+    it('a parent match carries its children', () => {
+        const r = selectSections(doc, ['response']);
+        assert.ok(r.ok);
+        assert.ok(r.markdown.includes('### Success Response (201 Created)'));
+        assert.ok(r.markdown.includes('### Error Response (404 Resource not found)'));
+        assert.ok(r.markdown.startsWith('# Create an Issue for a Repository'));
+    });
+    it('prefix matches that all share a canonical name return the group', () => {
+        const r = findSections(doc, 'error response');
+        assert.ok(r.ok);
+        assert.equal(r.sections.length, 6);
+    });
+    it('an ambiguous prefix returns candidates rather than guessing', () => {
+        const r = findSections(doc, 'e');
+        assert.ok(!r.ok);
+        assert.equal(r.reason, 'ambiguous');
+        assert.ok(r.candidates.length > 1);
+    });
+    it('an unknown name returns not-found with the full section list', () => {
+        const r = findSections(doc, 'pricing');
+        assert.ok(!r.ok);
+        assert.equal(r.reason, 'not-found');
+        assert.equal(r.candidates.length, flattenSections(doc.sections).length);
+    });
+    it('selectSections accepts several names, dedupes, and orders by document position', () => {
+        const r = selectSections(doc, ['notes', 'Method', 'success-response-201-created', 'response']);
+        assert.ok(r.ok);
+        assert.deepEqual(r.sections.map((s) => s.heading), ['Method', 'Response', 'Notes']);
+    });
+    it('selectSections reports the first bad name', () => {
+        const r = selectSections(doc, ['method', 'nope']);
+        assert.ok(!r.ok);
+        assert.equal(r.query, 'nope');
+    });
+});
+describe('parseSectionFlag', () => {
+    it('splits repeated flags and comma lists', () => {
+        assert.deepEqual(parseSectionFlag(undefined), []);
+        assert.deepEqual(parseSectionFlag('a, b'), ['a', 'b']);
+        assert.deepEqual(parseSectionFlag(['a,b', ' c ', '']), ['a', 'b', 'c']);
+    });
+});

package/build/schemas.js

@@ -25,7 +25,10 @@ export const searchOnePlatformActionsInputSchema = {
  */
 export const getOneActionKnowledgeInputSchema = {
     actionId: z.string().describe("The action ID to get knowledge for (from the actions list returned by search_one_platform_actions). REQUIRED: This tool must be called before execute_one_action to load the action's documentation into context."),
-    platform: z.string().describe("The platform name to get knowledge for (e.g., 'ship-station', 'shopify'). This is the kebab-case version of the platform name that comes from the list_one_integrations tool AVAILABLE PLATFORMS section.")
+    platform: z.string().describe("The platform name to get knowledge for (e.g., 'ship-station', 'shopify'). This is the kebab-case version of the platform name that comes from the list_one_integrations tool AVAILABLE PLATFORMS section."),
+    section: z.string().optional().describe("Load specific section(s) of the documentation by name (e.g. 'Response Fields', or comma-separated 'Response Fields, Optional Request Body Fields'). Large docs return a digest first; use this on a follow-up call to pull a section the digest omitted."),
+    full: z.boolean().optional().describe("Return the entire documentation verbatim instead of the token-saving digest. Ignored when `section` is set. Leave unset by default; only set it when you genuinely need every section."),
+    toc: z.boolean().optional().describe("Return only the table of contents (every section's id, heading, and size), no bodies. Use it to see everything available when the digest collapsed its list. Ignored when `section` is set.")
 };
 /**
  * Schema for executing One actions
@@ -111,7 +114,7 @@ export const searchOnePlatformActionsToolConfig = {
 };
 export const getOneActionKnowledgeToolConfig = {
     title: "Get Action Knowledge",
-    description: "Get comprehensive documentation for a specific action including parameters, requirements, and usage examples. MANDATORY: You MUST call this tool before execute_one_action to understand the action's requirements, parameter structure, caveats, and proper usage. This loads the action documentation into context and is required for successful execution.",
+    description: "Get comprehensive documentation for a specific action including parameters, requirements, and usage examples. MANDATORY: You MUST call this tool before execute_one_action to understand the action's requirements, parameter structure, caveats, and proper usage. This loads the action documentation into context and is required for successful execution. Large documents come back as a digest (the sections needed to build a correct request, plus a list of what was omitted); request an omitted section by name with `section`, or the whole document with `full: true`.",
     inputSchema: getOneActionKnowledgeInputSchema
 };
 export const executeOneActionToolConfig = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/mcp",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "description": "A Model Context Protocol Server for One",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
   ],
   "scripts": {
     "build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\"",
+    "test": "node scripts/run-tests.mjs",
     "prepare": "npm run build",
     "watch": "tsc --watch",
     "inspector": "npx @modelcontextprotocol/inspector build/index.js",
@@ -31,6 +32,7 @@
     "@types/express": "^5.0.3",
     "@types/node": "^22.0.0",
     "nodemon": "^3.1.10",
+    "tsx": "^4.23.13",
     "typescript": "^5.6.0"
   },
   "author": {