# todiagram-mcp-windows-fix

**Windows-compatible fork** of `@todiagram/todiagram-mcp` that fixes `ERR_UNSUPPORTED_ESM_URL_SCHEME` on Node.js v22+ and v25+ on Windows.

> Connect ToDiagram to Cursor, Claude, Windsurf, and other AI assistants — now works on Windows!

## ⚠️ The Problem

The original `@todiagram/todiagram-mcp` crashes on Windows with:

```
Fatal error in main(): Error [ERR_UNSUPPORTED_ESM_URL_SCHEME]:
Only URLs with a scheme in: file, data, and node are supported by the default ESM loader.
On Windows, absolute paths must be valid file:// URLs. Received protocol 'c:'
```

**Root cause**: In `dist/mcp-server.js`, the `lazyLoadUtil()` function dynamically imports tool modules using `path.join()`, which on Windows produces paths like `C:\Users\...\tools\file.js`. The Node.js ESM loader requires `file://` URLs, not bare Windows paths.

## ✅ The Fix

A one-line change in `dist/mcp-server.js`:

```diff
- import { fileURLToPath } from "url";
+ import { fileURLToPath, pathToFileURL } from "url";

  // ... in lazyLoadUtil():
- await import(toolPath);
+ await import(pathToFileURL(toolPath).href);
```

`pathToFileURL()` converts `C:\Users\...\file.js` → `file:///C:/Users/.../file.js`, which the ESM loader accepts on all platforms.

## 📦 Install

```bash
npm install -g todiagram-mcp-windows-fix
```

## 🔧 MCP Configuration

### Claude Code (`.mcp.json`)

```json
{
  "mcpServers": {
    "todiagram": {
      "type": "stdio",
      "command": "todiagram",
      "env": {
        "TODIAGRAM_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Or via npx

```json
{
  "mcpServers": {
    "todiagram": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "todiagram-mcp-windows-fix"],
      "env": {
        "TODIAGRAM_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### API Key Setup

1. Go to [ToDiagram Editor](https://todiagram.com/editor)
2. Click the **account icon** at top right
3. Go to **API Key** section
4. Create a key with a descriptive name and expiry time

## 🐛 Upstream Issue

This fix should be applied to the original `@todiagram/todiagram-mcp` package. The upstream issue is in `src/mcp-server.ts`:

```typescript
// Current (broken on Windows):
for (const toolPath of toolsPaths) {
    await import(toolPath);
}

// Fix:
import { pathToFileURL } from "url";
for (const toolPath of toolsPaths) {
    await import(pathToFileURL(toolPath).href);
}
```

**Affected platforms**: Windows with Node.js v22+ (any version using ESM loader with strict URL scheme validation)

**Affected versions**: `@todiagram/todiagram-mcp` v1.1.0 and likely earlier versions

## ✅ Platform Compatibility

| Platform | Node.js v20 | Node.js v22 | Node.js v25 |
|----------|-------------|-------------|-------------|
| Windows  | ✅          | ✅          | ✅          |
| macOS    | ✅          | ✅          | ✅          |
| Linux    | ✅          | ✅          | ✅          |

## 📄 License

FSL-1.1-ALv2 (same as upstream)