firmfind

firmfind

公式の企業登記簿から企業を検索し、目的の企業の完全な記録を取得します。firmfind は CompanyData サービス用の小さなクライアントです。登記簿を名前、所在地、業種コード、企業規模、設立年数、およびメールアドレス、電話番号、ウェブサイト、または CEO の氏名が記録されているかどうかで検索できます。ID を指定して特定企業の完全なエントリーをエクスポートしたり、うろ覚えの地名を市区町村の候補に変換してから検索に使ったりすることもできます。

サービスから返された内容は、送信されたとおりにそのまま返されます。途中で切り詰めたり、名前を変更したり、要約したりすることはありません。

設定

• COMPANYDATA_API_KEY（必須）— リクエストごとに x-api-key ヘッダーとして送信されます。設定されていない場合、すべてのツールは COMPANYDATA_API_KEY is not set で失敗し、リクエストは送信されません。
• COMPANYDATA_API_BASE_URL（任意）— API のベース URL です。デフォルトは https://app.companydata.com です。

ツール

• company_search — 企業を名前、所在地、業種、規模、連絡先の条件で検索します。38 個の引数はすべて任意です。ページ指定（page、pageSize）、識別情報とテキストのフィルター（ID、search、sic4Digits、importExportCode、legalStatus、statusCode、subsidiaryCode、countryCode、provinceName、cityName、streetName、regionName、countryName、postalCode、phoneNumber、email、worldwideHeadquarterID、nationalId、website）、数値範囲（postalCodeIntegerMin/Max、employeesHereMin/Max、employeesTotalMin/Max、annualSalesMin/Max、foundingYearsMin/Max）、および有無のフラグ（hasEmail、hasMarketability、hasPhone、hasWebsite、hasNationalID、hasCEOName、strictCountry）を指定できます。実際に設定した引数だけが送信されます。ブール値は true／false として送信され、範囲の境界値には employeesHere[min] のように API の角括弧付きワイヤー名が使われます。
• company_enrich — CompanyData の ID（必須）を指定して、1 社の完全な記録をエクスポートします。この呼び出しでは、常にエクスポートエンドポイントに記録のエクスポート形式を要求します。
• field_lookup — 地名の search（必須）に対する市区町村の候補を返します。countries で任意に絞り込み、limit で件数を制限できます。

上流から 2xx 以外の応答が返された場合は companydata error: HTTP <status> で失敗し、API に到達できない場合は companydata unreachable で失敗します。

エンドポイントの根拠

ツールのインターフェース、キーの環境変数とヘッダー、デフォルトのベース URL、エンリッチメントの動作は、元のパッケージの README に基づいています。パラメーター名、型、ワイヤー名は公式の OpenAPI ドキュメントに基づいています。

• 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

各ツールは、1 つの JSON 引数文字列を受け取るサブコマンドです。

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

出力はツールの結果テキスト（成功時は上流のレスポンス本文）です。終了コード：成功時は 0、実行時エラー（キーの未設定や上流の失敗を含む）時は 1、使用方法のエラー時は 2 です。

MCP サーバー

npx -y @reneturcios/firmfind mcp

MCP クライアントの設定：

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

Docker

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

開発

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

ライセンス

MIT — Copyright (c) 2026 Rene Turcios