ofw-mcp 2.7.0 → 2.8.0

package/dist/config.js

@@ -82,6 +82,48 @@ export function getCalendarWritesAllowed() {
         return true;
     return mode === 'drafts' && parseBoolEnv('OFW_CALENDAR_WRITES');
 }
+/**
+ * Deployment-wide ceiling on reads that STAMP the record.
+ *
+ * Fetching a message body from OFW marks it read and stamps a "First Viewed"
+ * timestamp the co-parent can see. That is part of the court-visible record and
+ * it cannot be undone — and unlike a send, it happens as a side effect of an
+ * ordinary read, so nothing about the caller's intent signals it.
+ *
+ * Default TRUE: unset means exactly the behaviour that shipped before this flag
+ * existed. Set OFW_ALLOW_MARK_READ=false and it becomes a hard ceiling rather
+ * than a default — `ofw_get_message` refuses a fetch that would stamp,
+ * `ofw_check_freshness` ignores `allowMarkRead:true`, and `ofw_sync_messages`
+ * ignores `fetchUnreadBodies:true`. A per-call argument (or an instruction
+ * injected into one) cannot raise it, which is the same structural posture
+ * OFW_WRITE_MODE takes for writes.
+ *
+ * An unrecognized value fails CLOSED, with a warning: someone who wrote
+ * "flase" meant to disable this, and honouring the typo as the permissive
+ * default would keep stamping the record while looking configured.
+ */
+export function getAllowMarkRead() {
+    const raw = process.env.OFW_ALLOW_MARK_READ;
+    if (typeof raw !== 'string' || raw.trim().length === 0)
+        return true;
+    const value = raw.trim().toLowerCase();
+    if (['1', 'true', 'yes', 'on'].includes(value))
+        return true;
+    if (['0', 'false', 'no', 'off'].includes(value))
+        return false;
+    // stdio transport: stderr only — stdout is reserved for JSON-RPC.
+    console.error(`[ofw-mcp] Unrecognized OFW_ALLOW_MARK_READ "${raw.trim()}" — failing closed to "false" (no tool may mark a message read on OFW). Valid values: true, false.`);
+    return false;
+}
+/**
+ * Default for ofw_sync_messages' `fetchUnreadBodies` arg. False (the shipped
+ * default) so an ordinary sync never stamps unread inbox messages; set
+ * OFW_FETCH_UNREAD_BODIES=true on a deployment where read receipts are routine
+ * and you would rather have the bodies cached. Capped by getAllowMarkRead().
+ */
+export function getFetchUnreadBodies() {
+    return parseBoolEnv('OFW_FETCH_UNREAD_BODIES');
+}
 // Default for ofw_download_attachment's `inline` arg when the caller doesn't
 // pass one. Set OFW_INLINE_ATTACHMENTS=true to have attachments returned as
 // MCP content blocks by default (skipping disk) — useful on sandboxed MCP

package/dist/extract/document.js

