Fac

@pipeworx/fac

联邦审计信息交换中心（FAC）MCP——美国单一审计申报（统一指南，前身为 OMB A-133）：谁在使用联邦拨款资金、资金属于哪个援助清单项目，以及审计人员发现了什么。数据基于每周刷新的 FAC 自有批量数据副本（fleet #2504）——无需 API 密钥。

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

工具

• fac_search_audits(auditee_name|uei|ein|state|zip|audit_year|min_total_expended, ...) — 查找审计；返回 report_id、机构身份信息（包括档案中的 ZIP）、联邦拨款总支出、监督机构及 FAC 接收日期。
• fac_get_audit(report_id, ...) — 获取一份审计及其《联邦拨款支出明细表》中的所有联邦项目行（援助清单编号、项目名称、支出金额、主要项目标记、意见类型）、审计事务所，以及 FAC 收录的审计发现。
• fac_audit_findings(report_id | auditee_name | uei, ...) — 获取针对某项审计记录的审计发现，或汇总某一受资助方提交的所有审计发现，并按严重程度归纳（重大缺陷、重要缺陷、质疑费用、重复发现、非无保留意见）。include_text 会附上审计发现的叙述文本。
• fac_federal_awards_by_program(cfda | federal_agency_prefix + federal_award_extension, ...) — 查询哪些机构使用了某个 CFDA 编号下的资金（例如 93.224），按金额排序，并关联受资助方名称、州和年份。
• fac_recipient_audit_history(uei | auditee_name | ein, ...) — 按年份列出某一受资助方的审计记录、每年支出总额以及趋势的百分比变化。
• fac_findings_search(query, ...) — 新增。 对审计发现叙述进行全文搜索（例如“未能在规定时限内提交……”、“质疑费用”）。无法通过实时 FAC API 实现（不支持跨表联接）；此工具基于 Postgres websearch_to_tsquery RPC（fac_findings_search），搜索由 GIN 索引的 tsvector 列。
• fac_cross_table_screen(state | cfda | finding_type | material_weakness_only | min_amount | audit_year, ...) — 新增。 一次调用即可按州、CFDA 项目和审计发现类型筛查审计（例如“德克萨斯州 CFDA 93.224 项目的重大缺陷”）。此工具基于跨 fac_general、fac_federal_awards 和 fac_findings 的三表 SQL 联接 RPC（fac_cross_table_screen）。

各处均支持宽松别名：query / q / name 可代替 auditee_name；zip / auditee_zip / zipcode / zip_code / postal_code 可互换；cfda / program_number / assistance_listing / program 均接受 "93.224"、"93-224"、"93224"，或用于查询该机构所有项目的纯数字 "93"。

如果工具无法识别某个参数，会报告该参数，而不会将其丢弃。 任何未知键都会在 ignored_arguments 中返回，并附带一条 warnings，说明未应用该筛选条件，并列出工具接受的参数。静默丢弃调用方提供的最具体信息，比报错更糟，因为响应仍然看起来像是答案。

每个响应都包含 data_as_of——上次成功刷新的时间戳（来自 fac_ingest_runs）。首次刷新完成前，该值为 null，响应会添加一条 coverage_status 说明，而不是静默返回空结果，让人误以为“没有审计记录”。

为什么要提前加载这些数据（fleet #2504）

这个数据包过去会在每次请求时实时调用 api.fac.gov（由 api.data.gov 统一入口代理的 PostgREST API）。截至 2026-09-29 的 60 天测量结果显示：fac_search_audits 在约 1,620 次外部调用中有 572 次出现 upstream_down（占 35%，平均延迟 3.9 秒），是目录中最大的 ask_pipeworx 无匹配问题簇（约 25 种不同的问题形式：姓名+州+ZIP 变体、report_id 查询、“关于 X 的审计发现”）。此外，api.fac.gov 自身的 PostgREST 未在 /general 和 /findings 之间公开外键（任何嵌入尝试都会返回 PGRST200），因此，诸如“德克萨斯州 CFDA 93.224 下的重大缺陷”这类跨表问题，在实时 API 上从结构上就无法实现，而不仅仅是速度慢。

根据 Bruce 于 2026-09-23 的裁定（“实时服务无法满足需求／速度太慢时，就建立副本”），该数据包现在改为读取自己的定期刷新的数据表。由 scripts/fac-upsert.sh 每周刷新，并由 .github/workflows/fac-refresh.yml 定时触发。架构和 RPC：supabase/migrations/220_fac_local_mirror.sql。

