MeshLab-mcp

MeshLab-MCP

一个精简且可扩展的 MeshLab 模型上下文协议（MCP）桥接工具，使用 FastAPI（HTTP）和自定义 TCP（JSON）后端，通过 pymeshlab 执行网格操作。

---

功能

• 使用 FastAPI 为 MCP 客户端（Web UI、编排器）提供 HTTP API
• 使用 TCP（JSON）后端与 MeshLab 进程通信（使用 pymeshlab）
• 可扩展：轻松添加新的网格工具和协议命令

---

项目结构

MeshLab-mcp/
├── meshlab_tcp_server.py   # TCP server wrapping pymeshlab
├── meshlab_tcp_client.py   # TCP client for server communication
├── meshlab_mcp.py          # Core MCP protocol logic (extensible)
├── mcp_server.py           # FastAPI HTTP server (entrypoint)
├── mcp_client.py           # HTTP client for testing
├── requirements.txt
└── README.md

---

设置说明

1. 克隆仓库，并 cd 进入该目录。

2. 安装依赖：

   pip install -r requirements.txt
   

3. 将 Python Scripts 目录添加到 PATH（如果尚未添加）：

   • 示例：C:\Users\<your-username>\AppData\Roaming\Python\Python313\Scripts\
   • 更改 PATH 后，重启终端。

4. 启动 MeshLab TCP 服务（在一个终端中）：

   python meshlab_tcp_server.py
   

5. 启动 HTTP MCP 服务（在另一个终端中）：

   python -m uvicorn mcp_server:app --reload
   

   如果系统无法识别 uvicorn，请使用完整路径，或像上面那样使用 python -m uvicorn ...。

6. 使用 HTTP 客户端测试（可选）：

   python mcp_client.py
   

   你应该会看到类似以下的输出：

   {'mesh_loaded': False, 'current_mesh_name': None}
   

---

MCP 客户端配置示例（用于 MeshLab 集成）

要将 MeshLab（或编排器）连接到此 MCP 服务，请使用类似以下的配置：

{
  "mcpServers": {
    "meshlab": {
      "command": "uvx",
      "args": [
        "meshlab-mcp"
      ],
      "host": "127.0.0.1",
      "port": 8000
    }
  }
}

• command：用于启动 MCP HTTP 服务的命令（例如，uvx meshlab-mcp 或 python -m uvicorn mcp_server:app --reload）
• host/port：HTTP API 的访问地址。

---

工作原理

• MCP 客户端（Web UI、编排器）向 FastAPI 服务发送 HTTP 请求。
• FastAPI 服务将这些请求转发到 MeshLab TCP 服务（该服务使用 pymeshlab 执行网格操作）。
• TCP 服务返回 JSON 结果。

---

扩展

• 在 meshlab_tcp_server.py 中添加新的网格工具/命令，并在协议中公开这些功能。
• 在 meshlab_tcp_client.py 中添加对应的方法，并在 mcp_server.py 中添加新的 HTTP 端点。

---

故障排除

• 如果系统无法识别 uvicorn，请确保 Python Scripts 目录已添加到 PATH，或使用 python -m uvicorn ...。
• 请始终先启动 TCP 服务，再启动 HTTP 服务。
• 执行网格操作时，请确保网格文件位于工作目录中。

---

后续步骤

• 开始构建新的网格工具和协议命令！
• 如需与 MeshLab GUI 或其他工具进行高级集成，请参阅 MeshLab 文档和 MCP 规范。

---

如果你有任何问题或想添加新功能，尽管提出！