dide-mcp is the Model Context Protocol (MCP) service compiled directly into Digital IDE's digital-server (digital-server.exe on Windows) binary. By connecting MCP-compatible AI agents—such as Codex, Claude Code, Claude Desktop, or Cursor—to dide-mcp, the agent can inspect and manage project hierarchy, launch interactive simulations, orchestrate and diff VS Code waveform views, edit Block Designs, drive Vivado/Efinity toolchains, and perform static/dynamic RTL root-cause analysis (including X-state and active-driver tracing).

Quick navigation: Architecture & Operating Modes · Installation & Client Setup · Project & Toolchain Tools (10) · VS Code Waveform Control & Auto-Diff (4) · Block Design & IP Configuration (7) · Waveform & RTL Root-Cause Analysis (34) · Standalone Efinix Tools (7) · Typical AI Workflows

---

Video Demonstration

Real dide-mcp tool calls drive VS Code throughout this five-part demonstration. Manual file navigation uses the Explorer sidebar.

Video time	Demonstration
00:00	Locate the backend and endpoint, configure the client, and verify the connection
00:48	Read the project hierarchy and open the RTL netlist
01:42	Run an interactive simulation, create a virtual bus and groups, and focus the first mismatch
02:41	Generate diagnostic VCDs, trace values and X causes across modules, and populate Analysis
04:19	Add IP, a port and a connection, arrange and fit the canvas, then save the design

The example flips bit zero at 1250 ns (expected 123, actual 122), traces the mismatch and a multi-driver X conflict using VCDs generated with Icarus Verilog, and finally creates, lays out, and saves a .bd Block Design.

Note: signal paths in the live waveform viewer can differ from those in an offline analysis session; always use the paths returned by each tool.

1. Architecture and Operating Modes

digital-server dide-mcp exposes tools to AI clients over standard MCP stdio transport and supports two operating modes depending on its launch arguments:

AI Agent (Codex / Claude / Cursor)
  │  MCP stdio
  ▼
