Skip to content

README.md

Latest commit

 

History

History
90 lines (61 loc) · 6.36 KB

README.md

File metadata and controls

90 lines (61 loc) · 6.36 KB
Raw

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.

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.

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 18 or newer.
  • 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 C:\Users\<your-user>\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.

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, 3.8 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)

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
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)
  2. Build a Javadoc Search Tool (MCP Server)
  3. Find a Class, Read Its Real Page
  4. Trace a Macro from getActiveSimulation()
  5. Audit a Macro for Invented and Deprecated Calls
  6. Stress-Test a Grounded Macro Against a Recording

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

Tags: series1 marks the tree that corresponds to Part 2 of the first series.

Related

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.