Files
modelruimte/docs/MCP.md
robbertjanssen85andClaude Opus 4.7 5a16cb4c06 Add REST API, MCP server, OpenAPI/ReDoc docs, and client connect page
- /api/v1/* REST endpoints: health, model catalog (vehicles, functions,
  distributions, profiles, defaults), and simulate. Accepts functionCounts
  and/or functionBvoM2 (auto-converted via DEFAULT_BVO_PER_UNIT). Runs 2500
  Monte Carlo iterations by default; response adds a labeled `summary`
  (totalLengthM, totalAreaM2, per-vehicle + per-cluster) alongside the raw
  SimulationResult.
- /api/mcp Streamable-HTTP MCP endpoint (hand-rolled JSON-RPC 2.0, no new
  deps). Tools: get_model_info, list_vehicles/functions/distributions,
  get_delivery_profile, run_simulation.
- /api/v1/openapi.json + /api-docs: OpenAPI 3.0.3 spec rendered with ReDoc,
  themed to DMI palette + IBM Plex typography, DMI logo in the sidebar.
- /mcp-connect: DMI-styled page with copy-paste config blocks for Claude
  Code, Claude Desktop, Cursor, Codex CLI, Windsurf, and VS Code. MCP URL
  substituted from window.location.origin.
- Cover page gets an "Integraties" section with pill buttons linking to
  API-referentie and MCP instellen.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-23 14:52:51 +02:00

3.6 KiB

Ruimtemodel Stadslogistiek — MCP server

The webapp exposes a Model Context Protocol server so AI agents (Claude Desktop, Claude Code, Cursor, IDE plugins, custom LLM clients, …) can inspect the model and run simulations.

  • Transport: Streamable HTTP (JSON-RPC 2.0 over HTTPS).
  • Endpoint: POST /api/mcp
  • Protocol version: 2025-03-26
  • Auth: none (public, read/compute only).

GET /api/mcp returns a small discovery document useful when hitting the URL in a browser.

Quickest way to wire up a client: open /mcp-connect — it renders ready-to-paste config blocks for Claude Desktop, Claude Code, Cursor, Codex CLI, Windsurf, and VS Code, with the deployed MCP URL already filled in and a Copy button per block.


Tools

Name Purpose
get_model_info Full metadata: vehicles, functions, distributions, defaults.
list_vehicles 6 vehicle types with length in meters.
list_functions 12 urban function types.
list_distributions 15 distribution / delivery profile types.
get_delivery_profile Look up one delivery profile by function + distribution ID.
run_simulation Run the Monte Carlo simulation; see REST API for input schema.

Each tool's inputSchema is returned by the standard tools/list method.


Connecting from Claude Desktop / Claude Code

Claude clients speak MCP natively but (as of early 2026) the built-in stdio client is what most people use. To bridge stdio ↔ HTTP use mcp-remote:

// claude_desktop_config.json
{
  "mcpServers": {
    "ruimtemodel": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-host/api/mcp"]
    }
  }
}

For Claude Code, run:

claude mcp add --transport http ruimtemodel https://your-host/api/mcp

Connecting from a custom MCP client

Any client that speaks the Streamable HTTP transport can connect by POSTing JSON-RPC 2.0 requests to /api/mcp. Minimal handshake:

# 1. initialize
curl -s -X POST https://your-host/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"example","version":"0.1"}}}'

# 2. list tools
curl -s -X POST https://your-host/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# 3. call run_simulation
curl -s -X POST https://your-host/api/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"run_simulation","arguments":{"functionCounts":{"F1":362,"F2":2},"numSimulations":1000}}}'

tools/call responses wrap the tool output in a content[] array containing a single {type: "text", text: "<json-string>"} entry per the MCP spec. The JSON string is the same shape the REST API returns for /api/v1/simulate.


Notes / limits

  • The server is stateless — every request is independent; no Mcp-Session-Id is required. Clients that send one will get it echoed back.
  • numSimulations is capped at 5000 to keep response times under a minute.
  • Resources and prompts are not implemented; every capability is exposed as a tool.

See src/app/api/mcp/route.ts for the JSON-RPC dispatch logic and src/lib/api/mcp-tools.ts for tool definitions.