Sos Entities

@pipeworx/sos-entities

将美国各州的商业实体登记处（州务卿）的数据整理为统一格式。覆盖 Florida、New York、Colorado、Oregon、Connecticut 和 Pennsylvania，以及通过特许经营税登记信息覆盖 Texas Comptroller。记录包含实体编号、法定名称、类型、状态、成立日期、主要地址和注册代理人；如果州政府公布高管信息，也会提供其姓名和职务。成立信息流会列出某州自指定日期以来成立的新实体。无需密钥。

属于 Pipeworx — 一个将 AI Agent 连接到 1855+ 个实时数据源的 MCP 网关。这是一个独立的非官方集成，与上游提供方无关联、未获其认可，也非其发布。

工具

• sos_search(name, state?, status?, limit?)：按公司名称查找实体。此工具会匹配以查询内容开头的名称；如果没有匹配项，则会重试包含匹配。省略 state 即可同时搜索全部七个州。每个州都会分别报告自己的 count、match 和 data_as_of。如果某州的登记处未能响应，该州会显示在 state_errors 中，此时 complete 为 false。
• sos_entity(state, entity_number)：返回单个实体的完整记录，包括该州公布的 officers: [{name, role}]。Florida 最多提供六位高管，Connecticut 提供其负责人，Pennsylvania 提供所有列出的相关方，New York 提供董事长或 CEO，Oregon 提供授权代表。Colorado 和 Texas 不公布高管信息。found: false 仅表示登记处已响应，且没有该编号。
• sos_new_entities(state, since, name_query?, entity_type?, limit?)：列出从 since 到今天成立的实体，按最新优先排序，并依成立日期、再依实体编号排列。不会包含未来生效（延迟生效）的申报。Florida 最多可追溯 70 天；其他州可查询任意日期。这是用于生成新企业名单和监控成立情况的信息流。

身份验证

无需密钥。

个人数据

Bruce 于 2026-10-08 作出裁定 PD（“names-and-roles”），允许提供高管、董事、经理和代理人的姓名、职务及来源。绝不提供或获取个人地址：

• 每个 Socrata 查询都会明确指定列。
• 个人地址列要么完全不纳入查询，要么使用 SoQL case() 包装，仅当持有人为企业时才返回 null 以外的值。
• 仅当注册代理人为企业时，才会提供其地址。

Florida 的数据导入流程会在解析时移除高管地址。此外，只有当代理人被标记为实体 且 名称看起来像实体时，才会保留其地址：Florida 标记为实体的代理人中，约有 37% 实际上是个人。

删除请求请发送至 [email protected]。姓名会通过 src/removals.ts 屏蔽，适用于所有州。

数据源

• NY：https://data.ny.gov/d/n9v6-gdp6。州务院活跃公司。仅列出活跃实体。
• CO：https://data.colorado.gov/d/4ykn-tg5h。科罗拉多州州务卿商业实体数据。涵盖所有状态。
• OR：https://data.oregon.gov/d/tckn-sxa6。公司部活跃企业数据。每个关联名称（营业地点、邮寄地址、注册代理人、授权代表）各占一行，数据包会按 registry_number 对这些行分组。
• CT：https://data.ct.gov/d/n7gp-d28j（企业主数据）、https://data.ct.gov/d/ka36-64k6（负责人）和 https://data.ct.gov/d/qh2m-n44y（代理人），通过内部 business_id 关联。公开实体编号为 accountnumber。
• TX：https://data.texas.gov/d/9cir-efmm。州审计长办公室活跃特许经营税纳税人数据。这不是德克萨斯州州务卿的注册名册，该服务需付费。类型、状态和交易权代码来自数据集附带的“Franchise Layout.docx”。
• PA：https://data.pa.gov/d/xvd7-5r2c。宾夕法尼亚州州务院注册企业数据。每个相关方各占一行，地址为企业的注册地址。file.dos.pa.gov 上的搜索门户会以 HTTP 999“Security Check”响应自动化客户端。此开放数据集是 Worker 可以访问的途径。
• FL：佛罗里达州公司部的公共 SFTP 服务 sftp.floridados.gov。用户名 Public 及其密码由该部门发布于 https://dos.fl.gov/sunbiz/other-services/data-downloads/。该服务提供季度完整文件 doc/Quarterly/Cor/cordata.zip（约 1.8 GB，Deflate64，约 13.0M 条记录）和每日文件 doc/cor/YYYYMMDDc.txt。记录采用 1,440 字节定宽格式，布局见 scripts/sos-entities/ingest_fl.py。