digital-server dide-mcp --connect <endpoint.json>
  │  Loopback WebSocket (ws://127.0.0.1:<port> + 64-hex-digit token authentication)
  ▼
VS Code Digital IDE Daemon
  ├─ WaveToolRuntime (Waveform / Slang static netlist sessions, standalone Efinix tasks)
  └─ WaveUiBridge ──► VS Code Extension Host
                        ├─ Project Manager / Architecture / Netlist Webview
                        ├─ Live Interactive Simulation & Built-in Waveform Webview
                        ├─ Block Design (.bd) Visual Editor
                        └─ HARD (Vivado / Efinity) & SOFT (XSCT) Session Managers

Mode	Launch Arguments	Exposed Tools	Capabilities and Use Cases
Plugin Bridge Mode (Recommended) (--connect)	digital-server dide-mcp --connect <endpoint.json>	All 62 tools	Attaches to an open VS Code workspace. Reloads endpoint.json on each call so the client survives extension reloads automatically. Provides full control over VS Code UI views (projects, interactive simulation, live waveform Webviews, Block Design, HARD/SOFT builds) as well as offline waveform and RTL analysis.
Standalone Headless Mode (Standalone)	digital-server dide-mcp [--session <dir|session.json>]	43 tools (34 waveform/RTL analysis + 7 Efinix CLI + 2 task polling)	Runs without VS Code in CLI or CI environments. Inspects .vcd / .fst / .ghw / .fsdb waveforms and RTL filelists for static fan-in/fan-out, signal transitions, two-waveform diffs, X-state root-cause tracing, and standalone Efinix builds/programming.

---

2. Installation and Client Setup

2.1 One-Step AI Auto-Installation Prompt (Recommended)

Start your AI agent (Codex, Claude Code, Cursor, etc.) in the project workspace and send the following prompt verbatim. The agent will locate digital-server and the active endpoint.json automatically:

Install and configure dide-mcp for my current Digital IDE project, then verify the connection.

Locate all required paths directly from the current terminal environment, working directory, VS Code extensions directory, and globalStorage directory without asking me to fill in paths manually:

1. Identify the current project directory (prefer the current working directory or a parent directory containing `.vscode/property.json`).
2. Locate the bundled `digital-server` executable inside the installed Digital IDE extension:
   - Prefer the `Digital Server executable` path from the active window's Output → Digital-IDE. If logs are unavailable, search `~/.vscode/extensions/sterben.fpga-support-*` or `~/.vscode-server/extensions/sterben.fpga-support-*` for the `resources/server/<platform>/<arch>/digital-server` (`digital-server.exe` on Windows) binary matching the active window.
   - `dide-mcp` is built into `digital-server`; do not run `npm install` or `pip install`.
3. Locate the active `endpoint.json` for this project:
   - Search inside VS Code globalStorage (Linux: `~/.config/Code/User/globalStorage/sterben.fpga-support` or `~/.vscode-server/data/User/globalStorage/sterben.fpga-support`; Windows: `%APPDATA%/Code/User/globalStorage/sterben.fpga-support`; macOS: `~/Library/Application Support/Code/User/globalStorage/sterben.fpga-support`) or the latest VS Code `logs/` `output_logging_*/` directory for `endpoint.json`.
   - When multiple endpoints exist, select the `endpoint.json` matching the current project workspace (do not print the authentication token).
4. Register the MCP server in your client configuration:
   - Command: absolute path to `digital-server`.
   - Args: `["dide-mcp", "--connect", "<absolute/path/to/endpoint.json>"]`.
   - For Codex: run `codex mcp add dide-mcp -- "<digital-server-path>" dide-mcp --connect "<endpoint.json-path>"` and verify with `codex mcp get dide-mcp`.
   - For other clients (Claude Code, Cursor, Claude Desktop, etc.), merge the same `command` and `args` into the client's MCP config file.
5. Verify the connection:
   - If tools reload in the current session, call `list_wave_views` and `get_project` (read-only: do not modify HDL or start simulations/builds).
   - If a session restart is required to load new MCP servers, print the updated configuration path and remind me to reopen the session and run `list_wave_views` and `get_project`.

2.2 Manual Configuration

1. Copy paths from VS Code: Open the project folder in VS Code, ensure digital-ide.mcp.enabled is true (default), and check Output → Digital-IDE for:
   • Digital Server executable: /path/to/digital-server
   • DIDE MCP ready ... Endpoint: /path/to/endpoint.json
2. Register with Codex CLI:

   codex mcp add dide-mcp -- "/absolute/path/to/digital-server" dide-mcp --connect "/absolute/path/to/endpoint.json"
   codex mcp get dide-mcp

3. Example for clients accepting mcpServers JSON (follow the client's actual config location and enclosing fields; preserve other services when merging):

   {
     "mcpServers": {
       "dide-mcp": {
         "command": "/absolute/path/to/digital-server",
         "args": [
           "dide-mcp",
           "--connect",
           "/absolute/path/to/endpoint.json"
         ]
       }
     }
   }

   • Security and lifecycle: endpoint.json contains a 64-character hexadecimal authentication token; the backend listens on 127.0.0.1 only. Do not publish the token or commit the file to Git. The client and bridge must be able to access paths on the backend's host. Keep the corresponding VS Code workspace window open while using --connect.

---

3. Module 1: Project Management, Simulation, and Toolchains (10 Tools)

Provided by dide_tools.json in --connect mode. Long-running operations return a task_id immediately; poll get_task to inspect completion status and artifacts.

Tool Name	Required Parameters	Optional Parameters	Description and Boundaries
get_project	None	workspace_path: string include_hierarchy: boolean (false) top: string	Reads .vscode/property.json, compact HDL module counts, and HARD / SOFT session states. Set include_hierarchy=true for the full elaborated instance tree (optionally rooted at top without modifying property.json). Read-only.
manage_project	action	workspace_path: string action: "generateProperty" | "setSrcTop" | "setSimTop" | "addFile" | "delFile" | "setLibraries" top: string file_path: string kind: "src" | "sim" project_name: string toolchain: "xilinx" | "efinity" mode: "remote" common: string[] custom: string[]	Runs a project configuration command and returns task_id: - generateProperty: Initializes .vscode/property.json (project_name, toolchain); - setSrcTop / setSimTop: Sets design or simulation top module (top); - addFile / delFile: Adds or excludes a source/simulation file (delFile only excludes the file in property.json and never deletes disk files); - setLibraries: Updates library.hardware.common and custom references.
filelist	action, file_path	workspace_path: string action: "import" | "export" file_path: string kind: "src" | "sim" scope: "src" | "sim" | "all" apply: boolean (false) relative_paths: boolean	Imports or exports .f / .fl / .filelist files (returns task_id). import defaults to apply=false (preview only); set apply=true to write merged sources, includeDirs, and defines to property.json.
open_netlist	file_path, module_name	workspace_path: string mode: "before" | "after" | "RTL"	Synthesizes module_name with the bundled Yosys frontend and opens the interactive Netlist Webview in VS Code (returns task_id).
validate_toolchains	None	workspace_path: string	Runs Validate Configured Toolchains on explicitly configured tool paths in settings.json (returns task_id).
start_simulation	file_path, module_name, backend	workspace_path: string backend: "iverilog" | "verilator" | "cxxrtl" | "vcs" | "modelsim" | "questa" dry_run: boolean	Compiles and launches an interactive HDL simulation, automatically opening its VS Code Waveform Webview. Poll get_task for compilation logs and the resulting view_id. dry_run=true prepares the command plan only.
control_simulation	action	view_id: string (defaults to active view) action: "status" | "run_for" | "pause" | "stop" duration_ns: integer ($\ge 1$)	Controls the live simulator attached to a VS Code waveform view: run_for advances simulation by duration_ns, pause / stop pauses or closes the session, and status verifies the actual simulator state.
run_toolchain	domain, action	workspace_path: string domain: "hardware" | "software" action: "launch" | "refresh" | "build" | "synth" | "impl" | "bitstream" | "simulateCli" | "simulateGui" | "gui" | "exit" | "gdbStop" dry_run: boolean	Executes HARD Options (launch, refresh, build, synth, impl, bitstream, simulateCli, simulateGui, gui, exit) or SOFT Options (launch, build, exit, gdbStop) via the plugin session manager (returns task_id). Board programming and Flash writes are intentionally excluded for hardware safety.
get_task	task_id	task_id: string	Reads asynchronous task state (running / completed / failed / cancelled), elapsed time, output artifacts, and stdout/stderr tail logs.
cancel_task	task_id	task_id: string	Requests cancellation of a running HARD or SOFT toolchain task; poll get_task to confirm cleanup.

---

4. Module 2: VS Code Live Waveform Control and Auto-Comparison (4 Tools)

Provided by mcp_vscode_tools.json and show_waveform_analysis, enabling the AI agent to control the actual VS Code Waveform Webview visible to the user:

Tool Name	Parameters	Capabilities
open_vscode_waveform	file_path?: string	Opens a .vcd, .fst, .ghw, or .dws file in the VS Code Waveform Webview (or focuses the active waveform if file_path is omitted), returning view_id and the rendered state.
get_vscode_waveform_state	view_id?: string	Returns the active waveform's displayed signals, radix formats, colors, groups, virtual buses, main cursor, viewport, comparison highlights, and open panels.
configure_vscode_waveform	- view_id?: string - signals?: Array<{ path, format?: "binary"|"octal"|"hex"|"unsigned"|"signed", color? }> (max 256) - groups?: Array<{ id, name, members: string[] }> - buses?: Array<{ id, name, members: string[], format? }> (members in MSB-to-LSB order, min 2) - comparison?: { expected: string, actual: string, focus_first_difference?: boolean } - clear_comparison?: boolean - cursor?: { time: string, unit: "s"|"ms"|"us"|"ns"|"ps"|"fs" } - viewport?: { from: string, to: string, unit } - annotation?: string (max 4000 chars)	Applies a complete debugging layout to the VS Code Waveform Webview and returns the verified state after execution: 1. Signal, Group, and Virtual Bus Layout: Populates signals with radixes/colors, concatenates MSB-to-LSB buses, and organizes groups; 2. Automated Signal/Bus Comparison (comparison): Compares expected against actual across the waveform, highlights mismatch intervals in red, and (with focus_first_difference=true by default) inserts a marker and centers the cursor and viewport at the exact first mismatch timestamp; 3. Analysis Notes (annotation): Writes plain-language diagnostic findings into the waveform's collapsible Analysis sidebar.
show_waveform_analysis	view_id?: string	Reveals the collapsible Analysis sidebar in the active VS Code waveform view.

signals replaces the displayed layout; groups and buses require signals in the same call. Cursor-only or annotation-only calls can omit signals to preserve existing tracks. Read the first mismatch from state.comparison.first_difference (with time and unit), not first_difference_time. These tools do not automatically save a .dws; save it explicitly in the UI.

---

5. Module 3: Block Design Editor and IP Configuration (7 Tools)

For workspaces whose property.json toolChain supports Block Design (such as "xilinx" .bd designs), mcp_block_tools.json lets the agent inspect IP catalogs, edit the live diagram, run auto-layout, and validate IP parameters.

• Optimistic concurrency (expected_revision): Every mutating call (edit_block_design, configure_block_ip, save_block_design) requires the exact expected_revision returned by the latest read or edit, preventing the agent from overwriting concurrent user edits.

Tool Name	Required Parameters	Description and Supported Operations
get_block_design_capabilities	None (workspace_path?)	Queries Block Design support for the active toolChain, returning backend, file_extensions, supported edit_operations, and component_id_format. Call this first.
open_block_design	file_path	Opens an existing .bd file or creates a new unvalidated design (create=true with name, never overwriting existing files) in the VS Code Block Design Webview, returning state and revision.
get_block_design_state	file_path	Reads the live Block Design graph: cells (cell_id), ports, bus interfaces (@bus:<id>), coordinates, nets, local diagnostics, and current revision.
get_block_ip_catalog	file_path	Searches the offline IP catalog (query, offset, limit) or inspects a specific component_id (VLNV on Xilinx) for its default ports, interfaces, and parameters without spawning vendor processes.
edit_block_design	file_path, expected_revision, operation	Applies one undoable edit operation to the live graph and returns the new revision and changed_id. Supported operation.type values: - "add_ip": Adds an IP instance by component_id (name, optional x, y, scope_path); - "add_port": Adds a top-level port or interface (name, direction: "input"|"output"|"inout", optional width, interface_id, role, x, y); - "connect": Connects pins or @bus:<id> interfaces (source_id, source_port, target_id, target_port, optional net_name); - "rename" / "move" / "remove": Renames (id, name), moves (id, x, y), or deletes (id) an object; - "auto_layout": Computes automatic block placement and orthogonal routing; - "undo" / "redo": Undoes or redoes the last graph edit.
configure_block_ip	file_path, expected_revision, cell_id, action	Inspects or updates parameters on cell_id: - "inspect": Reads offline parameter metadata and current values without saving; - "apply": Writes string values to the instance and saves the draft; - "validate": Invokes the configured vendor validator (e.g., Vivado) and returns task_id (poll get_task for the validation result). Saving resets editor undo history.
save_block_design	file_path, expected_revision	Saves and reparses the current Block Design and layout sidecars, returning saved: true and the updated revision (call configure_block_ip(action="validate") when vendor parameter validation is needed).

---

6. Module 4: Offline Waveform Queries and RTL Root-Cause Tracing (34 Tools)

Available in both --connect and standalone modes (compatible with the wave-mcp contract). These tools combine a built-in Slang SystemVerilog/Verilog elaborator (netlist/maps.json) with a high-speed FST / VCD / GHW / FSDB waveform engine.

6.1 Session Initialization and Format Conversion (7 Tools)

Initialize a session with prepare_session, open_static_session, or open_session before calling the query tools in Sections 6.2–6.4:

Tool Name	Key Parameters	Description
prepare_session	out_dir, wave_path, top?, filelist? / filelist_path?, incdirs?, defines?, session_id?, fst_path?, mode?, fsdb_scopes?, fsdb_signals_file?	Creates an analysis session from a waveform file (.fst / .vcd / .ghw / .fsdb) and the RTL filelist, include directories, and defines. Converts VCD/FSDB to indexed FST when needed, writes session.json, and activates the session.
open_static_session	out_dir, top?, filelist / filelist_path, incdirs?, defines?	Creates a static-only RTL analysis session without a waveform file.
open_session	session_path, session_id?	Opens an existing session.json manifest or session directory.
session_info	session_id?	Returns top module, waveform time range, timescale, module/file counts, and consistency warnings.
close_session	session_id?	Closes and releases a session.
convert_vcd_to_fst	vcd_path, fst_path?, mode?, parallel?	Converts VCD to indexed FST; mode is speed, balanced or size.
convert_fsdb_to_fst	fsdb_path, fst_path?, scopes?, signals_file?	Converts .fsdb to .fst (optionally filtered by scopes or signals_file).

6.2 Hierarchy and Source File Queries (8 Tools)

Tool Name	Key Parameters	Description
list_modules	name_contains?, session_id?	Filters module definitions by name substring.
list_child_instances	instance_full_path?, number_of_levels?, max_scopes?, filter_noise?, session_id?	Queries child hierarchy under an instance.
instances_of_module	module, session_id?	Finds instance paths for a module.
instances_of_module_matching	module, string_in_instance_name, session_id?	Filters a module's instances by instance-name substring.
scope_info	scope_full_path, session_id?	Queries an instance scope.
list_files	session_id?	Lists RTL files in the session.
find_files	file_short_name, return_exact_names?, session_id?	Searches session files by short name.
modules_in_file	full_file_path, session_id?	Queries module definitions in a file.

6.3 Signal Values and Two-Waveform Diff (6 Tools)

Tool Name	Key Parameters	Description
list_signals	instance_full_path, filter_by_name?, filter_by_type?, max_signals?, aggregate_buses?, underscore_style?, session_id?	Lists signals in an instance, optionally filtered by name and type.
signal_info	full_path, session_id?	Queries signal information.
signal_value_at	full_path, time_as_string, session_id?	Queries a signal at a time such as time_as_string="1250ns".
signal_values	full_path, max_number_of_values?, session_id?	Returns signal transitions.
signal_values_in_range	full_path, start_time_as_string, end_time_as_string, max_number_of_values?, session_id?	Queries signal values in a time window.
diff_waveforms	fst_a, fst_b, scope?, signals?, clock?, after?	Compares two FST waveform files and returns the earliest divergence and coverage information. Supports filtering by scope/signals, sampling on clock rising edges, or using after to skip reset.

6.4 Static Connectivity and Dynamic Driver / X-State Root-Cause Tracing (8 Tools)

Tool Name	Key Parameters	Description
signal_connectivity	full_path, session_id?	Queries connections across module ports.
signal_drivers	full_path, session_id?	Queries static drivers and source locations.
signal_loads	full_path, session_id?	Queries static loads reading the signal.
signal_fanin	signal_path, transitive?, session_id?	Queries upstream fan-in, optionally transitively.
active_drivers	signal_full_path, time_as_string, session_id?	Evaluates active drivers at a waveform time; contention can return driver_conflict.
driver_contributors	driver_unique_id, session_id?	Queries contributors by the unique ID returned by a driver query, not by signal / time.
trace_value	signal_path, time_point, max_depth?, session_id?	Traces values across ports to inputs, constants or sequential boundaries, returning source locations.
trace_x	signal_path, time_point, max_depth?, session_id?	Traces backward from a signal carrying X/Z bits at time_point along unknown-valued upstream branches or multi-driver conflicts (driver_conflict) to locate the root-cause RTL assignment (requires a four-state waveform and complete static maps).

6.5 Standalone Lightweight Web Waveform Views (5 Tools)

For headless CLI sessions without VS Code, open_wave_view, update_wave_view, get_view_state, list_wave_views, and close_wave_view manage local browser waveform views (in --connect mode, prefer open_vscode_waveform and configure_vscode_waveform).

---

7. Module 5: Standalone Efinix Build and Programming Tools (7 Tools)

Standalone Efinix tools run without VS Code to generate interfaces, run synthesis/place-and-route, and program boards. Generation, build, and board operations return a task_id for get_task; toolchain_path returns the executable path directly:

Tool	Required parameters	Optional parameters / behavior
efinity_interface_generate	None	config, defaults, pins, output_dir, package; generates interface artifacts from configuration or defaults and pins.
efinity_flow	project, stage, efinity_home, work_dir, timeout	stage is map or pnr; ordered options pass through to efx_run. Poll get_task for exit code, full log paths and reports; cancel_task terminates the process group.
efinix_read_idcode	serial, frequency_hz, timeout_ms	Reads the selected hardware IDCODE.
efinix_program_sram	serial, frequency_hz, timeout_ms, idcode, bitstream	dry_run?; checks IDCODE before Titanium SRAM programming.
efinix_deconfigure	serial, frequency_hz, timeout_ms, idcode	dry_run?; puts Titanium into its PROGRAM deconfigured state.
efinix_program_flash	serial, frequency_hz, timeout_ms, idcode, image, bridge, sram, readback	dry_run?; actual Flash writes require confirm_flash=true. Programs, verifies readback and restores SRAM.
toolchain_path	name	Returns the cached executable path for riscv-wch-elf-gdb, riscv-wch-elf-nm or riscv-wch-elf-gcc.

---

8. Typical AI Agent Workflows

Once connected to dide-mcp, you can ask your AI agent to combine the tools above for simulation comparison, root-cause tracing, and Block Design editing:

Scenario 1: Simulate, Compare and Explain the First Mismatch

Prompt: "Read the project and run compare_tb in user/sim/compare_tb.sv with a configured simulator. Display expected and actual data as unsigned decimal, build a virtual {inject_fault, rst_n} bus and groups, compare the data and focus the first mismatch. Analyze a diagnostic VCD generated from the same RTL and write the cause into Analysis."

1. Call get_project(include_hierarchy=true) to confirm the workspace and hierarchy. Confirm asynchronous open_netlist results with get_task.
2. Call start_simulation, poll get_task for view_id, request advancement with control_simulation(action="run_for", duration_ns=2000), and verify the actual simulator state with status.
3. Read available signal paths from get_vscode_waveform_state, then configure signals, buses, groups and comparison (use the paths returned by each respective tool, as live view prefixes can differ from offline session paths).
4. Read state.comparison.first_difference: the mismatch is found at 1250 ns (highlighting 1250–1350 ns), with expected 123 (0x7B) versus actual 122 (0x7A).
5. Generate a VCD with Icarus Verilog, pass wave_path, the RTL filelist, and top="compare_tb" to prepare_session, then call trace_value(signal_path="compare_tb.dut.u_stage.actual_data", time_point="1250ns") to trace the driver chain.
6. Use configure_vscode_waveform(annotation="...") and show_waveform_analysis to explain that inject_fault XORs bit zero.

Scenario 2: Explain Conflicting Drivers Producing X

Prompt: "Create a diagnostic session from four-state conflict.vcd and the same RTL. Trace conflict_tb.shared_bus at 1250ns and write the evidence into Analysis."

1. Call prepare_session with conflict.vcd, the complete RTL filelist and top="conflict_tb".
2. Call trace_x(signal_path="conflict_tb.shared_bus", time_point="1250ns", max_depth=12).
3. The trace returns active_driver_count=2, showing that two drivers in conflict_driver output 0 and 1 simultaneously; inspect the enable conditions for mutual exclusion.

Scenario 3: Edit and Save a Xilinx Block Design

Prompt: "Create user/bd/mcp_demo/mcp_demo.bd, find xlconstant, add constant_0 and an output port led, connect constant_0.dout → led, and auto-layout. Inspect parameters, apply CONST_VAL as string \"0\", and save the design."

1. Call get_block_design_capabilities, open_block_design(create=true, name="mcp_demo") and get_block_design_state.
2. Query get_block_ip_catalog(query="xlconstant") for xilinx.com:ip:xlconstant:1.1; read actual node and port IDs before editing.
3. Use edit_block_design for add_ip, add_port, connect and auto_layout, passing the latest expected_revision each time.
4. Call configure_block_ip(action="inspect"), then configure_block_ip(action="apply", values={"CONST_VAL":"0"}) and save_block_design.
5. Confirm saved=true, dirty=false, and the generated .bd and .layout.json sidecar files. To run vendor parameter validation as well, call configure_block_ip(action="validate") and poll get_task for the validation result.