# india-company-diligence

<!-- mcp-name: io.github.amit043/india-company-diligence -->

An open-source MCP server that makes India's public company data agent-legible:
a full local mirror of the MCA company master data (~3.74M companies), offline
CIN decoding and GSTIN validation, and provenance on every field.

**v0.1.0** · mirror as_of **2026-10-25** · upstream dataset updated **2026-10-13** · MIT license
· [github.com/amit043/india-company-diligence](https://github.com/amit043/india-company-diligence)

## 60-second demo

> **You:** A vendor called "Hella Infra Market" wants a ₹2 crore credit line. Check them out.
>
> **Claude** *(calls `company_search`, then `company_lookup`)*: **HELLA INFRA MARKET
> LIMITED** (CIN `U46632MH2016PLC283737`) is **Active**, a public unlisted company
> registered with ROC Mumbai, incorporated 2016-07-15, paid-up capital
> **₹285.8 crore**. Note: `HELLA INFRACON PRIVATE LIMITED` — a similarly named
> entity — is **Strike Off**, so confirm the exact CIN on the invoice. *Missing:
> directors, charges, and financials require the live MCA layer (roadmap). Source:
> mca-master-data, as_of 2026-10-25.*

Every answer carries where each field came from, what is missing, and what is
stale. Missing is stated, never fabricated.

## Install & run (Claude Desktop)

Requires [uv](https://docs.astral.sh/uv/).

```bash
# 1. one-time: download the prebuilt mirror (~530 MB download, ~1.4 GB on disk)
uvx --from india-company-diligence icd-fetch
```

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "india-company-diligence": {
      "command": "uvx",
      "args": ["india-company-diligence"],
      "env": { "ICD_MIRROR_DB": "C:\\full\\path\\to\\mca_mirror.duckdb" }
    }
  }
}
```

Restart Claude Desktop. Ask: *"Look up CIN L17110MH1973PLC019786"*.

## Tools

| Tool | What it does | Network |
|---|---|---|
| `company_lookup(cin)` | Full registry row for one CIN, per-field provenance | mirror only |
| `company_search(name, limit)` | Case-insensitive name search, ≤50 rows, ranked | mirror only |
| `cin_decode(cin)` | Offline structural decode: listing status, state, year, company type | none |
| `gstin_validate(gstin)` | Offline GSTIN structure + mod-36 checksum validation | none |

## The provenance contract

Every tool returns data plus provenance, and states what is missing or stale —
never fabricated, never an error page:

```json
{
  "data": { "...": "..." },
  "provenance": [{"field": "CompanyStatus", "source": "mca-master-data", "as_of": "2026-10-25"}],
  "missing": ["director_network (live layer unavailable)"],
  "stale": []
}
```

## Data & attribution

Company Master Data (RoC-wise), published by the Ministry of Corporate Affairs
via [data.gov.in](https://data.gov.in), licensed under the
[Government Open Data License – India (GODL)](https://data.gov.in/godl).
3,738,721 companies; upstream dataset updated 2026-10-13; this mirror built 2026-10-25.

`gstin_validate` is offline-only by design: no keyless public GST API exists, so
legal name / registration status are stated as `missing` rather than guessed.

## Roadmap

- **L1 live layer** — MCA directors & charges via browser automation (week 2)
- **LLP decode** — `cin_decode` currently handles company CINs; LLP IDs (e.g. `ABA-1729`) next
- Refresh cadence: monthly mirror rebuilds as upstream updates

Bugs and data gaps: [open an issue](https://github.com/amit043/india-company-diligence/issues).

## Sync the mirror yourself (alternative to `icd-fetch`)

Get a free API key on [data.gov.in](https://data.gov.in), then:

```bash
export OGD_API_KEY=your-key        # or put it in a .env file at the repo root
uv run icd-sync                    # paginated pull, checkpointed, safe to interrupt
uv run icd-import                  # CSV -> data/mca_mirror.duckdb, source/as_of baked in
```

The pull is paced (5s between pages by default; override with `OGD_DELAY_SECONDS`
or `uv run icd-sync --delay 3`). Completion matters, not speed.

### Pausing & resuming

- stop: `uv run icd-watch stop` (or just close the terminal)
- status: `uv run icd-watch status`
- resume: `uv run icd-watch start` — continues from `data/mca_master.checkpoint`
- when the checkpoint reaches the dataset total, run `uv run icd-import`

## Development

```bash
uv sync
uv run pytest
uv run ruff check .
```

Prefer plain pip? `requirements.txt` / `requirements-dev.txt` mirror the deps.

## License

MIT. Data under GODL-India; attribution as above.