Tool

Parameters

Description

host_status

None

Returns the agent version and uptime, host CPU/memory/disk information, configured tool probes, active sessions, active jobs, and job-slot usage. This is the recommended first call.

agent_ensure

force: bool = false

Deploys or upgrades the remote agent. force=true restarts the daemon and closes active sessions; durable jobs are unaffected.

Tool

Parameters

Description

session_open

tool?: str, cwd?: str

Starts a long-lived tool interpreter and returns a session_id. tool selects a configured tool version; cwd is the remote process working directory and can usually be omitted.

session_list

None

Lists live sessions, including their idle, busy, or dead state, PID, idle time, command count, and log path.

session_close

session_id: str

Closes a session and releases its memory. Interpreter state that has not been written to disk is lost.

tcl_eval

session_id: str, script: str, timeout_s: float = 120, allow_blocking: bool = false

Executes Tcl in an existing session and returns rc, result, log, errorinfo, and elapsed time. Long-running synthesis, implementation, and bitstream commands are rejected by default and should be submitted as jobs. exit, quit, and start_gui are always rejected.

tcl_help

session_id: str, command: str

Runs help <command> in the active Vivado version and returns its actual syntax and option documentation.

Tool

Parameters

Description

sync_status

workspace?: str

Returns the local Git HEAD and dirty-file list together with the exact commit currently active on the build server.

sync_push

workspace?: str, paths?: list[str], dry_run: bool = false

Synchronizes the local worktree to the build server. Omitting paths captures all changes; providing it limits the overlay on HEAD to those paths. dry_run=true reports status only. The user's branch and staging area are not modified.

sync_pull

paths: list[str], workspace?: str

Pulls selected remote artifacts or directories into the local workspace using rsync over SSH. Passing the configured build directory pulls the complete build tree. Paths must be workspace-relative, and --delete is never used.

file_read

path: str, workspace?: str, offset: int = 0, limit: int = 12000

Reads a bounded UTF-8 segment from a remote workspace file. Returns next_offset, total file size, and truncation status. Each read is limited to 64 KiB.

file_grep

pattern: str, workspace?: str, glob: str = "**/*", limit: int = 200

Searches the remote source and build trees with a regular expression and returns relative paths, line numbers, and matching text. Results are capped at 1,000 entries, and the number of scanned files is bounded.

Tool

Parameters

Description

project_create

path: str, part?: str, board?: str, top?: str, target_language: str = "Verilog", workspace?: str, tool?: str

Creates and opens an .xpr inside the workspace, returning the session_id that holds the project lock. Exactly one of part or board is required. target_language accepts Verilog or VHDL.

project_open

path: str, workspace?: str, tool?: str

Opens an existing .xpr in a new session and acquires its single-writer lock. The call is rejected if another session owns the project.

project_close

session_id: str

Closes the current project and releases its single-writer lock without terminating the Vivado session.

project_info

session_id: str, workspace?: str

Returns the project path, part, board, top, target language, source inventory, run status, IP inventory, and residual lock information. File paths are converted to workspace-relative paths.

sources_add

session_id: str, files: list[str], workspace?: str, type: str = "auto", library?: str, scoped_to?: str

Adds HDL, constraint, or data files to the current project. Vivado FILE_TYPE, library, and SCOPED_TO_REF values may be set explicitly.

sources_remove

session_id: str, files: list[str], workspace?: str

Removes file references from the project without deleting the files from disk.

sources_list

session_id: str, workspace?: str

Lists files registered with the current project, including their type and library.

set_top

session_id: str, top: str

Sets the top-level module or entity for the current source fileset.

set_generics

session_id: str, generics: dict[str, str]

Sets generic or parameter overrides on the current fileset.

add_include_dirs

session_id: str, directories: list[str], workspace?: str

Appends workspace-relative directories to the Verilog/SystemVerilog include path.

set_run_strategy

session_id: str, run: str, strategy: str

Sets the Vivado strategy for a named synthesis or implementation run.

set_property

session_id: str, object: str, name: str, value: str, workspace?: str

Sets one Vivado property on a typed object. object accepts project, fileset, run:<name>, ip:<name>, or file:<path>. Values for Tcl pre/post hooks are resolved as workspace paths.

ip_create

session_id: str, module_name: str, vlnv: str, config?: dict[str, str]

Creates a Vivado IP instance and optionally sets CONFIG.* properties. The CONFIG. prefix is added automatically when omitted.

