topsolid-automation-mcp

Community Model Context Protocol server for TopSolid® 7 — bring any MCP-compatible AI agent (Claude, ChatGPT-MCP clients, Cursor, Windsurf, JetBrains, VS Code + Copilot, OpenClaw, etc.) into your TopSolid workflow.

Community project. TopSolid® is a registered trademark of TOPSOLID SAS. This repository is an independent, community-maintained MCP server. It is not endorsed by, sponsored by, or affiliated with TOPSOLID SAS. It wraps the publicly documented TopSolid Automation API and indexes the publicly shipped help documentation. A valid TopSolid license is required to run it against a live TopSolid instance.

What is this?

An MCP server written in C# (.NET Framework 4.8) that exposes the TopSolid 7 Automation API as a set of 13 tools any MCP client can call. On top of the raw API, it ships with:

• 195 pre-built recipes — curated C# snippets for the most common CAD/PDM operations (read mass/volume, set designation, export STEP/DXF/PDF, activate BOM rows, detect drafting scale, ...), browsable with topsolid_list_recipes.
• A 4119-edge type graph of the API (1728 methods, 242 types), queryable by Dijkstra / BFS to discover method chains between any two types.
• A 5809-page help index (EN + FR) in SQLite FTS5 — ask your agent "how does the sheet-metal unfolding command work?" and get the official help excerpt.
• A 2428-command catalog — look up any ribbon/menu command by keyword, get its FullName ready to invoke.
• A dry-run compile check — the script is compiled against the TopSolid assemblies without being run, so hallucinated APIs and syntax errors surface before execution. It uses CSharpCodeProvider (the csc compiler bundled with the .NET Framework), not Roslyn: generated snippets are therefore compiled as C# 5, which is why string interpolation ($"...") is rejected everywhere in generated code.
• Corpus search over local user-provided C# examples (paths configured locally, never shipped).

Plus a native HTTP endpoint for remote clients (claude.ai web, mobile apps, server-side agents) — Streamable HTTP (MCP spec 2025-03-26) on port 8080, X-API-Key protected, Origin-validated, no Node.js required.

Quick start

Prerequisites

• Windows 10/11
• TopSolid 7.15+ (tested on 7.20 / 7.21)
• An MCP client: Claude Code, Claude Desktop, Cursor, Windsurf, VS Code + Copilot...

Install

The easy way (v1.8.0+) — one double-click, no terminal, no Node.js:

1. Download the latest release and unzip it.
2. Double-click install\Installer_TopSolidMCP.bat — it generates the API key (DPAPI-encrypted in settings.json), creates the scheduled task that auto-starts the native server on port 8080, and cleans up any legacy v1.7 Node bridge.
3. A tray icon appears next to the clock: one process serves stdio and native HTTP. Right-click for Status / Restart / Stop / API key.

Since v1.8.0 the tray also handles:

• API key management — generate / copy / regenerate / revoke the X-API-Key of the native HTTP endpoint (stored DPAPI-encrypted in settings.json, never in clear).
• Auto-connect — reconnects to TopSolid by itself (backoff 15/30/60 s capped) if TopSolid was started after the server or gets restarted.
• What's new — opens the GitHub release notes of the installed version; the update flow now opens them automatically.
• Report a bug / Suggest a feature — prefilled GitHub issue (template, version, OS and connection state auto-injected; API key scrubbed).

Then point your MCP client at http://127.0.0.1:8080/mcp (v1.8.0+: the native endpoint, X-API-Key required as soon as a key is defined). Details: install/README.md.

The native endpoint validates the Origin header per the MCP HTTP transport spec (DNS-rebinding defense): no Origin (CLI/MCP clients) and localhost/127.0.0.1/[::1] origins are allowed, any other host is rejected with HTTP 403; extra origins can be whitelisted with the TOPSOLID_MCP_ALLOWED_ORIGINS environment variable.

Manual path (developers / headless machines):

1. Enable remote access in TopSolid: Tools > Options > General > Automation → check "Manage remote access", port 8090, restart TopSolid.

2. Download the latest release (TopSolidMcpServer-vX.Y.Z.zip) and unzip to e.g. C:\TopSolidMCP\.

3. Register with your client. For Claude Code CLI:

   claude mcp add --scope user topsolid C:\TopSolidMCP\TopSolidMcpServer.exe
   

