内容
新闻采集 CatchAll MCP 服务器
新闻采集 CatchAll API 的 MCP 服务器。
## 快速入门 — 使用我们的托管服务器
您不需要克隆或运行此仓库即可使用 MCP — NewsCatcher 运行了一个托管实例：
```
https://catchall-mscatcherapi.com/mcp?apiKey=您的_CATCHALL_API_KEY
```
在 [platform.newscatcherapi.com](https://platform.newscatcherapi.com/) 获取 CatchAll API 密钥，然后连接：
```json
{
"mcpServers": {
"catchall": {
"type": "http",
"url": "https://catchall-mcp.newscatcherapi.com/mcp?apiKey=您的_CATCHALL_API_KEY"
}
}
}
```
或通过 Claude Code CLI：
```bash
claude mcp add --transport http catchall "https://catchall-mcp.newscatcherapi.com/mcp?apiKey=您的_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}` |
### 监视器
| MCP 工具 | 方法 | 端点 |
| --- | --- |
| `create_monitor` | `POST` | `//monitors/create` |
| `update_monitor` | ` | `/catchAll/monmonitor_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` Webhooks
| MCP 工具 | 方法 | 端点 --- | --- | --- `list_webhooks`GET` | `/catchhooks` |
| `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}` |
### 项目
| MCP 工具 | 方法 | 端点 |
| --- | --- | --- |
| `create_project` | `POST` | `/catchAll/projects/` |
| `list | `GET`catchAll/projects/` |
| `get_project` | ` | `/catchAllproject_id}` |
|_project` | `PATCH` | `/catchAll/projects/{}` |
| `` | `DELETE`catchAll/projects/{project_id}` |
| `get` | `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}` |
### 数据集
| MCP 工具 | 方法 | 端点 |
| --- | --- | --- |
| `create_dataset` | `POST` | `/catchAll/datasets/` |
| `list_datasets` | `GET` | `/catchAll/datasets/` |
| `` | `GET` | `/catchAll/datasets/{dataset_id}` |
| `update_dataset` | `PATCH` | `/catchAll/datasets/{dataset_id}` |
| `delete_dataset` | `DELETE` | `/catchAlldataset_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` |
| `_status` | `GET `/catchAll/datasets/{dataset_id}/status` |
| `create_dataset_from_csv `POST` |All/datasets/upload` `append_csv_to_dataset` | `POST` | `/catchAll/datasets/{dataset_id}/upload` |
> **CSV 上传（v1.6.1）：** `_from_csv` 和 `append_csv_to_dataset` 需要` 参数中的 CSV **内容** — 原始 CSV 文本或标准 base64。它们
> 从不读取服务器路径，因此在远程/托管的 MCP 上保持安全联 CSV 内容的上限为 10 MB（base码后）。
> `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 | `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` 字符串客户提供的标识符，用于将实体链接到外部系统中的记录。
### 用户和元数据
| 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 网关）
通过 fastmcp.app 部署时，一个无状态网关位于服务器前面。网关
转发 HTTP 头到后端，但 **不** 转发 URL 查询参数。请使用 `x-api-key`
头或 `CATCHALL_API_KEY` 环境变量代替 `?apiKey=`。
**Claude Code / Cursor：**
```json
{
"mcpServers": {
"catchall": {
"type": "http",
"url": "https://您的部署.fastmcp.app/mcp",
"headers": { "x-api-key": "您的_API_密钥" }
}
```
或通过 CLI：
```bash
claude mcp add --transport http catchall "https://您的部署.fastmcp.app/mcp" \
--header "x-api-key: 您的_API_密钥"
```
**直接服务器访问**（无网关）：`?apiKey=您的密钥` 在 URL 中仍然有效。
## 核心工作流（作业）
1. 可选：调用 `initialize_query` 以预览验证器/增强/日期窗口。
2. `initialize_query仅用于预览（它作业），建议是非。
3. 使用 `submit_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`（`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`。
- Webhooks 在 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`（传递 `webhook_ids=[]` 以清除分配）。
- `itors` 支持分页包括 `page`page_size`，search`、`ownership`project_id` 过；它返回 `totalpage`、``、`total_pages `monitors` 丰富输出说明enrichmentment_confidence`存在。
- 公司结构化对象， - `source_text`
- `confidence`
- `metadata.name - `metadata.domain_url`
- `metadata.domain_url_confidence`
## 错误处理
工具返回：
- 成功时返回漂亮的 JSON 字符串。
- 验证/API 错误时返回 `"Error: ..."`。
- 未处理的异常返回 `"Unexpected error: ..."`。
## 运行
安装依赖项：
```bash
pip install -r requirements.txt
```
通过 stdio 运行：
```bash
python server.py
```
通过