@@ -0,0 +1,83 @@
+// Word (.docx) text extraction.
+//
+// The goal is a readable transcript, not a faithful re-render: headings keep
+// their level as `#` prefixes, list paragraphs keep their bullet, and table
+// rows come back pipe-delimited. Structure is what makes an extracted custody
+// schedule answerable ("which row is Thanksgiving?"); a flat wall of runs is
+// not much better than the blob we are replacing.
+import { readZip } from './zip.js';
+import { decodeXmlEntities, elements } from './xml.js';
+import { findPart } from './ooxml.js';
+// A run's text, a tab, or a break — matched in document order so an inline tab
+// does not get hoisted out of position by a tags-then-text pass.
+const RUN_CONTENT = /<w:t(?:\s[^>]*)?>([\s\S]*?)<\/w:t>|<w:(tab|br|cr)\s*\/>/g;
+function paragraphText(inner) {
+    let text = '';
+    for (let m = RUN_CONTENT.exec(inner); m !== null; m = RUN_CONTENT.exec(inner)) {
+        if (m[1] !== undefined)
+            text += decodeXmlEntities(m[1]);
+        else
+            text += m[2] === 'tab' ? '\t' : '\n';
+    }
+    RUN_CONTENT.lastIndex = 0;
+    return text;
+}
+/** Prefix a paragraph according to its `<w:pStyle>`, if it has a known one. */
+function styledParagraph(inner) {
+    const text = paragraphText(inner);
+    if (text === '')
+        return '';
+    const style = /<w:pStyle\s[^>]*w:val="([^"]*)"/.exec(inner)?.[1] ?? '';
+    const heading = /^Heading(\d)$/.exec(style);
+    if (heading)
+        return `${'#'.repeat(Math.min(Number(heading[1]), 6))} ${text}`;
+    if (style === 'Title' || style === 'Subtitle')
+        return `# ${text}`;
+    if (style === 'ListParagraph')
+        return `- ${text}`;
+    return text;
+}
+function tableText(inner) {
+    const rows = [];
+    for (const tr of elements(inner, 'w:tr')) {
+        const cells = [];
+        for (const tc of elements(tr.inner, 'w:tc')) {
+            // A cell holds paragraphs; keep it on one line so the row stays a row.
+            const parts = [];
+            for (const p of elements(tc.inner, 'w:p')) {
+                const text = paragraphText(p.inner);
+                if (text !== '')
+                    parts.push(text);
+            }
+            cells.push(parts.join(' '));
+        }
+        rows.push(`| ${cells.join(' | ')} |`);
+    }
+    return rows.join('\n');
+}
+// Top-level block scan: a table swallows its own paragraphs (the match spans
+// them), so the alternation yields tables and stray paragraphs in order without
+// emitting a table's cell text twice.
+// The paragraph arm mirrors `elements()`: a lazy attribute run that does not
+// eat a self-closing slash, so `<w:p w14:paraId="…"/>` cannot swallow the
+// following paragraph.
+const BLOCK = /<w:tbl(?:\s[^>]*?)?>[\s\S]*?<\/w:tbl>|<w:p(?:\s[^>]*?)?(?:\s*\/>|>([\s\S]*?)<\/w:p>)/g;
+/** Extract the text of a .docx document part. */
+export async function extractDocx(bytes) {
+    const zip = await readZip(bytes);
+    const path = findPart(zip, 'word/document.xml', 'document.xml');
+    if (!path)
+        throw new Error('no document part found in the .docx archive');
+    /* v8 ignore next -- findPart only returns a name the archive contains, so readText cannot be null here */
+    const xml = (await zip.readText(path)) ?? '';
+    const blocks = [];
+    for (let m = BLOCK.exec(xml); m !== null; m = BLOCK.exec(xml)) {
+        // Group 1 is the paragraph's inner XML — undefined for a table match and
+        // for a self-closing (empty) paragraph.
+        const text = m[0].startsWith('<w:tbl') ? tableText(m[0]) : styledParagraph(m[1] ?? '');
+        if (text !== '')
+            blocks.push(text);
+    }
+    BLOCK.lastIndex = 0;
+    return { kind: 'document', text: blocks.join('\n\n') };
+}

package/dist/extract/index.js

