Repository navigation
cudaq-docs-mcp: serving the CUDA-Q docs to AI agents, pinned to the installed version #5103
rogerawong
started this conversation in
Show and tell
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
Hello! I would like to share a small community project: cudaq-docs-mcp, an open-source MCP server that lets AI coding assistants (Claude Code, Cursor, Copilot, and anything else that speaks MCP) look up CUDA-Q documentation, API signatures, and runnable examples, so answers come from the current docs for the installed version rather than from an educated guess. It is available on PyPI.
Why I built it
CUDA-Q evolves quickly, and the models behind coding assistants only know whatever was true when they were trained. Before writing any code, I ran a small experiment: I asked a current model, from memory only, for the exact signature of
cudaq.samplein CUDA-Q 0.14. To its credit, the model was careful. It offered what it called “the shape I remember, not a quotation,” flagged the keyword argument it suspected might not exist in 0.14, and recommended checking the real documentation. That caution is reasonable, but it leaves all of the verification work with the developer. With the server connected, the same question returns the exact signature together with a canonical link into the 0.14.0 documentation, because 0.14.0 is what that environment had installed. The developer never has to say which version they are on; the server reads it from the installed distribution metadata.How it works
Everything the server does builds on material this project already publishes. The Sphinx inventory (objects.inv) serves as both the crawl manifest and the API symbol table, the markdown mirrors added in #3308 provide the page content, llms.txt from #3512 is exposed as an MCP resource, and the examples come from the repository at the matching release tag. The index is plain SQLite full-text search, so there are no API keys and no embeddings involved, and everything works offline once a prebuilt index has downloaded on first use.
There are five tools:
search_docsreturns ranked excerpts with canonical URLs,get_pagereturns a whole page as markdown,find_apiresolves exact Python and C++ symbols,search_examplesreturns complete runnable programs, andlist_targetsprovides a curated matrix of the 24 execution targets with guidance on choosing among them.Trying it
Any client that accepts a JSON server map can use:
First use downloads a prebuilt, nightly-refreshed index of a couple of megabytes, and
pip install cudaq-docs-mcpworks as well. The README covers other clients and the local build path for pinned versions.Related
While ingesting the documentation I noticed two small publishing gaps in llms.txt and filed them as #5100, with a fix branch ready in case it is useful.
Questions for this community
I would welcome feedback of any kind, and I have two questions in particular. First, would a link from the documentation, or some deeper form of upstreaming, be useful to the project? I am happy to keep maintaining it as a community tool either way. Second, for anyone who works with CUDA-Q daily: what questions would you most want an assistant to answer correctly? I am assembling an evaluation set from real developer questions, and real ones are much better than invented ones.
The project is Apache-2.0 licensed, community-maintained, and not affiliated with NVIDIA. I built it in the open with Claude Code. Thank you to the docs team for the markdown mirrors, the inventory, and llms.txt: they made this straightforward to build.
All reactions