已加载的表： general、federal_awards、findings、findings_text、corrective_action_plans（对应为 fac_general、fac_federal_awards、fac_findings、fac_findings_text、fac_corrective_action_plans）。尚未加载（不在 #2504 的范围内，属于未来扩展，并非未说明的遗漏）：notes_to_sefa（725MB）、passthrough（559MB），以及较小的 additional_ueis／additional_eins／secondary_auditors 表。

不含个人数据

FAC 的 general.csv 提取文件包含具名个人的联系字段——被审计方／审计方的认证人姓名+职务、联系人姓名+职务、电子邮件、电话。这些字段均未加载。保留组织身份信息（auditee_name、auditor_firm_name、地址、EIN），因为这些信息用于识别提交强制性联邦合规披露的实体，而非私人个人；这类数据也已由 samgov 和 fed-nic 数据包携带。过去，fac_get_audit 在代理实时 API 时也会公开被审计方的联系人姓名／电子邮件／电话（GENERAL_CONTACT_SELECT）；现已有意移除此功能，而非降低其能力——fac_get_audit 的每个响应都会附带 personal_data_note，指向 fac.gov 上该报告的 summary_url。逐列说明详见迁移文件和 scripts/fac-normalize.py 的文件头注释。

刷新流程

node scripts/fac-upsert.sh          # local dry run (needs the database connection secret in env — see the script header)

在生产环境中，此流程由 GitHub Actions runner（.github/workflows/fac-refresh.yml，每周运行，可通过 workflow_dispatch 手动触发）执行，而非由 CF 网关 Worker 执行——仅 federal_awards 解压后就约有 1.34GB，远超 Worker 的执行预算；而 psql \copy 可以一次性完成加载，Worker 的流式解析器则无法做到（与 samgov 和 openfema 数据包的原因相同）。加载器会：

1. 应用所有 *_fac_*.sql 迁移（可幂等执行——无需另行记住“手动应用一次”）。
2. 从 https://app.fac.gov/dissemination/public-data/gsa/full/{table}.csv 下载每个表的 CSV（会跟随 302 跳转至预签名 S3 URL，该 URL 约 30 秒后失效——切勿解析并重用 Location 标头，这与迁移 135 中的 samgov 表遇到的问题相同）。
3. 使用 scripts/fac-normalize.py 进行规范化——逐行流式处理（绝不将整个文件缓冲到内存中），移除个人数据列，并将字面值 "GSA_MIGRATION" 转为 NULL。FAC 自身的数据会在从 2022 年之前由 Census 运行的 FAC 迁移而来的记录中，将此值用作发现文本／纠正措施计划文本的占位符（已于 2026-09-29 在线验证——数千个 2016 年左右的 report_id 都带有这个字面字符串，仿佛它是实际内容）。
4. 通过 psql \copy 加载到暂存表，再分批 upsert 到正式表（绝不使用单个巨大事务）。
5. 在 fac_ingest_runs 中记录此次运行（状态、行数、finished_at）——data_as_of 会读取此处的信息。

数据源

• https://www.fac.gov/data/download/current/ — 批量数据提取文件的人类可读索引。
• https://app.fac.gov/dissemination/public-data/gsa/full/{general,federal_awards,findings,findings_text,corrective_action_plans}.csv — 实际下载地址（302 → 预签名 S3，无需凭据）。2026-09-29 观察到的文件大小：general 271MB、federal_awards 1.34GB、findings 68MB、findings_text 258MB、corrective_action_plans 110MB。
• API 文档（介绍这些数据所依据的实时上游数据结构）：https://www.fac.gov/developers/ · Assistance Listing 查询：https://sam.gov/content/assistance-listings
• 根据 2 CFR 200 Subpart F 收集的美国联邦单一审计数据——属于公共领域。

名称和 ZIP 匹配

ZIP 以两种编码方式存储，必须按前缀匹配。 部分行的 auditee_zip 存储 5 位数字（75082），而其他行则存储不带分隔符的 9 位 ZIP+4（009601588、750814198），因此 eq. 会漏掉表中的大多数记录——波多黎各的调用方传入 00960 时，完全匹配不到任何记录。该工具包按 5 位前缀筛选（auditee_zip=like.00960*），这是两种编码共有的唯一部分；对于 ZIP+4 输入，则会先截断。

被审计方档案中的 ZIP 会随申报年份变化。 CITY OF RICHARDSON TX 在 2018–2021 年以 75080 申报，在 2022 年以 75083 申报，并在 2025 年以 75082 申报——但 UEI 都相同。因此，当前 ZIP 无法匹配较早的审计记录是正常情况。当 zip 筛选条件让原本能匹配的结果变为空时，该工具包会去掉此条件重新查询，并返回 reason: 'zip_no_match'，列出 FAC 中该实体实际使用的 ZIP，而不是只返回调用方无法诊断的空结果。

