ntopology-mcp

Сервер MCP для nTop (ранее nTopology), который напрямую читает и редактирует графы блоков блокнотов, запускает их в безголовом режиме через nTop Automate и измеряет получаемую геометрию.

nTop поставляет официальный MCP-сервер, и он решает другую задачу: он ищет в документации nTop. Этот же работает с вашими файлами. Они дополняют друг друга — их сервер отвечает на вопрос «как настроить топологическую оптимизацию», а этот настраивает её и запускает.

Документированный путь автоматизации (nTop Automate) предполагает, что вы вручную создаёте блокнот в графическом интерфейсе, выставляете несколько входов как переменные и изменяете их из скрипта. Это покрывает перебор параметров. Но это не позволяет добавить блок, переподключить вход или изменить структуру графа. Этот сервер делает это, рассматривая файл .ntop как то, чем он является: контейнер, содержащий JSON-граф блоков.

Инструменты

Related MCP server: Onshape MCP Server

Требования

• Установлен nTop. Проверено на 5.54.2 в Windows.

• Лицензия nTop Automate для run_notebook. Она лицензируется отдельно от места в графическом интерфейсе; всё остальное работает без неё.

• Node.js 20+ для запуска сервера. Тестовому набору нужен 21+, где node --test принимает глоб.

Установка

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_INSTALL_ROOT необязателен, если nTop находится в стандартном расположении Windows. 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

Инструменты редактирования проверяют перед записью и отказываются сохранять граф с ошибками, поэтому всё, что они создают, уже проверено. Запустите validate_graph на блокнотах, которые этот сервер не записывал — например, отредактированных в графическом интерфейсе nTop — прежде чем тратить минуты на run_notebook.

Формат блокнота

Формат .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 является литералом. Входы ссылаются на производящий блок по идентификатору, при этом 0 и -1 оба означают «не подключено».

Поведение, о котором стоит знать

Эти моменты стоят реального времени отладки и, где возможно, закодированы в validate_graph или в описаниях инструментов:

• Параметр list<T> должен питаться ровно одним блоком core.list<T>. Подключение двух неявных значений прямо в слот списка заставляет nTop отклонять весь файл при загрузке с общим сообщением «unable to load your file», не называя ничего. validate_graph ловит форму, которая возникает на практике: подключённые рёбра сверх объявленного количества параметров у блока, имеющего параметр list<T>.

• Лишние хвостовые неподключённые входные слоты — это нормально. nTop сам их создаёт, когда версия блока получает необязательный параметр, так что это не ошибка.

• plane<point,vector,vector> принимает начало координат и два вектора, которые натягивают плоскость. Нормаль — это их векторное произведение, а не второй аргумент.

• offset_implicit инвертирован относительно интуиции: положительное смещение разъедает. Скругление выпуклых рёбер (морфологическое открытие) — это offset(+r) затем offset(-r).

• Перечисление blend у boolean_union: 1 добавляет материал в месте соединения, 2 удаляет его, 0 — жёсткое объединение.

• Третий вход implicit_to_mesh v2.4.0 — это минимальный размер элемента. Установите его на 5 мм, и пластина толщиной 5 мм молча исчезнет.

• Суффикс версии имеет значение. Бинарные файлы содержат все исторические ревизии блока, но nTop регистрирует только текущую. Старая ревизия завершается с тем же сообщением «Unknown block … Toolkit or Connector that is not installed», что и нелицензированный набор инструментов, поэтому устаревшая сигнатура выглядит точно так же, как отсутствующая лицензия. 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, добавленный в список ограничений оптимизации. Вход Initial Density ничего не замораживает — nTop документирует его только как начальное предположение.

nTop поставляет собственные примеры — сначала читайте их

nTop устанавливает около 100 рабочих примеров блокнотов в C:\ProgramData\nTopology\documentation\ExtendedBlockDocs\ и полные HTML-справочные страницы в block-documentation\blocks\. 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.

Разработка

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» являются товарными знаками их соответствующего владельца.