Full per-client setup (Claude Desktop, Cursor, Windsurf, JetBrains, VS Code, Antigravity, Continue, OpenClaw...) is in the integration guide.

First call

In your AI assistant, ask:

Read the designation of the open TopSolid document.

The agent picks topsolid_run_recipe with recipe read_designation and returns the result.

The 13 MCP tools

Security: do not auto-approve the script tools

topsolid_execute_script and topsolid_modify_script are not sandboxed, and "read-only" in this project has only ever meant outside a TopSolid modification transaction — it is not a permission level.

Both tools compile the C# they are handed and run it in-process, fully trusted, on your workstation. System.IO is available (export recipes need it), so a script can read and write files anywhere your user account can. A deny-list rejects a handful of symbols before compilation (System.Diagnostics.Process, System.Net, System.Reflection, DllImport, File.Delete, Directory.Delete, registry access, Environment.Exit); it is a guardrail against an LLM wandering off, not a security boundary, and TOPSOLID_MCP_ALLOW_UNSAFE=1 removes it entirely.

Practical consequences:

• Do not add topsolid_execute_script or topsolid_modify_script to the auto-approved / always-allow tool list of your MCP client. Read each script before you let it run.
• Run the server with --read-only (or TOPSOLID_MCP_READ_ONLY=1) when you only need to query: topsolid_modify_script is then not registered at all, and recipes run in read-only mode.
• Do not expose the HTTP endpoint publicly without authentication — see the HTTP guide.

Data sources & attribution

All the knowledge this server exposes comes from publicly available TopSolid material:

• API graph (4119 edges, 1728 methods) — extracted by reflection from the TopSolid Automation .dll assemblies shipped with every TopSolid installation, cross-referenced with the official API reference at help.topsolid.com.
• Help index (5809 pages, EN + FR) — converted to Markdown from the publicly shipped help site at help.topsolid.com.
• UI commands catalog (2428 commands) — parsed from those same help pages (files ending in *Command.md).
• Recipes (195 C# snippets) — hand-written for this project, referring back to the public help and the graph for each API call.

No proprietary TopSolid SDK sample code, no customer project, and no identified individual's private code is included in anything that ships with this repo. Private corpora support (topsolid_search_examples) is opt-in via environment variables on the user's own machine — nothing is ever bundled.

Why this exists

TopSolid ships a powerful .NET Automation API, but it is hard to discover: 1728 methods across 46 interfaces, ~10-20% of the product surface is only reachable via ribbon/menu commands, and half the "how do I..." answers are in help pages no one reads. This server collapses that discovery cost for an AI agent — and for a human developer who treats the MCP as a knowledge base for writing standalone TopSolid Automation apps.

Repository layout

topsolid-automation-mcp/
├── server/        TopSolid MCP Server (.NET 4.8, stdio + native HTTP, 2 transports, 1 process)
│   ├── src/       Program.cs, Protocol/, Tools/, Utils/
│   ├── data/      Data shipped next to the .exe: graph.json, help.db,
│   │              commands-catalog.json, recipe-list.txt, recipes.md
│   ├── scripts/   build-release.ps1, update.ps1, sync-topsolid-api.py
│   └── models/    Ollama Modelfile for the local code sub-agent
├── graph/         API graph builder (.NET 4.8, reflection-based)
├── bridge/        Legacy HTTP/SSE bridge (v1.7, superseded by the native endpoint — kept for migration)
├── scripts/       Graph enrichment, help index, commands catalog, privacy scan (Python)
├── data/          Build-time artefacts: graph.json, api-index.json,
│                  recipe-name-mapping-fr-en.json, recipes.md
├── docs/          VitePress documentation site
├── tests/         Automated test harness (C# runner + PowerShell scripts)
└── skills/        Optional skill package for MCP-aware agents

server/data/ is what gets packaged into the release zip and read at runtime (help.db in particular lives there, not in the top-level data/).

Contributing

Read CONTRIBUTING.md. Short version: pick up a good-first-issue, add a recipe to server/src/Tools/RecipeTool.cs, or improve the docs. Every PR helps.

All interactions are governed by our Code of Conduct.

License

MIT. Use commercially, fork, modify freely. TopSolid itself is proprietary — you need your own license from TOPSOLID SAS to run this against a live TopSolid instance.