mcp-gennx
Gabriel-Hong/mcp-gennx
MCP server that dynamically generates LLM tools from REST API schemas for structural engineering software
Instalação
npx convez-ai Gabriel-Hong/mcp-gennx1 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
README
A tradução para o português deste README ainda está na fila.
mcp-gennx
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:
| Method | Tool prefix | Example | Behavior |
|---|---|---|---|
| POST | post_ | post_db_node | Create records |
| GET | get_ | get_db_node | Read all records |
| PUT | put_ | put_db_node | Update records |
| DELETE | delete_ | delete_db_node | Delete by ID list |
Tool Description Composition
Tool descriptions are composed from fields in each schema file rather than hardcoded. Each schema may carry:
| Field | Used for |
|---|---|
description | The feature summary in every tool description |
feature_name | GUI feature name, appended to POST/PUT descriptions as (GUI: "…") |
menu_path | GUI menu path, appended to POST/PUT descriptions as Menu: … |
usage | Long-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-KeyHTTP 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
| Variable | Default | Description |
|---|---|---|
GENNX_API_BASE_URL | http://localhost:8080 | GEN 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_TIMEOUT | 30.0 | API request timeout (seconds) |
TOOLSETS | default | Toolset selection (see below) |
READ_ONLY | false | When true, only GET tools are exposed |
LOG_LEVEL | INFO | Logging 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)
| Domain | Endpoint | Description |
|---|---|---|
| modeling | db/NODE | Nodes (절점) — geometry points |
| modeling | db/ELEM | Elements (요소) — beams, plates, solids |
| modeling | db/MATL | Materials (재료) |
| modeling | db/SECT | Sections (단면) — 11 sub-types |
| modeling | db/THIK | Thickness (두께) — plate thickness |
| boundary | db/CONS | Constraints (지점조건) — supports |
| boundary | db/NSPR | Nodal Springs (절점스프링) |
| loads | db/STLD | Static Load Cases (정적하중) |
| loads | db/BODF | Body Forces (자중) |
| loads | db/CNLD | Concentrated Nodal Loads (절점하중) |
| loads | db/BMLD | Beam Loads (보하중) |
| loads | db/LCOM-* | Load Combinations (하중조합) — 6 sub-types |
| analysis | db/EIGV | Eigenvalue Analysis (고유치해석) |
| analysis | db/NMAS | Nodal Masses (절점질량) |
Tier 2 — Advanced
| Domain | Endpoint | Description |
|---|---|---|
| modeling | db/GRUP | Structure Groups (구조그룹) |
| modeling | db/BNGR | Boundary Groups |
| modeling | db/SKEW | Local Coordinates (경사좌표계) |
| modeling | db/STOR | Stories (층 정보) |
| boundary | db/GSPR | General Springs |
| boundary | db/ELNK | Elastic Links (탄성링크) |
| boundary | db/RIGD | Rigid Links (강체링크) |
| boundary | db/FRLS | Floor Releases |
| boundary | db/OFFS | Beam Offsets (보 오프셋) |
| boundary | db/MCON | Multi-point Constraints |
| loads | db/PRES | Pressure Loads (압력하중) |
| loads | db/PSLT | Pressure Load Types (압력하중 타입) |
| loads | db/ETMP | Element Temperatures (요소온도) |
| loads | db/GTMP | Gradient Temperatures (온도경사) |
| loads | db/SPLC | Response Spectrum Load Cases (응답스펙트럼 하중 케이스) |
| analysis | db/ACTL | Analysis Control (해석 제어) |
| analysis | db/BUCK | Buckling Analysis (좌굴해석) |
| analysis | db/PDEL | P-Delta Analysis |
| analysis | db/NLCT | Nonlinear Control |
| project | db/UNIT | Unit System |
| project | db/STYP | Structure Type |
Project Operations (manually registered)
| Tool | Description |
|---|---|
post_doc_anal | Run analysis (standard or pushover) |
post_doc_new | Create new project |
post_doc_open | Open project file |
post_doc_save | Save project |
post_doc_saveas | Save project as new file |
post_doc_close | Close project |
post_view_capture | Capture current view as image |
Development
Run Tests
pip install -e ".[dev]"
pytest
Adding a New API
- Place the JSON schema file in
src/mcp_gennx/schemas/raw/. To enrich the generated descriptions, include the optionaldescription,feature_name,menu_path, andusagefields (theusagetext is served via thegennx://feature/{slug}resource, not inlined). - Add one line to the endpoint map
src/mcp_gennx/data/endpoint_subserver_map.json, routing it to a sub-server, toolset, and tier:
No Python edit is needed — each sub-server reads its endpoints from this map at startup via"db/NEW_ENDPOINT": {"sub_server": "modeling", "toolset": "modeling_advanced", "tier": 2}register_routed_tools(). (tests/test_routing.pyfails if a schema and its map entry drift out of sync.) - Restart the server — tools and the feature resource are generated automatically.
License
MIT