convez.ai
MCP Server
Gabriel-Hong

mcp-gennx

Gabriel-Hong/mcp-gennx

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP server that dynamically generates LLM tools from REST API schemas for structural engineering software

Instalação

$npx convez-ai Gabriel-Hong/mcp-gennx

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

mcp-gennx

Python 3.11+ FastMCP 3.x License: MIT

Domain-driven MCP server that exposes GEN NX structural engineering REST APIs via the Model Context Protocol.

Features

  • Dynamic Tool Generation — Tools are generated at startup from JSON schema files. No code generation step; add a schema file plus one line to the endpoint map, and the tool appears.
  • Domain-Driven Sub-Servers — 5 sub-servers (modeling, boundary, loads, analysis, project) keep tools organized by structural engineering domain.
  • Data-Driven Routing — Endpoint→sub-server/toolset/tier mapping and toolset presets live in packaged JSON (data/endpoint_subserver_map.json, data/toolset_definitions.json), the single source of truth for which tools load where — no hardcoded routing dicts in Python.
  • Toolset Filtering — Control which tools are exposed via environment variables: 87 tools (default), 161 tools (all), or GET-only (read-only mode).
  • Schema-Sourced Descriptions — Tool descriptions, GUI feature names, and menu paths are read from the JSON schema files (single source of truth). Long-form GUI usage guides are served lazily as an MCP resource (gennx://feature/{slug}) instead of being inlined, keeping the tool list compact.

Architecture

Claude / GPT / Cursor
    │  MCP Protocol (stdio)
    ▼
Main FastMCP ("gennx")
    ├── modeling    (9 endpoints  · nodes, elements, materials, sections …)
    ├── boundary    (8 endpoints  · constraints, springs, rigid links …)
    ├── loads       (15 endpoints · load cases, nodal/beam loads, LCOM 6 sub-types …)
    ├── analysis    (6 endpoints  · eigenvalue, buckling, pushover …)
    └── project     (9 endpoints  · open/save/close, analysis run, view capture …)
              │  tool call
              ▼
         GennxApiClient (httpx async)  ──▶  GEN NX REST API (localhost:8080)

    + resource  gennx://feature/{slug}  ──▶  SchemaRegistry (in-memory, no GEN NX call)

Dynamic Tool Pipeline

schemas/raw/*.json
    → SchemaRegistry (load & merge 66 schema files → 47 endpoints)
    → ToolFactory (generate closure per method)
    → FunctionTool (name, description, JSON Schema params, annotations)
    → FastMCP.add_tool()

Each endpoint produces up to 4 tools — one per HTTP method:

MethodTool prefixExampleBehavior
POSTpost_post_db_nodeCreate records
GETget_get_db_nodeRead all records
PUTput_put_db_nodeUpdate records
DELETEdelete_delete_db_nodeDelete by ID list

Tool Description Composition

Tool descriptions are composed from fields in each schema file rather than hardcoded. Each schema may carry:

FieldUsed for
descriptionThe feature summary in every tool description
feature_nameGUI feature name, appended to POST/PUT descriptions as (GUI: "…")
menu_pathGUI menu path, appended to POST/PUT descriptions as Menu: …
usageLong-form GUI usage guide — not inlined; served via the feature resource

Feature Documentation Resource

To keep the always-loaded tool list compact, the long-form usage guide is exposed on demand as an MCP resource instead of being inlined into descriptions:

gennx://feature/{slug}      # slug = endpoint with "/" and "-" → "_", lowercased
                            # e.g. gennx://feature/db_node, gennx://feature/doc_new

POST/PUT tool descriptions that have a usage guide end with a Docs: gennx://feature/<slug> pointer. The LLM fetches that resource only when it needs the full guide, so the per-endpoint usage text (~1.5 KB each) stays out of the tool list. Parameter schema and a truncated example remain inline in each tool's input schema, since they are needed to construct valid calls.

Quick Start

1. Install

pip install -e .

2. Configure

Copy .env.example to .env and set the required environment variables:

cp .env.example .env

Edit .env:

# GEN NX REST API base URL (required)
GENNX_API_BASE_URL=https://moa-engineers.midasit.com:443/gen

# MAPI key for GEN NX authentication (required for MIDAS cloud API)
GENNX_MAPI_KEY=your-mapi-key-here

MAPI Key: Issued from the MIDAS user portal. The server passes it as the MAPI-Key HTTP header on every request to the GEN NX REST API. Leave empty only when targeting a local GEN NX instance that does not require authentication.

3. Register with Claude Code

Pass the environment variables via -e flags so the spawned MCP process inherits them:

claude mcp add gennx \
  -e GENNX_API_BASE_URL=https://moa-engineers.midasit.com:443/gen \
  -e GENNX_MAPI_KEY=your-mapi-key-here \
  -- mcp-gennx

Or add manually to your MCP client config:

{
  "mcpServers": {
    "gennx": {
      "command": "mcp-gennx",
      "args": [],
      "env": {
        "GENNX_API_BASE_URL": "https://moa-engineers.midasit.com:443/gen",
        "GENNX_MAPI_KEY": "your-mapi-key-here"
      }
    }
  }
}

4. Use

You: Create a simple beam model with 3 nodes at (0,0,0), (5,0,0), (10,0,0)
AI:  [calls post_db_node with Assign: {"1": {"X":0,"Y":0,"Z":0}, "2": {"X":5,...}, ...}]
     Created 3 nodes successfully.

You: Connect them with beam elements
AI:  [calls post_db_elem with Assign: {"1": {"TYPE":"BEAM","MATL":1,"SECT":1,"NODE":[1,2]}, ...}]
     Created 2 beam elements.

Configuration

VariableDefaultDescription
GENNX_API_BASE_URLhttp://localhost:8080GEN NX REST API base URL (e.g. https://moa-engineers.midasit.com:443/gen)
GENNX_MAPI_KEY(empty)MAPI key sent as MAPI-Key header — required for MIDAS cloud API
GENNX_API_TIMEOUT30.0API request timeout (seconds)
TOOLSETSdefaultToolset selection (see below)
READ_ONLYfalseWhen true, only GET tools are exposed
LOG_LEVELINFOLogging level

Toolset Examples

TOOLSETS=default                  # 87 tools — core endpoints only
TOOLSETS=all                      # 161 tools — all endpoints
TOOLSETS=default,loads_advanced   # default + advanced load types
TOOLSETS=modeling_core            # only core modeling tools (20 tools)
READ_ONLY=true                   # expose only GET tools

Project Structure

mcp-gennx/
├── pyproject.toml
├── .env.example
└── src/mcp_gennx/
    ├── __init__.py              # Entry point (main)
    ├── server.py                # Server assembly & toolset filtering
    ├── config.py                # GennxSettings (pydantic-settings)
    ├── routing.py               # Endpoint routing + toolset presets loaded from data/*.json
    ├── data/
    │   ├── endpoint_subserver_map.json   # endpoint → sub-server/toolset/tier (single source of truth)
    │   └── toolset_definitions.json      # default/all toolset presets
    ├── client/
    │   └── gennx_client.py      # Async HTTP client for GEN NX API
    ├── schemas/
    │   ├── registry.py          # SchemaRegistry — loads & merges JSON schemas (incl. description/usage)
    │   ├── models.py            # ApiSchema (+ description, feature_name, menu_path, usage), ToolDef
    │   └── raw/                 # 66 JSON schema files
    ├── servers/
    │   ├── _common.py           # register_routed_tools() — map-driven tool registration
    │   ├── modeling.py          # Nodes, elements, materials, sections
    │   ├── boundary.py          # Constraints, springs, rigid links
    │   ├── loads.py             # Load cases, forces, combinations (LCOM), response spectrum
    │   ├── analysis.py          # Eigenvalue, buckling, nonlinear
    │   ├── project.py           # File ops, analysis run, view capture
    │   └── feature_docs.py      # gennx://feature/{slug} resource (lazy GUI/usage docs)
    ├── tools/
    │   └── factory.py           # ToolFactory — dynamic tool generation
    └── utils/
        └── descriptions.py      # Composes tool descriptions from schema fields

Supported APIs

Tier 1 — Core (default toolset)

DomainEndpointDescription
modelingdb/NODENodes (절점) — geometry points
modelingdb/ELEMElements (요소) — beams, plates, solids
modelingdb/MATLMaterials (재료)
modelingdb/SECTSections (단면) — 11 sub-types
modelingdb/THIKThickness (두께) — plate thickness
boundarydb/CONSConstraints (지점조건) — supports
boundarydb/NSPRNodal Springs (절점스프링)
loadsdb/STLDStatic Load Cases (정적하중)
loadsdb/BODFBody Forces (자중)
loadsdb/CNLDConcentrated Nodal Loads (절점하중)
loadsdb/BMLDBeam Loads (보하중)
loadsdb/LCOM-*Load Combinations (하중조합) — 6 sub-types
analysisdb/EIGVEigenvalue Analysis (고유치해석)
analysisdb/NMASNodal Masses (절점질량)

Tier 2 — Advanced

DomainEndpointDescription
modelingdb/GRUPStructure Groups (구조그룹)
modelingdb/BNGRBoundary Groups
modelingdb/SKEWLocal Coordinates (경사좌표계)
modelingdb/STORStories (층 정보)
boundarydb/GSPRGeneral Springs
boundarydb/ELNKElastic Links (탄성링크)
boundarydb/RIGDRigid Links (강체링크)
boundarydb/FRLSFloor Releases
boundarydb/OFFSBeam Offsets (보 오프셋)
boundarydb/MCONMulti-point Constraints
loadsdb/PRESPressure Loads (압력하중)
loadsdb/PSLTPressure Load Types (압력하중 타입)
loadsdb/ETMPElement Temperatures (요소온도)
loadsdb/GTMPGradient Temperatures (온도경사)
loadsdb/SPLCResponse Spectrum Load Cases (응답스펙트럼 하중 케이스)
analysisdb/ACTLAnalysis Control (해석 제어)
analysisdb/BUCKBuckling Analysis (좌굴해석)
analysisdb/PDELP-Delta Analysis
analysisdb/NLCTNonlinear Control
projectdb/UNITUnit System
projectdb/STYPStructure Type

Project Operations (manually registered)

ToolDescription
post_doc_analRun analysis (standard or pushover)
post_doc_newCreate new project
post_doc_openOpen project file
post_doc_saveSave project
post_doc_saveasSave project as new file
post_doc_closeClose project
post_view_captureCapture current view as image

Development

Run Tests

pip install -e ".[dev]"
pytest

Adding a New API

  1. Place the JSON schema file in src/mcp_gennx/schemas/raw/. To enrich the generated descriptions, include the optional description, feature_name, menu_path, and usage fields (the usage text is served via the gennx://feature/{slug} resource, not inlined).
  2. Add one line to the endpoint map src/mcp_gennx/data/endpoint_subserver_map.json, routing it to a sub-server, toolset, and tier:
    "db/NEW_ENDPOINT": {"sub_server": "modeling", "toolset": "modeling_advanced", "tier": 2}
    
    No Python edit is needed — each sub-server reads its endpoints from this map at startup via register_routed_tools(). (tests/test_routing.py fails if a schema and its map entry drift out of sync.)
  3. Restart the server — tools and the feature resource are generated automatically.

License

MIT

Ver o original no GitHub

Bom para

Relacionados