# Troubleshooting

## Debug logs

MCP server uses stdio (standard console output) for the communication between MCP Client and MCP server. In order to provide essential debug information at this stage of the development, detailed logs are reported as console **error** output, until better logging system is implemented.

## What if the server goes down?

Extension has exponential re-connection mechanism. Robust connection management is not in place yet.

When server is disconnected, you should see attempts to reconnect in the Extension:

```
[background] WebSocket connection closed CloseEvent {isTrusted: true, wasClean: false, code: 1006, reason: '', type: 'close', …}

Attempting to reconnect in 4.5 seconds... (attempt 1)

[background] broadcast to tabs (2) [{…}, {…}]
[background] WebSocket connection established Event {isTrusted: true, type: 'open', target: WebSocket, currentTarget: WebSocket, eventPhase: 2, …}
[background] broadcast to tabs (2) [{…}, {…}]
```

There are currently **5** reconnection attempts with initial delay of **3 seconds** growing exponentially.

You can force the reconnection by re-enabling / refreshing the Extension in [chrome://extensions](chrome://extensions).

## Does the MCP server run by itself?

Running `pnpm` version should output the following.

```sh
pnpm dlx drawio-mcp-server
```

Terminal output:

```
Packages: +109
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Progress: resolved 109, reused 107, downloaded 2, added 109, done
Listening to port 3333 undefined
Draw.io MCP Server running on stdio undefined
```

Running `npx` version should output the following.

```sh
npx -y drawio-mcp-server
```

Terminal output:
```
DEBUG: Draw.io MCP Server starting (WebSocket extension port: 3333)
DEBUG: [start_websocket_server] Listening to port 3333
DEBUG: Draw.io MCP Server WebSocket started on extension port 3333
DEBUG: Draw.io MCP Server running on stdio
```

When using a custom port (e.g., port 8080), you should see:
```
DEBUG: Draw.io MCP Server starting (WebSocket extension port: 8080)
DEBUG: [start_websocket_server] Listening to port 8080
DEBUG: Draw.io MCP Server WebSocket started on extension port 8080
DEBUG: Draw.io MCP Server running on stdio
```

When Extension connects, you should see:

```
DEBUG: [ws_handler] A WebSocket client #0 connected, presumably MCP Extension!
```

### Streamable HTTP transport

The HTTP transport is opt-in. If your MCP client tries to reach `/mcp` and gets `ECONNREFUSED` or a 404, confirm you started the server with `--transport http` (or `--transport stdio,http`). Example output when HTTP is enabled:

```
DEBUG: Draw.io MCP Server Streamable HTTP transport active
DEBUG: Health check: http://localhost:3000/health
DEBUG: MCP endpoint: http://localhost:3000/mcp
DEBUG: Draw.io MCP Server running on stdio,http
```

Use the health check to verify connectivity:

```sh
curl http://localhost:3000/health
```

If it responds with `{"status":"mcp not ready"}`, the server has not fully started. Wait a moment or restart with the correct flags.

## Port Already in Use

**Error**: `Error: Port 3333 is already in use`

**Solution**:
1. Check what's using port 3333: `lsof -i :3333` (macOS/Linux) or `netstat -ano | findstr :3333` (Windows)
2. Stop the conflicting process, OR
3. Configure drawio-mcp-server to use a different port by adding `--extension-port <number>` to the configuration

Example with custom extension port:
```json
{
  "mcpServers": {
    "drawio": {
      "command": "npx",
      "args": ["-y", "drawio-mcp-server", "--extension-port", "8888"]
    }
  }
}
```

**HTTP transport port clash**: If port 3000 is busy, either stop the conflicting service or change the HTTP port with `--http-port <number>` and update your MCP client to the new `/mcp` URL.
