# firmfind

Find companies in official business registers, then pull the
full record for the one you meant. firmfind is a small client
for the CompanyData service: search the registers by name,
place, industry code, company size, age and whether a record
carries an email address, a phone number, a website or a named
CEO; export the complete entry for a single company by its
ID; or resolve a half-remembered place name into city
suggestions before you search with it.

Whatever the service returns comes back exactly as it was
sent — nothing is trimmed, renamed or summarised on the way
through.

## Configuration

- `COMPANYDATA_API_KEY` (required) — sent on every request as
  the `x-api-key` header. When it is not set, every tool fails
  with `COMPANYDATA_API_KEY is not set` and no request is made.
- `COMPANYDATA_API_BASE_URL` (optional) — API base URL.
  Defaults to `https://app.companydata.com`.

## Tools

- `company_search` — search companies by name, location,
  industry, size and contact filters. All 38 arguments are
  optional: paging (`page`, `pageSize`), identity and text
  filters (`ID`, `search`, `sic4Digits`, `importExportCode`,
  `legalStatus`, `statusCode`, `subsidiaryCode`,
  `countryCode`, `provinceName`, `cityName`, `streetName`,
  `regionName`, `countryName`, `postalCode`, `phoneNumber`,
  `email`, `worldwideHeadquarterID`, `nationalId`, `website`),
  numeric ranges (`postalCodeIntegerMin/Max`,
  `employeesHereMin/Max`, `employeesTotalMin/Max`,
  `annualSalesMin/Max`, `foundingYearsMin/Max`) and presence
  flags (`hasEmail`, `hasMarketability`, `hasPhone`,
  `hasWebsite`, `hasNationalID`, `hasCEOName`,
  `strictCountry`). Only arguments you actually set are sent;
  booleans go as `true`/`false` and the range bounds use the
  API's bracketed wire names, for example
  `employeesHere[min]`.
- `company_enrich` — export the full record for one company
  by its CompanyData `ID` (required). The call always asks
  the export endpoint for the export form of the record.
- `field_lookup` — city suggestions for a place-name
  `search` (required), optionally narrowed by `countries`
  and capped by `limit`.

An upstream non-2xx reply fails with
`companydata error: HTTP <status>` and an unreachable API
with `companydata unreachable`.

### Endpoint provenance

The tool surface, the key environment variable and header,
the default base URL and the enrichment behaviour are pinned
by the original package's README; the parameter names, types
and wire names are pinned by the official OpenAPI document:

- `GET <base>/api/company/search?<params>` —
  `company_search`.
- `GET <base>/api/company/export?ID=<id>&export=true` —
  `company_enrich`.
- `GET <base>/api/cities?<params>` — `field_lookup`.

## CLI

Each tool is a subcommand taking one JSON argument string:

```bash
npx @reneturcios/firmfind company_search '{"search":"bakery","countryCode":"NL","hasEmail":true}'
npx @reneturcios/firmfind company_enrich '{"ID":"abc-123"}'
npx @reneturcios/firmfind field_lookup '{"search":"amster","countries":"NL","limit":5}'
npx @reneturcios/firmfind --version
```

Output is the tool's result text (the upstream body on
success). Exit codes: `0` on success, `1` on a runtime error
(including a missing key or an upstream failure), `2` on a
usage error.

## MCP server

```bash
npx -y @reneturcios/firmfind mcp
```

MCP client config:

```json
{
  "mcpServers": {
    "firmfind": {
      "command": "npx",
      "args": ["-y", "@reneturcios/firmfind", "mcp"],
      "env": {
        "COMPANYDATA_API_KEY": "<your key>"
      }
    }
  }
}
```

## Docker

```bash
docker run -i ghcr.io/cloudcorprecords/firmfind
docker run --rm ghcr.io/cloudcorprecords/firmfind company_search '{"search":"bakery"}'
```

## Development

```bash
npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (fake fetch only, no network)
npm run dev     # run the CLI from source
```

## License

MIT — Copyright (c) 2026 Rene Turcios