@@ -0,0 +1,222 @@
+// The delivery ladder's extraction rung.
+//
+// `ofw_download_attachment` fetches bytes successfully and then has to hand the
+// caller something it can actually read. A host renders four image types
+// inline and rejects every other embedded resource outright ("Resources of
+// type 'application/vnd.…sheet' are not currently supported"), so for a
+// spreadsheet, PDF, Word or PowerPoint attachment the bytes are delivered and
+// unreadable at the same time. Rendering is a display concern; content is a
+// data concern, and this module is what keeps the second from being decided by
+// the first: whatever the host can draw, the FILE's text comes back as text.
+import { extractXlsx, extractDelimited } from './spreadsheet.js';
+import { extractDocx } from './document.js';
+import { extractPptx } from './presentation.js';
+import { extractPdf } from './pdf.js';
+const MIME_KINDS = {
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet': 'xlsx',
+    'application/vnd.ms-excel.sheet.macroenabled.12': 'xlsx',
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document': 'docx',
+    'application/vnd.openxmlformats-officedocument.presentationml.presentation': 'pptx',
+    'application/pdf': 'pdf',
+    'text/csv': 'csv',
+    'text/tab-separated-values': 'tsv',
+    'application/json': 'text',
+    'application/xml': 'text',
+    'application/xhtml+xml': 'text',
+    'application/javascript': 'text',
+    'application/x-yaml': 'text',
+};
+const EXT_KINDS = {
+    '.xlsx': 'xlsx', '.xlsm': 'xlsx',
+    '.docx': 'docx',
+    '.pptx': 'pptx',
+    '.pdf': 'pdf',
+    '.csv': 'csv',
+    '.tsv': 'tsv', '.tab': 'tsv',
+    '.txt': 'text', '.md': 'text', '.json': 'text', '.xml': 'text',
+    '.html': 'text', '.htm': 'text', '.log': 'text', '.yaml': 'text', '.yml': 'text',
+    '.ics': 'text', '.vcf': 'text', '.srt': 'text',
+};
+/**
+ * Which extractor handles this attachment, by MIME then by extension. The
+ * extension is a real fallback, not a formality: OFW serves binaries with a
+ * `charset` bolted on and sometimes with no useful type at all.
+ */
+export function extractKindFor(mimeType, fileName) {
+    const byMime = MIME_KINDS[mimeType];
+    if (byMime)
+        return byMime;
+    const dot = fileName.lastIndexOf('.');
+    const byExt = dot === -1 ? undefined : EXT_KINDS[fileName.slice(dot).toLowerCase()];
+    if (byExt)
+        return byExt;
+    // Any other text/* type (text/plain, text/markdown, text/html, …) is text.
+    return mimeType.startsWith('text/') ? 'text' : null;
+}
+/**
+ * Build a part selector from a `"1-3,5"` / `"Summary,2026"` spec. Numbers are
+ * 1-based positions; anything else matches a sheet or slide/page label. An
+ * empty spec selects everything rather than nothing — a filter that silently
+ * excluded all content would look exactly like an empty file.
+ */
+export function parsePartSpec(spec) {
+    const ranges = [];
+    const names = new Set();
+    for (const token of spec.split(',').map((t) => t.trim()).filter(Boolean)) {
+        const range = /^(\d+)\s*-\s*(\d+)$/.exec(token);
+        if (range) {
+            ranges.push([Number(range[1]), Number(range[2])]);
+            continue;
+        }
+        // A bare number is a position AND a possible name: spreadsheet tabs are
+        // routinely named for a year ("2026"), and reading that token as a position
+        // only would make the obvious `parts: "2026"` select nothing at all.
+        if (/^\d+$/.test(token))
+            ranges.push([Number(token), Number(token)]);
+        names.add(token.toLowerCase());
+    }
+    if (ranges.length === 0 && names.size === 0)
+        return () => true;
+    return (index, name) => ranges.some(([from, to]) => index + 1 >= from && index + 1 <= to)
+        || names.has(name.toLowerCase());
+}
+/** Cut `text` to `budget` characters on a line boundary where possible. */
+function clip(text, budget) {
+    const cut = text.slice(0, budget);
+    const lastBreak = cut.lastIndexOf('\n');
+    return lastBreak > 0 ? cut.slice(0, lastBreak) : cut;
+}
+function omissionNote(label) {
+    return `${label} (omitted: response character budget)`;
+}
+/**
+ * Trim an extraction to `maxChars`, recording exactly what was dropped. A
+ * truncated payload that does not say so is worse than a short one: the caller
+ * reads a partial custody schedule as the whole schedule.
+ */
+export function applyCharBudget(extracted, maxChars) {
+    switch (extracted.kind) {
+        case 'text':
+        case 'document': {
+            if (extracted.text.length <= maxChars)
+                return extracted;
+            return { ...extracted, text: clip(extracted.text, maxChars), truncated: true };
+        }
+        case 'spreadsheet': {
+            const sheets = [];
+            const omitted = [...(extracted.omitted ?? [])];
+            let budget = maxChars;
+            let truncated = extracted.truncated ?? false;
+            for (const sheet of extracted.sheets) {
+                if (budget <= 0) {
+                    omitted.push(omissionNote(sheet.name));
+                    truncated = true;
+                    continue;
+                }
+                if (sheet.csv.length <= budget) {
+                    sheets.push(sheet);
+                    budget -= sheet.csv.length;
+                    continue;
+                }
+                const csv = clip(sheet.csv, budget);
+                sheets.push({ ...sheet, csv, rows: csv.split('\n').length, truncated: true });
+                budget = 0;
+                truncated = true;
+            }
+            return {
+                ...extracted, sheets, truncated,
+                ...(omitted.length ? { omitted } : {}),
+            };
+        }
+        case 'presentation': {
+            const slides = [];
+            const omitted = [...(extracted.omitted ?? [])];
+            let budget = maxChars;
+            let truncated = extracted.truncated ?? false;
+            for (const slide of extracted.slides) {
+                const size = slide.text.length + (slide.notes?.length ?? 0);
+                if (budget <= 0) {
+                    omitted.push(omissionNote(`slide ${slide.number}`));
+                    truncated = true;
+                    continue;
+                }
+                if (size <= budget) {
+                    slides.push(slide);
+                    budget -= size;
+                    continue;
+                }
+                slides.push({ ...slide, text: clip(slide.text, budget), notes: undefined });
+                budget = 0;
+                truncated = true;
+            }
+            return { ...extracted, slides, truncated, ...(omitted.length ? { omitted } : {}) };
+        }
+        case 'pdf': {
+            const pages = [];
+            const omitted = [...(extracted.omitted ?? [])];
+            let budget = maxChars;
+            let truncated = extracted.truncated ?? false;
+            for (const page of extracted.pages) {
+                if (budget <= 0) {
+                    omitted.push(omissionNote(`page ${page.number}`));
+                    truncated = true;
+                    continue;
+                }
+                if (page.text.length <= budget) {
+                    pages.push(page);
+                    budget -= page.text.length;
+                    continue;
+                }
+                pages.push({ ...page, text: clip(page.text, budget) });
+                budget = 0;
+                truncated = true;
+            }
+            return { ...extracted, pages, truncated, ...(omitted.length ? { omitted } : {}) };
+        }
+    }
+}
+/** Default response budget: roughly 12k tokens of extracted text. */
+export const DEFAULT_MAX_CHARS = 50_000;
+function decodeText(bytes) {
+    const text = bytes.toString('utf8');
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+/**
+ * Extract readable content from an attachment, or return null when the format
+ * has no extractor (a .zip, a .heic, an unknown binary) and the caller should
+ * fall through to the next rung of the delivery ladder.
+ *
+ * Throws when a format that SHOULD be extractable cannot be read, so the
+ * failure can be reported by name rather than swallowed.
+ */
+export async function extractAttachment(bytes, mimeType, fileName, opts = {}) {
+    const kind = extractKindFor(mimeType, fileName);
+    if (kind === null)
+        return null;
+    const select = opts.parts === undefined ? undefined : parsePartSpec(opts.parts);
+    let extracted;
+    switch (kind) {
+        case 'xlsx':
+            extracted = await extractXlsx(bytes, { select });
+            break;
+        case 'csv':
+            extracted = extractDelimited(decodeText(bytes), fileName, ',');
+            break;
+        case 'tsv':
+            extracted = extractDelimited(decodeText(bytes), fileName, '\t');
+            break;
+        case 'docx':
+            extracted = await extractDocx(bytes);
+            break;
+        case 'pptx':
+            extracted = await extractPptx(bytes, { select });
+            break;
+        case 'pdf':
+            extracted = await extractPdf(bytes, { select });
+            break;
+        case 'text':
+            extracted = { kind: 'text', text: decodeText(bytes) };
+            break;
+    }
+    return applyCharBudget(extracted, opts.maxChars ?? DEFAULT_MAX_CHARS);
+}

package/dist/extract/inflate.js

@@ -0,0 +1,55 @@
+// Bounded decompression, shared by the ZIP reader and the PDF stream decoder.
+//
+// Both formats let the FILE state how big a member expands to, and both are
+// read from co-parent-supplied attachments. A declared size is therefore a
+// hint, never a guarantee: a ZIP central directory can claim 1 KB in front of a
+// member that expands to a gigabyte, and a PDF stream dictionary declares
+// nothing about its inflated length at all. Checking the declared number before
+// inflating rejects an HONEST oversized member cheaply — it does nothing about
+// a lying one.
+//
+// So the real cap is enforced on the bytes as they actually arrive: read the
+// decompressed stream chunk by chunk, and abort the moment the running total
+// passes the limit. Peak memory is then bounded by the limit rather than by
+// whatever the file felt like claiming.
+/** 32 MiB. Sized to fit comfortably inside the Worker's memory budget. */
+export const MAX_DECOMPRESSED_BYTES = 32 * 1024 * 1024;
+/**
+ * Thrown when decompression is aborted for exceeding its cap. Distinct from a
+ * decode failure so callers can tell "this file is hostile or absurd" from
+ * "this stream is corrupt" — the first deserves to be reported, the second is
+ * routinely survivable.
+ */
+export class DecompressionLimitError extends Error {
+    constructor(label, limit) {
+        super(`${label} expands past the ${limit}-byte decompression cap`);
+        this.name = 'DecompressionLimitError';
+    }
+}
+/**
+ * Inflate `data`, aborting if the OUTPUT exceeds `limit` bytes.
+ *
+ * `deflate-raw` is the ZIP member format; `deflate` is the zlib-wrapped form a
+ * PDF `/FlateDecode` stream uses. Both go through the WHATWG
+ * `DecompressionStream` so this runs unchanged on Node and workerd.
+ */
+export async function inflateBounded(data, format, limit, label) {
+    const stream = new Blob([data]).stream()
+        .pipeThrough(new DecompressionStream(format));
+    const reader = stream.getReader();
+    const chunks = [];
+    let total = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        total += value.length;
+        if (total > limit) {
+            // Stop pulling: the rest of the payload is never allocated.
+            await reader.cancel();
+            throw new DecompressionLimitError(label, limit);
+        }
+        chunks.push(value);
+    }
+    return Buffer.concat(chunks);
+}

