# au-trademark-trends-mcp

An MCP server for Australian trade mark trends, built on IP Australia's open
data at [data.gov.au/data/dataset/iprapid](https://data.gov.au/data/dataset/iprapid).
Python + DuckDB.

## Architecture

```
5 CSVs (5.2GB) ──→ etl/build_db.py ──→ data/tm.duckdb (995MB) ──→ src/server.py (MCP)
                   DuckDB reads CSV     6 normalised tables       12 tools, 10-800ms
                   directly             + 1 wide table
```

The ETL runs in about 47 seconds. `tm_application` is a **denormalised wide
table** - applicant, country, mark text and class count are all flattened into
it - so the common query is a single-table scan with no joins.

## Setup

```bash
python -m venv .venv
```

```bash
.venv\Scripts\python.exe -m pip install -r requirements.txt
```

Build the database (needs the five CSVs in the project root, about 33 seconds):

```bash
.venv\Scripts\python.exe etl\build_db.py
```

Run the end-to-end test (spawns a real MCP server and makes 20 tool calls
through the official client):

```bash
.venv\Scripts\python.exe test\smoke.py
```

Run the `tm_sql` guard tests, which assert the escape hatch cannot reach the
filesystem or the network:

```bash
.venv\Scripts\python.exe test\test_sql_guard.py
```

## Connecting

**Claude Code** - the repository ships a `.mcp.json` whose paths are relative to
the project root, so a clone works as soon as the dependencies are installed.
Start Claude Code in the project directory; the first run asks whether you trust
the project's MCP servers. No paths to edit.

To use it from any directory, register it at user scope instead. This needs
absolute paths - replace `<project path>` with your own:

```bash
claude mcp add -s user au-trademark-trends -- "<project path>/.venv/Scripts/python.exe" "<project path>/src/server.py"
```

**Claude Desktop** has no concept of a project directory, so absolute paths are
the only option. Edit `%APPDATA%\Claude\claude_desktop_config.json`, and note
that backslashes must be doubled inside JSON:

```json
{
  "mcpServers": {
    "au-trademark-trends": {
      "command": "<project path>\\.venv\\Scripts\\python.exe",
      "args": ["<project path>\\src\\server.py"]
    }
  }
}
```

Quit Claude Desktop **completely** and restart it afterwards - closing the
window is not enough, exit it from the system tray.

On Linux and macOS, use `.venv/bin/python` in place of
`.venv/Scripts/python.exe`.

## The 12 tools

| Tool | Answers |
|---|---|
| `tm_dataset_info` | Coverage, freshness, and **what it explicitly cannot answer** |
| `tm_filing_trend` | Filing volume over time, split by class, outcome or origin; yearly, quarterly or monthly |
| `tm_class_ranking` | Which Nice classes are rising or falling against an equal-length baseline |
| `tm_registration_outcomes` | Registration, lapse and refusal rates, plus average time to registration |
| `tm_keyword_trend` | **A word's trend in brand names**, with a `per_10k_filings` normalised rate |
| `tm_keyword_examples` | The actual marks a keyword matched, to check it measures what you think |
| `tm_applicant_ranking` | Leading applicants with growth and registration rates, merged into corporate groups |
| `tm_applicant_profile` | One group's filing history, main classes and usual agents |
| `tm_origin_trend` | Domestic versus foreign share, and the leading source countries |
| `tm_madrid_flow` | Madrid Protocol flow in and out of Australia; imports split by origin and class |
| `tm_render_chart` | Renders a self-contained SVG into `charts/` |
| `tm_sql` | Read-only SQL escape hatch for questions the other tools do not cover |

## Tables

| Table | Rows | Grain |
|---|---|---|
| `tm_application` | 2,314,887 | One row per application, denormalised |
| `tm_class` | 3,727,611 | Application x Nice class |
| `tm_mark` | 5,345,477 | Application x mark text representation |
| `tm_mark_primary` | 2,228,469 | One searchable headline mark text per application |
| `tm_party` | 7,656,643 | Application x party (applicant, agent, opponent) |
| `tm_applicant_primary` | 2,314,679 | The **founding** applicant of each application |
| `tm_applicant_entity` | 674,221 | party_id to resolved corporate group |
| `tm_link` | 1,428,159 | Madrid, convention priority, related applications |

### Applicant entity resolution

Neither identifier in the source data is a usable company key on its own. They
are many-to-many in **both** directions: one `party_id` can carry 19 different
names, and `avon products inc` spans 4 different `party_id` values across 1,975
filings. Nestlé is scattered across more than ten id/name pairs.

This changes answers. Ranked by legal name, the top 2021-2025 applicant is
Novartis on 484 filings. But Aristocrat filed 476 as `aristocrat technologies
australia pty ltd` and another 288 as `aristocrat technologies inc` - as a group
it leads with 767.

[`etl/entities.py`](etl/entities.py) treats `(party_id, normalised_name)` as
edges of a bipartite graph and takes its connected components, merging in both
directions at once. Names are normalised by stripping trading-as clauses,
punctuation, a leading article and trailing legal-form tokens (`pty ltd`,
`gmbh`, `kabushiki kaisha`, …). Names that are nothing but a legal form get no
matching edge, so they cannot pool unrelated companies.

The result is deliberately conservative - 674,221 party ids collapse to 638,142
groups, and no component exceeds 12 ids:

| Group size | Count |
|---|---|
| 1 (unmerged) | 606,306 |
| 2 | 28,612 |
| 3-5 | 3,169 |
| 6-10 | 66 |
| 11-50 | 1 |
| 51+ | 0 |

`tm_applicant_ranking` groups by entity by default; pass
`group_by="legal_name"` for the raw entities.

## Counting rules and traps

Every tool returns a `caveats` field. Pass it on when reporting results.

- **applications vs class_filings.** With no class filter the metric counts
  applications; with a class filter it counts class filings, so an application
  covering three classes is counted three times. The `metric` field says which.
- **The trailing period is always incomplete.** Data runs through 2026-08.
  `partial_buckets` flags the affected periods and charts shade them grey. Do
  not read the final period as a decline.
- **Status is a snapshot, not an examination outcome.** `dead` includes marks
  that registered and later lapsed or ceased. A high `pending` share in the last
  two or three cohorts is expected, not a signal.
- **Keyword search covers mark text only, not goods and services text.** Mark
  text exists for 96.3% of applications.
- **`per_10k_filings` is more trustworthy than a raw count.** It normalises
  against total filing volume, separating a real trend from overall market
  growth.
- **Individual applicant names are pseudonymised upstream** and cannot be
  recovered. Only organisation names are real.
- **Applicant rows are corporate groups by default.** Entity resolution is
  name-based and conservative, so unrelated companies sharing a plain name
  (several "Delta" companies) can still be pooled, and misspelt names
  (`aristocrat technolgies`) stay separate. `legal_entities_merged` shows how
  many names went into a row.
- **Filings are attributed to the founding applicant**, so later assignments do
  not move them.
- **Madrid exports have no destination country.** The source records only that a
  mark went out, so a total is all that is available.
- **The CSVs escape quotes with a backslash** (`\"`) rather than doubling them,
  so `read_csv` needs `escape='\'` or it fails partway through
  `party_activity.csv`.

## Not loaded yet

`application_events.csv` (4.2GB, 31.7M trade mark events) is not loaded. It
would unlock adverse examination rates, opposition rates, renewal rates and true
stage-by-stage pendency. Adding it is one more block in the ETL - the event
types are already confirmed: `exam_outcome_adverse` 1.36M,
`published_opp_lodged` 26,834, `removed_non_use` 6,495.

## Data source

**https://data.gov.au/data/dataset/iprapid** - IP Australia's intellectual
property rights open data, published on data.gov.au and updated periodically.
Drop replacement CSVs in the project root and re-run `etl/build_db.py`; the
server needs no changes.

The source CSVs and the built database are gitignored - 10.4GB in total, well
past GitHub's limits. The five files needed are:

```
application.csv                 720 MB
application_classification.csv  2.0 GB
application_description.csv     451 MB
application_links.csv           271 MB
party_activity.csv              1.8 GB
```

## Licence

The code is MIT - see [LICENSE](LICENSE).

That does not extend to the data, which IP Australia publishes under its own
terms. Confirm the current licence on the
[dataset page](https://data.gov.au/data/dataset/iprapid) before redistributing
the data or any derived dataset, and attribute IP Australia as the source.