ip_upgrade

session_id: str, ips: list[str]

Upgrades selected IP instances to the current catalog version.

ip_generate

session_id: str, ips: list[str]

Runs generate_target all for the selected IP instances.

flow_run

sources: list[str], part: str, top: str, xdc?: list[str], target: str = "synth", workspace?: str, tool?: str, idempotency_key?: str, timeout_s: float = 0

Starts a durable non-project job. target accepts synth, impl, or bitstream; outputs are written under build/flows/<job_id>. timeout_s=0 disables the wall-clock timeout.

project_unlock

path: str, workspace?: str

Removes stale Vivado .lck files left after a process crash. The operation is rejected while any active session owns the project.

Tool

Parameters

Description

build

project: str, target: str = "bitstream", run?: str, jobs?: int, reset: bool = false, strategy?: str, idempotency_key?: str, tool?: str, timeout_s: float = 0, workspace?: str

Starts an independent durable job for an existing .xpr and returns its job_id immediately. target accepts synth, impl, bitstream, or flow; non-project builds should normally use flow_run. jobs defaults to the host configuration, and timeout_s=0 disables the wall-clock timeout.

job_list

limit: int = 100

Lists durable jobs in reverse creation order.

job_status

job_id: str

Returns job state, the current step and phase, a monotonic progress estimate, elapsed time, message counts, the log tail, and the latest event sequence number.

job_events

job_id: str, since_seq: int = 0, limit: int = 200

Reads events after since_seq from the append-only event stream. Use the returned last_seq as the next cursor to avoid duplicates or gaps.

job_wait

job_id: str, timeout_s: float = 600, since_seq?: int

Long-polls a job until it reaches a terminal state, emits an important event, or times out. Each call is limited to 3,600 seconds and uses MCP progress notifications to remain visible to the client.

job_cancel

job_id: str

Cancels a queued or running job and sends a termination signal to its dedicated process group. Calling it on a terminal job is safe.

job_logs

job_id: str, tail: int = 100, grep?: str

Returns a bounded job log tail, optionally filtered by a regular expression. It never returns an entire multi-megabyte Vivado log.

messages

job_id: str, min_severity: str = "warning"

Aggregates log messages by Vivado message ID and returns the severity, occurrence count, and one example. min_severity accepts warning, critical_warning, error, or fatal.

job_artifacts

job_id: str

Lists DCP, bitstream, report, XSA, LTX, and related job artifacts. Workspace-backed jobs return workspace-relative paths.

Tool

Parameters

Description

report_utilization

source: str, hierarchical: bool = false, cells?: list[str], workspace?: str, tool?: str

Returns used, available, and percentage values for LUT, LUTRAM, FF, BRAM, URAM, DSP, IO, and BUFG resources. Zero-use resources are omitted by default. Hierarchical output and cell filters are supported.

report_timing_summary

source: str, max_paths: int = 5, workspace?: str, tool?: str

Returns WNS, TNS, WHS, THS, pulse-width metrics, failing endpoint counts, per-clock-domain statistics, clock frequencies, and compact worst-path summaries. max_paths must be between 1 and 20.

report_timing_paths

source: str, from_endpoint?: str, to_endpoint?: str, through?: str, nworst: int = 5, delay_type: str = "max", detail: str = "summary", workspace?: str, tool?: str

Queries targeted timing paths. Endpoint arguments use Vivado object-matching patterns. delay_type accepts max or min; detail accepts summary or full. To bound response size, detail="full" requires nworst=1.

report_clocks

source: str, workspace?: str, tool?: str

Returns clock periods, target frequencies, WNS-derived achieved frequencies, and timing metrics for each clock domain.

report_drc

source: str, workspace?: str, tool?: str

Aggregates DRC violations by rule and returns the rule, severity, count, description, and one example.

report_methodology

source: str, workspace?: str, tool?: str

Aggregates Vivado methodology findings by rule without returning the full report.

report_cdc

source: str, workspace?: str, tool?: str

Aggregates clock-domain crossing findings by rule and severity.

report_power

source: str, workspace?: str, tool?: str

Returns total on-chip, dynamic, and static power, junction temperature, confidence, and component-level power data.

report_diff

a: str, b: str, kind: str, workspace?: str, tool?: str

Compares normalized reports from two jobs or DCPs. kind accepts utilization or timing and returns only semantic resource or timing deltas. DCP paths must belong to the same workspace.