# OpenROAD MCP — API Reference This document is the authoritative reference for the MCP tools exposed by the TypeScript server. It is generated from the source of truth: [`typescript/src/server.ts`](../typescript/src/server.ts), [`typescript/src/config/command_whitelist.ts`](../typescript/src/config/command_whitelist.ts), [`typescript/src/core/models.ts`](../typescript/src/core/models.ts), and the golden fixtures under [`typescript/__tests__/golden/fixtures/`](../typescript/__tests__/golden/fixtures/). The golden fixtures are the machine-readable wire contract. Regenerate them with: ```bash make golden ``` --- ## Contents - [Wire Format Conventions](#wire-format-conventions) - [Error Conventions](#error-conventions) - [Session Tools](#session-tools) - [interactive_openroad_query](#interactive_openroad_query) - [interactive_openroad_exec](#interactive_openroad_exec) - [create_interactive_session](#create_interactive_session) - [terminate_interactive_session](#terminate_interactive_session) - [list_interactive_sessions](#list_interactive_sessions) - [inspect_interactive_session](#inspect_interactive_session) - [get_session_history](#get_session_history) - [get_session_metrics](#get_session_metrics) - [grep_session_output](#grep_session_output) - [Report Image Tools](#report-image-tools) - [list_report_images](#list_report_images) - [read_report_image](#read_report_image) - [ORFS Metrics Tools](#orfs-metrics-tools) - [read_orfs_metrics](#read_orfs_metrics) - [Flow Run Tools](#flow-run-tools) - [run_orfs_stage](#run_orfs_stage) - [get_orfs_job](#get_orfs_job) - [cancel_orfs_job](#cancel_orfs_job) - [Session Lifecycle Notes](#session-lifecycle-notes) --- ## Wire Format Conventions All tool responses carry a single MCP content item of type `"text"` whose `text` field is a JSON string. **All JSON keys are snake_case** — the server converts camelCase models at the boundary before serialising. `isError` is never set on any tool response; errors are signalled inside the JSON payload itself. Every result type has a nullable `error` field: ``` "error": null // success "error": "" // failure — human-readable or error-code string ``` --- ## Error Conventions ### Normal Errors All tools return a JSON object. On failure the `error` field is non-null and the rest of the payload is either zero-valued or `null`. Example (blocked command): ```json { "output": "", "session_id": "sess-0001", "timestamp": "2026-01-01T00:00:00", "execution_time": 0, "command_count": 0, "buffer_size": 0, "error": "CommandBlocked: 'exit'", "message": "Command blocked: 'exit' is not on the OpenROAD allowlist.\nFull command: 'exit'" } ``` The `message` field is present **only** on blocked-command responses; it contains the human-readable explanation alongside the machine-readable `error` code. ### Image-tool Error Codes `list_report_images` and `read_report_image` use structured error codes in the `error` field: | Code | Meaning | |------|---------| | `ValidationError` | Bad `platform`, `design`, path traversal attempt, or empty segment | | `RunNotFound` | The run directory does not exist | | `InvalidImageName` | `image_name` does not end in `.webp` | | `ImageNotFound` | The named file is not present in the run directory | | `NotAFile` | The path exists but is not a regular file | | `FileTooLarge` | Image exceeds the 50 MB on-disk limit | | `UnexpectedError` | Any other failure | --- ## Session Tools ### `interactive_openroad_query` Execute a **read-only** OpenROAD command. The whitelist is default-deny: only `READONLY_PATTERNS` (`report_*`, `get_*`, `check_*`, `sta`, `help`, `version`, and a set of safe Tcl built-ins) are accepted. Everything else is rejected with `CommandBlocked`. See [SECURITY.md](SECURITY.md) for full whitelist details. | Parameter | Type | Required | Default | |-----------|------|----------|---------| | `command` | string | **yes** | — | | `session_id` | string | no | (auto-generates new session) | | `timeout_ms` | integer | no | `30000` (`OPENROAD_COMMAND_TIMEOUT`) | **Annotations:** - `readOnlyHint: true` - `destructiveHint: false` - `idempotentHint: false` - `openWorldHint: false` **Response shape** (`interactive_exec_result_success.json`): ```json { "output": "OpenROAD v2.0", "session_id": "sess-0001", "timestamp": "2026-01-01T00:00:00", "execution_time": 1.5, "command_count": 3, "buffer_size": 131072, "truncated": false, "bytes_discarded": 0, "total_bytes": 13, "error": null } ``` | Field | Meaning | |-------|---------| | `output` | Everything OpenROAD wrote for this command, ANSI-stripped | | `session_id` | The session used (auto-created if none was passed) | | `execution_time` | Seconds spent on this command | | `command_count` | Commands executed in this session so far | | `buffer_size` | The session buffer's capacity in characters | | `truncated` | `true` when output exceeded the buffer and its head was discarded | | `bytes_discarded` | Characters dropped from the **start** of the output | | `total_bytes` | Raw characters the command produced, before ANSI cleaning | > **Truncation warning.** Output larger than the session buffer loses its **beginning**, not its > end. When `truncated` is `true` the result is a **partial answer**: the retained text may start > mid-line, and any error or warning printed before the cut is not in `output` and is not > reflected in `error`. A truncated result also carries a `[TRUNCATED: ...]` banner at the head of > `output`. Narrow the command and re-run rather than analysing what came back. > **Session accumulation warning.** Omitting `session_id` creates a session and **leaves it > running**. Capture the returned `session_id` and reuse it, or you will accumulate sessions > until `OPENROAD_MAX_SESSIONS` (default 50) is reached and new commands fail. --- ### `interactive_openroad_exec` Execute a **state-modifying** OpenROAD command. The whitelist is default-allow: only `BLOCKED_COMMANDS` (`quit`, `socket`, `load`, `glob`, `fconfigure`, `chan`, `vwait`, `rename`, `after`, `subst`) are rejected. Read-only commands such as `report_wns` are also accepted here — use `interactive_openroad_query` when you want to keep state changes visible and auditable. | Parameter | Type | Required | Default | |-----------|------|----------|---------| | `command` | string | **yes** | — | | `session_id` | string | no | (auto-generates new session) | | `timeout_ms` | integer | no | `30000` (`OPENROAD_COMMAND_TIMEOUT`) | **Annotations:** - `readOnlyHint: false` - `destructiveHint: true` - `idempotentHint: false` - `openWorldHint: false` The response shape is identical to `interactive_openroad_query`. Long-running flow commands routinely exceed 30 s — pass a larger `timeout_ms` for placement, CTS, and routing. #### Rendering a layout or timing-path image from a session A session is headless, but Qt renders offscreen, so `save_image` works — the GUI-only commands (`gui::show_worst_path`, `gui::set_display_controls`) just need a GUI event loop to exist first. `gui::show