内容
# aparser-mcp
**中文** · [Русский](README.ru.md)
[](https://www.npmjs.com/package/aparser-mcp)
一个 [MCP](https://modelcontextprotocol.io) 服务器，暴露 [A-Parser](https://a-parser.com) 的 HTTP API 作为工具，使 AI 代理可以直接驱动解析任务 - 运行搜索引擎结果页面（SERP）或建议查询，队列批量任务，轮询它们，并获取结果。
传输方式：**stdio**。基于官方的 [TypeScript MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) 构建。
## 要求
- 运行中的 A-Parser 实例，启用 API（设置 → API）及其密码。API 监听在 `http://<host>:9091/API`。
- Node.js ≥ 18（用于 `npx` 或从源代码构建）。
## 运行
已发布到 npm - 无需安装，`npx` 会自动获取并运行：
```bash
AP_URL=http://<host>:9091/API AP_PASSWORD=<password> npx -y aparser-mcp
```
<details>
<summary>或从源代码运行</summary>
```bash
git clone <此仓库> aparser-mcp && cd aparser-mcp
npm install # 通过 prepare 脚本构建 dist/
AP_URL=http://<host>:9091/API AP_PASSWORD=<password> npm start
```
</details>
## 配置
服务器读取三个环境变量：
| 变量 | 必需 | 描述 |
|---------------|----------|----------------------------------------------------------|
| `AP_URL` | 是 | API 基本 URL，例如 `http://127.0.0.1:9091/API`（如果缺少，则自动添加 `/API`）。 |
| `AP_PASSWORD` | 是 | A-Parser 网页界面中的 API 密码。 |
| `AP_TIMEOUT` | 否 | 每请求 HTTP 超时（秒），默认值 `130`。 |
## 注册到 Claude Code
```bash
claude mcp add aparser \
--env AP_URL=http://<host>:9091/API \
--env AP_PASSWORD=<password> \
-- npx -y aparser-mcp
```
或将其添加到 `.mcp.json` / 您的 MCP 客户端配置中：
```json
{
"mcpServers": {
"aparser": {
"command": "npx",
"args": ["-y", "aparser-mcp"],
"env": {
"AP_URL": "http://<host>:9091/API",
"AP_PASSWORD": "<password>"
}
}
}
}
```
## 使用 - 直接询问
一旦服务器和 `aparser` 技能安装完成，直接用自然语言询问，技能会自动选择解析器、地理位置和输出格式：
- **“aparser, 查找 `domain.com` 在塞尔维亚的排名”**
→ 在 google.rs 上查找排名（`gl=rs`，`hl=sr`）。
- **“aparser, Google 搜索建议 'buy iphone'”** → 建议。
- **“aparser, 在西班牙查找 'best running shoes' 的前 20 个 Google 结果”** → SERP 链接。
更多具体的工具调用示例：[`skills/aparser/examples.md`](skills/aparser/examples.md)。
## 工具
| 工具 | 功能描述 |
|----------------|--------------|
| `ping` | 健康检查。返回 `"pong"`。 |
| `info` | 服务器状态：队列任务、pid、可用解析器列表。 |
| `list_parsers` | 仅解析器名称（例如 `SE::Google`，`SE::Google::Suggest`）。 |
| `parser_info` | 解析器的结果字段模式（`arrays` + `flat`），用于构建 `resultsFormat`。 |
| `get_proxies` | 来自检查器的实时代理，格式为 `{"ip:port": ["type", ...]}`。 |
| `one_request` | **同步**运行一个解析任务并返回结果。适用于单个查询。 |
| `add_task` | 队列一个 **批量** 任务并保存到文件。返回任务 ID。 |
| `task_state` | 任务状态和实时统计。 |
| `wait_task` | 轮询任务直到完成；返回最终状态。 |
| `task_results` | 已完成任务结果文件的单次下载 URL。 |
### `one_request` vs `add_task`
- **`one_request`** - 同步，单个查询，内联返回结果。用于建议查询、单个 SERP 或检查单个页面。
- **`add_task`** - 异步队列，多个查询，输出写入服务器上的文件。使用 `wait_task` 然后 `task_results` 检索结果。
### 解析器堆栈 & resultsFormat
`add_task` 接受一个 `parsers` 堆栈 - 一个 `[name, preset, ...overrides]` 条目的列表：
```json
[["SE::Google", "default"]]
```
在 `results_format` 中， `$p1` 指第一个条目， `$p2` 指第二个条目，以此类推。调用 `parser_info("SE::Google")` 查看可引用的字段：
```
$p1.serp.format('$link; $anchor\n')
```
每请求覆盖（在 `one_request.options` 或 `parsers` 条目中）使用以下格式：
`{"type": "override", "id": "<param_id>", "value": <value>}`。
## 示例
可复制的请求示例 - 建议、SERP、地理位置检查、验证码解决、桌面/移动设备、批量任务 - 参见
[`skills/aparser/examples.md`](skills/aparser/examples.md)。
## 配套技能（`aparser`）
[`skills/aparser/`](skills/aparser/) 目录包含一个 Claude Code 技能，教导代理 **何时** 和 **如何** 调用这些工具 - 解析器命名、预设、地理位置、`resultsFormat` 和位置检查查询格式。安装它以便 Claude 自动加载：
```bash
# 最简单 - 通过 skills.sh（安装到每个支持的代理中）：
npx skills add izzipizzy/aparser-mcp
# 或手动作为个人 Claude Code 技能：
cp -r skills/aparser ~/.claude/skills/aparser
```
然后，当您询问 A-Parser 位置/SERP/建议时，它会自动加载。（在 `izzy` 插件中，它是 `izzy:aparser` 技能。）参见
[`skills/aparser/SKILL.md`](skills/aparser/SKILL.md) 和 [`skills/aparser/api-reference.md`](skills/aparser/api-reference.md)。
## 注意
- 访问搜索引擎的解析器需要可用的代理。如果 `one_request` 挂起或出错，请检查 `get_proxies` 和 A-Parser 中的解析器代理设置。
- 机密信息从未存储在此仓库中。请在您的 MCP 客户端配置或环境中保管 `AP_PASSWORD`。
## 开发
```bash
npm install # 安装依赖 + 构建
npm run build # 编译 src/ -> dist/
npm start # 运行已构建的服务器（需要 AP_URL / AP_PASSWORD）
```
源代码是一个文件：[`src/index.ts`](src/index.ts)。
