# robosimtools-mcp

An [MCP](https://modelcontextprotocol.io) server that exposes
[robosimtools.com](https://robosimtools.com)'s 12 robotics/simulation tools to
AI agents. The tool logic here is the **same code robosimtools.com serves to
your browser** — vendored into `lib/` so this server is self-contained. All
computation is local; nothing is uploaded.

> This is the open-source MCP server for robosimtools.com. The website itself is
> a separate project; only the browser tools it already ships publicly are
> included here (see [Vendored modules](#vendored-modules)).

## Tools

| Tool | What it does |
|------|--------------|
| `robosim_convert_rotation` | Quaternion ↔ Euler (12 sequences) ↔ 3×3 matrix ↔ axis-angle ↔ URDF roll-pitch-yaw. |
| `robosim_dh_to_urdf` | Denavit-Hartenberg table → URDF joint chain (standard or modified/Craig). |
| `robosim_diff_ardupilot_params` | Diff two ArduPilot `.param` files; changed / added / removed. |
| `robosim_mesh_mass_properties` | STL/OBJ → mass, center of mass, full inertia tensor. |
| `robosim_validate_urdf` | Structural URDF validation — tree, inertia sanity, joint limits. |
| `robosim_inspect_urdf` | URDF → links, joints, kinematic roots, degrees of freedom. |
| `robosim_xacro_to_urdf` | Expand Xacro properties, macros, conditionals, includes → URDF. |
| `robosim_urdf_to_mjcf` | URDF → MuJoCo MJCF. |
| `robosim_sdf_to_urdf` | Gazebo SDF → URDF with correct relative joint origins. |
| `robosim_step_to_urdf` | STEP/IGES CAD → URDF with per-solid inertia (OCCT WASM kernel). |
| `robosim_generate_sbom` | Lockfile (npm/pip/cargo/go) → CycloneDX 1.6 SBOM. |
| `robosim_cra_readiness` | EU Cyber Resilience Act scoping wizard. |

Every tool is read-only with no side effects.

## Install

```bash
git clone https://github.com/RahulRajelli/robosimtools-mcp
cd robosimtools-mcp
npm install
```

## Use it

The server talks over stdio, so any client that supports local MCP servers
works. Replace the path below with wherever you cloned the repo.

### Claude Desktop

Add to `claude_desktop_config.json` and restart:

```json
{
  "mcpServers": {
    "robosimtools": {
      "command": "node",
      "args": ["ABSOLUTE/PATH/TO/robosimtools-mcp/src/index.js"]
    }
  }
}
```

### OpenAI Codex CLI

Add to `~/.codex/config.toml` and restart Codex:

```toml
[mcp_servers.robosimtools]
command = "node"
args = ["ABSOLUTE/PATH/TO/robosimtools-mcp/src/index.js"]
```

> ChatGPT's own connectors target **remote** (HTTP) MCP servers — for this
> local stdio server, use the Codex CLI or Claude Desktop.

Then ask, e.g.: *"Convert the quaternion (w=0.707, x=0, y=0, z=0.707) to URDF
roll-pitch-yaw"*, or *"Turn this STEP file into a URDF with computed inertia."*

## Test

```bash
npm test             # 39 known-answer checks across all 12 tools
npm run test:e2e     # connects a real MCP client over stdio
npm run test:install # packs, installs to a temp dir, drives the installed copy
```

`test:install` is the one that matters before a release: it verifies the *published* artifact —
that the `files` allowlist is complete, the `bin` shebang works, and the lazily-imported OCCT
WASM kernel still resolves once the package is inside someone else's `node_modules`.

## Vendored modules

`lib/` holds the tool logic — the same ES modules robosimtools.com serves at
`robosimtools.com/js/*.js`. They are vendored (not fetched at runtime) so the
package is self-contained. To refresh them from a local site checkout:

```bash
node scripts/sync-from-site.mjs /path/to/site/public/js
```

## Design notes

- **DOM in Node.** Four tools (URDF validator, Xacro, MJCF, SDF converters) use
  the browser `DOMParser`/`XMLSerializer`. `src/browser-globals.js` provides
  those via [linkedom](https://github.com/WebReflection/linkedom) so the modules
  run unchanged (its `XMLSerializer` strips the XML prolog linkedom adds, to
  match browsers).
- **CAD kernel.** `robosim_step_to_urdf` loads `occt-import-js` (a 7.6 MB WASM
  build of OpenCascade) lazily on first use.
- **Plain JS ESM**, zero build step.

## Contributing

Bug reports and PRs are welcome — see [CONTRIBUTING.md](./CONTRIBUTING.md) for scope, setup and
the AI-assisted contribution policy (disclosure required). Security issues go through
[SECURITY.md](./SECURITY.md), not the public issue tracker. Participation is governed by the
[Code of Conduct](./CODE_OF_CONDUCT.md).

One thing worth knowing up front: **`lib/` is synced from robosimtools.com and PRs editing it
directly will be closed** — the next sync overwrites them. Report tool-logic bugs as issues here
and they get fixed upstream, then synced down.

## License

[MIT](./LICENSE) © 2026 Rahul Rajelli. All code in `src/` and `lib/` is first-party.

The `robosim_step_to_urdf` tool depends on [`occt-import-js`](https://github.com/kovacsv/occt-import-js)
(a WASM build of Open CASCADE), which is **LGPL-2.1**. It is consumed unmodified as a separate npm
dependency and loaded dynamically at runtime — no part of it is redistributed in this package.
Full details, and the conditions a fork must preserve, are in
[THIRD-PARTY-NOTICES.md](./THIRD-PARTY-NOTICES.md).