ntopology-mcp
ntopology-mcp
一个用于 nTop(原 nTopology)的 MCP 服务器,可直接读取和编辑笔记本块图,通过 nTop Automate 无头运行它们,并测量输出的几何体。
nTop 自带一个官方 MCP 服务器,它解决的是另一个问题:它搜索 nTop 的文档。本服务器操作的是你的文件。两者互补——前者回答"如何设置拓扑优化",后者则实际设置并运行一个。
文档化的自动化路径(nTop Automate)期望你在 GUI 中手工构建笔记本,将少量输入暴露为变量,并从脚本中改变这些变量。这覆盖了参数扫描。它不允许你添加块、重新接线输入或重构图形。本服务器可以做到,因为它把 .ntop 文件当作它本来的样子:一个包含 JSON 块图的容器。
工具
工具 | 描述 |
| 版本、节、块和值计数,以及根节点求值的内容 |
| 带类型签名的块、接线和字面值;可过滤,默认 200 |
| 悬空输入、重复 id、缺失根节点、无值的字面量、超出 |
| 更改标量、文件路径、向量、点、布尔值或枚举 |
| 重新接线块的一个输入槽 |
| 从类型签名添加计算块 |
| 添加常量 |
| 将根节点指向选定的输出并丢弃所有不可达的内容 |
| 通过 |
| 搜索 nTop 安装中存在的块签名 |
| 体积、面积、包围盒、开放边和非流形边计数、连通分量 |
| 选择 |
| 搜索 nTop 自带的示例笔记本和参考页面 |
| 报告服务器在这台机器上能找到什么 |
Related MCP server: Onshape MCP Server
要求
已安装 nTop。已在 Windows 上针对 5.54.2 验证。
run_notebook需要 nTop Automate 许可证。这与 GUI 席位分开授权;其他一切无需它即可工作。Node.js 20+ 用于运行服务器。测试套件需要 21+,其中
node --test接受 glob。
安装
git clone https://github.com/sohumsuthar/ntopology-mcp.git
cd ntopology-mcp
npm install
npm run build配置
添加到你的 MCP 客户端配置:
{
"mcpServers": {
"ntopology": {
"command": "node",
"args": ["C:\\path\\to\\ntopology-mcp\\dist\\index.js"],
"env": {
"NTOP_INSTALL_ROOT": "C:\\Program Files\\nTopology\\nTopology"
}
}
}
}如果 nTop 位于默认的 Windows 位置,NTOP_INSTALL_ROOT 是可选的。NTOPCL_PATH 可以直接指向 ntopcl.exe。先调用 environment 以确认服务器找到了什么。
示例
将现有优化重新定向到不同的设计空间,将其缩减为一条输出链,然后运行:
read_graph notebook=bracket.ntop filter=file_path
set_literal_value notebook=bracket.ntop blockId=477 value={"val": "C:/parts/wedge.step"}
prune_graph notebook=bracket.ntop rootInputs=[900] output=bracket_run.ntop
run_notebook notebook=bracket_run.ntop
mesh_stats path=C:/parts/result.stl listComponents=true编辑工具在写入前会进行验证,并拒绝保存有错误的图形,因此它们产生的任何内容都已检查过。在花费数分钟运行 run_notebook 之前,请对非本服务器写入的笔记本(例如在 nTop GUI 中编辑的)运行 validate_graph。
笔记本格式
.ntop 格式未经 nTop 文档化。以下内容是通过检查 5.54.2 写入的文件推导出来的,解析器通过逐字节往返真实笔记本得到验证。
file : "MAGIC%$1" u64 sectionCount u64 reserved
sectionCount * { name[16], u64 endOffset }
80 zero bytes, then sections laid out in table order
section : "MAGIC@@9" type[16] name[16] u64 contentLength 80 zero bytes, contentmain 节包含两个子项:fn,即块图(JSON 格式),以及 leaves,一个对象容器,其 index 节承载每个字面值。具有非空 func 的块计算某些内容;具有空 func 的块是字面量。输入通过 id 引用产生块,0 和 -1 都表示未连接。
值得了解的行为
这些会耗费实际的调试时间,并尽可能编码在 validate_graph 或工具描述中:
list<T>参数必须由恰好一个core.list<T>块提供。将两个隐式直接接入列表槽会使 nTop 在加载时拒绝整个文件,并给出通用的"无法加载您的文件",不指明任何内容。validate_graph捕获实践中产生的这种形式:在具有list<T>参数的块上,超出声明参数数量的已连接边。多余的尾部未连接输入槽是正常的。当块版本获得可选参数时,nTop 自己会发出这些,因此它们不是错误。
plane<point,vector,vector>接受一个原点和两个张成平面的向量。法线是它们的叉积,而不是第二个参数。offset_implicit与直觉相反:正偏移会侵蚀。对凸边进行圆角处理(形态学开运算)是offset(+r)然后offset(-r)。boolean_union的混合枚举:1在接合处添加材料,2移除材料,0是硬并集。implicit_to_meshv2.4.0 的第三个输入是最小特征尺寸。将其设置为 5 mm,5 mm 的板会静默消失。版本后缀至关重要。 二进制文件包含块的每个历史修订版,但 nTop 只注册当前版本。旧修订版会失败,并出现与未授权工具包相同的"未知块 … 未安装的 Toolkit 或 Connector"消息,因此过时的签名看起来与缺失许可证完全一样。
search_blocks首先返回名称的最新修订版;优先使用它,并对裸的无版本形式保持怀疑。未连接的输入是
-1(Empty),而不是0(None)。在必需输入上使用0会使 nTop 拒绝加载文件。但-1也不是普遍安全的:某些可选输入会以Input at N is Empty but optional拒绝它,必须提供字面量。匹配周围笔记本已有的做法,让validate_graph和试运行解决其余问题。ntopcl -o报告图形自身output键命名的块,set_output设置该键。根组的输入不是笔记本输出;没有set_output,你会得到Output path specified, but can't find output in notebook.暴露时间序列的结果块从 1 开始索引,步骤 1 通常是非物理的初始化而不是答案。读取它会产生看似合理但无错误的胡说八道。
在优化期间保留区域使用
passive_region_constraint<region>,由fe_region_by_implicit提供,添加到优化约束列表中。初始密度输入不会冻结任何内容——nTop 将其文档化为仅作为起始猜测。
nTop 自带示例——先读它们
nTop 在 C:\ProgramData Topology\documentation\ExtendedBlockDocs\ 安装了大约 100 个工作示例笔记本,并在 block-documentationlocks\ 下安装了完整的 HTML 参考页面。find_example 搜索两者。示例笔记本可以在几秒钟内确定块的接线、字面量形状和属性路径,而从错误消息中逆向工程相同内容需要数小时。在猜测之前先检查那里。
字面值形状
字面值按类型存储,形状并不统一:
类型 | 值 |
|
|
| 三个此类对象的数组 |
|
|
|
|
|
|
|
|
错误的形状会在加载时失败,并出现 Leaf failed to deserialize with block/variable <name>。
块签名
nTop 将其块签名以 ASCII 字符串形式存储在自己的二进制文件中,包括不再注册的修订版。search_blocks 在运行时从你的安装中提取它们,并将每个名称的最新修订版排在前面。本仓库不包含任何签名数据——签名是 nTop 的,本服务器从你获得许可的安装中读取它们,而不是重新分发。
限制
容器格式是逆向工程的,仅针对 nTop 5.54.2 验证。
inspect_notebook报告每个文件记录的版本;将其他版本视为未验证并保留备份。编辑工具就地写入,除非你传递
output。它们拒绝写入未通过验证的图形,但它们无法知道编辑对你的模型在语义上是否正确。run_notebook需要 nTop Automate 许可证。没有它,ntopcl在登录后退出,错误会被呈现出来。实际上仅限 Windows,因为 nTop 在 Windows 上运行。
开发
npm run check # type-check src and test
npm test # build, then run the test suite
npm run format:check # Prettier is enforced by config, not by CI测试是自包含的,不需要 nTop。两个套件在给定更多内容时会扩展:
NTOP_TEST_NOTEBOOKS——分号分隔的.ntop路径,逐字节往返。这取决于你提供的路径,而不是 nTop 是否安装。仓库不附带笔记本,因此上述往返声明你应该针对自己的文件重新验证,而不是轻信。目录套件在找到真实安装时扫描它,否则跳过。
许可证
MIT——参见 LICENSE。
与 nTop 无关联,也未获得其认可。"nTop" 和 "nTopology" 是其各自所有者的商标。
Available Tools
14 toolsadd_blockA
Add a computed block. Give the full typed signature from search_blocks. Inputs are source block ids in parameter order; use 0 for an unconnected optional input. A list parameter takes exactly one core.list block.
Inputs: func (required), name (required), type (required), inputs (required), +3 more.
add_literalC
Add a literal block holding a constant. Value shape follows nTop: a length scalar is {"isFinite":true,"units":{"length":1},"val":0.005} in metres, a point is an array of three such objects, an enum is {"enum":0}.
Inputs: name (required), type (required), value (required), notebook (required), +2 more.
environmentB
Report whether ntopcl and an nTop installation were found, and how many block signatures are visible.
Inputs: no named parameters.
find_exampleA
Search nTop's own shipped documentation for a block: working example notebooks and HTML reference pages. Consult this BEFORE reverse-engineering a block's wiring - nTop ships 100+ example .ntop files that show the correct inputs, literal shapes and property paths.
Inputs: query (required), documentationRoot.
inspect_notebookA
Summarise a .ntop notebook: nTop version it was written by, its sections, how many blocks and literal values it holds, and what the root block evaluates.
Inputs: notebook (required).
mesh_statsA
Measure an STL: volume, surface area, bounding box, watertightness and connected components. Use this to check what a notebook actually produced.
Inputs: path (required), listComponents.
prune_graphA
Point the root block at the given outputs and drop every block no longer reachable. Use this to cut a large notebook down to one chain before running it.
Inputs: notebook (required), rootInputs (required), output.
read_graphA
List the blocks in a notebook with their typed signatures, wiring and literal values. Use filter to narrow by block name or signature.
Inputs: notebook (required), limit, filter.
run_notebookB
Execute a notebook headlessly through nTop Automate (ntopcl) and return its errors, warnings and per-block timings. Requires an nTop Automate licence.
Inputs: notebook (required), save, timeoutMs, inputsJson, +1 more.
search_blocksA
Search the block signatures present in the installed nTop binaries. Returns the exact typed signature strings that add_block needs, newest revision of each name first. The binaries retain retired revisions, and nTop rejects those with the same error it gives an unlicensed toolkit - so prefer the highest [version] and distrust a bare unversioned form.
Inputs: query (required), limit, installRoot.
set_inputA
Rewire one input slot of a block to a different source block. Use 0 to disconnect.
Inputs: slot (required), blockId (required), notebook (required), sourceId (required), +1 more.
set_literal_valueC
Set the value of a literal block - a scalar, file path, vector, point, boolean or enum. Writes in place unless output is given.
Inputs: value (required), blockId (required), notebook (required), output.
set_outputA
Choose which block ntopcl reports as the notebook output. Required before run_notebook's outputJson will produce anything - nTop reads the graph's own output key, not the root group's inputs, and answers "can't find output in notebook" when it is unset. Pass -1 to clear.
Inputs: blockId (required), notebook (required), output.
validate_graphA
Check a notebook for problems that stop it loading or building: dangling inputs, duplicate ids, literals with no value, and list parameters wired with several inline edges instead of a core.list block.
Inputs: notebook (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Each tool has a clearly distinct purpose: adding literals vs. setting their values, reading the graph vs. inspecting the notebook, validating vs. running, searching blocks vs. finding examples. No two tools appear to do the same thing, so an agent can reliably pick the right one.
The vast majority of tools follow a consistent verb_noun snake_case pattern (add_literal, search_blocks, set_output). Two exceptions break the pattern: 'mesh_stats' is a noun_noun compound and 'environment' is a bare noun, which slightly reduces predictability but does not cause real confusion.
14 tools is well within the sweet spot for a domain-specific server. Each tool addresses a distinct step in the notebook lifecycle—inspection, editing, validation, execution, and analysis—earning its place without bloat or obvious omission.
The tool surface covers the core workflow: read/inspect/validate, add and modify blocks/literals, rewire inputs, set outputs, run, and check results. Minor gaps exist (e.g., no explicit block deletion, no direct 'save notebook' tool), but existing tools like prune_graph and set_input can work around these without agent failure.
Maintenance
Related MCP Connectors
Control Unreal Engine to browse assets, import content, and manage levels and sequences. Automate…
Manage SysML2 projects; check, evaluate, verify, query, document and diagram models.
Geometry and CAD file metadata extraction for STL, OBJ, PLY, PCD, LAS/LAZ, glTF/GLB.
Formula-backed WorkPaper tools for workbook readback, input edits, and JSON persistence.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables automated control of Ansys Workbench, Mechanical, and MAPDL through scripted journals and batch processing for simulation workflows.111MIT
- FlicenseNot gradedqualityDmaintenanceEnables programmatic CAD modeling with Onshape through document discovery, parametric sketching, feature management, and gear creation.-
- AlicenseNot gradedqualityDmaintenanceEnables building and modifying parametric solid models in a local SOLIDWORKS installation via the COM API.MIT
- FlicenseNot gradedqualityBmaintenanceEnables control of a live SOLIDWORKS session through the Windows COM API, providing native sketch, feature, body, reference-geometry, view, probe, and export operations, along with transactional CAD plans, parametric sketches, multibody tools, and deterministic raster-to-sketch vectorization pipelines.1-