Florida 并非实时调用

Sunbiz 搜索会向自动化客户端发出 JavaScript 验证。佛罗里达州的单实体数据仅以 SFTP 文件形式发布，而 Worker 无法使用 SFTP。由 .github/workflows/sos-entities-fl-refresh.yml 运行的 scripts/sos-entities/ingest_fl.py（处理每日申报文件，并每周完整构建一次）会将这些文件解析到网关的数据集存储桶中。数据包会对每次查询范围读取一个 gzip 压缩分块。完整构建之后的每日文件会叠加应用，因此佛罗里达州发布新申报文件当天即可搜索。佛罗里达州的响应包含 data_as_of，表示最新每日文件的日期。如果没有网关的数据集绑定（仅运行裸 npm install），调用 Florida 会报错说明原因；其他六个州仍可正常使用。

设计说明：docs/sos-entities-design.md。

注意事项

• data.ny.gov 的 URL 超过约 8 KB 时会返回 HTTP 414。$select 中的企业名称测试会针对每个地址重复执行，因此模式列表保持较短，并将每个地址作为以 | 连接的一列获取。
• Florida 的成立日期可能是未来的生效日期。Colorado 和 Texas 也包含 2026 年末的日期。sos_new_entities 的范围截止到今天。
• NY、OR 和 PA 仅发布活跃实体。对于这些州，status: "inactive" 会返回一条 state_notes，而不是空结果。
• Florida 的人员姓名采用定宽格式：姓（20）、名（14）、中间名首字母（1）、后缀（7）。如果后缀栏只有一个字母，说明中间名首字母被误填到了错误字段。

快速开始

添加到你的 MCP 客户端（Claude Desktop、Cursor、Windsurf 等）：

{
  "mcpServers": {
    "sos-entities": {
      "url": "https://gateway.pipeworx.io/sos-entities/mcp"
    }
  }
}

此端点实际提供的内容

https://gateway.pipeworx.io/sos-entities/mcp 上的 tools/list 会返回上表中的工具，以及 Pipeworx 共享元工具——ask_pipeworx、 discover_tools、search_within、remember/recall 和其余整个网关范围内的工具。因此，你看到的工具数量会多于此表中的数量：目前，单个工具包端点会列出约 30 个共享工具，以及该工具包自身的工具。连接的 initialize 响应会说明其确切范围，是当天的权威答案。

这是有意为之，并非意外地进行了多路复用。元工具让限定范围的连接也能回答此工具包不涉及的问题——通过 ask_pipeworx 跨整个目录进行路由——而无需添加第二个 MCP 服务。目前无法挂载不含这些工具的工具包端点；如果额外的架构定义占用的上下文比路由带来的价值更多，请连接一次完整网关，而不是连接多个工具包端点。

或者，连接完整的 Pipeworx 网关，直接列出每个工具包的所有工具，而不只是此工具包的工具：

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

两个 URL 都会连接到同一个网关和同样的 1855+ 个数据源。唯一的区别是直接列出的工具所属的工具包不同；无论连接哪个端点，ask_pipeworx 都能访问所有工具。

没有 MCP 客户端？通过 HTTP 调用

curl -X POST https://gateway.pipeworx.io/v1/tools/sos_search \
  -H 'Content-Type: application/json' \
  -d '{"name":"Goldman Sachs & Co","state":"NY","limit":3}'

首次调用无需账户。检查任意工具：GET https://gateway.pipeworx.io/v1/tools/sos_search。查找工具：使用 {"query":"..."} 向 https://gateway.pipeworx.io/v1/tools/search_packs 发送 POST 请求。

独立运行（无需网关账户）

此软件包也可以作为本地 stdio MCP 服务运行——无需 Pipeworx 账户，也无需往返网关：

{
  "mcpServers": {
    "sos-entities": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-sos-entities"]
    }
  }
}

或者直接运行，以确认它可以启动：

npx -y @pipeworx/mcp-sos-entities

它通过 stdin/stdout 使用 MCP 通信，并仅针对该工具包的工具响应 initialize/tools/list/tools/call——不包含上述网关连接额外提供的任何共享元工具。源代码相同，工具相同，但没有 ask_pipeworx 路由。

使用 ask_pipeworx

你可以用自然语言提问，而不是直接调用工具——这既适用于上文的工具包端点，也适用于完整网关：

ask_pipeworx({ question: "your question about Sos Entities data" })

网关会选择合适的工具并自动填写参数。

更多信息

• 文档和指南
• pipeworx.io

许可证

MIT