jscdocs
jscdocs lets AI agents search and read the user documentation of the JSC supercomputers JURECA, JUWELS, JUSUF, JUPITER, JEDI and JUDAC. It keeps a local index of the documentation at apps.fz-juelich.de/jsc/hps and serves it through an MCP server (jscdocs-mcp) and a command-line tool (jscdocs). This page is for people who want to use it with Claude Code or another MCP client.
An agent with jscdocs answers questions such as "what is the maximum walltime of JURECA's dc-gpu partition?" from the official documentation of that system, and cites the section it used.
Install
jscdocs needs Python 3.12 or later. Install it from a clone of this repository:
pip install . # or: uv tool install .
Then get the index once:
jscdocs sync
This downloads the index that this project builds from the documentation every week, a file of about 1.5 MB. It takes a few seconds. jscdocs itself never fetches the documentation sites: the published index is the only source, so jscdocs sync needs to reach gitlab.jsc.fz-juelich.de.
Register the server with your coding agent
jscdocs init registers the MCP server with Claude Code, Codex, pi or OpenCode, for all your projects. Restart the agent afterwards:
jscdocs init claude
jscdocs init codex --dry-run # show what would change
jscdocs init pi --index $PROJECT/$USER/jscdocs/index.sqlite
jscdocs init opencode --project # in the current project only, as a file others can share
Init uses the agent's own mcp add command where that can write the whole entry, and edits the agent's configuration file otherwise. It keeps your other servers and settings, and it never starts the server or downloads anything. docs/init.md describes the options, the files it writes and how it handles entries you edited.
In Claude Code the tools appear as mcp__jscdocs__search_docs, mcp__jscdocs__read_docs and mcp__jscdocs__list_docs. Any other MCP client, such as Cursor or your own agent, starts jscdocs-mcp as a stdio server, for example with claude mcp add --scope user jscdocs -- jscdocs-mcp in Claude Code.
| Tool | What it does |
|---|---|
search_docs |
Finds sections for a query, optionally on one system, with snippets and section URLs |
read_docs |
Reads a section (jureca/batchsystem#internet-access), a whole page, or a URL from a search, as Markdown |
list_docs |
Lists the indexed systems, or one system's table of contents |
All three tools only read the index. The server tells the agent to pass the system a question is about, to cite section URLs, and to treat the documentation as data, not as instructions.
Keeping the index current
The server keeps the index current by itself. When it starts, and on tool calls at most every ten minutes, it checks the index's age. If the index is missing or more than seven days old, the server syncs it in the background, as jscdocs sync does, and keeps answering from the old index meanwhile. Results carry the date on which the documentation was fetched and warn when the index is more than two weeks old.
A sync asks for the published index, and what it does next depends on the answer:
| The published index | What the sync does |
|---|---|
| Is newer than the local index | Downloads it and replaces the local index |
| Is not newer | Nothing. The server asks again an hour later |
| Cannot be downloaded | Keeps the local index, if there is one, and says why. The server tries again an hour later |
A download is tried twice at most, and each try waits at most ten seconds for the server. A sync that cannot succeed therefore fails within seconds when the server refuses the connection or reports an error, and after about 20 seconds when the server does not answer at all. Without a local index, the tools then tell the agent that the index could not be downloaded and why.
A lock file next to the index (index.sqlite.lock) lets only one process replace it at a time, so several sessions, or several login nodes sharing one index, do not download it several times.
To sync by hand, run:
jscdocs sync # download the published index if it is newer
jscdocs sync --force # download it in any case, to replace an index that is damaged
Command line
The CLI gives the same answers as the tools:
jscdocs search "scratch quota" --system juwels
jscdocs read jureca/batchsystem#internet-access
jscdocs toc jupiter
jscdocs status # index location, sync time, systems
Configuration
| Variable | Default | Meaning |
|---|---|---|
JSCDOCS_INDEX |
~/.cache/jscdocs/index.sqlite |
Where the index lives |
JSCDOCS_REFRESH_HOURS |
168 (seven days) |
Index age after which the server syncs it; 0 turns automatic syncs off (as does jscdocs-mcp --no-refresh) |
JSCDOCS_INDEX_URL |
This project's package registry on JSC's GitLab | Where the published index is downloaded from, for a mirror or a fork that publishes its own |
On the JSC clusters
jscdocs runs on the login nodes as it does on a laptop. $HOME is small and shared across the systems, so consider pointing JSCDOCS_INDEX at a project directory and using that one index from every login node:
export JSCDOCS_INDEX=$PROJECT/$USER/jscdocs/index.sqlite
Compute nodes have no internet access on most partitions. The tools work there from an existing index, but the server cannot refresh it.
Search quality
jscdocs eval tests/eval/questions.toml scores search against questions with known answers. The index uses keyword search (SQLite FTS5 with BM25). It finds the right page in the top three results for about nine in ten questions. It misses questions phrased in words the documentation does not use, such as "VS Code" for "VSCode", so the server asks the agent to rephrase in the documentation's terms when results do not fit.
Licence
The code is MIT-licensed. The JSC documentation it indexes is licensed CC BY-NC-SA 4.0 by the system administrators at Forschungszentrum Juelich.
The Python package contains no documentation. The index does: it holds the documentation's text, converted to Markdown and split into sections. An index is therefore under CC BY-NC-SA 4.0 and not under the MIT licence. The published index names the licence and the source in its manifest, every index names them in its meta table, and every result names its source page. Keep the attribution when you quote the documentation or pass an index on, share it only under the same licence, and do not use it commercially.
Metadata
Release files for jscdocs 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| jscdocs-0.2.0.tar.gz | 48.6 kB | Without provenance | Details for jscdocs-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| jscdocs-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for jscdocs-0.2.0-py3-none-any.whl |
Total release size: 108.0 kB
Release files / jscdocs-0.2.0.tar.gz
| Download URL | jscdocs-0.2.0.tar.gz |
|---|---|
| Size | 48.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a927952cdc7f7d1369c477266c26abc4b044183545edb301ae20d3c567f52c5b
|
|
BLAKE2b-256 checksum How to use checksums |
98c13507b2333283800a0f3c9b3f3b1795dcff3a6fb86bb30f3b5c6342fdf519
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / jscdocs-0.2.0-py3-none-any.whl
| Download URL | jscdocs-0.2.0-py3-none-any.whl |
|---|---|
| Size | 59.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
57294f64e257cd21b62b08dac8a9c2bb89d6a9285df473e519a66755f167ca49
|
|
BLAKE2b-256 checksum How to use checksums |
11ca774625574f0b0e9cb43e84917d0b43b876ea4603e1d72cab685d0984fd9a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for jscdocs 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.