CatchAll

Newscatcher CatchAll MCP 服务

适用于 NewsCatcher CatchAll Web Search API 的 MCP 服务。

快速开始 — 使用我们的托管服务

使用 MCP 无需克隆或运行此仓库 — NewsCatcher 提供托管实例：

https://catchall-mcp.newscatcherapi.com/mcp?apiKey=YOUR_CATCHALL_API_KEY

在 platform.newscatcherapi.com 获取 CatchAll API 密钥，然后连接：

{
  "mcpServers": {
    "catchall": {
      "type": "http",
      "url": "https://catchall-mcp.newscatcherapi.com/mcp?apiKey=YOUR_CATCHALL_API_KEY"
    }
  }
}

也可以通过 Claude Code CLI 使用：

claude mcp add --transport http catchall "https://catchall-mcp.newscatcherapi.com/mcp?apiKey=YOUR_CATCHALL_API_KEY"

完整集成文档：https://www.newscatcherapi.com/docs/web-search-api/integrations/mcp

想自行运行服务（本地或可自托管）？请参阅下文的运行。

工具与端点映射

任务

MCP 工具	方法	端点
initialize_query	POST	/catchAll/initialize
submit_query	POST	/catchAll/submit
validate_query	POST	/catchAll/validate
continue_job	POST	/catchAll/continue
list_user_jobs	GET	/catchAll/jobs/user
get_job_status	GET	/catchAll/status/{job_id}
pull_results	GET	/catchAll/pull/{job_id}
pull_job_csv	GET	/catchAll/pull/{job_id}/csv
delete_job	DELETE	/catchAll/jobs/{job_id}

任务列表筛选条件：list_user_jobs 除了支持 page/page_size 筛选条件外，还支持 search、ownership、project_id 和 mode（base 或 lite）筛选条件。

监控器

MCP 工具	方法	端点
create_monitor	POST	/catchAll/monitors/create
update_monitor	PATCH	/catchAll/monitors/{monitor_id}
delete_monitor	DELETE	/catchAll/monitors/{monitor_id}
list_monitors	GET	/catchAll/monitors/
list_monitor_jobs	GET	/catchAll/monitors/{monitor_id}/jobs
get_monitor_status	GET	/catchAll/monitors/{monitor_id}/status
pull_monitor_results	GET	/catchAll/monitors/pull/{monitor_id}
pull_monitor_csv	GET	/catchAll/monitors/pull/{monitor_id}/csv
enable_monitor	POST	/catchAll/monitors/{monitor_id}/enable
disable_monitor	POST	/catchAll/monitors/{monitor_id}/disable

Webhook

MCP 工具	方法	端点
list_webhooks	GET	/catchAll/webhooks
create_webhook	POST	/catchAll/webhooks
get_webhook	GET	/catchAll/webhooks/{webhook_id}
update_webhook	PATCH	/catchAll/webhooks/{webhook_id}
delete_webhook	DELETE	/catchAll/webhooks/{webhook_id}
test_webhook	POST	/catchAll/webhooks/{webhook_id}/test
assign_webhook_resource	POST	/catchAll/webhooks/{webhook_id}/resources
list_webhook_resources	GET	/catchAll/webhooks/{webhook_id}/resources
remove_webhook_resource	DELETE	/catchAll/webhooks/{webhook_id}/resources/{resource_type}/{resource_id}
list_resource_webhooks	GET	/catchAll/resources/{resource_type}/{resource_id}/webhooks
get_webhook_history	GET	/catchAll/webhook-history
trigger_webhook	POST	/catchAll/webhook/trigger/{resource_type}/{resource_id}

Webhook 说明：create_webhook 接受可选的 project_id，以便在创建时将 Webhook 关联到某个项目。list_webhooks 也接受可选的 project_id，用于筛选属于特定项目的 Webhook。get_webhook_history 支持两种查询模式：传入 resource_type + resource_id 可查询某个任务/监控器/监控组的投递记录；传入 webhook_id 则可查询通过某个 Webhook 投递的所有记录（每次调用只能使用一种模式）。手动测试投递（test_webhook）仅会出现在 Webhook 模式中，且记录为 resource_type: "test"。

项目

MCP 工具	方法	端点
create_project	POST	/catchAll/projects/
list_projects	GET	/catchAll/projects/
get_project	GET	/catchAll/projects/{project_id}
update_project	PATCH	/catchAll/projects/{project_id}
delete_project	DELETE	/catchAll/projects/{project_id}
get_project_overview	GET	/catchAll/projects/{project_id}/overview
add_project_resources	POST	/catchAll/projects/{project_id}/resources
list_project_resources	GET	/catchAll/projects/{project_id}/resources
remove_project_resource	DELETE	/catchAll/projects/{project_id}/resources/{resource_type}/{resource_id}

项目资源：resource_type 可以是 job、monitor、dataset、 monitor_group 或 webhook。一个 webhook 可以同时属于多个项目。 使用 delete_resources=true 调用 delete_project 会删除其中包含的任务、监控项、 数据集和监控组，但只会从项目中移除 webhook，不会删除 webhook；响应中的 deleted_resources 会通过 webhook_unlinked 计数报告被解除关联的 webhook 数量。

数据集

