# fold3-com-mcp

An MCP server for [Fold3](https://www.fold3.com), Ancestry's military-records site. It covers:
- search across service records, pension files, muster rolls, draft cards, casualty lists, census and newspapers;
- reading files, pages, index records, census lines and memorials;
- browsing a collection's tree;
- full-resolution page images.

It calls the site's own services from Node. It signs in through the Ancestry session that
[ancestry-com-mcp](https://github.com/ball2jh/ancestry-com-mcp) already saved (Fold3's "Sign in with Ancestry"), so
there is no browser or password. It is read-only.

## Tools

| Tool | Actions | What for |
|---|---|---|
| `fold3_search` | `search`, `facets` | Hits with their type, collection, index fields and matched values; facet counts to choose filters. |
| `fold3_record` | `get` | A FILE (index fields, every page's image id, access, citation), IMAGE, INDEX_RECORD, SUB_IMAGE (a census line) or MEMORIAL (facts and linked Ancestry records). |
| `fold3_collection` | `list`, `get`, `browse` | Find collections, read one (access level, NARA publication), and walk its browse tree (state › surname › given name › file). |
| `fold3_download` | `image`, `file` | Page images at full resolution (stitched from the viewer's tiles), inline or to disk; a whole file to a directory with a SHA-256 manifest. |
| `fold3_session` | `status`, `login` | Whether the session is signed in and what the account may open. |
| `fold3_raw_request` | `get`, `post` | Read-only requests to Fold3's services, and POST only to the search. |

What the search does, and why (each point checked against live counts; see `docs/endpoints.md`):
- **Person dates use the person fields.** `birthYear`, `deathYear` and `serviceYear` map to `date.vital.birth`,
  `date.vital.death` and `date.military`. Fold3's generic date filter matches collection date spans: a 1775-2019
  gravesite index matches any year. That filter is offered as `coverageYear` and described as such.
- **`name` matches every name indexed in a file**, witnesses included; `matched` shows why a hit came back.
- **`[Blank]` index fields are dropped.** Fold3 lists every field of a collection's schema on every record.
- **`/record/` URLs are resolved by their slug.** Index records and census lines share ids (61017601 is both).

Access: searching and index data need no subscription. Images need an account that may view the collection. The
user's account (linked to their Ancestry login) is a Fold3 non-subscriber, so `PUBLIC` collections (the War of 1812
pension files, among others) open and `SUBSCRIBER` ones say they need a subscription.

## Setup

Requirements: Node 26+ (runs TypeScript directly) and pnpm; no browser.

```bash
pnpm install
```

`.mcp.json`:

```json
{ "mcpServers": { "fold3": { "command": "node", "args": ["/path/to/fold3-com-mcp/src/server.ts"],
  "env": { "ANCESTRY_SESSION_FILE": "/path/to/ancestry-com-mcp/.session.json", "FOLD3_SESSION_FILE": "/path/to/fold3-com-mcp/.session.json" } } } }
```

- `ANCESTRY_SESSION_FILE` (default `~/Projects/ancestry-com-mcp/.session.json`) is only read, never written.
- `FOLD3_SESSION_FILE` (default `.session.json` in this checkout, mode 600, git-ignored) keeps the Fold3 cookies.
- `FOLD3_MIN_INTERVAL_MS` (default 250) spaces requests.

## Tests

- `pnpm test`: unit tests on recorded responses (`test/fixtures`, re-recorded with `node scripts/record-fixtures.ts`,
  which strips tokens and the account id). No network.
- `pnpm mcp-test`: live, over stdio. It calls every action and error path, checks sizes, and downloads a few pages
  to a temp directory. It also runs a count comparison for every search filter: a real value must narrow the total
  and a nonsense value must give about zero.
- `pnpm typecheck`.

## Caveats

- Fold3's index is transcribed by volunteers and staff. Read the images for anything that matters, and cite the file
  (`fold3_record get` returns a citation for a FILE).
- A search reaches only its first 10,000 hits and returns at most 50 per call.
- A full-resolution page is 20 to 60 tiles, so it takes several seconds. `fold3_download file` fetches at most 40
  pages per call and keeps pages already on disk.