# ArcaTax

Open-source, **local-first** US federal tax engine (Form 1040 + Schedules A, B, C, D, E and S-corp K-1
pass-throughs) that Claude drives over the [Model Context Protocol](https://modelcontextprotocol.io).
Claude interviews you and enters your documents; **deterministic Python does all the math**; the
result can be written onto the official IRS Form 1040 PDF.

> ## ⚠️ Read this first
> **ArcaTax is not a CPA, enrolled agent, attorney, or tax software vendor, and nothing it produces is tax,
> legal, or financial advice.** It is experimental, unaudited software. Tax law is intricate and several
> features (AMT, EITC, premium tax credit, education credits, foreign tax credit, state returns, the
> new 2025-2028 tips/overtime/auto-loan deductions, and more) are **not modelled**. The 2026 parameters were
> transcribed from IRS Rev. Proc. 2025-32 and statute, and items marked `[UNV]` in
> [`rules/2026/federal_1040.yaml`](rules/2026/federal_1040.yaml) were **not** independently verified.
> **Have a qualified professional review any return before you file it.** You alone are responsible for
> what you file. The software is provided "as is" under the license, with no warranty.
>
> **Privacy:** all tax data stays on your machine in `user_data/` and `returns/`, both git-ignored.
> ArcaTax has no telemetry, no cloud service, and does not store SSNs. The only network call it makes is
> an optional one-time download of the blank `f1040.pdf` from `irs.gov`. Caveat: when you chat with
> Claude, whatever you type or upload goes to Claude under your Anthropic account's terms. Local-first
> describes where ArcaTax stores data, not where the conversation goes.

## Architecture

```
 You ── chat/upload ──► Claude (skills/tax-interview.md)
                           │  MCP tool calls (stdio)
                           ▼
   src/arcatax/mcp_server.py   FastMCP("ArcaTax")
        │            │              │
        ▼            ▼              ▼
   schema.py     engine.py      pdf_filler.py / txf_exporter.py
   Pydantic      pure, no LLM   pypdf → returns/2026_Form1040_Draft.pdf
   state JSON    math + gap     TXF   → returns/2026_return.txf
        │        questions
        ▼            ▲
 user_data/       rules/2026/federal_1040.yaml   (all IRS numbers; edit here, not in code)
 return_2026.json rules/2026/f1040_field_map.json (result key → PDF field)
```

| Piece | Responsibility |
|---|---|
| `rules/2026/federal_1040.yaml` | Standard deductions, brackets, capital-gain breakpoints, NIIT, payroll/SE, SALT cap, QBI, credits. Each section is tagged with its source. |
| `schema.py` | Strict Pydantic v2 models: profile, W-2, 1099-INT/DIV/B/NEC, Schedule C, Schedule E, K-1 (1120-S), itemized deductions, adjustments, payments. Atomic, owner-only (0600) JSON persistence. |
| `engine.py` | `compute_return(state)` → line-by-line `Form1040Result` (lines 1a-37) plus Schedule D/E/SE, Forms 8959/8960/8995, QDCG worksheet, credits. `get_missing_or_clarifying_questions(state)` powers the interview. |
| `pdf_filler.py` | Downloads the blank form from irs.gov, resolves AcroForm fields from the JSON map (exact id or tooltip regex), fills numbers only. |
| `txf_exporter.py` | Exports source documents (W-2, 1099, Schedule C, estimated payments) as TXF v042. |
| `mcp_server.py` | Tools: `get_return_status`, `update_filing_profile`, `upsert_w2`, `upsert_1099`, `upsert_schedule_c`, `upsert_k1_1120s`, `calculate_1040_return`, `export_filing_packet`, plus `upsert_schedule_e`, `update_other_inputs`, `remove_document`. |

Rounding follows the paper form (whole dollars, half up, rounded values carried forward), and income below
$100,000 uses the IRS Tax Table midpoint method.

## Quick start (non-technical users)

Full walkthrough with screenshots-in-words and troubleshooting: **[docs/INSTALL.md](docs/INSTALL.md)**.

1. **Install Python 3.11+** from [python.org](https://www.python.org/downloads/) (Windows: tick *Add python.exe to PATH*).
2. **Install ArcaTax:** `python3 -m pip install arcatax` (Windows: `py -m pip install arcatax`).
3. **Connect it to Claude Desktop:** `python3 -m arcatax.installer` (Windows: `py -m arcatax.installer`), then fully
   quit and reopen Claude Desktop and say *"Help me prepare my 2026 federal tax return with ArcaTax."*

The setup tool backs up your Claude Desktop config and adds only the `arcatax` entry; your other servers are left
untouched. Your data lives in `~/ArcaTax` (override with `--data-dir`). `--dry-run` previews, `--uninstall` removes it.

## Developer install

Requires Python 3.11+.

```bash
git clone <this repo> ArcaTax && cd ArcaTax
python3 -m venv .venv
.venv/bin/pip install -e .
.venv/bin/python -m pytest
```

> `mcp` is pinned `<2` because 2.x renamed `FastMCP`.

## Claude Desktop (manual configuration)

`arcatax-setup` does this for you. To do it by hand instead, edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`,
Windows: `%APPDATA%\Claude\claude_desktop_config.json`), using **absolute paths**:

```json
{
  "mcpServers": {
    "arcatax": {
      "command": "/absolute/path/to/ArcaTax/.venv/bin/arcatax-mcp",
      "args": [],
      "env": { "ARCATAX_HOME": "/absolute/path/to/ArcaTax" }
    }
  }
}
```

Restart Claude Desktop. `ARCATAX_HOME` is where `user_data/`, `returns/` and `templates/` live (defaults to the
repo root in a source checkout, otherwise `~/ArcaTax`). Claude Desktop starts servers with an arbitrary working
directory, so set it explicitly. The interview procedure ships inside the server as the `tax_interview` prompt
(and as server instructions), so no copy-pasting is needed.

### Claude Code

```bash
claude mcp add arcatax --env ARCATAX_HOME=$PWD -- $PWD/.venv/bin/arcatax-mcp
```

### Cowork / plugin

[`plugin.json`](plugin.json) (mirrored at `.claude-plugin/plugin.json`) registers the MCP server and the skill.
Claude Code expects skills as `skills/<name>/SKILL.md`; if the flat `skills/tax-interview.md` is not picked up
by your client version, move it to `skills/tax-interview/SKILL.md`.

## The IRS PDF

```bash
.venv/bin/python -m arcatax.pdf_filler --download   # blank f1040.pdf → templates/irs_blank/
.venv/bin/python -m arcatax.pdf_filler --inspect    # list real field names + tooltips
```

IRS rewrites internal field ids every year, and its forms are XFA hybrids whose field descriptions
(`"1a. Total amount from Form(s) W-2..."`) live in the XFA template. The field map therefore matches on those
descriptions unless you pin an exact `field`. It resolves all 37 mapped lines uniquely on the **2025** Form 1040,
but **has not been run against a 2026 form**: the IRS was still serving the 2025 form when this was written.
**ArcaTax refuses to fill a form from the wrong year** (it reports why instead of writing 2026 numbers onto 2025
lines). When the 2026 form appears, run `--inspect`, check the `keys_unmatched` list that `export_filing_packet`
returns, and adjust `rules/2026/f1040_field_map.json` if lines were renumbered.
Name, SSN, address and signature are intentionally left blank.
ArcaTax does not e-file; use IRS Free File, commercial software, or a preparer.

## Modelling notes and known gaps

- Single-year (2026), federal only. Filing status MFS assumes you lived with your spouse (no passive allowance).
- QBI: per-business W-2 wage/UBIA limits, SSTB phase-out, loss netting, REIT/PTP dividends, $400 minimum.
  Home-office, SE-deduction and retirement adjustments are allocated to businesses pro rata.
- Passive losses: simplified Form 8582 ($25k allowance with phase-out); suspended amounts are reported, not tracked.
- S-corp K-1: ordinary loss and distribution limits apply only if `stock_basis_start_of_year` is supplied.
- Capital gains: 0/15/20% only (no 25%/28% collectibles or unrecaptured §1250 rates).
- Itemized: SALT cap with high-income phase-down, 7.5% medical floor, 0.5% charity floor; the 37%-bracket
  limitation is flagged, not computed.
- Not computed: AMT, EITC, premium tax credit, education/foreign/energy credits, taxable Social Security,
  tips/overtime/car-loan deductions, estimated-tax penalty, state taxes.

## Layout

```
rules/2026/        IRS parameters + PDF field map
src/arcatax/       schema, engine, pdf_filler, txf_exporter, mcp_server
skills/            tax-interview.md
templates/irs_blank/  blank IRS PDFs (the only PDFs git will track)
tests/             hand-checked 2026 scenarios
user_data/ returns/ tax_docs/   YOUR data (git-ignored)
```

## License

See [LICENSE](LICENSE).