122 lines
3.8 KiB
Markdown
122 lines
3.8 KiB
Markdown
|
||
> 地址：`http://bh.vps.honor3.com:3000`
|
||
> 一句话：**读用 MCP（免密钥），写用 REST（要 `X-Ingest-Key`）**。
|
||
|
||
---
|
||
|
||
## 1. 接入 MCP（只读，无需密钥）
|
||
|
||
MCP 端点是 `POST http://bh.vps.honor3.com:3000/mcp`，走标准 JSON-RPC 2.0，
|
||
**不校验任何密钥**，只暴露只读工具。
|
||
|
||
客户端配置（Claude Desktop / Cursor / Cherry Studio 通用）：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"awesome-index": {
|
||
"url": "http://bh.vps.honor3.com:3000/mcp"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
手动测试（curl）：
|
||
|
||
```bash
|
||
curl -s -X POST "http://bh.vps.honor3.com:3000/mcp" \
|
||
-H "Content-Type: application/json" \
|
||
-H "Accept: application/json, text/event-stream" \
|
||
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
|
||
```
|
||
|
||
⚠️ 必须带 `Accept: application/json, text/event-stream`，否则会被拒。
|
||
|
||
---
|
||
|
||
## 2. 四个只读工具
|
||
|
||
| 工具 | 参数 | 用途 |
|
||
| --- | --- | --- |
|
||
| `search_entries` | `q`（必填，关键字）、`limit`（1–50，默认 20） | 按关键字/类型/标签搜索 |
|
||
| `get_entry` | `slug`（必填，也可传标题关键字自动匹配） | 取单条详情 |
|
||
| `random_entry` | 无 | 随机抽一条，用于发现 |
|
||
| `list_tags` | 无 | 列全部标签组与数量 |
|
||
|
||
调用示例：
|
||
|
||
```bash
|
||
curl -s -X POST "http://bh.vps.honor3.com:3000/mcp" \
|
||
-H "Content-Type: application/json" \
|
||
-H "Accept: application/json, text/event-stream" \
|
||
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
|
||
"params":{"name":"search_entries","arguments":{"q":"自托管相册","limit":5}}}'
|
||
```
|
||
|
||
结果在 `result.content[0].text` 里，是一段 JSON 字符串，需再解析一次。
|
||
|
||
---
|
||
|
||
## 3. 提交条目（写入，要密钥）
|
||
|
||
```bash
|
||
curl -X POST "http://bh.vps.honor3.com:3000/api/ingest/entry" \
|
||
-H "X-Ingest-Key: sk-test" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"title": "MinerU",
|
||
"url": "https://github.com/opendatalab/MinerU",
|
||
"type": "工具",
|
||
"summary": "PDF/文档转 Markdown 的解析引擎",
|
||
"tags": ["Python", "OCR", "文档解析"]
|
||
}'
|
||
```
|
||
|
||
成功返回：`{"ok":true,"data":{"created":true,"id":54,"status":"pending"}}`
|
||
|
||
中文内容建议存成 `.json` 文件再 `-d @file.json`，避免 shell 编码踩坑；
|
||
Windows 下用 Python `json.dumps(..., ensure_ascii=False).encode('utf-8')` 最稳。
|
||
|
||
---
|
||
|
||
## 4. 字段规则
|
||
|
||
| 字段 | 必填 | 约束 |
|
||
| --- | --- | --- |
|
||
| `title` | ✅ | 标题 |
|
||
| `url` | ✅ | 合法 URL，**用于去重** |
|
||
| `type` | ✅ | 只能是：`微服务` `SaaS` `网站` `工具` `应用` `脚本` `插件` |
|
||
| `summary` | ❌ | ≤ 200 字符 |
|
||
| `description_md` | ❌ | ≤ 5000 字符，支持 Markdown |
|
||
| `license` | ❌ | 如 `MIT`、`GPL-3.0` |
|
||
| `stars` | ❌ | 整数 |
|
||
| `tags` | ❌ | 字符串数组 |
|
||
| `status` | ❌ | `pending` / `active` |
|
||
|
||
**`slug` 不是合法字段**，传了会被静默丢弃。
|
||
|
||
---
|
||
|
||
## 5. 五个坑（记牢就够）
|
||
|
||
1. **认证头是 `X-Ingest-Key`**。`Authorization: Bearer`、`X-API-Key`、`?key=` 全部 403。
|
||
2. **MCP 免密钥 ≠ 密钥有效**。`/mcp` 根本不查 key，别拿它验证密钥。
|
||
3. **提交后默认 `pending`**，前台搜不到是正常的，要等管理员审核变 `active`。
|
||
4. **同 URL 重复提交返回 200 `created:false`**，不是报错，说明已存在。
|
||
5. **`/api/entries` 也能写**（未登录时回退到 AI key 校验），但推荐用 `/api/ingest/entry`。
|
||
|
||
---
|
||
|
||
## 6. 典型工作流
|
||
|
||
```
|
||
1. search_entries 查重 → 已有就 get_entry 看详情，别重复提交
|
||
2. WebSearch / WebFetch 收集项目信息
|
||
3. 组装 JSON（title + url + type 三个必填）
|
||
4. POST /api/ingest/entry（X-Ingest-Key）
|
||
5. 记下返回的 id，状态 pending
|
||
```
|
||
|
||
---
|
||
|
||
*整理于 2026-10-27 · 已在 MinerU / Mio CUA / Windows-Use / Transub / TinyJS / Quickemu / nanoMuse 七个条目上验证* |