@orboto/mcp 0.178.0

package/dist/tools/doc-edits.js

@@ -0,0 +1,229 @@
+/**
+ * ORB-1342 (epic ORB-1339) - doc snippet-search + targeted-edit MCP tools.
+ *
+ * Phase-3 four-way-sync rollout of the two REST primitives shipped in
+ * ORB-1340 (GET /docs/search) and ORB-1341 (POST /docs/:id/edits). The
+ * whole point of the feature is context efficiency: an agent finds the
+ * right passage with one search (snippet + heading anchor, NOT the full
+ * doc body) and changes it with one edit that ships only the diff in both
+ * directions. Prefer these over orboto_get_doc + orboto_update_doc for
+ * small changes to a large doc.
+ *
+ * Three tools:
+ *   - orboto_search_docs       GET  /docs/search
+ *   - orboto_edit_doc          POST /docs/:id/edits (string-replace edits)
+ *   - orboto_edit_doc_section  POST /docs/:id/edits (heading-addressed ops)
+ *
+ * The two edit tools hit the same endpoint with a different half of its
+ * body, so they share the 409-conflict translation below: a machine-
+ * readable conflict (no/ambiguous match, stale revision, heading not
+ * found / ambiguous) comes back as a NON-throwing tool result with
+ * `isError: true` so the model can self-correct instead of the raw API
+ * error bubbling up as an opaque failure.
+ */
+import { z } from 'zod';
+import { OrbotoApiError } from '../orboto-client.js';
+import { resolveDocId } from './docs.js';
+import { resolveProjectByKey } from './shared.js';
+// ---------------------------------------------------------------------------
+// 409 translation - shared by both edit tools.
+// ---------------------------------------------------------------------------
+/** Turn a 409 from POST /docs/:id/edits into a clear, non-throwing tool
+ *  result the model can act on. Returns null for any non-409 so the caller
+ *  rethrows (a genuine transport/permission failure should still surface). */
+function editConflictResult(err) {
+    if (!(err instanceof OrbotoApiError) || err.status !== 409)
+        return null;
+    let c = {};
+    try {
+        c = JSON.parse(err.body);
+    }
+    catch { /* non-JSON body */ }
+    let text;
+    switch (c.reason) {
+        case 'no_match':
+            text =
+                `⛔ Edit ${c.editIndex} did not apply: oldString was not found in the doc (0 matches).\n` +
+                    `The doc content may differ from what you expected. Re-read the passage (orboto_search_docs or orboto_get_doc) and rebuild the oldString to match exactly, whitespace included.`;
+            break;
+        case 'ambiguous_match':
+            text =
+                `⛔ Edit ${c.editIndex} did not apply: oldString matched ${c.occurrences ?? 'multiple'} times.\n` +
+                    `Add surrounding context so the oldString is unique, or pass replaceAll=true to change every occurrence deliberately.`;
+            break;
+        case 'stale_revision':
+            text =
+                `⛔ Doc changed since your baseRevisionId; nothing was written.\n` +
+                    `Re-read the doc, rebuild the edit against the current content, and retry with baseRevisionId="${c.currentRevisionId ?? 'null'}".`;
+            break;
+        case 'heading_not_found':
+            text =
+                `⛔ Section op ${c.editIndex}: no heading matched the path [${(c.headingPath ?? []).join(' > ')}].\n` +
+                    `Heading matching is exact + case-sensitive. Check the exact heading text (orboto_search_docs returns each hit's headingPath).`;
+            break;
+        case 'ambiguous_heading':
+            text =
+                `⛔ Section op ${c.editIndex}: the heading path [${(c.headingPath ?? []).join(' > ')}] matched multiple headings.\n` +
+                    (c.candidates?.length ? `Candidates: ${c.candidates.join(' | ')}.\n` : '') +
+                    `Narrow the path by adding ancestor headings to disambiguate.`;
+            break;
+        default:
+            text = `⛔ Edit rejected (409): ${c.error ?? (err.body || 'conflict')}.`;
+    }
+    return {
+        content: [{ type: 'text', text }],
+        structuredContent: { conflict: true, ...c },
+        isError: true,
+    };
+}
+function renderEditResult(res) {
+    const lines = [
+        `Applied ${res.edits.length} change(s) to doc ${res.docKey ?? res.docId}.`,
+        `  new revisionId: ${res.revisionId ?? '(no content change)'}`,
+        '',
+        ...res.edits.map((w) => `  [${w.index}] ${w.kind} · replaced ${w.replaced} · …${w.window}…`),
+    ];
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+        structuredContent: {
+            docId: res.docId,
+            docKey: res.docKey ?? null,
+            revisionId: res.revisionId,
+            edits: res.edits.map((w) => ({
+                index: w.index,
+                kind: w.kind,
+                replaced: w.replaced,
+                window: w.window,
+            })),
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_search_docs  (GET /docs/search - ORB-1340)
+// ---------------------------------------------------------------------------
+export const searchDocsToolConfig = {
+    title: 'Search docs for snippets (context-efficient)',
+    description: 'Full-text search across wiki docs that returns a highlighted SNIPPET (matched fragments, <mark>…</mark> around each hit) plus the nearest markdown heading path (section anchor) and char/line offset per hit - WITHOUT echoing the full doc body. Use this instead of orboto_get_doc when you only need to locate a passage: find the right doc + section, then change it with orboto_edit_doc / orboto_edit_doc_section, all without transferring the whole document. ACL-filtered in SQL (you only see docs you can read). Ranked by relevance.',
+    inputSchema: z.object({
+        q: z.string().min(1).max(10_000).describe('Search terms. Keyword FTS (tsvector); more distinctive words rank higher.'),
+        projectKey: z.string().min(1).optional().describe('Scope to one project by key (e.g. "ORB"). Resolved to the project UUID.'),
+        spaceId: z.string().uuid().optional().describe('Scope to one doc space by UUID (discover via orboto_list_doc_spaces).'),
+        limit: z.number().int().positive().max(100).default(20).describe('Max hits (default 20, max 100).'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeSearchDocsHandler(client) {
+    return async (input) => {
+        const qs = new URLSearchParams({ q: input.q });
+        if (input.spaceId)
+            qs.set('spaceId', input.spaceId);
+        if (input.projectKey) {
+            const project = await resolveProjectByKey(client, input.projectKey);
+            qs.set('projectId', project.id);
+        }
+        if (input.limit)
+            qs.set('limit', String(input.limit));
+        const res = await client.get(`/docs/search?${qs.toString()}`);
+        if (res.items.length === 0) {
+            return {
+                content: [{ type: 'text', text: `No docs matched "${input.q}".` }],
+                structuredContent: { items: [], total: 0 },
+            };
+        }
+        const lines = res.items.map((h) => {
+            const anchor = h.headingPath.length ? `  §${h.headingPath.join(' > ')}` : '';
+            const where = h.charOffset >= 0 ? `  (line ${h.lineOffset})` : '';
+            return `- ${h.title} (${h.docKey ?? h.id})${anchor}${where}\n    ${h.snippet.replace(/\s+/g, ' ').trim()}`;
+        });
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: {
+                items: res.items.map((h) => ({
+                    id: h.id,
+                    docKey: h.docKey,
+                    title: h.title,
+                    spaceId: h.spaceId,
+                    spaceName: h.spaceName,
+                    projectId: h.projectId,
+                    snippet: h.snippet,
+                    headingPath: h.headingPath,
+                    charOffset: h.charOffset,
+                    lineOffset: h.lineOffset,
+                    rank: h.rank,
+                    url: h.url,
+                })),
+                total: res.total,
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_edit_doc  (POST /docs/:id/edits - string-replace, ORB-1341)
+// ---------------------------------------------------------------------------
+export const editDocToolConfig = {
+    title: 'Targeted string-replace edit of a doc (context-efficient)',
+    description: 'Change a doc by byte-precise string replacement (Edit-tool-like) - ship only the diff, not the whole doc. Each oldString must match EXACTLY ONCE in the current content (add surrounding context to make it unique) unless replaceAll=true (then >=1). The whole batch is atomic: any match failure applies nothing and returns a 409 you can act on. Prefer this over orboto_update_doc for small changes to a large doc. Pass baseRevisionId (from a previous edit\'s revisionId or orboto_list_doc_revisions) for optimistic concurrency - a stale token is rejected with the current revision id instead of clobbering a concurrent change. Returns a short context window around each change, not the full doc.',
+    inputSchema: z.object({
+        docId: z.string().min(1).describe('Doc UUID or human-readable key (ORB-D12 / DOC-5). Find via orboto_search_docs.'),
+        edits: z.array(z.object({
+            oldString: z.string().min(1).describe('Exact substring to replace. Must be unique in the doc unless replaceAll.'),
+            newString: z.string().describe('Replacement text (may be empty to delete).'),
+            replaceAll: z.boolean().optional().describe('Replace every occurrence instead of requiring exactly one.'),
+        })).min(1).max(100).describe('Applied sequentially; edit N sees the result of edits 0..N-1.'),
+        baseRevisionId: z.string().uuid().optional().describe('Optimistic-concurrency token = the revision id you last saw. Omit to always apply.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeEditDocHandler(client) {
+    return async (input) => {
+        const docId = await resolveDocId(client, input.docId);
+        const body = { edits: input.edits };
+        if (input.baseRevisionId)
+            body.baseRevisionId = input.baseRevisionId;
+        try {
+            const res = await client.post(`/docs/${docId}/edits`, body);
+            return renderEditResult(res);
+        }
+        catch (err) {
+            const conflict = editConflictResult(err);
+            if (conflict)
+                return conflict;
+            throw err;
+        }
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_edit_doc_section  (POST /docs/:id/edits - section ops, ORB-1341)
+// ---------------------------------------------------------------------------
+export const editDocSectionToolConfig = {
+    title: 'Edit a doc section by heading path (context-efficient)',
+    description: 'Change a doc by markdown-heading-addressed section operations - ship only the new section content, not the whole doc. A section is addressed by its heading path (e.g. ["Setup","Credentials"] = a "Credentials" heading nested under "Setup"). Heading matching is EXACT + case-sensitive; the leading path elements must be an ordered ancestor chain (not necessarily immediate parents). op=replace swaps the section body, op=append adds to its end, op=insertAfter inserts directly below the heading line (the heading line itself is never removed). A path that matches zero or multiple headings returns a 409 you can act on (narrow the path to disambiguate). Prefer this over orboto_update_doc for section-scoped rewrites. baseRevisionId gives optimistic concurrency. Returns a short context window per op.',
+    inputSchema: z.object({
+        docId: z.string().min(1).describe('Doc UUID or human-readable key (ORB-D12 / DOC-5). Find via orboto_search_docs.'),
+        sectionOps: z.array(z.object({
+            headingPath: z.array(z.string().min(1)).min(1).describe('Ordered heading breadcrumb, top-down. Exact + case-sensitive.'),
+            op: z.enum(['replace', 'append', 'insertAfter']).describe('replace body / append to body / insert directly below the heading line.'),
+            content: z.string().describe('New markdown content for the op.'),
+        })).min(1).max(100).describe('Applied sequentially after any string edits.'),
+        baseRevisionId: z.string().uuid().optional().describe('Optimistic-concurrency token = the revision id you last saw. Omit to always apply.'),
+    }).shape,
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false },
+};
+export function makeEditDocSectionHandler(client) {
+    return async (input) => {
+        const docId = await resolveDocId(client, input.docId);
+        const body = { sectionOps: input.sectionOps };
+        if (input.baseRevisionId)
+            body.baseRevisionId = input.baseRevisionId;
+        try {
+            const res = await client.post(`/docs/${docId}/edits`, body);
+            return renderEditResult(res);
+        }
+        catch (err) {
+            const conflict = editConflictResult(err);
+            if (conflict)
+                return conflict;
+            throw err;
+        }
+    };
+}

package/dist/tools/doc-edits.test.js

@@ -0,0 +1,218 @@
+/**
+ * ORB-1342 - doc snippet-search + targeted-edit tool tests.
+ *
+ * Same fetch-stub harness as docs.test.ts. Each test asserts the outgoing
+ * wire shape (URL + method + body) and the structured content the model
+ * gets back. The edit tools also cover the two machine-readable 409 paths
+ * (ambiguous / stale) the acceptance criteria call out - the API returns a
+ * JSON conflict body, the tool must surface it as a non-throwing isError
+ * result the model can act on, NOT let the raw OrbotoApiError bubble up.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoClient } from '../orboto-client.js';
+import { makeSearchDocsHandler, makeEditDocHandler, makeEditDocSectionHandler, } from './doc-edits.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+/** Stub fetch with a queue of responses. Error responses carry a `text`
+ *  body (the OrbotoClient reads res.text() on non-2xx) so the 409 JSON
+ *  conflict body reaches the tool's catch branch. */
+function stubJSON(responses) {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        calls.push({
+            url: url.toString(),
+            method: init?.method ?? 'GET',
+            body: typeof init?.body === 'string' ? JSON.parse(init.body) : init?.body,
+        });
+        const r = responses.shift();
+        if (!r)
+            throw new Error('unexpected extra fetch');
+        return {
+            ok: r.ok ?? true,
+            status: r.status ?? 200,
+            statusText: 'OK',
+            json: async () => ('json' in r ? r.json : {}),
+            text: async () => r.text ?? '',
+        };
+    });
+    return calls;
+}
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const DOC_UUID = '33333333-3333-3333-3333-333333333333';
+const REV_UUID = '44444444-4444-4444-4444-444444444444';
+// ---------------------------------------------------------------------------
+// orboto_search_docs
+// ---------------------------------------------------------------------------
+describe('orboto_search_docs', () => {
+    const HIT = {
+        id: DOC_UUID,
+        docKey: 'ORB-D12',
+        title: 'Backup Runbook',
+        spaceId: '11111111-1111-1111-1111-111111111111',
+        spaceName: 'Backend Runbooks',
+        projectId: '22222222-2222-2222-2222-222222222222',
+        snippet: 'To <mark>restore</mark> a project from backup …',
+        headingPath: ['Setup', 'Restore'],
+        charOffset: 120,
+        lineOffset: 7,
+        rank: 0.42,
+        url: '/spaces/11111111-1111-1111-1111-111111111111/docs/33333333-3333-3333-3333-333333333333',
+    };
+    it('GETs /docs/search with the query + limit and surfaces snippet + anchor', async () => {
+        const calls = stubJSON([{ json: { items: [HIT], total: 1 } }]);
+        const res = await makeSearchDocsHandler(client)({ q: 'restore backup', limit: 10 });
+        expect(calls[0].method).toBe('GET');
+        expect(calls[0].url).toContain('/docs/search?');
+        expect(calls[0].url).toContain('q=restore+backup');
+        expect(calls[0].url).toContain('limit=10');
+        const sc = res.structuredContent;
+        expect(sc.total).toBe(1);
+        expect(sc.items[0].headingPath).toEqual(['Setup', 'Restore']);
+        expect(sc.items[0].snippet).toContain('<mark>restore</mark>');
+        expect(res.content[0].text).toContain('§Setup > Restore');
+    });
+    it('resolves projectKey to a projectId before searching', async () => {
+        const calls = stubJSON([
+            { json: { id: '22222222-2222-2222-2222-222222222222', key: 'ORB', name: 'orboto', status: 'active' } }, // by-key
+            { json: { items: [], total: 0 } },
+        ]);
+        await makeSearchDocsHandler(client)({ q: 'deploy', projectKey: 'ORB' });
+        expect(calls[0].url).toContain('/projects/by-key/ORB');
+        expect(calls[1].url).toContain('projectId=22222222-2222-2222-2222-222222222222');
+    });
+    it('passes spaceId straight through', async () => {
+        const calls = stubJSON([{ json: { items: [], total: 0 } }]);
+        await makeSearchDocsHandler(client)({ q: 'x', spaceId: '11111111-1111-1111-1111-111111111111' });
+        expect(calls[0].url).toContain('spaceId=11111111-1111-1111-1111-111111111111');
+    });
+    it('reports no matches cleanly', async () => {
+        stubJSON([{ json: { items: [], total: 0 } }]);
+        const res = await makeSearchDocsHandler(client)({ q: 'nothing' });
+        expect(res.content[0].text).toContain('No docs matched');
+    });
+});
+// ---------------------------------------------------------------------------
+// orboto_edit_doc - string-replace
+// ---------------------------------------------------------------------------
+describe('orboto_edit_doc', () => {
+    it('POSTs edits to /docs/:id/edits (UUID passthrough) and renders the window', async () => {
+        const calls = stubJSON([{
+                json: {
+                    docId: DOC_UUID,
+                    docKey: 'ORB-D12',
+                    revisionId: REV_UUID,
+                    edits: [{ index: 0, kind: 'edit', replaced: 1, window: 'The slow brown fox' }],
+                },
+            }]);
+        const res = await makeEditDocHandler(client)({
+            docId: DOC_UUID,
+            edits: [{ oldString: 'quick', newString: 'slow' }],
+            baseRevisionId: REV_UUID,
+        });
+        expect(calls[0]).toMatchObject({
+            method: 'POST',
+            url: `https://orboto.example.com/docs/${DOC_UUID}/edits`,
+            body: { edits: [{ oldString: 'quick', newString: 'slow' }], baseRevisionId: REV_UUID },
+        });
+        const sc = res.structuredContent;
+        expect(sc.revisionId).toBe(REV_UUID);
+        expect(res.content[0].text).toContain('Applied 1 change');
+    });
+    it('resolves a doc key to a UUID before editing', async () => {
+        const calls = stubJSON([
+            { json: { id: DOC_UUID } }, // /docs/by-key/ORB-D12
+            { json: { docId: DOC_UUID, docKey: 'ORB-D12', revisionId: REV_UUID, edits: [] } },
+        ]);
+        await makeEditDocHandler(client)({ docId: 'ORB-D12', edits: [{ oldString: 'a', newString: 'b' }] });
+        expect(calls[0].url).toContain('/docs/by-key/ORB-D12');
+        expect(calls[1].url).toBe(`https://orboto.example.com/docs/${DOC_UUID}/edits`);
+    });
+    it('surfaces an ambiguous-match 409 as a non-throwing isError result', async () => {
+        stubJSON([{
+                ok: false,
+                status: 409,
+                text: JSON.stringify({ error: 'ambiguous', reason: 'ambiguous_match', editIndex: 0, occurrences: 3 }),
+            }]);
+        const res = await makeEditDocHandler(client)({ docId: DOC_UUID, edits: [{ oldString: 'the', newString: 'a' }] });
+        expect(res.isError).toBe(true);
+        expect(res.content[0].text).toContain('matched 3 times');
+        expect(res.structuredContent).toMatchObject({ conflict: true, reason: 'ambiguous_match', occurrences: 3 });
+    });
+    it('surfaces a stale-revision 409 with the current revision id to retry with', async () => {
+        stubJSON([{
+                ok: false,
+                status: 409,
+                text: JSON.stringify({ error: 'stale', reason: 'stale_revision', currentRevisionId: REV_UUID }),
+            }]);
+        const res = await makeEditDocHandler(client)({
+            docId: DOC_UUID,
+            edits: [{ oldString: 'a', newString: 'b' }],
+            baseRevisionId: '00000000-0000-0000-0000-000000000000',
+        });
+        expect(res.isError).toBe(true);
+        expect(res.content[0].text).toContain(REV_UUID);
+        expect(res.structuredContent).toMatchObject({ conflict: true, reason: 'stale_revision', currentRevisionId: REV_UUID });
+    });
+    it('rethrows a non-409 API error (permission / transport)', async () => {
+        stubJSON([{ ok: false, status: 403, text: 'Forbidden' }]);
+        await expect(makeEditDocHandler(client)({ docId: DOC_UUID, edits: [{ oldString: 'a', newString: 'b' }] })).rejects.toThrow(/403/);
+    });
+});
+// ---------------------------------------------------------------------------
+// orboto_edit_doc_section - heading-addressed
+// ---------------------------------------------------------------------------
+describe('orboto_edit_doc_section', () => {
+    it('POSTs sectionOps to /docs/:id/edits', async () => {
+        const calls = stubJSON([{
+                json: {
+                    docId: DOC_UUID,
+                    docKey: 'ORB-D12',
+                    revisionId: REV_UUID,
+                    edits: [{ index: 0, kind: 'sectionOp', replaced: 1, window: 'New creds.' }],
+                },
+            }]);
+        const res = await makeEditDocSectionHandler(client)({
+            docId: DOC_UUID,
+            sectionOps: [{ headingPath: ['Setup', 'Credentials'], op: 'replace', content: '\nNew creds.\n' }],
+        });
+        expect(calls[0]).toMatchObject({
+            method: 'POST',
+            url: `https://orboto.example.com/docs/${DOC_UUID}/edits`,
+            body: { sectionOps: [{ headingPath: ['Setup', 'Credentials'], op: 'replace', content: '\nNew creds.\n' }] },
+        });
+        expect(res.content[0].text).toContain('sectionOp');
+    });
+    it('surfaces an ambiguous-heading 409 with candidates', async () => {
+        stubJSON([{
+                ok: false,
+                status: 409,
+                text: JSON.stringify({
+                    error: 'ambiguous heading',
+                    reason: 'ambiguous_heading',
+                    editIndex: 0,
+                    headingPath: ['Notes'],
+                    candidates: ['A > Notes', 'B > Notes'],
+                }),
+            }]);
+        const res = await makeEditDocSectionHandler(client)({
+            docId: DOC_UUID,
+            sectionOps: [{ headingPath: ['Notes'], op: 'append', content: 'x' }],
+        });
+        expect(res.isError).toBe(true);
+        expect(res.content[0].text).toContain('A > Notes | B > Notes');
+        expect(res.structuredContent).toMatchObject({ conflict: true, reason: 'ambiguous_heading' });
+    });
+    it('surfaces a heading-not-found 409', async () => {
+        stubJSON([{
+                ok: false,
+                status: 409,
+                text: JSON.stringify({ error: 'not found', reason: 'heading_not_found', editIndex: 0, headingPath: ['Ghost'] }),
+            }]);
+        const res = await makeEditDocSectionHandler(client)({
+            docId: DOC_UUID,
+            sectionOps: [{ headingPath: ['Ghost'], op: 'replace', content: 'x' }],
+        });
+        expect(res.isError).toBe(true);
+        expect(res.content[0].text).toContain('no heading matched');
+    });
+});

package/dist/tools/doc-export.js

@@ -0,0 +1,87 @@
+/**
+ * ORB-915 - doc-export MCP tools (epic ORB-911 Phase 4).
+ *
+ * - orboto_export_doc_md - GET /docs/:id/export/md   (text/markdown)
+ * - orboto_export_doc_pdf - POST /docs/:id/export/pdf (application/pdf)
+ *
+ * The Markdown export differs from `orboto_get_doc.content` because
+ * the server-side renderer strips backlinks / smart-link inflation
+ * and emits the raw saved Markdown - useful when the agent wants to
+ * pipe the body through another tool without the get-doc envelope.
+ *
+ * The PDF export returns binary bytes. MCP supports binary resource
+ * attachments via the `{ type: 'resource', resource: { uri, blob:
+ * <base64>, mimeType } }` content shape; we return the PDF that way.
+ *
+ * Both endpoints rely on `OrbotoClient.getText` / `postBinary` which
+ * landed alongside this phase - JSON-only `get` / `post` would have
+ * blown up on the non-JSON response bodies.
+ */
+import { z } from 'zod';
+import { resolveDocId } from './docs.js';
+// ---------------------------------------------------------------------------
+// orboto_export_doc_md
+// ---------------------------------------------------------------------------
+export const exportDocMdToolConfig = {
+    title: 'Export a doc page as Markdown',
+    description: 'Return the doc body as plain Markdown (text/markdown). Differs from orboto_get_doc.content in that the server-side export endpoint emits the canonical saved body - agents pulling docs to feed into another tool should prefer this over get_doc, which wraps the body in get-doc envelope text + backlinks.',
+    inputSchema: z.object({
+        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeExportDocMdHandler(client) {
+    return async ({ docId }) => {
+        docId = await resolveDocId(client, docId);
+        const markdown = await client.getText(`/docs/${docId}/export/md`);
+        return {
+            content: [{ type: 'text', text: markdown }],
+            structuredContent: {
+                docId,
+                markdown,
+                sizeBytes: Buffer.byteLength(markdown, 'utf8'),
+            },
+        };
+    };
+}
+// ---------------------------------------------------------------------------
+// orboto_export_doc_pdf
+// ---------------------------------------------------------------------------
+export const exportDocPdfToolConfig = {
+    title: 'Export a doc page as PDF',
+    description: 'Render the doc page to PDF via the workspace\'s PdfService (Puppeteer-backed) and return the bytes as a base64 MCP resource attachment. Requires the PDF engine to be configured - deployments without Chromium / Puppeteer return 503 (errors.pdf.engine_unavailable) which surfaces as an OrbotoApiError.',
+    inputSchema: z.object({
+        docId: z.string().min(1).describe('Doc UUID or human-readable doc key (ORB-D12 / DOC-5).'),
+    }).shape,
+    annotations: { readOnlyHint: true, idempotentHint: true },
+};
+export function makeExportDocPdfHandler(client) {
+    return async ({ docId }) => {
+        docId = await resolveDocId(client, docId);
+        const { bytes, contentType } = await client.postBinary(`/docs/${docId}/export/pdf`);
+        // MCP's `resource` content type takes a base64 blob - Buffer →
+        // base64 is the standard Node path.
+        const base64 = Buffer.from(bytes).toString('base64');
+        return {
+            content: [
+                {
+                    type: 'resource',
+                    resource: {
+                        uri: `orboto://doc/${docId}/export.pdf`,
+                        mimeType: contentType,
+                        blob: base64,
+                    },
+                },
+                {
+                    type: 'text',
+                    text: `Rendered ${docId} to PDF (${Math.round(bytes.byteLength / 1024)} KB).`,
+                },
+            ],
+            structuredContent: {
+                docId,
+                sizeBytes: bytes.byteLength,
+                contentType,
+            },
+        };
+    };
+}

package/dist/tools/doc-export.test.js

@@ -0,0 +1,109 @@
+/**
+ * ORB-915 - doc-export tool tests.
+ *
+ * Markdown export: stub fetch returning a string + content-type
+ * text/markdown. Verify the tool returns the Markdown verbatim.
+ *
+ * PDF export: stub fetch returning a Uint8Array body. Verify the
+ * tool wraps it as an MCP resource attachment with base64 blob.
+ *
+ * 503 from a deployment with no PDF engine: verify the
+ * OrbotoApiError bubbles up so the model can tell the user what's
+ * wrong.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { OrbotoApiError, OrbotoClient } from '../orboto-client.js';
+import { makeExportDocMdHandler, makeExportDocPdfHandler, } from './doc-export.js';
+beforeEach(() => { vi.restoreAllMocks(); });
+afterEach(() => { vi.restoreAllMocks(); });
+const client = new OrbotoClient({ baseUrl: 'https://orboto.example.com', apiKey: 'orb_x' });
+const DOC_ID = 'd0000000-0000-0000-0000-000000000001';
+function stubText(text, contentType = 'text/markdown; charset=utf-8') {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        calls.push({ url: url.toString(), method: init?.method ?? 'GET' });
+        return {
+            ok: true,
+            status: 200,
+            statusText: 'OK',
+            headers: new Headers({ 'content-type': contentType }),
+            text: async () => text,
+            arrayBuffer: async () => Buffer.from(text, 'utf8').buffer,
+            json: async () => { throw new Error('not json'); },
+        };
+    });
+    return calls;
+}
+function stubBinary(bytes, contentType = 'application/pdf') {
+    const calls = [];
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (url, init) => {
+        calls.push({ url: url.toString(), method: init?.method ?? 'GET' });
+        return {
+            ok: true,
+            status: 200,
+            statusText: 'OK',
+            headers: new Headers({ 'content-type': contentType }),
+            arrayBuffer: async () => bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength),
+            text: async () => '',
+        };
+    });
+    return calls;
+}
+function stub5xx(status, body) {
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async () => {
+        return {
+            ok: false,
+            status,
+            statusText: 'Server Error',
+            headers: new Headers(),
+            text: async () => JSON.stringify(body),
+            json: async () => body,
+            arrayBuffer: async () => new ArrayBuffer(0),
+        };
+    });
+}
+describe('orboto_export_doc_md', () => {
+    it('GETs /docs/:id/export/md and surfaces the raw Markdown', async () => {
+        const md = '# My Page\n\nBody text.';
+        const calls = stubText(md);
+        const res = await makeExportDocMdHandler(client)({ docId: DOC_ID });
+        expect(calls[0]).toMatchObject({
+            method: 'GET',
+            url: `https://orboto.example.com/docs/${DOC_ID}/export/md`,
+        });
+        expect(res.content[0].text).toBe(md);
+        expect(res.structuredContent).toMatchObject({
+            docId: DOC_ID,
+            markdown: md,
+            sizeBytes: Buffer.byteLength(md, 'utf8'),
+        });
+    });
+});
+describe('orboto_export_doc_pdf', () => {
+    it('POSTs /docs/:id/export/pdf and wraps the bytes as a base64 MCP resource', async () => {
+        // Pretend the renderer returned a minimal 8-byte PDF header.
+        const pdfBytes = new Uint8Array([0x25, 0x50, 0x44, 0x46, 0x2d, 0x31, 0x2e, 0x37]);
+        const calls = stubBinary(pdfBytes);
+        const res = await makeExportDocPdfHandler(client)({ docId: DOC_ID });
+        expect(calls[0]).toMatchObject({
+            method: 'POST',
+            url: `https://orboto.example.com/docs/${DOC_ID}/export/pdf`,
+        });
+        const first = res.content[0];
+        expect(first.type).toBe('resource');
+        expect(first.resource.uri).toBe(`orboto://doc/${DOC_ID}/export.pdf`);
+        expect(first.resource.mimeType).toBe('application/pdf');
+        // The blob is the base64 of the bytes - decode it back and compare.
+        const decoded = Buffer.from(first.resource.blob, 'base64');
+        expect(Array.from(decoded)).toEqual(Array.from(pdfBytes));
+        expect(res.structuredContent).toMatchObject({
+            docId: DOC_ID,
+            sizeBytes: pdfBytes.byteLength,
+            contentType: 'application/pdf',
+        });
+    });
+    it('bubbles up a 503 when the deployment has no PDF engine', async () => {
+        stub5xx(503, { error: 'PDF engine unavailable', errorKey: 'errors.pdf.engine_unavailable' });
+        await expect(makeExportDocPdfHandler(client)({ docId: DOC_ID })).rejects.toBeInstanceOf(OrbotoApiError);
+    });
+});