CUDA-Q Docs

cudaq-docs-mcp

一个 MCP 服务，为 AI Agent 提供 NVIDIA CUDA-Q 文档、API 参考和可运行示例，并固定到你实际安装的 cudaq 版本。

社区项目，与 NVIDIA 无关，也未获得 NVIDIA 认可。CUDA-Q 是 NVIDIA Corporation 的商标。

为什么需要它

量子 SDK 的迭代速度比模型训练数据更新快。让 AI 助手编写 CUDA-Q 代码时，它会根据记忆中的内容作答：已重命名的 API、已弃用的目标名称，以及与你使用的版本不符的安装步骤。问题出在版本不一致上，而这恰恰影响最重要的新手入门阶段：最初的十分钟。

这个服务让任何支持 MCP 的 Agent 都能获得当前的准确答案。它提供文档搜索、精确的 API 符号解析、完整的可运行示例和后端选择指南，所有内容都来自与你安装的 cudaq 软件包匹配的文档索引。无需 API 密钥，也无需嵌入：索引建好后，即可在你的机器上离线使用 SQLite 全文搜索和 BM25 排序。

快速开始

向你的客户端注册此服务；首次使用时，它会自动下载预构建索引（约几 MB）。只有预构建资源中没有对应版本时，才需要本地构建：

uvx cudaq-docs-mcp build --version 0.14.0

Claude Code

claude mcp add cudaq-docs -- uvx cudaq-docs-mcp

Claude Desktop（claude_desktop_config.json）、Cursor（.cursor/mcp.json）或任何接受 JSON 服务映射的客户端：

{
  "mcpServers": {
    "cudaq-docs": {
      "command": "uvx",
      "args": ["cudaq-docs-mcp"]
    }
  }
}

VS Code（.vscode/mcp.json）：

{
  "servers": {
    "cudaq-docs": {
      "type": "stdio",
      "command": "uvx",
      "args": ["cudaq-docs-mcp"]
    }
  }
}

更喜欢使用 pip？运行 pip install cudaq-docs-mcp，并将 cudaq-docs-mcp 用作命令。

工具

工具	返回内容
search_docs(query, version?, limit?)	排序后的文档摘录，附带导航路径和规范 URL
get_page(path, version?)	一篇完整、简洁的 Markdown 文档页面
find_api(name, language?, version?)	精确的 Python 或 C++ 符号、类型、文档 URL 和摘录
search_examples(query, language?, version?, limit?)	CUDA-Q 仓库中与对应版本匹配的完整可运行程序
list_targets(category?)	全部 24 个执行目标：模拟器、硬件提供商和云平台，并附带选择代码片段和使用建议

资源：cudaq://versions（已安装和已索引的版本）以及 cudaq://llms.txt（所提供版本对应的 CUDA-Q 自有 llms.txt）。

固定版本的回答

每个工具都按以下顺序解析文档版本：

1. 显式传入的 version 参数（“0.15.0”、“latest”）
2. 从发行版元数据检测到的已安装 cudaq 软件包（绝不会导入 cudaq）
3. latest

每个版本都有独立索引。若缺少指定版本的索引，服务会在响应中说明，并改为提供 latest，同时给出解决问题所需的一条命令。这样，版本不一致会显式呈现，而不会悄然发生。

工作原理

CUDA-Q 会发布原始资料：列出所有页面和 API 符号的 Sphinx inventory（objects.inv）、每个文档页面的 Markdown 镜像、按版本提供的 llms.txt，以及仓库中的示例源代码。此服务以此为基础构建：

• objects.inv 是爬取清单和 API 符号表：无需依赖启发式抓取
• 每个 Markdown 镜像都会清除主题界面元素，重建带语言标记的代码块，并保留标题锚点以支持深层链接
• 页面按标题分块，并使用 SQLite FTS5 建立索引（Porter 词干提取、BM25 排序）
• 示例、代码片段和应用源码均从与文档版本匹配的 GitHub 发布标签获取

每个版本的完整索引都是缓存目录中的一个 SQLite 文件（运行 cudaq-docs-mcp info 可查看位置）。每晚运行的工作流会重建 latest 索引，让更新只需下载，无需构建。

CLI

cudaq-docs-mcp            # serve MCP on stdio (what clients run)
cudaq-docs-mcp build      # build the index for your installed cudaq, else latest
cudaq-docs-mcp build --version 0.15.0
cudaq-docs-mcp info       # cache location, indexed versions, detected cudaq

设置 CUDAQ_DOCS_MCP_AUTOBUILD=1 可在首次使用时自动构建；设置 CUDAQ_DOCS_MCP_CACHE 可更改缓存位置。

路线图

• 为固定的发布版本提供预构建索引，而不只支持 latest
• 构建真实开发者问题的评测集，并公布检索分数
• CUDA-QX 库文档

贡献

欢迎提交问题和 PR。提交需要 DCO 签署（git commit -s）；请参阅 CONTRIBUTING.md。使用 Claude Code 开放构建。

许可证

Apache-2.0。文档内容归 NVIDIA Corporation & Affiliates 所有，源自采用 Apache-2.0 许可证的 NVIDIA/cuda-quantum 仓库，且每个提供的结果都会链接回规范页面。请参阅 NOTICE。