catchall-mcp

catchall-mcp 是 NewsCatcher 发布的 MCP 服务器，用于对接 NewsCatcher CatchAll Web Search API。它被定位为“召回优先”（recall-first）的开放网页搜索能力，目标是在开放网络上找到相关事件，而不仅限于常规的顶部搜索结果。

用途与定位 该服务器通过 Model Context Protocol（MCP）向 AI 客户端暴露 CatchAll Web Search API 的能力。官方提供托管实例：用户无需克隆或自行运行本仓库，先在 platform.newscatcherapi.com 获取 CatchAll API 密钥，然后进行连接即可；也可以通过 Claude Code CLI 接入。其完整集成文档地址为 https://www.newscatcherapi.com/docs/web-search-api/integrations/mcp。若希望自行运行，可选择本地或自托管方式，仓库中也给出了相关运行说明。

主要能力与工具映射 服务器把多个 MCP 工具映射到 API 端点。

1. 作业与查询：initialize_query 用于预览验证器、增强项和日期窗口。它是仅预览，不会创建作业，而且建议结果是非确定性的。submit_query 用于提交查询，query 为必填；可选字段可以只提供其中一部分，未提供的字段会被自动选择或生成。start_date 与 end_date 过滤的是网页发现日期，而不是抽取内容中的事件日期；如需事件时间准确，应使用面向事件的验证器或增强项，并核对结果里的 event_date。作业状态用 get_job_status 轮询，建议第一次在约 1-2 分钟后检查，之后每 30-60 秒检查一次，直到状态为 completed 或 failed。pull_results 用于拉取结果，在 enriching 阶段也会出现部分数据；应通过 page < total_pages 分页以获取全部可用记录。continue_job 用于处理更多记录（会影响成本），仅适用于最初以 limit 提交的作业，其 new_limit 为可选，省略时 API 默认使用套餐上限。
2. 列表筛选：list_user_jobs 除 page / page_size 外，还支持 search、ownership、project_id 以及 mode（base 或 lite）筛选。
3. Webhook：create_webhook 可在创建时接受可选的 project_id，将 Webhook 绑定到项目；list_webhooks 同样接受可选 project_id，用于筛选特定项目的 Webhook。get_webhook_history 有两种查询模式：传入 resource_type 与 resource_id 查询某个 job/monitor/monitor_group 的投递，或传入 webhook_id 查询通过该 Webhook 投递的全部内容，单次调用只能使用其中一种模式。手动测试投递（test_webhook）只会出现在 webhook 模式中，并以 resource_type: "test" 记录。
4. 项目资源：resource_type 可为 job、monitor、dataset、monitor_group 或 webhook。一个 Webhook 可以同时属于多个项目。delete_project 在 delete_resources=true 时会删除其中包含的 job、monitor、dataset 和 monitor_group，但 Webhook 只会被解除关联、不会被删除，响应的 deleted_resources 会以 webhook_unlinked 计数报告它们。
5. CSV 上传（v1.6.1）：create_dataset_from_csv 和 append_csv_to_dataset 通过 file 参数接收 CSV 内容——原始 CSV 文本或标准 base64。它们不会从服务器文件系统读取路径，因此在远程或托管 MCP 上更安全。内联 CSV 内容有 10 MB 硬上限（base64 解码后）。create_dataset_from_csv 还接受新增的可选 project_id 字段。
6. 实体：external_entity_id（v1.6.3）：create_entity 和 update_entity 接受可选的 external_entity_id 字符串，这是客户提供的标识符，用于把实体链接到外部系统中的记录。project_id（v1.8.0）：list_entities 接受可选 project_id，用于筛选属于特定项目的实体。
7. 来源组（v1.8.0）：命名且可复用的域名白名单（公共组，加上组织可访问的组织可见性组）。list_source_groups 返回每个组的 slug、name 和 description。直接 API 的 POST /catchAll/submit 现在接受 source_groups 字段（slug 列表），用于把抓取范围限定到域名白名单；submit_query 尚未暴露该参数，在后续版本加入前请使用直接 API。

