> 地址：`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 七个条目上验证*