RSAP MCP — Robot Structural Analysis ↔ Claude

MCP server cho Autodesk Robot Structural Analysis Professional 2027 — dùng với Claude hoặc Codex.

Mục lục / Contents

• Yêu cầu / Requirements
• Bước 1 — Cài đặt / Install
• Bước 2 — Đăng ký với Claude Desktop / Register with Claude Desktop
• Bước 3 — Dùng thử / First run
• Dùng với Codex / Use with Codex
• Kiểm thử bằng client rời / Test with the standalone client
• Thêm công cụ mới / Add a new tool
• Danh sách công cụ / Tool list
• Xử lý sự cố / Troubleshooting
• Cấu trúc thư mục / Repository layout

---

Yêu cầu / Requirements

OS	Windows 10/11 (64-bit)
Robot	Robot Structural Analysis Professional 2027, đã cài & mở ít nhất một lần
Python	3.10+, 64-bit
uv	powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Host	Claude Desktop hoặc Codex

---

Bước 1 — Cài đặt / Install

git clone https://github.com/nhantruong96/rsap-mcp.git
cd rsap-mcp
uv sync

Chạy lại uv sync sau mỗi git pull.

Kiểm tra (không cần Robot):

uv run python -m rsap_mcp --selfcheck
# -> [selfcheck] 35 tools registered ... OK

Tùy chọn thêm / optional extras:

uv sync --extra dev     # + ruff

Tùy chọn — chép .env.example thành .env rồi sửa RSAP_VISIBLE, RSAP_INTERACTIVE, RSAP_AUTO_CONNECT, RSAP_LOG_LEVEL, RSAP_LOG_FILE, RSAP_PROJECT_DIR.

Không có uv:

powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1

---

Bước 2 — Đăng ký với Claude Desktop / Register with Claude Desktop

powershell -ExecutionPolicy Bypass -File .\scripts\register_claude_desktop.ps1

Hoặc sửa tay %APPDATA%\Claude\claude_desktop_config.json: chép một trong hai khối dưới đây, thay C:\path\to\rsap-mcp bằng đường dẫn thật (mẫu: config/claude_desktop_config.example.json).

A. Qua uv — khuyến nghị:

{
  "mcpServers": {
    "rsap": {
      "command": "uv",
      "args": ["--directory", "C:/path/to/rsap-mcp", "run", "rsap-mcp"]
    }
  }
}

B. Trỏ thẳng Python của venv — khi uv không có trong PATH của Claude Desktop:

{
  "mcpServers": {
    "rsap": {
      "command": "C:\\path\\to\\rsap-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "rsap_mcp"],
      "env": {
        "PYTHONPATH": "C:\\path\\to\\rsap-mcp\\src",
        "RSAP_VISIBLE": "true",
        "RSAP_LOG_LEVEL": "INFO"
      }
    }
  }
}

Sau khi sửa: thoát hẳn rồi mở lại Claude Desktop. Log: %APPDATA%\Claude\logs\mcp-server-rsap.log.

---

Bước 3 — Dùng thử / First run

Mở Claude Desktop và ra lệnh bằng lời:

"Kết nối Robot, tạo dự án khung 2D, dựng khung cổng nhịp 6 m cao 4 m bằng thép S235 IPE300, ngàm 2 chân, thêm trọng lượng bản thân và tải mái 10 kN/m, chạy tổ hợp ULS 1.35×TT+1.5×HT rồi cho biết phản lực chân cột và mô men lớn nhất ở xà."

"Connect to Robot, make a 2D frame, build a 6×4 m portal in S235 IPE300, fix both bases, add self-weight and a 10 kN/m roof load, run a 1.35G+1.5Q ULS combination, then tell me the base reactions and peak rafter moment."

Trình tự chuẩn / the workflow:

connect → new_project → add_nodes → add_bars → define_section/material → assign →
define_support → assign_support → add_load_case → add_*_load → add_combination →
calculate → bar_forces / node_displacement / node_reaction → save_project

• Đơn vị: m, N, N·m.
• Chuỗi chọn đối tượng: '1to10', '1 2 3', '1to20by2'.
• Chờ lâu ở tool đầu tiên — Robot đang mở.

---

Dùng với Codex / Use with Codex

1. Mở C:\Users\<YOU>\.codex\config.toml (macOS/Linux: ~/.codex/config.toml).

