概述
BLVCK-RAG 是一个自建的 RAG（检索增强）知识库,以 MCP 服务的形态对外提供。任意支持 Model Context Protocol 的客户端接入后,会得到三个检索原语:
query_kb
向量语义 + 中文全文混合检索,经 RRF 融合与 rerank 精排。
add_to_kb
把文本切块、向量化并写入 PostgreSQL,之后立即可被检索。
graph_neighbors
沿 Obsidian Wikilink 图双向遍历 1–3 跳关联笔记。
快速接入
服务端点与认证方式如下。推荐 OAuth 2.1 自动授权;不支持 OAuth 的客户端可向管理员获取静态 Bearer token。
https://rag.blvck.wang/mcp
OAuth 2.1 / Authorization: Bearer <token>
Claude Code · OAuth — 推荐
claude mcp add --transport http blvck-rag https://rag.blvck.wang/mcp -s user
# 添加后对 blvck-rag 执行 Authenticate静态 Bearer — 兼容通道
claude mcp add --transport http blvck-rag https://rag.blvck.wang/mcp \ --header "Authorization: Bearer <你的token>" -s user
其他 Agent — 通用 HTTP
支持 OAuth 的客户端直接添加端点并完成授权;程序直连可带 Bearer 头,走 MCP Streamable HTTP 协议。
query_kb
用 pgvector 语义检索与 zhparser 中文全文检索召回,经 RRF 融合和 rerank 精排。返回的是素材、不是成品答案——由调用方 AI 读片段后自行综合。
question问题或主题 必填
自然语言,描述你想查什么
topN返回几条 可选
整数 1–15,默认 6
type类型过滤 可选
person / topic / daily / note
category分类过滤 可选
必须是受控词表中的分类
返回:每条含 来源标题 · 相关度分数 · 原始片段正文。
add_to_kb
把文本按 Markdown 标题切块、嵌入并写入 PostgreSQL,之后 query_kb 即可检索到。相同标题生成相同 ID 时会 UPSERT 覆盖;删除与重索引由管理台提供。
title文档标题 必填
简短描述,作为来源标签
content正文内容 必填
最长约 100 万字符,超了请拆成多篇
type内容类型 可选
默认 note,必须已登记
category分类 可选
未知分类会被拒绝
graph_neighbors
从指定笔记名出发,沿 Wikilink 双向遍历 1–3 跳,用于发现仅靠文本相似度不容易命中的关联内容。
name笔记名 必填
使用 basename,如 World Model
hops最大跳数 可选
1–3,默认 2
错误码
401OAuth 未完成,或 Bearer 错误/已吊销 —— 重新授权或联系管理员
503触发限流(短时高频)—— 降低请求频率
400请求格式有误 —— 检查 JSON 与参数
限流
为防滥用,每个来源 IP 平均 10 请求/秒、允许突发 20。正常的 Agent 查询远到不了这个量,触发不了;超限的请求会返回 503。