使用方式与鉴权 API 密钥优先级从高到低为：api_key 工具参数、x-api-key 请求头、Authorization: Bearer <key> 请求头、URL 查询参数 ?apiKey=...、环境变量 CATCHALL_API_KEY。check_health 与 get_version 不需要 API 密钥鉴权。 托管部署（FastMCP Gateway）说明：通过 fastmcp.app 部署时，无状态网关位于服务器前方。网关会把 HTTP 头转发给后端，但不转发 URL 查询参数。因此应使用 x-api-key 请求头或 CATCHALL_API_KEY 环境变量，而不是 ?apiKey=。在 Claude Code / Cursor 中亦然。若直接访问服务器（不经网关），URL 中的 ?apiKey=YOUR_KEY 仍然可用。 运行方式方面，仓库说明包括：安装依赖、通过 stdio 运行、以及（如果有 fastmcp CLI）通过 HTTP 运行。

核心工作流（作业） 可选：调用 initialize_query 预览验证器、增强项和日期窗口（仅预览，不创建作业；建议为非确定性）。然后用 submit_query 提交（query 必填），可只发送 query，其余可选字段会自动选择或生成；可选字段相互独立，可只提供任意子集（例如仅自定义验证器），未提供的仍会自动生成。start_date / end_date 过滤网页发现日期而非事件日期。轮询 get_job_status 按上述节奏检查，直到 completed 或 failed。用 pull_results 拉取，enriching 期间会有部分数据；按 page < total_pages 分页取全。仅在需要处理更多记录时使用 continue_job（影响成本），且只适用于最初带 limit 提交的作业。

limit 与 page_size 的区别 limit（submit_query、continue_job）控制处理多少条记录，因而影响成本；如提供则必须 >= 10；省略则按套餐上限取全部。page_size（pull_results、list_user_jobs）只控制分页，不影响处理成本；pull_results.page_size 默认 100，范围为 1..1000。pull_results 响应包含 error（失败的作业）和 limit（已应用的作业限制）。page/page_size/total_pages 表示已可用的记录；可用 progress_validated < candidate_records 判断是否可能还有更多记录出现。

监控器约束 create_monitor.backfill=true 时，参考作业的 end_date 必须在最近 7 天内；backfill=false 时不适用该参考作业时间约束。监控器最小调度频率取决于套餐。create_monitor 支持可选的 limit（最小 10）、backfill（默认 true）、timezone、webhook_ids 和 project_id。Webhook 在 v1.5.3 中集中管理：先用 create_webhook 注册，再通过 create_monitor.webhook_ids / update_monitor.webhook_ids 按 ID 关联（不再内联配置 Webhook）。监控器仅支持 base 作业（不支持 lite）。enable_monitor 支持可选 backfill。update_monitor 可更新 webhook_ids、运行 limit、schedule 和/或 timezone（传 webhook_ids=[] 可清除关联；除非同时设置 schedule，否则 timezone 会被忽略）。list_monitors 支持通过 page 和 page_size 分页，并支持 search、ownership 和 project_id 筛选；返回 total、page、page_size、total_pages、monitors。

增强输出说明 enrichment.enrichment_confidence 始终存在。公司增强结果是结构化对象，包含 source_text、confidence、metadata.name、metadata.domain_url、metadata.domain_url_confidence。成功时返回美观的 JSON 字符串。

错误行为 （v1.8.0）对于任何上游非 2xx 响应（api_key 错误、无效或外来的 project_id、找不到 ID、验证失败等）或未处理异常，MCP 工具会报错（isError=True）。错误消息带有上游状态码和消息，例如 API Error (401): Api key not found。在 v1.8.0 之前，工具会吞掉这些失败，把“Error: ...”当成功结果返回，只检查 isError 的客户端会看到假成功；现已修复，每个工具都会抛出 ToolError，因此失败始终被报告为真正的工具错误。

适用场景与限制 适用于希望通过 MCP 接入 AI 客户端、在开放网络上做事件发现与线索搜索、设定查询并拉取或持续监控结果、以及使用增强项和来源组限定抓取范围的场景。限制包括：需要有效的 CatchAll API 密钥；作业处理量、监控器频率、分页范围等受套餐与 API 约束；submit_query 尚不支持 source_groups；监控器仅限 base 作业；托管网关下需使用请求头或环境变量而非 URL 查询参数。