# MeshLab-MCP

A minimal, extensible Model Context Protocol (MCP) bridge for MeshLab, using FastAPI (HTTP) and a custom TCP (JSON) backend for mesh operations via `pymeshlab`.

---

## Features
- **HTTP API** for MCP clients (web UIs, orchestrators) using FastAPI
- **TCP (JSON) backend** to communicate with a MeshLab process (using `pymeshlab`)
- **Extensible**: Add new mesh tools and protocol commands easily

---

## Project Structure
```
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
```

---

## Setup Instructions

1. **Clone the repository** and `cd` into the directory.

2. **Install dependencies:**
   ```sh
   pip install -r requirements.txt
   ```

3. **Add Python Scripts directory to PATH** (if not already):
   - Example: `C:\Users\<your-username>\AppData\Roaming\Python\Python313\Scripts\`
   - Restart your terminal after changing PATH.

4. **Start the MeshLab TCP server** (in a terminal):
   ```sh
   python meshlab_tcp_server.py
   ```

5. **Start the HTTP MCP server** (in another terminal):
   ```sh
   python -m uvicorn mcp_server:app --reload
   ```
   > If `uvicorn` is not recognized, use the full path or the `python -m uvicorn ...` form as above.

6. **Test with the HTTP client** (optional):
   ```sh
   python mcp_client.py
   ```
   You should see output like:
   ```json
   {'mesh_loaded': False, 'current_mesh_name': None}
   ```

---

## MCP Client Configuration Example (for MeshLab integration)

To connect MeshLab (or an orchestrator) to this MCP server, use a configuration like:

```json
{
  "mcpServers": {
    "meshlab": {
      "command": "uvx",
      "args": [
        "meshlab-mcp"
      ],
      "host": "127.0.0.1",
      "port": 8000
    }
  }
}
```
- `command`: The command to launch your MCP HTTP server (e.g., `uvx meshlab-mcp` or `python -m uvicorn mcp_server:app --reload`)
- `host`/`port`: Where the HTTP API is reachable.

---

## How It Works
- **MCP clients** (web UI, orchestrator) send HTTP requests to the FastAPI server.
- The FastAPI server bridges these requests to the MeshLab TCP server (which runs mesh operations using `pymeshlab`).
- The TCP server responds with JSON results.

---

## Extending
- Add new mesh tools/commands in `meshlab_tcp_server.py` and expose them in the protocol.
- Add corresponding methods in `meshlab_tcp_client.py` and new HTTP endpoints in `mcp_server.py`.

---

## Troubleshooting
- If `uvicorn` is not recognized, ensure your Python Scripts directory is in PATH or use `python -m uvicorn ...`.
- Always start the TCP server before the HTTP server.
- For mesh operations, ensure your mesh files are present in the working directory.

---

## Next Steps
- Start building new mesh tools and protocol commands!
- For advanced integration with MeshLab's GUI or other tools, refer to MeshLab's documentation and MCP specs.

---

If you have questions or want to add new features, just ask!