内容
# 核心爪 MCP 服务器
核心爪 MCP 服务器向 MCP 客户端（如 Codex、Claude Desktop、Cursor、n8n 等）公开核心爪 OpenAPI v2 接口。
## 主机端点
一流的 MCP 入口点是托管的 Streamable HTTP 端点：
```text
https://mcp.coreclaw.com/mcp
```
在托管部署更新到此存储库版本时，请使用以下配置：
```json
{
"mcpServers": {
"coreclaw": {
"url": "https://mcp.coreclaw.com/mcp",
"headers": {
"api-key": "您的核心爪令牌"
}
}
}
}
```
服务器接受来自 MCP 客户端的 `api-key`、`X-API-Key` 或 `Authorization: Bearer <token>`，并将核心爪 API 身份验证转发到上游作为 `Authorization: Bearer <token>`。
## 范围
- API 真相来源：`exported-api-docs/openapi.json` 和 `exported-api-docs/endpoints.csv`
- 公共 v2 操作作为 MCP 工具暴露：34
- 排除的内部操作：`POST /api/v2/workers/{workerId}/versions`、`PUT /api/v2/workers/{workerId}/versions/{version}`、`GET /api/v2/workers/{workerId}/internal`
- 传输：stdio 和 Streamable HTTP
- REST 兼容性适配器：`POST /mcp/<tool_name>`
- 身份验证：传入的 `api-key`、`X-API-Key` 或 `Authorization: Bearer <token>` 被转发到核心爪作为 `Authorization: Bearer <token>`
- 服务器指令：在 MCP `initialize` 时返回推荐的核心爪工作流，支持英文和中文
- 工具注释：每个工具都暴露了明确的 `title`、`readOnlyHint`、`destructiveHint`、`idempotentHint` 和 `openWorldHint`
## 构建和测试
```bash
go test ./...
go vet ./...
go build -o coreclaw-mcp-server .
```
真实 API 和本地 HTTP 验证：
```powershell
$env:CORECLAW_API_KEY="您的核心爪令牌"
.\scripts\verify-real-api.ps1
```
真实 MCP 触发的端到端运行验证：
```powershell
$env:CORECLAW_API_KEY="您的核心爪令牌"
.\scripts\verify-e2e-run.ps1
```
端到端脚本启动本地 Streamable HTTP MCP 服务器，通过 MCP `tools/call` 调用 `run_worker_task`，轮询 `get_worker_run`，然后验证日志、结果行和 JSON 导出。
## 运行
stdio：
```bash
CORECLAW_API_KEY="您的核心爪令牌" ./coreclaw-mcp-server --transport stdio
```
HTTP：
```bash
./coreclaw-mcp-server --transport http --port 3000 --base-url https://openapi.coreclaw.com
```
HTTP 服务器暴露：
- `POST /mcp` 用于 MCP Streamable HTTP
- `POST /mcp/<tool_name>` 用于 REST 风格的工具调用
## MCP 工具
工具按模型通常使用的顺序注册：发现和预检、执行、运行查找、结果/日志/导出检索，然后重复或中止控制。
| 工具 | API |
| --- | --- |
| `list_proxy_regions` | `GET /api/v2/proxy/region` |
| `list_store_workers` | `GET /api/v2/store` |
| `list_workers` | `GET /api/v2/workers` |
| `get_worker` | `GET /api/v2/workers/{workerId}` |
| `get_worker_input_schema` | `GET /api/v2/workers/{workerId}/input-schema` |
| `list_worker_tasks` | `GET /api/v2/worker-tasks` |
| `get_worker_task` | `GET /api/v2/worker-tasks/{workerTaskId}` |
| `get_worker_task_input` | `GET /api/v2/worker-tasks/{workerTaskId}/input` |
| `get_account_info` | `GET /api/v2/users/account` |
| `create_worker_task` | `POST /api/v2/worker-tasks` |
| `update_worker_task` | `PUT /api/v2/worker-tasks/{workerTaskId}` |
| `update_worker_task_input` | `PUT /api/v2/worker-tasks/{workerTaskId}/input` |
| `delete_worker_task` | `DELETE /api/v2/worker-tasks/{workerTaskId}` |
| `run_worker` | `POST /api/v2/workers/{workerId}/runs` |
| `run_worker_task` | `POST /api/v2/worker-tasks/{workerTaskId}/runs` |
| `list_worker_runs` | `GET /api/v2/worker-runs` |
| `get_last_worker_run` | `GET /api/v2/worker-runs/last` |
| `get_worker_run` | `GET /api/v2/worker-runs/{runId}` |
| `get_worker_last_run` | `GET /api/v2/workers/{workerId}/runs/last` |
| `list_last_worker_run_results` | `GET /api/v2/worker-runs/last/result` |
| `export_last_worker_run_results` | `GET /api/v2/worker-runs/last/export` |
| `get_last_worker_run_log` | `GET /api/v2/worker-runs/last/log` |
| `list_worker_run_results` | `GET /api/v2/worker-runs/{runId}/result` |
| `export_worker_run_results` | `GET /api/v2/worker-runs/{runId}/result/export` |
| `get_worker_run_log` | `GET /api/v2/worker-runs/{runId}/log` |
| `list_worker_last_run_results` | `GET /api/v2/workers/{workerId}/runs/last/result` |
| `export_worker_last_run_results` | `GET /api/v2/workers/{workerId}/runs/last/export` |
| `get_worker_last_run_log` | `GET /api/v2/workers/{workerId}/runs/last/log` |
| `rerun_last_worker_run` | `POST /api/v2/worker-runs/last/rerun` |
| `rerun_worker_run` | `POST /api/v2/worker-runs/{runId}/rerun` |
| `rerun_worker_last_run` | `POST /api/v2/workers/{workerId}/runs/last/rerun` |
| `abort_last_worker_run` | `POST /api/v2/worker-runs/last/abort` |
| `abort_worker_run` | `POST /api/v2/worker-runs/{runId}/abort` |
| `abort_worker_last_run` | `POST /api/v2/workers/{workerId}/runs/last/abort` |
## 示例 MCP 配置
托管 HTTP：
```json
{
"mcpServers": {
"coreclaw": {
"url": "https://mcp.coreclaw.com/mcp",
"headers": {
"api-key": "您的核心爪令牌"
}
}
}
}
```
本地 stdio：
```json
{
"mcpServers": {
"coreclaw": {
"command": "/绝对路径/to/coreclaw-mcp-server",
"args": ["--transport", "stdio", "--base-url", "https://openapi.coreclaw.com"],
"env": {
"CORECLAW_API_KEY": "您的核心爪令牌"
}
}
}
}
```
本地 HTTP：
```json
{
"mcpServers": {
"coreclaw": {
"url": "http://localhost:3000/mcp",
"headers": {
"api-key": "您的核心爪令牌"
}
}
}
}
```
## REST 适配器示例
```bash
curl -X POST http://localhost:3000/mcp/list_store_workers \
-H "Content-Type: application/json" \
-d '{"keyword":"amazon","offset":0,"limit":5}'
curl -X POST http://localhost:3000/mcp/get_account_info \
-H "Content-Type: application/json" \
-H "api-key: 您的核心爪令牌" \
-d '{}'
curl -X POST http://localhost:3000/mcp/run_worker \
-H "Content-Type: application/json" \
-H "api-key: 您的核心爪令牌" \
-d '{"worker_id":"您的 worker ID","version":"v1.0.1","input_json":"{\"keyword\":\"coffee\",\"limit\":10}","is_async":true}'
```
对于 `run_worker`、`create_worker_task` 和 `update_worker_task_input`，请将 `get_worker_input_schema` 中的业务字段作为 `input_json` 传递。MCP 服务器将该对象包装为核心爪的 `input.parameters.custom`。高级调用者可以使用原始输入 JSON 代替 `raw_input_json`（仅限 `run_worker`）。
## GitHub 部署
存储库包括：
- `.github/workflows/ci.yml`：格式、检查、竞争条件测试、构建
- `.github/workflows/release.yml`：多平台制品
- `.github/workflows/deploy.yml`：手动 SSH 部署到 Linux 服务器
推荐的 GitHub 机密：
- `SSH_HOST`
- `SSH_USER`
- `SSH_PORT`（可选，默认为 `22`）
- `SSH_PASSWORD`
- `CORECLAW_BASE_URL`（可选，默认为 `https://openapi.coreclaw.com`）
请勿提交 `.env`、API 令牌或服务器密码。