2. Thêm khối sau, sửa đường dẫn (mẫu: config/codex_config.example.toml):

   [mcp_servers.rsap]
   enabled = true
   command = 'C:\path\to\rsap-mcp\.venv\Scripts\python.exe'
   args = ["-m", "rsap_mcp"]
   startup_timeout_sec = 30
   tool_timeout_sec = 600                      # rsap_calculate chạy lâu
   default_tools_approval_mode = "prompt"      # "auto" nếu không muốn hỏi từng tool
   
   [mcp_servers.rsap.env]
   RSAP_VISIBLE = "true"
   RSAP_INTERACTIVE = "true"
   RSAP_AUTO_CONNECT = "true"
   RSAP_LOG_LEVEL = "INFO"
   

   Hoặc thêm bằng một dòng lệnh / or add it with the CLI:

   codex mcp add rsap --env RSAP_VISIBLE=true --env RSAP_AUTO_CONNECT=true -- `
     "C:\path\to\rsap-mcp\.venv\Scripts\python.exe" -m rsap_mcp
   

3. Kiểm tra: codex mcp list.

4. Thoát hẳn và mở lại app Codex, gõ /mcp để thấy rsap và 35 tools.

Giới hạn tool: thêm enabled_tools = [...] hoặc disabled_tools = [...] vào khối [mcp_servers.rsap].

---

Kiểm thử bằng client rời / Test with the standalone client

uv run python client\test_client.py                # liệt kê tool qua MCP thật
uv run python client\test_client.py --call rsap_status
uv run python client\examples\01_portal_frame.py   # end-to-end (cần Robot)
uv run ruff check .                                # lint

---

Thêm công cụ mới / Add a new tool

1. Mở module phù hợp trong src/rsap_mcp/tools/ (project_, modeling_, property_, support_, load_, analysis_, results_tools.py).

2. Viết hàm bên trong register(mcp), gắn @mcp.tool() rồi @com_call, kèm type hints và docstring Google-style:

   def register(mcp):
       @mcp.tool()
       @com_call
       def rsap_count_objects() -> dict:
           """Return node and bar counts."""
           c = conn()
           return {"nodes": c.count(c.nodes), "bars": c.count(c.bars)}
   

3. Gọi hằng RobotOM bằng tên qua const("I_..."), không ghi số trực tiếp.

4. Trả về dict hoặc model Pydantic; lỗi thì raise.

5. Không dùng print(); log qua config.py.

6. Chạy uv run python -m rsap_mcp --selfcheck và uv run ruff check ..

---

Danh sách công cụ / Tool list

35 tool (tiền tố rsap_) và 3 resource. Dấu * = tham số bắt buộc.

Session & Project

Tool	Mô tả / Description	Tham số / Parameters
rsap_connect	Connect to (or launch) Autodesk Robot Structural Analysis Professional.	visible:boolean, interactive:boolean
rsap_status	Report connection status and a summary of the current Robot model.	(none)
rsap_new_project	Create a new, empty Robot project.	project_type:string
rsap_open_project	Open an existing Robot model from an absolute .rtd path.	path:string *
rsap_save_project	Save the current model. Pass a path to Save As, or omit to Save in place.	path:string/null
rsap_close_project	Close the current project (Robot itself stays open).	(none)

Modeling

Tool	Mô tả / Description	Tham số / Parameters
rsap_add_node	Create a single node at the given coordinates (metres).	x:number *, y:number *, z:number *, number:integer/null
rsap_add_nodes	Create many nodes at once.	nodes:array *
rsap_add_bar	Create a bar (beam/column) between two existing nodes, optionally assigning section/material.	start_node:integer *, end_node:integer *, number:integer/null, section:string/null, material:string/null
rsap_add_bars	Create many bars at once.	bars:array *
rsap_list_nodes	List nodes with their coordinates.	limit:integer
rsap_list_bars	List bars with their start/end node numbers.	limit:integer
rsap_delete_objects	Delete nodes or bars matching a selection string.	object_type:string *, selection:string *

Sections & Materials

Tool	Mô tả / Description	Tham số / Parameters
rsap_define_section	Define a bar section label by loading a profile from Robot's active database.	name:string *, db_section:string/null, material:string/null
rsap_define_material	Define a material label, either loaded from Robot's material database or from explicit properties.	name:string *, from_database:string/null, material_type:string/null, e:number/null, nu:number/null, ro:number/null, kirchoff:number/null
rsap_assign_section	Assign an existing section label to a set of bars.	section_name:string *, bars:string *
rsap_assign_material	Assign an existing material label to a set of bars.	material_name:string *, bars:string *
rsap_list_sections	List the names of section labels defined in the model.	(none)

Supports

Tool	Mô tả / Description	Tham số / Parameters
rsap_define_support	Define a support (boundary condition) label. True = restrained.	name:string *, ux:boolean, uy:boolean, uz:boolean, rx:boolean, ry:boolean, rz:boolean
rsap_assign_support	Assign an existing support label to a set of nodes.	support_name:string *, nodes:string *

Loads & Combinations

Tool	Mô tả / Description	Tham số / Parameters
rsap_add_load_case	Create a simple load case.	name:string *, nature:string, analysis:string, number:integer/null
rsap_add_self_weight	Add a self-weight (dead) load to a case.	case_number:integer *, direction:string, factor:number, selection:string
rsap_add_nodal_force	Add a nodal force/moment to a case (global axes).	case_number:integer *, nodes:string *, fx:number, fy:number, fz:number, cx:number, cy:number, cz:number
rsap_add_bar_uniform_load	Add a uniformly distributed load along bars.	case_number:integer *, bars:string *, px:number, py:number, pz:number, local:boolean, projected:boolean
rsap_add_bar_point_load	Add a concentrated (point) force/moment on bars.	case_number:integer *, bars:string *, fx:number, fy:number, fz:number, cx:number, cy:number, cz:number, position:number, relative:boolean, local:boolean
rsap_add_combination	Create a load combination from weighted load cases.	name:string *, factors:array *, combo_type:string, nature:string, number:integer/null
rsap_list_load_cases	List load cases and combinations in the model.	(none)

Analysis

Tool	Mô tả / Description	Tham số / Parameters
rsap_generate_mesh	Generate the finite-element mesh.	(none)
rsap_calculate	Run the structural analysis (solve the model).	(none)
rsap_calculation_status	Report whether analysis results are currently available.	(none)

Results

Tool	Mô tả / Description	Tham số / Parameters
rsap_bar_forces	Internal forces at a point along a bar (local axes).	bar:integer *, case:integer *, position:number
rsap_bar_force_envelope	Sample a bar along its length and return the extreme internal forces.	bar:integer *, case:integer *, samples:integer
rsap_node_displacement	Nodal displacement (global axes).	node:integer *, case:integer *
rsap_node_reaction	Support reaction at a node (global axes).	node:integer *, case:integer *
rsap_results_summary	Summarise results for a case: peak nodal displacement and peak bar moment.	case:integer *, max_nodes:integer, max_bars:integer

Resources

URI	Nội dung / Content
rsap://reference/enums	Bản đồ friendly → hằng RobotOM.
rsap://reference/sections	Hướng dẫn tiết diện & vật liệu.
rsap://reference/cheatsheet	Quy trình end-to-end.

Tham chiếu RobotOM COM API để mở rộng server: docs/RobotOM_API_Reference.md.

---

Xử lý sự cố / Troubleshooting

Triệu chứng / Symptom	Xử lý / Fix
Server không hiện trong Claude	Kiểm tra command/PYTHONPATH, khởi động lại Claude, xem mcp-server-rsap.log.
/mcp trong Codex không thấy rsap	Thoát hẳn & mở lại Codex; chạy codex mcp list; kiểm tra command trong config.toml.
constant 'I_...' not found	Mở Robot một lần để đăng ký type library; đối chiếu tên hằng trong enums.py.
Kết nối COM thất bại	Dùng Python 64-bit; kiểm tra Robot đã cài đúng bitness.
Giao thức hỏng ngay khi khởi động	Tìm thư viện đang in ra stdout; chuyển log sang stderr/file.
ModuleNotFoundError: mcp.server.fastmcp	Đang dùng mcp 2.x; gói đã ghim mcp[cli]<2 — chạy lại uv sync.
ModuleNotFoundError: mcp khi chạy client	Chạy qua venv: uv run python client\....
Could not read results	Chạy rsap_calculate() trước; kiểm tra số bar/node/case có tồn tại.
LoadFromDBase lỗi	Đặt đúng CSDL tiết diện/vật liệu trong Job Preferences (IPE300 cần catalog châu Âu).
Treo khi Calculate	Đóng hộp thoại đang chờ trong cửa sổ Robot.
Tool đầu tiên rất chậm / timeout	Robot đang khởi động — tăng tool_timeout_sec hoặc mở Robot sẵn.
Model gọi tool sai thứ tự	Nhắc trong prompt "làm tuần tự theo cheatsheet".

---

Cấu trúc thư mục / Repository layout

rsap-mcp/
├── src/rsap_mcp/          # MCP server (server.py, robot_app.py, com_utils.py,
│   │                      #   enums.py, config.py)
│   ├── tools/             # 35 tool rsap_* theo nhóm
│   ├── models/            # pydantic schemas
│   └── resources/         # rsap://reference/*
├── client/                # client MCP rời + examples
├── scripts/               # install / run / register (PowerShell)
├── config/                # claude_desktop_config.example.json, codex_config.example.toml
├── native/RsapHelper/     # DLL C# tùy chọn
├── docs/                  # RobotOM_API_Reference.md
├── pyproject.toml
└── uv.lock                # `uv sync` đọc file này

---

License

MIT. © 2026 PORTCOAST Taskforce.