refdocs

Name: refdocs
Author: CloudCorpRecords

本地服务

github.com/CloudCorpRecords开发工具02 周前更新

代码仓库

关于 refdocs

refdocs 是供 Agent 使用的文档检索命令行工具和 stdio MCP 服务。它可搜索公开技术文档与 GitHub，并将网页转换为便于阅读的 Markdown。

主要功能

01搜索技术文档和 GitHub
02将 URL 内容转为 Markdown
03保留页面结构和代码
04提供命令行与 stdio MCP 服务

适用场景

01查找技术问题相关文档
02在 GitHub 中查找代码示例
03以整洁的 Markdown 阅读网页
04为 Agent 提供文档检索工具

MCP 相关

它可作为 stdio MCP 服务运行，并将文档搜索和 URL 阅读功能作为工具提供给 MCP 客户端。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "cloudcorprecords-refdocs": {
      "command": "npx",
      "args": [
        "-y",
        "@reneturcios/refdocs"
      ]
    }
  }
}

启动命令npx -y @reneturcios/refdocs

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@reneturcios/refdocs0.1.0stdio

ocighcr.io/cloudcorprecords/refdocs:0.1.0stdio

工具

收录的工具列表 · 更新于 1 周前

参数	类型	必填	说明
query	string	是	用于搜索相关文档的查询。应为完整句子或问题。

详细介绍

refdocs

refdocs 可解答文档相关问题，并将网页转换成 Agent 实际可读的内容。搜索会遍历公开技术文档和 GitHub，查找问题背后的事实或代码片段；也可以抓取任意 URL，并以干净的 Markdown 而非原始 HTML 返回。

它是一个小型程序，有两种使用方式：用于快速查询的命令行工具，以及通过 stdio MCP 服务向 Agent 提供相同两项工具的 MCP 服务。

配置

两项操作都需要 Ref API 密钥：

export REF_API_KEY="your-key-here"

搜索端点默认为 https://api.ref.tools。如果要指向其他部署，可通过 REF_API_BASE_URL 覆盖。发起任何请求前都会检查密钥；如果缺少密钥，工具会报错并指出 REF_API_KEY。

安装

npx @reneturcios/refdocs search "How do I stream a response with fetch?"

或者运行容器镜像：

docker run -i -e REF_API_KEY ghcr.io/cloudcorprecords/refdocs

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。

CLI

# Search the documentation
refdocs search "How do I use the cache API in Next.js?"
refdocs search "What does this error mean?" --json

# Read a page as markdown
refdocs read https://example.test/some/guide
refdocs read https://example.test/some/guide --json

# Check the configuration without making a request
refdocs check

refdocs --version

退出码：成功时为 0；查询失败或配置未就绪时为 1（错误信息会指出问题）；用法错误时为 2。

MCP 服务

同一个二进制文件支持这两种使用方式。mcp 子命令会启动 stdio MCP 服务：

npx -y @reneturcios/refdocs mcp

MCP 客户端配置：

{
  "mcpServers": {
    "refdocs": {
      "command": "npx",
      "args": ["-y", "@reneturcios/refdocs", "mcp"],
      "env": {
        "REF_API_KEY": "your-key-here"
      }
    }
  }
}

工具

工具	输入	返回内容
`ref_search_documentation`	`query`（字符串，必填）——用于搜索的完整句子或问题	来自公开文档和 GitHub 的匹配文档结果；每条结果包含标题、URL，以及上游提供的内容或片段。
`ref_read_url`	`url`（字符串，必填）——要读取的网页 URL	转换为 Markdown 的页面内容：标题、链接、列表、强调和代码块均保留为 Markdown 格式，同时移除脚本、样式及其他非内容标记。

搜索响应会以宽容方式解析：裸数组、results 列表和 documents 列表均可接受。读取纯文本 URL 时，文本会原样返回。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network
npm run dev     # run the CLI from source via tsx

测试完全使用模拟的 fetch 函数运行；不会发起实时 API 调用。