Skip to main content
Glama
starccm-javadoc-mcp

starccm-javadoc-mcp

by pacoEzq
README.md
# starccm-javadoc-mcp

A small MCP server that lets an AI assistant search and read the Simcenter STAR-CCM+ Java API documentation (Javadoc) that ships with your own installation, so the macros it writes use real, current API calls instead of invented ones. Two tools, `search_api` and `get_doc`, plus the instruments used to measure and reduce what the server costs in tokens.

This repository accompanies two tutorial series published on the Siemens Simcenter community forum. The forum renders client side and is hard to index; this README is the indexable table of contents.

Latest change: an optional API notebook that survives context compaction, described [below](#optional-an-api-notebook-that-survives-compaction).

Everything that changed since the `series1` tag is in [CHANGELOG.md](CHANGELOG.md).

## What it does

`search_api` finds a class, interface, method or field by name in the Javadoc search index and returns the path to its page. `get_doc` returns that page as plain text: the class description and the Method Summary with exact signatures and any Deprecated tag. The AI asks, reads, then writes. Nothing is recited from memory.

**Limitation.** Members are listed only under the class that declares them, not under subclasses that inherit them, so a missing subclass in the results does not mean the method is unavailable there; `get_doc` on the subclass page lists its inherited members and their declaring classes. Measured on STAR-CCM+ 2606, 267 of 794 API calls (33.6 %) in 10 GUI recordings and 5 generated macros use a method that `search_api` does not list under the receiver's class ([issue #1](https://github.com/pacoEzq/starccm-javadoc-mcp/issues/1)). Indexing inherited members is tracked in [issue #2](https://github.com/pacoEzq/starccm-javadoc-mcp/issues/2).

The Javadoc itself is not in this repository and never will be. It is Siemens documentation that ships with STAR-CCM+; the server reads it from a folder on your machine.

## Requirements

- Simcenter STAR-CCM+ with its Javadoc (typically under `<STAR-CCM+ install>\doc\...\client\html`). Measured against 2606 Build 21.04.007; the tool reads any modern Javadoc that ships `type-search-index.js` and `member-search-index.js`.
- Node.js 22.23.4 or newer on the 22 line, or 24.22.1 or newer on the 24 line (18 and 20 are end-of-life).
- Claude Code CLI (the server is registered with `claude mcp add`). Any MCP client that speaks stdio should work; only Claude Code has been tested.

## Setup in five steps

1. Copy the Javadoc folder to a path without spaces, for example `<your-folder>\ccmp\html`. Keep the whole folder, including the `*-search-index.js` files.
2. Clone this repository and install its two dependencies: `npm install`.
3. Register the server with Claude Code:

   ```
   claude mcp add --scope user starccm -- cmd /c node <path-to-repo>\server.mjs <path-to-javadoc>
   ```

   On macOS or Linux drop the `cmd /c` wrapper.
4. Check with `claude mcp list` that `starccm` shows as connected.
5. In a Claude Code session, ask: `use search_api to find RegionManager`, then `use get_doc on star/common/RegionManager.html`.

Step by step, with the Windows pitfalls (the MSIX build of Claude Desktop silently ignores local MCP servers; PowerShell blocks `npx.ps1`; a cold `npx` start times out), see Part 2 of the first series below.

## Optional: an API notebook that survives compaction

When a long Claude Code session compacts its context, the model forgets which classes and methods it already looked up and fetches them again. Set `STARCCM_MCP_CUADERNO` (*cuaderno* is Spanish for notebook) to a folder and the server keeps one notebook file per project there: one line per class and method the session looked up, with its signature, return type and first sentence, or `No.` when the class does not have it. A fixed core of seven common pairs (`lib/cuaderno-nucleo.txt`) goes first; the rest is capped at 4,000 characters, oldest lines dropped first. The notebook never changes what `search_api` or `get_doc` return. Without the variable it does nothing.

Register the server with the variable:

```
claude mcp add --scope user --env STARCCM_MCP_CUADERNO=<notebook-folder> starccm -- cmd /c node <path-to-repo>\server.mjs <path-to-javadoc>
```

Then add a `SessionStart` hook with matcher `compact` to your Claude Code user settings, so the notebook is read back in after each compaction:

```json
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          { "type": "command", "command": "node <path-to-repo>/tools/cuaderno-hook.mjs <notebook-folder>" }
        ]
      }
    ]
  }
}
```

## Measured cost

All figures were measured on the reference machine (STAR-CCM+ 2606 Build 21.04.007, Node v20.14.0) in August 2026 with the instruments in `tools/`. The raw custody files live in `tok/` and `bench/`; the aggregated numbers and their provenance are in `bench/README.md`.

| What | Value |
|---|---|
| Class pages in the Javadoc | 23,498 |
| Extracted text per page, median | 5,587 characters |
| Extracted text per page, 99th percentile | 19,854 characters |
| Pages above 20,000 characters | 224 (0.95%) before whitespace collapse, 144 after |
| Pages above 50,000 characters (the current default cap) | 11 after collapse |
| `star.common.Simulation`: raw HTML / extracted text / `javap -public` | 201,275 / 29,981 / 7,920 characters |
| Cost of grounding one class through `search_api` + `get_doc` | 33,316 characters before whitespace collapse, 4.2 times `javap` |
| Effect of whitespace collapse on the benchmark, in tokens | 10 to 12% fewer |
| Characters per token, corpus wide, after collapse | 4.996 (`o200k_base`), 4.621 (Anthropic legacy tokenizer) |

### What the 1.1 changes save

Two measurements, made in November 2026 on the same machine and the same Javadoc. Each runs a fixed set of questions through the server as it was before 1.1 and through a build with the 1.1 changes, and counts the characters the assistant has to read. The two sets ask different things, so their results are given separately and never averaged.

| Question set | Before 1.1 | With 1.1 | Fewer characters |
|---|---|---|---|
| The Part 4 benchmark: find a class and read its whole page (15 questions) | 439,414 | 420,075 | 4.4% |
| Find the signature of one method in a given class (16 questions) | 281,576 in 32 calls | 4,107 in 16 calls | 98.5% |

Why the two figures are so far apart. The first set makes both servers do the same work: look up the class, then read its full page. The only difference is that the newer server returns lighter pages, without the side index that lists the page's own sections a second time, and that is worth 4.4%. The second set lets each server reach the method by its shortest route. The older one has to open the class page and read it, tens of thousands of characters, to find one line. The newer one answers a query such as `Simulation getRegionManager` with one line from its index, and the page is never opened. Both found all 16 methods.

That one line is the method name with its parameters. It does not include the return type or the description. When the assistant needs those, it still reads the page, and the cost moves back towards the first figure. Real sessions fall somewhere between the two numbers, depending on how often the name and parameters are enough.

## Layout

```
server.mjs              the MCP server: search_api and get_doc
lib/extract.mjs         HTML to text extraction used by get_doc and by every instrument
lib/resumen.mjs         minimal summary of a class page (methods, signatures, inherited members)
lib/cuaderno*           the optional API notebook (off unless STARCCM_MCP_CUADERNO is set)
tools/cuaderno-hook.mjs SessionStart hook that reads the notebook back in after compaction
tools/                  measurement instruments (token factor, corpus sweep, collapse guards)
sweep-corpus-*.mjs      corpus characterisation sweeps, one per criterion revision
tok/                    custody files: measured outputs and the acceptance criteria that certify them
bench/                  the Part 4 benchmark: plan, per query results, summaries
tools/publish-list.txt  the list of files derived from the private working repository
```

Every instrument that publishes a figure checks the STAR-CCM+ version and the Javadoc root before writing, and reproduces its own custody file byte for byte. The acceptance criteria are in `tok/esperados-*.md`, in Spanish: they are working documents, kept as they were written.

## The two tutorial series

**Simcenter STAR-CCM+ Macros with AI** (6 parts, published). Builds this server and uses it.

1. [Why AI Invents the API (and the Fix)](https://community.sw.siemens.com/s/question/0D5Vb00001LZ5ReKAL/simcenter-starccm-macros-with-ai-16-why-ai-invents-the-api-and-the-fix)
2. [Build a Javadoc Search Tool (MCP Server)](https://community.sw.siemens.com/s/question/0D5Vb00001LiDTCKA3/simcenter-starccm-macros-with-ai-26-build-a-javadoc-search-tool-mcp-server)
3. [Find a Class, Read Its Real Page](https://community.sw.siemens.com/s/question/0D5Vb00001ME3gzKAD/simcenter-starccm-macros-with-ai-36-find-a-class-read-its-real-page)
4. [Trace a Macro from getActiveSimulation()](https://community.sw.siemens.com/s/question/0D5Vb00001McZcIKAV/simcenter-starccm-macros-with-ai-46-trace-a-macro-from-getactivesimulation)
5. [Audit a Macro for Invented and Deprecated Calls](https://community.sw.siemens.com/s/question/0D5Vb00001MkZ4UKAV/simcenter-starccm-macros-with-ai-56-audit-a-macro-for-invented-deprecated-calls)
6. [Stress-Test a Grounded Macro Against a Recording](https://community.sw.siemens.com/s/question/0D5Vb00001NKFrkKAH/simcenter-starccm-macros-with-ai-66-stresstest-a-grounded-macro-against-a-recording)

**Simcenter STAR-CCM+ Agentic Macros** (7 parts, 1 published). Adds a compile loop, a batch runner and the token economy work whose "before" numbers are the table above. Each part lands here as a tag.

1. [Compile by Hand, Read the Real Errors](https://community.sw.siemens.com/s/question/0D5Vb00001gGHQnKAO/simcenter-starccm-agentic-macros-17-compile-by-hand-read-the-real-errors)

Tags: `series1` marks the tree that corresponds to Part 2 of the first series; `agentic1` marks the tree that Part 1 of the second series links to.

## Related

[simulation-capsule](https://github.com/pacoEzq/simulation-capsule) (same author) is the other half of the idea: this repository teaches a model to write a simulation, that one teaches it to read the results.

## A note on AI generated macros

Grounding confirms that every API call is real and current for your version. It does not confirm that a macro does what you meant, that its arguments are right, or that the physics is right. Treat AI output as a draft: review and test it before you rely on it. Use of Siemens documentation and AI tools remains subject to your applicable Siemens terms.

## License

BSD-3-Clause. See `LICENSE`.