Skip to main content
Glama
ntopology-mcp

ntopology-mcp

by sohumsuthar

ntopology-mcp

一个用于 nTop(原 nTopology)的 MCP 服务器,可直接读取和编辑笔记本块图,通过 nTop Automate 无头运行它们,并测量输出的几何体。

nTop 自带一个官方 MCP 服务器,它解决的是另一个问题:它搜索 nTop 的文档。本服务器操作的是你的文件。两者互补——前者回答"如何设置拓扑优化",后者则实际设置并运行一个。

文档化的自动化路径(nTop Automate)期望你在 GUI 中手工构建笔记本,将少量输入暴露为变量,并从脚本中改变这些变量。这覆盖了参数扫描。它不允许你添加块、重新接线输入或重构图形。本服务器可以做到,因为它把 .ntop 文件当作它本来的样子:一个包含 JSON 块图的容器。

工具

工具

描述

inspect_notebook

版本、节、块和值计数,以及根节点求值的内容

read_graph

带类型签名的块、接线和字面值;可过滤,默认 200

validate_graph

悬空输入、重复 id、缺失根节点、无值的字面量、超出 list<T> 参数的额外边

set_literal_value

更改标量、文件路径、向量、点、布尔值或枚举

set_input

重新接线块的一个输入槽

add_block

从类型签名添加计算块

add_literal

添加常量

prune_graph

将根节点指向选定的输出并丢弃所有不可达的内容

run_notebook

通过 ntopcl 执行,返回结构化错误、警告和逐块计时

search_blocks

搜索 nTop 安装中存在的块签名

mesh_stats

体积、面积、包围盒、开放边和非流形边计数、连通分量

set_output

选择 ntopcl -o 报告为笔记本输出的块

find_example

搜索 nTop 自带的示例笔记本和参考页面

environment

报告服务器在这台机器上能找到什么

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, content

main 节包含两个子项: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_mesh v2.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 搜索两者。示例笔记本可以在几秒钟内确定块的接线、字面量形状和属性路径,而从错误消息中逆向工程相同内容需要数小时。在猜测之前先检查那里。

字面值形状

字面值按类型存储,形状并不统一:

类型

值

real

{"isFinite":true,"units":{"length":1},"val":0.005}(SI——米)

point

三个此类对象的数组

text

{"string":"inlet"}——不是 {"val":...}

choice

{"choices":["Full Analysis","Potential Flow"],"selected":0}

file_path

{"val":"C:/path/to/file.step"}

unit_length_enum

{"id":"mm"}

错误的形状会在加载时失败,并出现 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 tools
add_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

    A3.7/5.0

    Scored across 14 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables building and modifying parametric solid models in a local SOLIDWORKS installation via the COM API.
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
      -