irish-census-mcp 0.2.0__tar.gz

irish_census_mcp-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,90 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.11"
+
+      - name: Verify package imports
+        run: |
+          uv sync --frozen
+          uv run python -c "
+          import asyncio
+          from irish_census_mcp.server import mcp
+          async def check():
+              tools = await mcp.list_tools()
+              names = {t.name for t in tools}
+              expected = {'resolve_place', 'search_people', 'get_household',
+                          'get_person', 'find_relatives', 'get_scan_url'}
+              assert names == expected, f'tool mismatch: got {names}, expected {expected}'
+              print(f'OK: {len(tools)} tools registered on {mcp.name!r}')
+          asyncio.run(check())
+          "
+
+      - name: Verify version matches the pushed tag
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION=$(uv run python -c "from importlib.metadata import version; print(version('irish-census-mcp'))")
+          echo "tag=$TAG_VERSION  pkg=$PKG_VERSION"
+          if [ "$TAG_VERSION" != "$PKG_VERSION" ]; then
+            echo "::error::Tag $TAG_VERSION does not match package version $PKG_VERSION. Bump pyproject.toml before tagging."
+            exit 1
+          fi
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Inspect built artifacts
+        run: |
+          ls -lh dist/
+          uv run python -m zipfile -l dist/*.whl
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    # Only publish on actual tag pushes — not workflow_dispatch dry-runs.
+    if: startsWith(github.ref, 'refs/tags/v')
+    environment:
+      name: pypi
+      url: https://pypi.org/p/irish-census-mcp
+    permissions:
+      id-token: write   # required for Trusted Publishing (OIDC)
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # Trusted Publishing is configured at https://pypi.org/manage/account/publishing/
+          # No API token needed — the action authenticates via OIDC.
+          verbose: true

irish_census_mcp-0.2.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+build/
+dist/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+
+# Editor / IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+.DS_Store
+
+# Local Claude Code state (per-user, not part of the project)
+.claude/
+
+# Downloaded scans during testing
+*.pdf

irish_census_mcp-0.2.0/1901_1911_CENSUS.md

@@ -0,0 +1,281 @@
+# Irish 1901 & 1911 Census — API Reference
+
+Unofficial reverse-engineered notes for the public JSON API behind the
+National Archives of Ireland's 1901/1911 census search at
+[`https://www.census.nationalarchives.ie/`](https://www.census.nationalarchives.ie/).
+The same API is also called from the newer 2026 unified site.
+
+These are the two surviving full Irish censuses from before independence —
+all earlier 19th-century enumerators' returns (1861, 1871, 1881, 1891)
+were destroyed in the Four Courts fire of 1922; the 1901 and 1911 books
+survived because they were stored elsewhere. This corpus covers all 32
+counties (i.e. the whole island, not just the later Free State).
+
+> **No authentication required.** CORS is wide-open
+> (`Access-Control-Allow-Origin: *`). Throttle yourself and identify with
+> a sensible `User-Agent`.
+
+---
+
+## Host
+
+```
+https://api-census.nationalarchives.ie
+```
+
+Backend is `nginx/1.26.2` with a `census` handler. Responses carry
+`x-cached: HIT|EXPIRED` headers, so the upstream is well-cached.
+
+---
+
+## Endpoints
+
+| Endpoint | Purpose |
+| --- | --- |
+| `GET /census/query` | Person search |
+| `GET /census/facets` | Facet counts |
+| `GET /census/image/{nai_id}.pdf` | Scan PDF (307-redirects to signed Linode URL) |
+
+---
+
+## `GET /census/query`
+
+### Query parameters
+
+Filters use Django-style suffixes; no suffix means exact match. Unknown
+parameters are silently ignored (no validation error).
+
+| Parameter | Type | Example | Notes |
+| --- | --- | --- | --- |
+| `surname` / `surname__icontains` / `surname__iexact` | str | `Murphy` | |
+| `firstname` / `firstname__icontains` / `firstname__iexact` | str | `Denis` | **One word**, not `first_name` |
+| `census_year` | `1901` \| `1911` | `1911` | Filter to one census |
+| `county` | str | `Cork` | All 32 counties; spelling per 1901-era usage (`Londonderry`, `Queens` for Laois, `Kings` for Offaly) |
+| `ded` / `ded__icontains` | str | `Skibbereen Rural` | District Electoral Division |
+| `townland` / `townland__icontains` | str | `Coolnagarrane` | |
+| `house_number` | str | `7` | |
+| `sex` | `M` / `F` | `F` | |
+| `age` / `age__gte` / `age__lte` | int | `80` / `85` | Integer column — range filters work directly |
+| `religion` | str | `Roman Catholic` | Raw transcription (`R Catholic`, `R.C.`, etc. all appear) |
+| `religion_updated` | str | `Roman Catholic` | **Normalized — prefer this for filtering** |
+| `occupation` / `occupation__icontains` | str | `Farmer` | |
+| `occupation_updated` | str | `Farmer` | Normalized |
+| `language` | str | `Irish & English` | Raw |
+| `language_updated` | str | | Normalized |
+| `relation_to_head` | str | `Head of Family` | Raw |
+| `relation_to_head_updated` | str | | Normalized |
+| `marriage_status` | str | `Married`, `Single`, `Widower`, `Not Married` | |
+| `marriage_years` | int | `15` | Integer where parseable |
+| `children_born` / `children_living` | int | | Numeric in 1911 (1901 forms didn't ask) |
+| `birthplace` / `birthplace__icontains` | str | `Co Dublin` | Raw transcription — very inconsistent |
+| `education` | str | `Read and write` | |
+| `deafdumb` | str | | Disability column from the form |
+| `image_group` | str | `388680` | All people in a household share this — use it to reconstruct a family |
+| `id` | int | `1434682` | Per-person primary key |
+| `limit` | int | `30` | Default page size |
+| `offset` | int | `0` | Pagination cursor |
+
+### Response
+
+```json
+{
+  "results": [
+    {
+      "id": 1434682,
+      "census_year": 1911,
+      "county": "Cork",
+      "ded": "Cork No. 4 Urban (part of)",
+      "townland": "Rathmore Buildings",
+      "house_number": "72",
+      "firstname": "Denis",
+      "surname": "Murphy",
+      "age": 34,
+      "sex": "M",
+      "relation_to_head": "Son",
+      "relation_to_head_updated": "Son",
+      "religion": "R Catholic",
+      "religion_updated": "Roman Catholic",
+      "education": "Read and write",
+      "occupation": "Labourer",
+      "occupation_updated": "Labourer",
+      "marriage_status": "Single",
+      "marriage_years": null,
+      "children_born": null,
+      "children_living": null,
+      "birthplace": "Cork City",
+      "language": "English",
+      "language_updated": "English Only",
+      "deafdumb": null,
+      "image_group": "388680",
+      "images": [
+        { "form": "Form A",  "side": "1", "id": "nai001861365", "url": "/census/image/nai001861365.pdf" },
+        { "form": "Form A",  "side": "2", "id": "nai001861366", "url": "/census/image/nai001861366.pdf" },
+        { "form": "Form N",  "side": "1", "id": "nai001861204", "url": "/census/image/nai001861204.pdf" },
+        { "form": "Form B1", "side": "1", "id": "nai001861206", "url": "/census/image/nai001861206.pdf" }
+      ]
+    }
+  ],
+  "meta": {
+    "count": 8830075,
+    "next": "?limit=1&offset=1",
+    "prev": null
+  }
+}
+```
+
+**Big convenience compared to the 1926 API:** each row already embeds an
+`images` array — no follow-up `related_images` call needed.
+
+### Forms returned
+
+| Form | Meaning |
+| --- | --- |
+| **Form A** | Individual return — the household head's record of every person resident on census night |
+| **Form B1** | House and Building Return — building fabric (walls, roof, windows, rooms) |
+| **Form B2** | Out-Offices and Farm-Steadings Return — stables, cow houses, piggeries, barns |
+| **Form N** | Enumerator's Abstract — summary page the enumerator compiled |
+
+Each form may have 2 `side`s (front and back of the original page).
+Institutional returns (workhouses, asylums, barracks, ships) use
+different form letters (D, E, F, G, H) and may or may not appear here.
+
+### Row counts
+
+```
+1901: 4,434,938 rows
+1911: 4,395,137 rows
+Total: 8,830,075
+```
+
+---
+
+## `GET /census/facets`
+
+Same filter parameters as `query`. Returns top-N value counts to drive
+sidebar drill-down.
+
+Returned facet fields (top 20 values each, top 14 for `age`):
+
+```
+county, ded, townland, surname, age, birthplace,
+religion_updated, occupation_updated, language_updated
+```
+
+Response shape:
+
+```json
+[
+  {
+    "field": "occupation_updated",
+    "counts": [
+      {"value": "Scholar", "ct": 1693048},
+      {"value": "Farmer",  "ct": 775485},
+      ...
+    ]
+  },
+  ...
+]
+```
+
+(`Scholar` topping the occupation list reflects compulsory schooling — every
+school-age child was recorded as "Scholar".)
+
+---
+
+## `GET /census/image/{nai_id}.pdf`
+
+Returns the scan as a PDF.
+
+```
+GET /census/image/nai003096222.pdf
+→ 307 Found
+   Location: https://nl-ams-1.linodeobjects.com/nai-census/1901-11/000/003/096/222.pdf
+             ?AWSAccessKeyId=…&Signature=…&Expires=1778444264
+```
+
+- The redirect target is a **signed Linode Object Storage URL** that
+  **expires in 30 minutes** (`Expires` query param + `Cache-Control: max-age=1800`).
+  Don't cache the redirected URL — cache the API URL and let the server
+  re-sign on each request.
+- Hosted in Linode's Amsterdam region (`nl-ams-1`).
+- The `nai_id` is exactly the string in `images[].id` (e.g. `nai001861365`).
+  Always append `.pdf` — bare IDs return 404.
+- A typical Form A side is ~600 KB, single page; institutional forms can
+  be much larger.
+
+---
+
+## Typical lookup flow
+
+```bash
+BASE=https://api-census.nationalarchives.ie/census
+
+# 1. Search
+curl -s "$BASE/query?surname__icontains=Murphy&county=Cork&census_year=1911&limit=10"
+
+# 2. Pick a row — note its image_group to fetch household-mates
+curl -s "$BASE/query?image_group=388680"
+
+# 3. Download a scan (the URL from images[].url is relative, prepend host)
+curl -sL -o form_a_side_1.pdf \
+  "$BASE/image/nai001861365.pdf"
+```
+
+The 1926 API requires three calls to do this (query → related_images →
+image_c26). Here, steps 1 already gives you the image URLs.
+
+---
+
+## Data quality notes
+
+- The **raw** columns (`religion`, `occupation`, `relation_to_head`,
+  `language`, `birthplace`) preserve enumerator handwriting variation —
+  expect every plausible abbreviation of "Roman Catholic": `R Catholic`,
+  `R.C.`, `Rom Cath`, `Roman Catholic`, …
+- The **`*_updated`** columns are post-hoc normalizations. Filter on
+  those; display the raw column if you want fidelity to the original.
+- `birthplace` is the noisiest field — free text covering counties,
+  countries, ships, regiments, and one-off place names. Use
+  `__icontains` rather than exact match.
+- `children_born` / `children_living` only appear on 1911 forms — the
+  1901 schema didn't ask the question. Don't treat them as numerics
+  without null-checking.
+- `marriage_years` is integer-typed in this API (unlike the 1926 schema
+  where it's a raw string).
+- 1911 `age` for women may show systematic **suffrage-protest blanks** —
+  some respondents refused to fill it in. Don't read too much into
+  null-age clusters.
+
+---
+
+## County names — gotchas
+
+The 1901/1911 census predates the renaming of two counties:
+
+| Modern name | 1901/1911 name |
+| --- | --- |
+| Laois | `Queens` (sometimes `Queen's`) |
+| Offaly | `Kings` (sometimes `King's`) |
+| Derry / Londonderry | `Londonderry` |
+
+If you're cross-referencing with the 1926 corpus (Free State only,
+modern names), you'll need to map between these.
+
+---
+
+## Operational details
+
+- **Server:** `nginx/1.26.2` with `x-handler: census`
+- **CORS:** `Access-Control-Allow-Origin: *` (no origin pinning, unlike the 1926 API)
+- **HTTPS:** mandatory
+- **Unknown query params:** silently ignored, no 422
+- **Pagination:** `meta.next` / `meta.prev` are relative query strings; append to the endpoint path
+- **Validation errors:** `{"detail": "..."}` JSON body
+- **Image redirects:** 307 with a 1800s-second TTL — single-flight per ID is plenty
+
+---
+
+## See also
+
+- [`1926_CENSUS.md`](./1926_CENSUS.md) — the post-independence 1926 census (different host, different schema, three-step image flow)
+- [`PRE_FAMINE_CENSUS.md`](./PRE_FAMINE_CENSUS.md) — surviving fragments from 1821, 1831, 1841, 1851 (same host as this API, `query_c19` / `facets_c19` endpoints)