MCP 工具	方法	端点
create_dataset	POST	/catchAll/datasets/
list_datasets	GET	/catchAll/datasets/
get_dataset	GET	/catchAll/datasets/{dataset_id}
update_dataset	PATCH	/catchAll/datasets/{dataset_id}
delete_dataset	DELETE	/catchAll/datasets/{dataset_id}
add_dataset_entities	POST	/catchAll/datasets/{dataset_id}/entities
remove_dataset_entities	DELETE	/catchAll/datasets/{dataset_id}/entities
list_dataset_entities	POST	/catchAll/datasets/{dataset_id}/entities/list
get_dataset_status	GET	/catchAll/datasets/{dataset_id}/status
create_dataset_from_csv	POST	/catchAll/datasets/upload
append_csv_to_dataset	POST	/catchAll/datasets/{dataset_id}/upload

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。

实体

MCP 工具	方法	端点
create_entity	POST	/catchAll/entities/
list_entities	GET	/catchAll/entities/
create_entities_batch	POST	/catchAll/entities/batch
get_entity	GET	/catchAll/entities/{entity_id}
update_entity	PATCH	/catchAll/entities/{entity_id}
delete_entity	DELETE	/catchAll/entities/{entity_id}

external_entity_id（v1.6.3）：create_entity 和 update_entity 接受一个可选的 external_entity_id 字符串——由客户提供、用于将实体关联到外部系统中记录的标识符。 project_id（v1.8.0）：list_entities 接受可选的 project_id，用于筛选属于特定 项目的实体。

来源组

MCP 工具	方法	端点
list_source_groups	GET	/catchAll/source-groups

**来源组（v1.8.0）：**可重复使用的命名域名允许列表（公共组，以及组织可访问的任何 组织可见性组）。list_source_groups 会返回每个组的 slug、name 和 description。 直接 API 的 POST /catchAll/submit 现在接受由 slug 组成的 source_groups 字段，以将抓取范围 限定在域名允许列表内；submit_query 尚未提供此参数——在后续版本将其加入之前，请使用直接 API。

用户与元数据

MCP 工具	方法	端点
get_user_limits	POST	/catchAll/user/limits
check_health	GET	/health
get_version	GET	/version

身份验证

API 密钥优先级（从高到低）：

1. api_key 工具参数
2. x-api-key 请求标头
3. Authorization: Bearer <key> 请求标头
4. URL 查询参数 ?apiKey=...
5. CATCHALL_API_KEY 环境变量

check_health 和 get_version 无需 API 密钥身份验证。

托管部署（FastMCP Gateway）

通过 fastmcp.app 部署时，服务器前面会有一个无状态网关。网关会将 HTTP 标头转发到后端，但不会转发 URL 查询参数。请改用 x-api-key 标头或 CATCHALL_API_KEY 环境变量，而不要使用 ?apiKey=。

Claude Code / Cursor：

{
  "mcpServers": {
    "catchall": {
      "type": "http",
      "url": "https://YOUR-DEPLOYMENT.fastmcp.app/mcp",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

也可以通过 CLI 使用：

claude mcp add --transport http catchall "https://YOUR-DEPLOYMENT.fastmcp.app/mcp" \
  --header "x-api-key: YOUR_API_KEY"

直接访问服务器（无网关）：URL 中仍可使用 ?apiKey=YOUR_KEY。

核心工作流（作业）

1. 可选：调用 initialize_query，预览验证器、增强项和日期范围。
2. initialize_query 仅用于预览（不会创建作业），且建议结果具有非确定性。
3. 使用 submit_query 提交（必须提供 query）。你可以只发送 query；未提供的可选字段会自动选择或生成。
4. 可选字段彼此独立：可提供任意子集（例如，仅自定义 validators），未提供的字段仍会自动生成。
5. start_date/end_date 用于筛选网页发现日期，而非提取内容中的事件日期。
6. 如需确保事件时间准确，请使用专注于事件的验证器和增强项，并核实拉取结果中的 event_date。
7. 轮询 get_job_status：首次在约 1–2 分钟后检查，之后每隔 30–60 秒检查一次；状态变为 completed 或 failed 时停止。
8. 使用 pull_results 拉取结果；在 enriching 阶段会显示部分数据。
9. 当 page < total_pages 时继续翻页，以获取所有可用记录。
10. 仅在需要处理更多记录时使用 continue_job（会影响成本）。它仅适用于最初提交时带有 limit 的作业。
11. continue_job.new_limit 为可选参数；若未提供，API 会默认使用你的套餐上限。
12. page/page_size/total_pages 表示当前已可用的记录；使用 progress_validated < candidate_records 判断是否可能还会有更多记录出现。

limit 与 page_size

• limit（submit_query、continue_job）控制要处理的记录数量，因此会影响成本。若提供，必须 >= 10。省略时会检索套餐上限内的所有记录。
• page_size（pull_results、list_user_jobs）仅控制分页，不影响处理成本。
• pull_results.page_size 的默认值为 100。
• page_size 范围为 1..1000。
• pull_results 响应包含 error（失败的作业）和 limit（应用的作业上限）。

API 强制执行的监控约束

• create_monitor.backfill=true：参考作业的 end_date 必须在最近 7 天内。
• create_monitor.backfill=false：不受参考作业时限约束。
• 监控的最短计划频率取决于套餐。
• create_monitor 支持可选的 limit（最小值为 10）、backfill（默认值为 true）、timezone、webhook_ids 和 project_id。
• v1.5.3 中 Webhook 已集中管理：使用 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，而不是返回错误字符串，因此失败总会作为真正的工具错误报告。

运行

安装依赖：

pip install -r requirements.txt

通过 stdio 运行：

python server.py

通过 HTTP 运行（如果有 fastmcp CLI）：

fastmcp run server.py:mcp --transport streamable-http --host 0.0.0.0 --port 8000