波多黎各的市镇会以两种语言申报，具体使用哪种取决于提交年份。 FAC 中有 MUNICIPALITY OF BAYAMON 和 MUNICIPALITY OF SAN JUAN，也有 MUNICIPIO DE MANATI、MUNICIPIO DE CAMUY、MUNICIPIO DE NARANJITO——同一实体的 Corozal 在 2019 年显示为 MUNICIPIO DE COROZAL，在 2017–2024 年则显示为 MUNICIPALITY OF COROZAL。依据波多黎各政府来源查询的调用方会使用西班牙语法定名称，而英文记录中没有任何子字符串与之匹配；如果只做单向转换为英文，就会漏掉西班牙语记录。该工具包会检测任一语言中的市镇名称（MUNICIPIO DE X、MUNICIPIO AUTONOMO DE X、MUNICIPALIDAD DE X、(AUTONOMOUS) MUNICIPALITY OF X），提取地名，并在一次 PostgREST or=(...) 查询中同时查询两种拼写，同时在 name_match 中说明所执行的匹配方式。

地名中的西班牙语重音符号并不一致。 FAC 中既有 MUNICIPALITY OF AÑASCO（还有一条因乱码显示为 MUNICIPALITY OF A?ASCO），也有不带重音符号的 MUNICIPIO DE ANASCO，因此任何一种拼写都无法找到全部记录：ASCII 拼写 ANASCO 会返回 1 条审计记录，带重音符号的 AÑASCO 会返回 4 条，而该实体共有 5 条记录。因此，每个地名模式也会执行忽略重音符号的查询，将可能带有西班牙语重音符号的字母替换为 LIKE 的单字符通配符（Municipality of ___SC_）；保留下来的辅音和固定长度可确保匹配足够精确。

这会在主查询中执行，而不是在结果为空时重试，这一区别正是关键所在：只有字面拼写一条记录都找不到时，才会触发重试；但实际的问题是它能找到部分记录——看起来完整的结果实际上并不完整。or=(...) 是单个 SQL 谓词，因此新增的分支会合并结果，不会重复行，也不需要额外的往返请求。

其他注意事项

federal_agency_prefix 和 federal_award_extension 分开存储，只有拼接起来才有意义：前缀 93 + 扩展码 224 即资助目录编号 93.224，因此调用方传入带点的编号时，系统会自动拆分，并在每个响应中回显 assistance_listing。扩展码存储时会补零至三位（47.076，而不是 47.76），因此发送前会为数字扩展码补零；未补零的值不会匹配任何记录，但不会报错。fac_federal_awards 不含受审计方列——接收方名称、州和审计年份位于 fac_general 中，因此 fac_federal_awards_by_program 会按 report_id 联接两者；如果设置了 state 或 audit_year 筛选条件，系统会先按金额取回排名靠前的行，再在联接后筛选，并报告 rows_scanned，以便调用方判断是否需要扩大扫描范围。没有发现事项也是一种答案，而不是数据缺失：合规的单次审计可以在 fac_findings 中没有任何记录，此时会返回 found: false, reason: 'no_findings'，并附上已检查的审计记录；这与 reason: 'findings_table_unavailable' 不同。联邦支出低于每年约 75 万美元门槛的实体无需提交审计，因此组织未出现通常是因为低于门槛，而不是数据缺失。较早审计的发现事项／纠正措施叙述文本通常缺失——fac_findings_search 和 fac_audit_findings 中的 include_text: true 都会直接省略没有文本记录的行（在 GSA_MIGRATION 哨兵值置空处理后），而不是显示空字符串，误导人以为那是实际（简短）的答案。

快速入门

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

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

此端点实际提供的内容

https://gateway.pipeworx.io/fac/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 都连接到同一个网关和相同的 1879+ 个数据源。唯一的区别是直接列出哪个工具包的工具；从任一端点都可以通过 ask_pipeworx 访问所有工具。

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

curl -X POST https://gateway.pipeworx.io/v1/tools/fac_search_audits \
  -H 'Content-Type: application/json' \
  -d '{"auditee_name":"stanford","limit":10}'

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

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

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

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

也可以直接运行以确认它能启动：

npx -y @pipeworx/mcp-fac

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

与 ask_pipeworx 搭配使用

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

ask_pipeworx({ question: "your question about Fac data" })

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

More

• Docs and guides
• pipeworx.io

License

MIT