内容
# sofa-mcp
SOFA物理仿真框架的MCP服务器。为通过stdio传输控制SOFA仿真提供24种工具。
## 安装
在SOFA链接到的Python环境中运行：
```bash
pip install -e .
```
对于开发工具（pytest、mypy、ruff）：
```bash
pip install -e ".[dev]"
```
## 连接
### Claude 桌面版
添加到您操作系统的配置文件中：
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"sofa-mcp": {
"command": "sofa-mcp"
}
}
}
```
### Claude 代码（命令行界面）
```bash
claude mcp add sofa-mcp sofa-mcp
```
### Cursor
在您的项目中添加至 `.cursor/mcp.json`（或全局 `~/.cursor/mcp.json`）：
```json
{
"mcpServers": {
"sofa-mcp": {
"command": "sofa-mcp"
}
}
}
```
### VS Code（GitHub Copilot）
在您的工作空间中添加至 `.vscode/mcp.json`:
```json
{
"servers": {
"sofa-mcp": {
"type": "stdio",
"command": "sofa-mcp"
}
}
}
```
## 工具
| 类别 | 工具 |
|----------|-------|
| 场景 | `create_scene`, `load_scene_file`, `add_child_node`, `add_component`, `get_scene_graph`, `save_scene`, `unload_scene` |
| 仿真 | `init_simulation`, `step_simulation`, `step_simulation_n`, `step_and_render`, `reset_simulation`, `get_state`, `get_node_energy` |
| 数据 | `get_field_value`, `set_field_value`, `list_components`, `list_component_fields`, `get_mechanical_state`, `set_mechanical_state` |
| 可视化 | `init_visualizer`, `render_frame` |
| 实用工具 | `query_available_components`, `load_plugins` |
## 示例
```bash
python demos/falling_sofa_demo.py
```
如果您的SOFA安装路径与默认路径（`/opt/sofa/install`）不同，请设置 `SOFA_ROOT`:
```bash
SOFA_ROOT=/path/to/sofa python demos/falling_sofa_demo.py
```
## 测试
```bash
pytest sofa_mcp/tests/test_mcp_tools.py # 不需要SOFA
pytest sofa_mcp/tests/test_sofa_bridge.py # SOFA依赖测试自动跳过
```
