Metadata-Version: 2.4
Name: bartram-companies-house
Version: 0.1.1
Summary: UK Companies House data via MCP — company search, profiles, officers, beneficial owners, and filings with cleaning and deduplication.
Project-URL: Homepage, https://github.com/RobertAlsop/bartram_foundry
Project-URL: Repository, https://github.com/RobertAlsop/bartram_foundry
Author: Bartram Foundry
License-Expression: MIT
License-File: LICENSE
Keywords: agent,companies-house,company-data,mcp,uk
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rapidfuzz>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Description-Content-Type: text/markdown

# UK Companies House MCP Server

Clean, structured UK company data for AI agents — via the [Model Context Protocol](https://modelcontextprotocol.io/).

<!-- mcp-name: io.github.RobertAlsop/companies-house -->

## What this does

This MCP server gives agents access to UK Companies House data — company search, profiles, officer records, beneficial ownership, and filing history — with data cleaning that the raw API doesn't provide.

Companies House data has known quality issues: officer names appear in multiple formats creating ~614K duplicate records, corporate entities get filed as natural persons in PSC (beneficial ownership) data, and addresses arrive in inconsistent formats. This server fixes those problems before the data reaches your agent.

**What the cleaning layer does:**

- **Officer deduplication** — fuzzy name matching merges records like "SMITH, John David" and "John Smith" when they share the same role and company.
- **PSC entity classification** — flags corporate entities incorrectly filed as natural persons, using identification fields and name pattern detection.
- **Address normalisation** — consistent formatting, postcode standardisation, single-line formatted output.
- **Filing descriptions** — converts Companies House's hyphenated codes (like `termination-director-company-with-name-termination-date`) into readable text.
- **Company number normalisation** — agents can send `445790` and the server correctly zero-pads it to `00445790`.
- **Full officer pagination** — fetches all pages automatically, not just the first 50.
- **Data quality annotations** — every cleaned record carries `_cleaning` metadata so agents can see what was changed and why.

## Quick start

**Works out of the box — no API key needed.**

```bash
# Install
pip install bartram-companies-house

# Run the MCP server
bartram-companies-house
```

Or with [uvx](https://docs.astral.sh/uv/):

```bash
uvx bartram-companies-house
```

For heavy usage or production workloads, register your own [Companies House API key](https://developer.company-information.service.gov.uk/) and set it as an environment variable:

```bash
export COMPANIES_HOUSE_API_KEY="your-key-here"
```

### Configure with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "companies-house": {
      "command": "uvx",
      "args": ["bartram-companies-house"]
    }
  }
}
```

## Tools

| Tool | Description |
|------|-------------|
| `uk_company_search` | Search for UK companies by name or number |
| `uk_company_profile` | Get company details — address, status, SIC codes, key dates |
| `uk_company_officers` | Get officers with name deduplication |
| `uk_company_psc` | Get beneficial owners with entity classification |
| `uk_company_filings` | Get filing history with readable descriptions |

See [SCHEMA.md](SCHEMA.md) for full parameter and response documentation with examples.

## Example

Ask your agent: *"Who are the directors of Tesco?"*

The agent calls `uk_company_search` with `query: "Tesco"`, gets the company number, then calls `uk_company_officers` with that number. The response includes deduplicated officer records with cleaning metadata:

```json
{
  "data": {
    "items": [
      {
        "name": "MURPHY, Ken",
        "officer_role": "director",
        "appointed_on": "2020-10-01",
        "nationality": "Irish",
        "_cleaning": {
          "deduplicated": true,
          "duplicate_count": 2,
          "original_names": ["MURPHY, Kenneth", "MURPHY, Ken"],
          "note": "Merged 2 records with similar names. Showing most recently appointed."
        }
      }
    ],
    "_cleaning": {
      "original_count": 45,
      "deduplicated_count": 38,
      "duplicates_removed": 7
    }
  },
  "metadata": {
    "source": "Companies House",
    "licence": "OGL v3.0",
    "endpoint": "/company/00445790/officers"
  }
}
```

Every response includes a `metadata` envelope with source attribution, licence information, and retrieval timestamp.

## Data source

All data comes from the [Companies House API](https://developer.company-information.service.gov.uk/) and is published under the [Open Government Licence v3.0](https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/). Crown copyright.

## Caching

Responses are cached locally in SQLite to reduce API calls and improve latency:

| Endpoint | TTL |
|----------|-----|
| Company search | 1 hour |
| Company profile | 24 hours |
| Officers | 6 hours |
| PSC | 6 hours |
| Filing history | 1 hour |

Cache is stored in `~/.bartram/cache.db` by default. Set `BARTRAM_DATA_DIR` to change the location.

## Development

```bash
git clone https://github.com/RobertAlsop/bartram_foundry.git
cd bartram_foundry
uv sync --all-extras
uv run pytest
uv run ruff check .
```

## Licence

MIT

---

Built by [Bartram Foundry](https://github.com/RobertAlsop/bartram_foundry) — production-grade MCP tools for UK public data.
