# gaff-check

**Due diligence on any Irish property, for AI agents.**

`gaff-check` is an open-source [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that gives AI assistants — Claude, Cursor, ChatGPT, or any MCP-compatible agent — ground truth from Ireland's scattered public property datasets.

Ask your assistant:

> *"Should I bid on this bungalow in Killiney? Tell me everything I should worry about."*

…and it can check, in one conversation:

- 🏗️ **Planning applications** near the property (that pending apartment block behind the back garden)
- 💶 **Sold prices** on the street and in the area (Property Price Register)
- 🌊 **Flood risk** (OPW / GSI flood mapping)
- ☢️ **Radon risk** (EPA radon risk areas)
- 🗺️ **Zoning** (Myplan generalised land-use zoning)
- ⚡ **BER / energy rating context** and retrofit grant signals
- 🚓 **Recorded-crime context** for the containing Garda sub-district — category counts and carefully qualified rates, never a safety score

All from official, public Irish datasets. No scraping of commercial listing sites. Records and clearly labelled derived context — never invented certainty.

## Why

Buying (or renovating, or just being nosy about) a house in Ireland means trawling six-plus government websites, each with its own dreadful UX, none of which talk to each other. The data is public. The synthesis isn't. `gaff-check` is the glue: a single, boring, reliable tool layer so the *reasoning* can happen in your AI assistant.

## What it is not

- Not a valuation engine. It returns records; your agent does the thinking.
- Not a Daft/MyHome scraper. Public state data only.
- Not a website. It's a utility that enhances tools you already use.

## Quick start

`gaff-check` runs as a stdio MCP server and requires Node.js 20 or newer. Do not run `npx -y gaff-check` on its own: it will wait for an MCP client to send requests, so the terminal will appear to hang. Add it to your assistant instead; no API keys or separate package installation are needed.

Claude Code:

```bash
claude mcp add --transport stdio --scope user gaff-check -- npx -y gaff-check
```

Run `/mcp` in Claude Code to confirm that gaff-check is connected. `--scope user` makes it available in every project; omit that option if you want Claude Code's default project-local configuration instead.

Codex:

```bash
codex mcp add gaff-check -- npx -y gaff-check
```

Run `codex mcp list` to confirm the server is configured, then start a new Codex session and use `/mcp` to inspect the active tools.

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "gaff-check": { "command": "npx", "args": ["-y", "gaff-check"] }
  }
}
```

## What it looks like

> **You:** I'm thinking about a house near Fitzwilliam Square in Dublin 2, built in the 1980s. What should I know?
>
> **Claude** *(calling `resolve_location`, `planning_applications`, `sold_prices`, `radon_risk`, `zoning`, `flood_risk`, `ber_context`, `recorded_crime_context`)*:
>
> Here's what the public records say about that area:
>
> - **Planning:** 5+ applications within 300 m — most recently a protected-structure alteration granted Feb 2025 (Dublin City Council, ref WEB1305/25, 81 m away). Several protected-structure precedents on the square itself.
> - **Sold prices:** recent registered sales nearby range widely; the register shows exact declared prices per address (e.g. €1.8 m for a Howth Road semi in June 2026 — every record carries its date, address and VAT flag).
> - **Radon:** the area is in the EPA's "about 1 in 20 homes" band — not a designated High Radon Area, but the EPA advises testing any home (~€50).
> - **Zoning:** the square itself is zoned open space under the Dublin City Development Plan 2022–2028; surrounding streets are residential/mixed.
> - **Flood:** no mapped groundwater or historic flood extents at the point — but note the OPW's river/coastal models are licence-restricted and not checked; verify at floodinfo.ie.
> - **BER context:** 1978–1999 dwellings in Dublin 2 skew C/D. If the listing claims a B, ask to see the cert. Current SEAI grants: €12,500 max for a heat pump, €1,300 attic insulation for a semi-D (verified July 2026).
> - **Recorded crime:** annual CSO category counts for the containing Garda sub-district, plus a separately labelled wider division trend. These are administrative area totals, not incidents at the address; homicide and sexual offences are not published at sub-district level.
>
> Every figure above came from an official dataset, with source, licence, vintage and caveats attached in the payload.

## Hacking on it

```bash
git clone https://github.com/iarfhlaith/gaff-check.git
cd gaff-check
npm install && npm run build
```

The repo ships a project-scoped [`.mcp.json`](./.mcp.json) for Claude Code and [`.codex/config.toml`](./.codex/config.toml) for Codex. After building, open and trust the repository, then approve or restart the configured server when prompted. `npm test` runs the fixture-based unit tests; `RUN_E2E=1 npm run test:e2e` and `npm run eval` hit the live upstreams.

See [CONTRIBUTING.md](./CONTRIBUTING.md) for house style, [docs/HANDOVER.md](./docs/HANDOVER.md) for the concise operating brief, and [SPEC.md](./SPEC.md) plus [docs/DATA_SOURCES.md](./docs/DATA_SOURCES.md) for the detailed sources of truth.

## Status

Published on npm as `gaff-check@0.2.0`. Working today:

| Tool | What it answers | Source |
|---|---|---|
| `resolve_location` | "Where exactly is this address?" | OpenStreetMap Nominatim |
| `planning_applications` | "What's been applied for / decided near this point?" | National Planning Application Database (DHLGH) |
| `sold_prices` | "What did homes here actually sell for?" | Property Price Register (PSRA, official CSVs) |
| `radon_risk` | "Is this a high radon area?" | EPA Radon Risk Map |
| `zoning` | "What is this land zoned for?" | Myplan generalised zoning (DHLGH) |
| `flood_risk` | "Any mapped groundwater/historic flooding here?" | GSI flood mapping (plus a pointer to OPW's floodinfo.ie for river/coastal models, which are licence-restricted) |
| `ber_context` | "What BER is typical for a house of this age here, and what grants exist?" | CSO BER statistics (EBA02) + SEAI grant reference data |
| `recorded_crime_context` | "What recorded-crime categories are published for this wider Garda area?" | CSO CJA11/CJA39/CJQ10/CJQ11 + Garda boundaries + Census 2022 denominator |

All eight tools are implemented. Current priorities are post-launch reliability, upstream-drift detection, and keeping source/licence/grant metadata current; see [docs/LAUNCH.md](./docs/LAUNCH.md) for the watchlist.

**A note on Eircodes:** Eircode lookup is proprietary, so there's no free official way to turn an Eircode into coordinates. If you only have an Eircode, give your assistant the address too (or a rough location) — `resolve_location` handles the rest.

## Prior art

[irishmcp.ie](https://irishmcp.ie) hosts a PPR-only MCP server built on [CivicTech Ireland's price-register API](https://github.com/civictech-ie/price-register) — nice work, check it out if sold prices are all you need. gaff-check's scope is broader (planning, flood, radon, zoning, BER context), and it reads the official PSRA CSVs directly.

## Licence

MIT. Data returned by the tools is subject to the licences of the underlying public datasets (mostly CC-BY 4.0 / PSI) — see DATA_SOURCES.md.