ntopology-mcp

Un servidor MCP para nTop (anteriormente nTopology) que lee y edita gráficos de bloques de cuadernos directamente, los ejecuta sin interfaz gráfica a través de nTop Automate y mide la geometría resultante.

nTop incluye un servidor MCP oficial y resuelve un problema diferente: busca en la documentación de nTop. Este opera sobre tus archivos. Ambos son complementarios: el suyo responde "cómo configuraría una optimización topológica", este la configura y la ejecuta.

La ruta de automatización documentada (nTop Automate) espera que construyas un cuaderno a mano en la interfaz gráfica, expongas algunas entradas como variables y varíes esas desde un script. Eso cubre barridos de parámetros. No te permite añadir un bloque, recablear una entrada o reestructurar un gráfico. Este servidor lo hace, tratando el archivo .ntop como lo que es: un contenedor que alberga un gráfico de bloques JSON.

Herramientas

Related MCP server: Onshape MCP Server

Requisitos

• nTop instalado. Verificado contra 5.54.2 en Windows.

• Licencia de nTop Automate para run_notebook. Esta se licencia por separado del asiento de la interfaz gráfica; todo lo demás funciona sin ella.

• Node.js 20+ para ejecutar el servidor. El conjunto de pruebas necesita 21+, donde node --test acepta un glob.

Instalación

git clone https://github.com/sohumsuthar/ntopology-mcp.git
cd ntopology-mcp
npm install
npm run build

Configuración

Añade a la configuración de tu cliente 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 es opcional si nTop está en la ubicación predeterminada de Windows. NTOPCL_PATH puede apuntar directamente a ntopcl.exe. Llama a environment primero para confirmar lo que el servidor encontró.

Ejemplo

Reorientar una optimización existente hacia un espacio de diseño diferente, reducirla a una sola cadena de salida y ejecutarla:

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

Las herramientas de edición validan antes de escribir y se niegan a guardar un gráfico con errores, por lo que cualquier cosa que produzcan ya está verificada. Ejecuta validate_graph en cuadernos que este servidor no escribió — por ejemplo, uno editado en la interfaz gráfica de nTop — antes de dedicar minutos a run_notebook.

El formato del cuaderno

El formato .ntop no está documentado por nTop. Lo siguiente se derivó inspeccionando archivos escritos por 5.54.2, y el analizador se verifica haciendo un viaje de ida y vuelta con cuadernos reales byte por byte.

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

La sección main contiene dos hijos: fn, el gráfico de bloques como JSON, y leaves, un contenedor de objetos cuya sección index lleva cada valor literal. Un bloque con un func no vacío calcula algo; un bloque con un func vacío es un literal. Las entradas referencian el bloque productor por id, con 0 y -1 ambos significando no conectado.

Comportamiento que vale la pena conocer

Estos cuestan tiempo real de depuración y están codificados en validate_graph o en las descripciones de las herramientas cuando es posible:

• Un parámetro list<T> debe ser alimentado por exactamente un bloque core.list<T>. Cablear dos implícitos directamente en la ranura de lista hace que nTop rechace el archivo completo al cargarlo con un error genérico "unable to load your file", sin nombrar nada. validate_graph detecta la forma que esto produce en la práctica: aristas conectadas más allá del recuento de parámetros declarado en un bloque que tiene un parámetro list<T>.

• Las ranuras de entrada adicionales no conectadas al final son normales. nTop las emite por sí mismo cuando una versión de bloque gana un parámetro opcional, por lo que no son un error.

• plane<point,vector,vector> toma un origen y dos vectores que abarcan el plano. La normal es su producto cruzado, no el segundo argumento.

• offset_implicit está invertido respecto a la intuición: un desplazamiento positivo erosiona. Redondear bordes convexos (una apertura morfológica) es offset(+r) seguido de offset(-r).

• El enumerado de mezcla de boolean_union: 1 añade material en la unión, 2 lo elimina, 0 es una unión dura.

• La tercera entrada de implicit_to_mesh v2.4.0 es el Tamaño Mínimo de Característica. Configúralo a 5 mm y una placa de 5 mm desaparece silenciosamente.

