Knowledge/1 使用/AI 大模型/Awesome Index · MCP 使用速查.md

地址：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 通用）：

{
  "mcpServers": {
    "awesome-index": {
      "url": "http://bh.vps.honor3.com:3000/mcp"
    }
  }
}

手动测试（curl）：

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	无	列全部标签组与数量

调用示例：

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. 提交条目（写入，要密钥）

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 七个条目上验证