package/dist/extract/ooxml.js

@@ -0,0 +1,58 @@
+// Shared OOXML plumbing: part-path resolution and relationship lookup.
+//
+// Every OOXML format points from one part to another through a `_rels` file
+// (`r:id="rId3"` → `Target="worksheets/sheet3.xml"`), and the target is
+// relative to the REFERRING part's directory. Guessing the target from the id
+// number instead works right up until a document has been edited enough for the
+// numbering to drift, which is why this indirection is followed properly.
+import { elements, attr } from './xml.js';
+/** Resolve a relationship target against the referring part's directory. */
+export function resolvePartPath(baseDir, target) {
+    // A leading "/" means package-absolute.
+    if (target.startsWith('/'))
+        return target.slice(1);
+    const segments = (baseDir + target).split('/');
+    const out = [];
+    for (const segment of segments) {
+        if (segment === '.' || segment === '')
+            continue;
+        if (segment === '..')
+            out.pop();
+        else
+            out.push(segment);
+    }
+    return out.join('/');
+}
+/** The directory of a part path, with a trailing slash (`""` at the root). */
+export function dirOf(partPath) {
+    const i = partPath.lastIndexOf('/');
+    return i === -1 ? '' : partPath.slice(0, i + 1);
+}
+/** Read the `_rels` companion of `partPath`. Empty when the part has none. */
+export async function readRels(zip, partPath) {
+    const dir = dirOf(partPath);
+    const base = partPath.slice(dir.length);
+    const xml = await zip.readText(`${dir}_rels/${base}.rels`);
+    if (!xml)
+        return [];
+    const rels = [];
+    for (const el of elements(xml, 'Relationship')) {
+        const id = attr(el.attrs, 'Id');
+        const target = attr(el.attrs, 'Target');
+        /* v8 ignore next -- a Relationship without Id/Target is malformed OOXML; skipping keeps one bad entry from failing the whole read */
+        if (!id || !target)
+            continue;
+        rels.push({ id, target: resolvePartPath(dir, target), type: attr(el.attrs, 'Type') ?? '' });
+    }
+    return rels;
+}
+/**
+ * Locate a top-level part: the conventional path when present, otherwise the
+ * first entry whose name ends with the same file name. Producers other than
+ * Microsoft's occasionally use a different directory.
+ */
+export function findPart(zip, conventional, fileName) {
+    if (zip.has(conventional))
+        return conventional;
+    return zip.names().find((n) => n.endsWith(`/${fileName}`) || n === fileName) ?? null;
+}