Metadata-Version: 2.5
Name: kyb-tool-mcp
Version: 0.1.0
Summary: Open-source KYB (Know Your Business) screening and case-review engine, run locally as an MCP server.
Project-URL: Homepage, https://aditya23770.github.io/kyb-tool-mcp/
Project-URL: Repository, https://github.com/Aditya23770/kyb-tool-mcp
Project-URL: Issues, https://github.com/Aditya23770/kyb-tool-mcp/issues
Author: Aditya Raj Pandey
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: aml,companies-house,compliance,kyb,kyc,mcp,sanctions,screening
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: anyascii>=0.3.2
Requires-Dist: httpx>=0.27
Requires-Dist: jellyfish>=1.0
Requires-Dist: mcp<3,>=2.3
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: rapidfuzz>=3.6
Description-Content-Type: text/markdown

# TrustLedger

**Trust, backed by evidence.**

TrustLedger checks whether a UK company is safe to do business with, from inside your AI assistant.
It looks the company up in Companies House, screens the company, its directors and owners against
the OFAC and UN sanctions lists, and checks its website. You get **APPROVE**, **ESCALATE** or
**REJECT**, with the evidence behind every flag.

It runs on your machine: the names you screen never leave it.

[![CI](https://github.com/Aditya23770/kyb-tool-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Aditya23770/kyb-tool-mcp/actions/workflows/ci.yml)
[![Licence](https://img.shields.io/badge/licence-Apache--2.0-blue)](LICENSE)
[![Website](https://img.shields.io/badge/website-TrustLedger-14213d)](https://aditya23770.github.io/kyb-tool-mcp/)

> Decision support, not legal advice. You stay responsible for your compliance decisions.

## Install

Needs Python 3.11+ and a free [Companies House API key](https://developer.company-information.service.gov.uk/).
No Claude or other LLM API key is needed: your assistant is the LLM.

```bash
uvx kyb-tool-mcp update-lists      # one-off: build the local sanctions index
```

**Claude Code**

```bash
claude mcp add kyb-tool-mcp -e COMPANIES_HOUSE_API_KEY=your-key -- uvx kyb-tool-mcp
```

**Claude Desktop / Cursor**: add to `claude_desktop_config.json` or `.cursor/mcp.json`, then restart.

```json
{
  "mcpServers": {
    "kyb-tool-mcp": {
      "command": "uvx",
      "args": ["kyb-tool-mcp"],
      "env": { "COMPANIES_HOUSE_API_KEY": "your-key" }
    }
  }
}
```

**pip**

```bash
pip install kyb-tool-mcp
```

Without the Companies House key, registry checks report `not_configured`. Sanctions and website checks still run.

## Use it

Ask your assistant in plain English:

- "Run a KYB check on company 09876543, director Sarah Holloway, born June 1979." → decision, flags with evidence, analyst note
- "Is Viktor Bout, born 1967, on a sanctions list?" → match / needs review / cleared, with reasons
- "Does harbourline-logistics.co.uk look real?" → reachable, parked, domain age, industry fit

Also works from the terminal (`kyb-tool-mcp review case.json`) and from Python (`from kyb_tool_mcp import review_case`).

## Benchmark

| | Result |
| --- | --- |
| Sanctioned names caught | **99.4%** |
| Real UK companies with no false alert | **92.9%** |
| Wrongly confirmed as sanctioned | **0.04%** |
| Test cases decided correctly | **100%** |

Measured on real public UK data the tool was never tuned on (992 sanctioned designations, 5,000
companies) plus 168 test cases.

## Coming next (phase 2)

- One-click install for Claude Desktop (desktop extension)
- Add it as a connector by URL (hosted version)
- A web form: check a company in the browser, no install

## More

[Policy and flags](docs/policy.md) · [Data sources](docs/providers.md) ·
[Contributing](CONTRIBUTING.md) · [Security](SECURITY.md) · [Apache-2.0](LICENSE) ([data licences](NOTICE))
