papers

Open interface for accounting working papers and engagements.

papers lets software and AI work with an engagement through portable accounting concepts — engagements, trial balances, adjustments, working papers, review notes — instead of one vendor's file format and field IDs. Caseware is the first adapter.

Status: early development. The concepts and the adapter contract are defined. The Caseware adapter is specified but not implemented, and every capability it reports is false. Treat this as infrastructure under construction, not production software.

The idea

A compilation or a year end is the same shape of work everywhere: a trial balance arrives, accounts get grouped, balances get supported by evidence, questions get raised and cleared, adjustments get proposed and reviewed. The concepts are portable. Only the storage is not.

So papers separates three things:

The concepts — what an engagement is made of, in accounting terms. Nothing in src/concepts names a vendor, a file format or a field ID. When a concept cannot be expressed without one, it belongs in an adapter.

The adapter contract — what a given system can actually do, declared rather than assumed, and how a mutation is planned before it is performed.

The adapters — the translation, and the only place vendor specifics live.

Related MCP server: manager-mcp

Two rules that shape the contract

Capabilities are declared, never assumed. A caller asks what an adapter supports before asking it to do anything. A desktop Working Papers bridge and a future Cloud adapter will not support the same set, and failing halfway through a write is not an option in a file a firm is professionally responsible for.

validate is the default; commit is a separate decision. Every mutation is planned first and returns what it would change, with the warnings a reviewer should see. Nothing reaches a firm's file until a caller asks for it explicitly — which in practice means an accountant did.

Two smaller ones fall out of the same concern. Money is integer minor units, because a trial balance has to tie exactly and floats do not. And every value carries where it came from — adapter, document, page, checksum — so a reviewer can get back to the source rather than trusting the number.

Grouping is the firm's, not ours

Account.group is a free string on purpose.

Grouping numbers differ between firms, and between files at the same firm. There is no universal Caseware grouping to learn. A fixed enum here would quietly mistranslate one firm's 240 into another's, which is exactly the class of error nobody catches until a financial statement is wrong.

The mapping belongs to the firm's own methodology, informed by the prior-year file and the accounts themselves, and confirmed by a person when it is uncertain. papers carries it; it does not decide it.

Reaching Caseware

Caseware is three surfaces, not one, and they do not answer the same questions.

Under all three, the floor that works at any firm today: the firm's own export — GIFI, the Working Trial Balance to Excel, or Cloud's Export to Working Papers (CSV ASCII). A person clicks it, we read the file, nothing is licensed.

The Desktop SDK is not a path we can take alone. Caseware's SDK licence is "not transferrable and cannot be used by third-party developers outside your firm", and does not permit development "for resale or distribution outside of the licensed firm". A bridge we author and hand to a firm is exactly that, whoever's licence it runs under. It needs the firm's own people, or a partner agreement.

So the order is: exports, then the Cloud API, then Sherlock for the trial balance, then the desktop only behind an agreement. docs/caseware-surface.md has the detail and the sources.

What does not change is the credential boundary. Working Papers is a desktop application — firms run it on Windows, often through Citrix, against a network share — so where a desktop path is taken it is taken by something running inside the firm's environment, beside the files:

papers (MCP)  →  adapter  →  documented bridge protocol
                                        │
                 ── firm environment ───┼───────────────
                                        ▼
                             bridge  →  Working Papers

The protocol and the adapters are ours and are open. Anything linking Caseware's own SDK is not distributed from here at all.

Before using any of this across more than one firm, read docs/security.md. Caseware's API Usage Policy permits a customer to engage a third-party developer for its own internal purposes, and separately requires a formal partner review and written approval before an integration is commercialized or offered to multiple firms.

Install

npm install
npm run build

Run the MCP server over stdio:

PAPERS_ADAPTER=caseware npm start

With no PAPERS_ADAPTER, the server starts and reports no capabilities — useful for inspecting the tool surface without touching a firm's files.

Related

fisc — the same idea for professional tax software: Taxprep, DT Max.

License

Apache-2.0. See LICENSE and NOTICE.