• El sufijo de versión es crucial. Los binarios contienen cada revisión histórica de un bloque, pero nTop solo registra la actual. Una revisión antigua falla con el mismo mensaje "Unknown block … Toolkit or Connector that is not installed" que un toolkit sin licencia, por lo que una firma obsoleta se ve exactamente como una licencia faltante. search_blocks devuelve la revisión más nueva de un nombre primero; prefierela y trata con sospecha una forma sin versión.

• Una entrada no conectada es -1 (Vacío), no 0 (Ninguno). 0 en una entrada requerida hace que nTop se niegue a cargar el archivo. Pero -1 tampoco es universalmente seguro: algunas entradas opcionales lo rechazan con Input at N is Empty but optional y deben recibir un literal. Iguala lo que el cuaderno circundante ya hace y deja que validate_graph y una ejecución de prueba resuelvan el resto.

• ntopcl -o informa el bloque nombrado por la clave output del propio gráfico, que set_output establece. Las entradas del grupo raíz no son salidas del cuaderno; sin set_output obtienes Output path specified, but can't find output in notebook.

• Los bloques de resultado que exponen series temporales están indexados desde 1, y el paso 1 a menudo es una inicialización no física en lugar de la respuesta. Leerlo produce tonterías de aspecto plausible sin error.

• Preservar una región durante la optimización usa passive_region_constraint<region> alimentado por fe_region_by_implicit, añadido a la lista de restricciones de optimización. La entrada Densidad Inicial no congela nada — nTop lo documenta como una suposición inicial solamente.

nTop incluye sus propios ejemplos: léelos primero

nTop instala aproximadamente 100 cuadernos de ejemplo funcionales en C:\ProgramData Topology\documentation\ExtendedBlockDocs\ y páginas de referencia HTML completas bajo block-documentationlocks\. find_example busca en ambos. Un cuaderno de ejemplo resuelve el cableado, las formas literales y las rutas de propiedades de un bloque en segundos, donde la ingeniería inversa de lo mismo a partir de mensajes de error lleva horas. Verifica allí antes de adivinar.

Formas de valores literales

Los valores literales se almacenan por tipo y las formas no son uniformes:

Una forma incorrecta falla al cargar con Leaf failed to deserialize with block/variable <name>.

Firmas de bloques

nTop almacena sus firmas de bloques como cadenas ASCII dentro de sus propios binarios, incluyendo revisiones que ya no están registradas. search_blocks las extrae de tu instalación en tiempo de ejecución y ordena la revisión más nueva de cada nombre primero. No se incluyen datos de firmas en este repositorio — las firmas son de nTop, y este servidor las lee de tu instalación con licencia en lugar de redistribuirlas.

Limitaciones

• El formato de contenedor está diseñado por ingeniería inversa y verificado solo contra nTop 5.54.2. inspect_notebook informa la versión que cada archivo registra; trata otras versiones como no verificadas y mantén copias de seguridad.

• Las herramientas de edición escriben en el lugar a menos que pases output. Se niegan a escribir un gráfico que falle la validación, pero no pueden saber si una edición es semánticamente correcta para tu modelo.

• run_notebook necesita una licencia de nTop Automate. Sin una, ntopcl sale después del inicio de sesión y el error se muestra.

• Solo Windows en la práctica, ya que es donde se ejecuta nTop.

Desarrollo

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

Las pruebas son autónomas y no requieren nTop. Dos conjuntos se amplían con más recursos disponibles:

• NTOP_TEST_NOTEBOOKS — rutas .ntop separadas por punto y coma, con viaje de ida y vuelta byte por byte. Esto está condicionado a las rutas que proporciones, no a que nTop esté instalado. No se incluyen cuadernos con el repositorio, por lo que la afirmación de viaje de ida y vuelta anterior es algo que deberías re-verificar con tus propios archivos en lugar de tomarlo por confianza.

• El conjunto de catálogo escanea una instalación real cuando se encuentra una, y se omite en caso contrario.

Licencia

MIT — ver LICENSE.

No afiliado ni respaldado por nTop. "nTop" y "nTopology" son marcas comerciales de su respectivo propietario.