Connector

Your coding agent uses three mdfi-connect tools, described here with every message they can return and what to do about it.

Configuration

Install the connector as the Quickstart shows. It reads two environment variables and nothing else:

The connector sends requests only to MDFI_API_URL, and it never logs document text. Every tool returns its answer, error messages included, as text: a tool never fails inside your agent's session.

Paths are read relative to the connector's working directory, the folder your agent starts it in. With Claude Code, that is the folder you start Claude Code in.

read_document

read_document(path) opens a local file.

• path: the file, absolute or relative to the working directory. ~ is expanded. Which files it reads lists what is accepted.

What it does:

1. It checks the path, then computes the file's SHA-256 and asks mdfi whether your account already has that file.
2. If not, it uploads the file: its contents and its name, not the folder it is in.
3. It waits up to 20 seconds, checking after 1 second and then every 2 seconds, and returns as soon as the document is ready or failed, a page is readable, or the document has an outline.

It returns a header (the file name, document_id, pages ready, status, quality, charge, and the ⚠ list of what is uncertain), the outline, and the text of the ready pages: all of them when they come to about 10,000 tokens or less, otherwise the first pages, up to about 3,000 tokens. The Quickstart shows a full example, and How it works explains each flag.

While the document converts, the last line starts with STILL CONVERTING — this is partial. It says which pages to read now and, when there is one, gives an estimate of the time left. Before mdfi has anything to report on the document, the answer is:

mdfi is preparing report.pdf
document_id: 1b4e28ba-2fa1-41d2-883f-0016d3cca427
status: converting
Nothing is readable yet — call read_document again with the same path shortly (no new upload, no extra charge).

A conversion that failed returns mdfi could not read <file>: <reason>, then the document id, status: failed and Nothing was charged. Do not rely on this file's content. Conversion failures lists the reasons.

Charges: a document is charged once, when its conversion completes. Calling read_document again on the same file sends only its SHA-256 and charges nothing, for as long as mdfi keeps the document (7 days). An edited file has a new hash, so it is a new document.

read_pages

read_pages(document_id, pages, section) returns the text of some pages of a document that read_document opened. Pass exactly one of pages and section.

• document_id: the id read_document printed, a UUID such as 1b4e28ba-2fa1-41d2-883f-0016d3cca427.
• pages: page numbers and ranges, such as "3,7,9-11". Pages start at 1, and a range runs low to high.
• section: a title from the outline; Choosing a section explains how it is matched.

pages and section are each at most 200 characters.

Each ready page comes under a --- page N --- line. A page with a concern gets a ⚠ line under that marker, and a page with an informational table note gets a plain note: line. Pages that are not ready yet are listed at the end, as still converting (about 5 minutes left): 8–12, or still converting — ask again shortly: 8–12 when there is no estimate. How it works says when each format's pages become readable.

After the text, the connector loads the document's page flags. If that request fails, the text still comes back, under a first line saying so: ⚠ page quality flags could not be loaded (<reason>) — call read_pages again before relying on these pages.

read_pages never charges.

Choosing a section

section is matched against the titles in the outline: exactly first, then ignoring case. Runs of spaces count as one space. The section's pages are the pages of that outline entry.

When several entries have the title, mdfi lists them instead of guessing. For example, with an "Introduction" in two chapters:

Section 'Introduction' matches 2 outline entries; pass one as "Parent > Title": Chapter 1 Filing Information > Introduction (pages 3–4); Chapter 2 Filing Status > Introduction (pages 12–13)

Pass the one you want as it is listed, without the pages in parentheses: section="Chapter 2 Filing Status > Introduction". The parts are separated by >, with a space on each side. You can name more of the entry's parents, outermost first: "Part I > Chapter 2 > Introduction". Entries with no parent, or with the same titles at every level above them, cannot be told apart this way; read them by page number.

A title that is not in the outline answers Section not found in outline: <section>.

export_table

export_table(document_id, table, path, overwrite) writes one table of a ready document to a CSV file.

• document_id: as for read_pages.
• table: the table's id, such as p13-t1, taken from its label in the page text: [table p13-t1 — 42 rows × 6 cols]. Tables explains the ids.
• path (optional): where to write the CSV, absolute or relative to the working directory. The default is mdfi-tables/<file-stem>-<table-id>.csv, for example mdfi-tables/report-p13-t1.csv. Missing folders are created.
• overwrite (optional, default false): replace files that already exist.

The CSV is UTF-8 with a byte-order mark, so Excel reads accented and other non-ASCII characters correctly. It has a header row and standard CSV quoting.

A cell that is not a number and starts with =, +, -, @, a tab or a carriage return is written with a leading ', so a spreadsheet does not run it as a formula. Numbers such as -12 and cells made only of dashes are written as they are.

When the table has notes, they are written to a notes file beside the CSV, named <name>.csv.notes.txt. The notes are the table's own notes, plus how many cells got a leading ' and which rows have a different number of cells from the header. With overwrite=true, a replaced file keeps its permissions (on macOS and Linux), and an old notes file is removed when the new table has no notes.

The reply says what was written:

Uncertain table — check it against the source before relying on it: "Total" row 3 does not add up in column "2025"
Wrote /home/you/project/mdfi-tables/report-p5-t1.csv (3 rows × 3 columns).
Notes: continues on page 6; 1 cell began with =, +, -, @, tab or carriage return and was prefixed with ' so spreadsheets do not run it as a formula
Notes saved to /home/you/project/mdfi-tables/report-p5-t1.csv.notes.txt.

The Uncertain table line comes first when the table has a problem; informational notes are on the Notes: line. A table can be exported only once the document is ready, because a page that is still being re-read can extend a table. export_table never charges.

Which files it reads

read_document reads only the path you pass, and only these file types (the extension may be in any case):

• A symbolic link is followed first, and the checks apply to the file it points to.
• A path with a hidden file or folder in it (a name starting with .) is refused, so .env, .git/config and ~/.ssh/… are never read. For a file inside the working directory, only the part of the path below that directory is checked, so a project that itself sits in a hidden folder still works.
• Files outside the working directory can be read.
• A file can be up to 100 MB and 1,000 pages (Limits).

The connector uploads nothing but that file. Data and privacy says what it sends.

Where CSVs are written

export_table writes a file only if all of these hold:

• the path ends in .csv (any case);
• it is inside the working directory;
• no file or folder in it below the working directory is hidden;
• neither the CSV nor its notes file is a symbolic link;
• neither file exists yet, unless overwrite=true.

Both files are first written to temporary files beside their targets and then renamed into place, the notes first. A write that fails part way, for example on a full disk, never leaves a half-written CSV, and an existing CSV is not lost.

Errors

Values in angle brackets, such as <path>, and the letters N, M and R stand for what the message fills in. Only a completed conversion is charged; an error answer never costs pages.

Setup and connection

Plan and allowance

Reading a file

These come from read_document.

When the path you passed is not the full path the connector read, the File not found, Not a file and Cannot read messages end with (you gave: <path>).

Reading pages and sections

These come from read_pages. The document_id and expiry messages also come from export_table.

Exporting a table

These come from export_table.

Conversion failures

When a conversion fails, read_document returns mdfi could not read <file>: <reason>, and read_pages and export_table answer Document is failed: <reason>. A failed conversion is not charged and not kept, so calling read_document on the file again converts it again.