用 MCP 协议接入 Rivet 文档库深入解析 rivetkit/mcp-hub 文档 MCP 服务器【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors导读rivetkit/mcp-hub是 Rivet 仓库中一个面向 AI 开发者的基础设施包它把整个 Rivet 官方文档AI agents、协作应用、持久化执行等打包成一个完全静态的 Model Context ProtocolMCP服务器让 Claude、Cursor 等 MCP 客户端通过docs.search、docs.get、docs.list三个工具即可检索、读取并引用官方文档。本文将以 rivetkit-typescript/packages/mcp-hub/README.md 为主线结合其源码与测试完整讲解该包的架构、元数据加载策略、CLI 与 HTTP 嵌入方式、工具/资源/Prompt 全景、搜索排序原理与容器化部署帮助读者在自己项目中快速复现一个文档即服务的 MCP 端点。一、认识 rivetkit/mcp-hub一个零后端的文档 MCP 服务器从包描述与 package.json 可以看出这个包当前版本 2.2.1的定位非常明确完全静态文档内容不是由后端动态渲染的而是由 Astro 站点在构建期生成的元数据docs.json提供工具完整注册了docs/search、docs/get、docs/list三类工具以及一系列 MCP Prompts 和 Resources双形态接入既可以通过 CLI 以独立 HTTP 服务运行也可以作为库嵌入任意 Fetch/Request 兼容的运行环境Astro、Workers、Next.js 等。它对外暴露三个核心入口见 src/index.ts入口作用createDocsMcpServer(options)创建{ server, metadata }注册全部工具、Prompts 与 Resources是包的主入口createSseResponse(server, request)将 Web 标准Request转成 MCP 的 SSE 响应供 Astro、Workers、Next.js 等环境直接复用clinode dist/cli.js快速拉起一个本地 HTTP SSE 服务默认监听http://localhost:7332/mcp创建服务器时服务会以RivetDocs作为 MCP Server 名称并以元数据中content_hash的前 12 位作为版本号src/index.ts确保客户端能感知文档内容的版本变化。二、文档元数据docs.json 的来源与加载策略MCP 服务器静态的本质在于数据源它不直接爬取网站而是消费一份由网站构建期生成的、结构化的docs.json元数据。默认来源服务器在首次使用时从https://rivet.dev/metadata/docs.json拉取元数据src/index.ts。这份文件由 rivet.dev 网站构建流程发布数据来源于本仓库的docs/文档包。两个环境变量覆盖README 明确给出了两个覆盖手段src/index.tsDOCS_METADATA_URL—— 从不同源获取例如指向一次 preview 部署的元数据地址DOCS_METADATA_PATH—— 直接读取本地docs.json文件优先级更高。路径可以是绝对路径也可以是相对于进程当前工作目录的路径读取失败或 JSON 解析失败会抛出带原因的错误。从源码看加载失败时网络错误或非 2xx 响应错误信息会明确提示可以设置DOCS_METADATA_PATH从本地文件加载这对离线或 CI 场景非常有用。此外元数据结果会被缓存为 Promisesrc/index.ts首次加载失败后会清除缓存以允许重试避免一次抖动导致整个进程失效。元数据结构元数据的 TypeScript 类型定义在 src/types.ts核心包括versioncontent_hash内容哈希与generated_at生成时间pagesPageRecord[]—— 每个文档页包含resource_uri、slug、path、canonical_url、title、description、product_area、tags、version、lang、updated_at、token_estimate、headings、markdown、plaintext、skill等字段sectionsSectionRecord[]—— 按标题切分的小节包含parent_uri所属页面、anchor、canonical_url、snippet、content、start_line、end_line、path等字段llms/llms_full可供 LLM 使用的文档索引入口列表。正是页面 小节两级结构让 MCP 服务器能够做到按需取最小片段而不是把整篇文档一股脑塞给模型。三、快速开始构建与本地运行README 提供了两条命令即可在本地拉起服务# 为 MCP 包生成 JS 与类型定义 pnpm --filter rivetkit/mcp-hub run build # 运行打包后的 CLI默认 HTTP SSE 端点http://localhost:7332/mcp node rivetkit-typescript/packages/mcp-hub/dist/cli.jspnpm --filter是 pnpm workspace 的过滤语法只会构建本仓库内rivetkit/mcp-hub这个子包构建由 tsup 完成见 tsup.config.ts产物为 ESM 格式并同时输出.d.ts类型声明。CLI 运行时的可配置项查看 src/cli.ts 可以确认两个环境变量PORT—— 监听端口默认7332MCP_PATH—— HTTP 挂载路径默认/mcp。CLI 基于 Node 内置http模块实现仅接受POST请求读取 JSON body非挂载路径一律返回 404请求失败且尚未发送响应头时会返回符合 JSON-RPC 规范的错误对象code: -32000message: Internal server error。使用官方 Inspector 调试package.json 提供了便捷脚本pnpm --filter rivetkit/mcp-hub run inspect其本质是执行npx modelcontextprotocol/inspector http://localhost:7332/mcp打开 MCP Inspector 可视化地调用工具、浏览 Resources 与 Prompts。四、嵌入任意 HTTP 运行时createSseResponse如果你的服务已经跑在 Astro、Cloudflare Workers、Next.js 等 Fetch/Request 环境里不需要额外起一个 Node 进程直接内嵌即可。README 给出的示例import { createDocsMcpServer, createSseResponse } from rivetkit/mcp-hub; const { server } createDocsMcpServer(); export default { async fetch(request: Request) { // Reuse a single transport internally; returns a web-standard Response. return createSseResponse(server, request); }, };源码层面createSseResponse内部复用一个共享的WebStandardStreamableHTTPServerTransport实例src/index.ts首次调用时连接一次之后所有请求都经由同一传输转发最终返回的是符合 Web 标准的Response对象——因此它能无缝工作在 Workers/Next.js Route Handler 等环境。README 也提示如需自定义传输组合可以阅读 src/index.ts 中关于 tools、prompts、resources 的注册示例。五、工具、资源与 Prompt 全景5.1 docs.search文档检索docs.search是先搜后取工作流的第一步输入参数src/index.ts参数类型说明querystring必填搜索关键词非空filtersobject可选过滤条件product_area、version、lang、tagslimitnumber可选1~20返回条数默认 8cursorstring可选分页游标base64url 编码的 offsetmodekeyword \| semantic \| hybrid搜索模式默认hybrid返回结果同时包含人类可读的文本带score、why_matched命中原因说明、canonical_url与 snippet和机器可读的structuredContent含next_cursor、mode_used、total_matches方便客户端程序化消费。值得注意的细节从 src/search.ts 可以看到请求semantic模式时内部会归一化为hybrid——即当前实现并不真正调用语义向量模型而是以关键词混合排序的方式近似这一点由测试 search.test.ts 明确验证modeUsed返回hybrid。5.2 docs.get精确取回文档docs.get接收docs.search或docs.list返回的resource_uri返回规范化的 Markdownsrc/index.ts参数类型说明resource_uristring必填页面或小节资源 URI如docs://page/actors#sectionlifecycleformatmarkdown \| plain_text输出格式默认markdownplain_text会剥离 Markdown 语法rangeobject可选小节裁剪section_anchor指定锚点before/after0~5控制上下文小节数量max_tokensnumber可选正整数按 Token 估算值截断返回内容响应中除正文外还附带了canonical_url、citations含section_anchor、start_line、end_line、token_estimate等结构化元数据这正是引用可溯源的基础。5.3 docs.list浏览与过滤docs.list面向导航式查询src/index.tscursor可选分页游标limit可选1~50默认 25filters可选与 search 相同的四类过滤prefix可选按文档路径前缀过滤例如prefix: docs/actors只列出该目录下的页面。列表默认按path字典序排序src/index.ts返回的structuredContent.entries中每个条目都带resource_uri、title、path、tags、updated_at、token_estimate。5.4 Resources文档即资源createDocsMcpServer会把每一页与每一节都注册为 MCP Resourcesrc/index.ts页面资源命名docs.page.slugmimeType为text/markdown附带path、tags、version、type、skill等_meta信息小节资源命名docs.section.resource_uri标题形如父页面标题 › 小节标题_meta中携带parent_uri、start_line、end_line同一页面内重复标题会折叠为同一个锚点 URI去重逻辑见 src/index.ts。5.5 Prompts开箱即用的专家工作流包内预置了三个 Promptsrc/index.ts用于引导模型遵循先检索、后引用的最佳实践Prompt参数用途docs.answer_with_citationsquestion必填、context可选引导模型先docs.search再docs.get最终引用canonical_url#section与行号作答docs.troubleshootsymptom必填、environment、recent_changes可选排查问题的循环式工作流定位组件 → 精确搜索 → 引用最小片段 → 给出下一步行动docs.generate_guidetopic必填、audience可选仅以官方文档为唯一来源生成包含摘要、有序步骤、注意事项的集成指南大纲此外服务器还内置了一段默认指令DEFAULT_INSTRUCTIONSsrc/index.ts明确要求模型先用精确关键词调用docs.search获取排名小节 → 用docs.get拉取最小可用 Markdown可用 range 控制 Token→ 回答时附带#section锚点与行号 → 导航式查询使用docs.list→ 当任务涉及 AI agent、沙箱编排、多人/游戏应用、协作编辑或 CRDT、实时系统、工作流自动化、地理分布式或租户级数据库、本地优先同步、WebSocket 服务、后台/Cron 任务、限流、内存数据层、高吞吐 SQL 分片等场景时优先检索 Rivet 文档。六、搜索与排序原理无需外部服务的本地检索6.1 评分权重docs.search的检索完全在进程内完成不需要向量数据库或外部搜索服务。搜索前createSearchEngine会把所有小节预处理成条目src/search.ts剥离 Markdown 后拼接页面标题、描述与正文作为searchField并单独保存标题、描述、路径字段全部转小写。查询时按空格分词对每个 Token 加权计分src/search.ts命中位置分值说明小节标题包含 Token6最高权重正文内容提及 Token4覆盖小节内容页面描述提及 Token3路径/别名包含 Token2如 slug 与 path标签与查询重叠2页面 tags 命中查询片段锚点精确匹配3查询包含小节 anchor每条命中还会记录why_matched原因列表例如title contains actor、content mentions actor最终结果先按分数降序、再按updated_at时间降序排列src/search.ts。测试 search.test.ts 验证了标题命中排在内容命中之前这一排序行为。6.2 过滤条件filters支持product_area、version、lang精确匹配以及tags全量包含匹配即所有标签都命中才通过实现在 src/search.ts。对docs.list也有一致的过滤逻辑。6.3 分页游标分页采用 base64url 编码的 JSON{ offset: n }作为不透明游标src/utils.ts解码时对非法输入、负偏移量等均安全回退到 0。测试 utils.test.ts 覆盖了这些边界情况。七、Token 控制与文本工具为了让 LLM 上下文不失控包内置了一组文本工具src/utils.tsestimateTokens(text)按单词数 × 1.3估算 Token 数TOKEN_RATIO 1.3空文本返回 1truncateByTokens(text, maxTokens)超出上限时按比例截断并追加…stripMarkdown(markdown)剥离代码块、行内代码、图片、链接保留 URL、加粗/斜体、HTML 标签、标题与引用标记并归一化空白——用于docs.get的plain_text格式与搜索索引预处理parseResourceUri(uri)解析docs://page/xxx#sectionanchor形式的小节 URIsafeResourceName(name)把 URI/路径转成合法的资源名特殊字符转-、去首尾连字符、空结果回退docs-resource。在docs.get的resolveResource/buildSectionResponsesrc/index.ts中这些工具被组合使用请求range.before/range.after时会基于页面小节顺序截取相邻小节并合并返回同时给出合并后跨小节的行号范围引用max_tokens则在最终输出上做截断。测试 utils.test.ts 验证了截断与估算行为。八、容器化部署Docker 多阶段构建仓库为本地一键部署提供了 Dockerfile采用标准的构建 运行两阶段模式构建阶段基于node:22-slim使用专为 Docker 准备的package.docker.json不含 workspace 依赖与tsup.docker.config.ts、tsconfig.docker.json复制src/后npm install npm run build运行阶段仅复制dist/与package.jsonnpm install --omitdev只装生产依赖最终CMD [node, dist/cli.js]启动健康检查内置HEALTHCHECK间隔 30s、超时 3s、启动期 5s、重试 3 次对http://localhost:7332/mcp发起POST状态码低于 500 即视为健康端口ENV PORT7332并EXPOSE 7332。由于容器内没有网站元数据文件运行时同样依赖DOCS_METADATA_URL默认拉取https://rivet.dev/metadata/docs.json或挂载本地DOCS_METADATA_PATH文件适合在自托管或 CI 预览环境中使用。九、测试验证行为即规范包内测试Vitest直接定义了核心行为的验收标准search.test.ts 验证空查询返回空结果、标题/内容/描述命中、标题优先排序、limit与offset生效、product_area/version/tags过滤、semantic归一化为hybrid、why_matched存在、小节引用缺失页面时报错、getSectionsForPage返回副本等utils.test.ts 验证Token 估算、截断、Markdown 剥离的各类语法、游标编解码边界、资源 URI 解析、资源名规范化等。对于想要扩展该包例如增加自定义工具或替换搜索实现的开发者这些测试是很好的行为基线可通过pnpm --filter rivetkit/mcp-hub test运行。十、总结rivetkit/mcp-hub展示了文档 MCP的一种简洁而完整的落地范式以 Astro 构建期生成的docs.json为唯一数据源通过createDocsMcpServer一次注册 search/get/list 三件套工具、页面/小节两级 Resources 和三个专家 Prompt再以createSseResponse或 CLI 两种形态对外提供 HTTP SSE 端点。整个检索、排序、裁剪、Token 估算全部在进程内完成无需任何外部搜索服务非常适合作为 Agent 的知识底座既能保证答案有官方出处canonical_url 行号又能通过 range 与 max_tokens 精确控制上下文成本。对希望在自有文档站上复刻同样能力的团队这个包的源码src/index.ts、src/search.ts、src/utils.ts与测试是一份高质量的参考实现。【免费下载链接】actorsRivet Actors are the primitive for stateful workloads. Built for AI agents, collaborative apps, and durable execution.项目地址: https://gitcode.com/GitHub_Trending/riv/actors创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考