## HexagonML ModelManager MCP Server

This is a HexagonML MCP server that provides a Model context protocol interface for HexagonML ModelManager tools.

### Local Development

#### Prerequisites

- **Python**: `python3`
- **Virtualenv**: recommended (project uses `.venv` in examples)

#### Environment variables

The server reads configuration from environment variables (and will also load a local `.env` file automatically).

- **`SECRET_KEY`**: secret key for ModelManager API auth
- **`MM_API_BASE_URL`**: base URL for ModelManager API (example: `http://localhost:8000`)
- **`OUTPUT_DIR`**: directory where generated HTML outputs are written
- **`HOST`** (optional): defaults to `0.0.0.0`
- **`PORT`** (optional): defaults to `9000`

Example `.env`:

```bash
SECRET_KEY=your-secret-key
MM_API_BASE_URL=http://localhost:8000
OUTPUT_DIR=./output
HOST=0.0.0.0
PORT=9000
```

#### Run the server

From the repo root:

```bash
python3 server/mm_mcp_server.py
```

To run with the FastMCP inspector (dev mode):

```bash
fastmcp dev server/mm_mcp_server.py
```

#### Troubleshooting

- **Port in use (FastMCP inspector)**: If you see `Proxy Server PORT IS IN USE` (commonly `6277`), stop the previous inspector process and retry.
- **Missing env vars**: The server will exit with a message listing missing required variables.

### Configuration For mcp integration on host (g: windsurf, vscode, claude desktop)

#### Local Configuration
```json
{
  "mcpServers": {
    "hex-mm-mcp": {
      "command": "hex-mm-mcp/.venv/bin/mcp",
      "args": ["run", "hex-mm-mcp/server/mm_mcp_server.py"]
    }
  }
}
```

#### Docker Configuration

##### For Dev (Using Local URL)
  - Run the ModelManager server in `--host 0.0.0.0 --port 8000`
    - cmd `python manage.py runserver 0.0.0.0:8000`
  - Get the hostname of your system using `hostname -I` command
    - eg: `192.168.10.75 172.17.0.1 2400:1a00:4b26:2af0:8f53:ede1:ec3a:c59b 2400:1a00:4b26:2af0:9139:c926:2fb5:6008`
    - use first ip address from the list eg: `192.168.10.75`
  - Replace `your-api-base-url` with `http://<hostIP>:8000`

```json
{
  "mcpServers": {
    "hex-mm-mcp-docker": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--network=host",
        "-e",
        "SECRET_KEY",
        "-e",
        "MM_API_BASE_URL",
        "-v",
        "OUTPUT_DIR",
        "<image-name>:<tag>"
      ],
      "env": {
        "SECRET_KEY": "your-secret-key",
        "MM_API_BASE_URL": "your-api-base-url",
        "OUTPUT_DIR": "your-output-dir"
      }
    }
  }
}
```

```
Docker Commands

Build Image
docker build --platform=linux/amd64 -t modelmanagerdev/mcp:version_id .

Run Container
docker run --platform=linux/amd64  -d --name mm-mcp -p 9000:9000 --env-file .env modelmanagerdev/mcp:v6
```

### Model Insights Tools

The server exposes Model Insights endpoints via MCP tools.

#### Create Insight

- **Tool name**: `create_insight`
- **Input**: `data` (dict)
- **Backend**: `POST /api/mmanager-modelinsights/create_insight/`

#### Get Insights

- **Tool name**: `get_insight`
- **Input**: `usecase_id` (str)
- **Backend**: `GET /api/mmanager-modelinsights/get_insights/?usecase_id=...`
- **Response shape**:
  - If the backend returns a dict, the tool returns that dict.
  - If the backend returns a list, the tool returns `{ "data": [...] }`.