MCP Server

pyadi-dt includes an MCP server (adidt-mcp) that exposes device tree generation, linting, and inspection tools to AI assistants like Claude and Cursor.

Installation

Install with the mcp extra:

pip install "adidt[mcp]"

This pulls in FastMCP as the server framework.

Running the server

Start the server directly:

adidt-mcp

Or configure it in your Claude Desktop / Cursor MCP settings:

{
  "mcpServers": {
    "pyadi-dt": {
      "command": "adidt-mcp"
    }
  }
}

For Claude Code, add to .claude/settings.json:

{
  "mcpServers": {
    "pyadi-dt": {
      "command": "adidt-mcp"
    }
  }
}

Available tools

generate_devicetree

Generate a complete device tree from a Vivado XSA archive. Runs the full XSA pipeline: sdtgen, topology parse, node build, merge, and optional visualization.

Parameters:

Parameter	Type	Description
`xsa_path`	str (required)	Path to the Vivado `.xsa` archive.
`output_dir`	str (required)	Directory where output files are written.
`config_json`	str	JSON string with JESD, clock, and datapath configuration. Typically from `pyadi-jif` solver output. Defaults to `"{}"`.
`profile`	str	Built-in profile name (e.g. `"ad9081_zcu102"`, `"fmcdaq2_zc706"`). Auto-detected when omitted.
`output_format`	str	`"default"` for overlay + merged DTS, or `"petalinux"` to additionally generate `system-user.dtsi` and `device-tree.bbappend`.
`emit_report`	bool	Generate an HTML topology report. Default `True`.
`emit_clock_graphs`	bool	Generate DOT/D2 clock-tree diagrams. Default `True`.
`sdtgen_timeout`	int	Max seconds for sdtgen. Default `300`.
`lint`	bool	Run structural DTS linter. Default `False`.
`strict_lint`	bool	Fail on lint errors. Default `False`.
`reference_dts`	str	Path to a reference DTS for parity checking.
`strict_parity`	bool	Fail on missing roles/links/properties. Default `False`.

Returns: Dict with paths to generated artifacts:

overlay — .dtso overlay file
merged — merged .dts file
dts_path — alias for merged
report — HTML topology report (when emit_report=True)
clock_dot, clock_d2 — clock-tree diagrams
pl_dtsi_path — path to sdtgen-generated pl.dtsi
system_user_dtsi — PetaLinux dtsi (when output_format="petalinux")
diagnostics — lint JSON (when lint=True)

Example:

{
  "xsa_path": "/path/to/design.xsa",
  "output_dir": "/tmp/dt_output",
  "profile": "fmcdaq2_zc706",
  "config_json": "{\"jesd\": {\"rx\": {\"L\": 4, \"M\": 2}}}"
}

list_xsa_profiles

List all available built-in XSA board profiles.

Parameters: None.

Returns: Sorted list of profile name strings.

Example response:

["ad9081_zcu102", "ad9084_vcu118", "adrv9009_zc706", "fmcdaq2_zc706"]

show_xsa_profile

Show the full configuration for a named profile.

Parameters:

name (str, required) — Profile name from list_xsa_profiles.

Returns: Profile dict with defaults key containing board configuration, clock settings, and JESD parameters.

read_dt_property

Read a device tree property from a DTS/DTB file or the running system.

Parameters:

Parameter	Type	Description
`node_name`	str (required)	Node name or compatible string to look up.
`property_name`	str	Specific property to read. All properties returned when omitted.
`filepath`	str	Path to a `.dts` or `.dtb` file. Reads from the running system (local sysfs) when omitted.

Returns: Dict with property values, or all properties when property_name is omitted.

lint_devicetree

Run the structural DTS linter on a generated DTS file. Checks for unresolved phandle references, clock-cell mismatches, duplicate SPI chip selects, and missing compatible strings.

Parameters:

dts_path (str, required) — Path to the .dts file to lint.

Returns: Dict with diagnostics list and summary counts by severity (error, warning, info).

Example response:

{
  "diagnostics": [
    {
      "severity": "warning",
      "rule": "unresolved_phandle",
      "node": "/axi/spi@e0006000/ad9680@2",
      "message": "Reference to non-existent label 'gpio'"
    }
  ],
  "summary": {"errors": 0, "warnings": 1, "info": 0, "total": 1}
}

Workflow examples

Generate a device tree with Claude

When the MCP server is configured, you can ask Claude:

“Generate a device tree for my AD9081 + ZCU102 design. The XSA is at /home/user/vivado/design.xsa and the pyadi-jif config is in /home/user/cfg.json.”

Claude will call generate_devicetree with the appropriate parameters and return the paths to the generated DTS, overlay, and HTML report.

PetaLinux workflow

“Generate a system-user.dtsi for my FMCDAQ3 ZC706 design for PetaLinux.”

Claude will call generate_devicetree with output_format="petalinux" and return the path to the generated system-user.dtsi ready for the PetaLinux project.

Inspect and lint

“Lint the device tree I just generated at /tmp/dt_output/merged.dts.”

Claude will call lint_devicetree and report any structural issues.

API reference

MCP server exposing pyadi-dt devicetree generation and profile tools.

adidt.mcp_server.generate_devicetree(xsa_path: str, output_dir: str, config_json: str = '{}', profile: str | None = None, emit_report: bool = True, emit_clock_graphs: bool = True, sdtgen_timeout: int = 300, reference_dts: str | None = None, strict_parity: bool = False, lint: bool = False, strict_lint: bool = False, output_format: str = 'default') → Dict[str, Any]

Generate a devicetree from a Vivado XSA archive.

Runs the full XsaPipeline: sdtgen -> topology parse -> node build -> merge -> visualize.

Parameters:

xsa_path – Path to the Vivado .xsa archive.
output_dir – Directory where output files are written.
config_json – JSON string with configuration (clock, JESD, datapath settings). For AD9084-EBZ on VCU118, prefer profile=”ad9084_vcu118” so the MCP path applies the board-specific HMC7044 + AD9084 + ADF4382 defaults. Low-level AD9084 overrides can still be passed via ad9084_board. JESD framing parameters (F/K/M/L/Np/S) are not in the profile and must be supplied here (typically from pyadi-jif solve_system output).
profile – Optional built-in profile name (e.g. “ad9081_zcu102”, “ad9084_vcu118”).
emit_report – When True, generate an HTML topology report. Defaults to True.
emit_clock_graphs – When True, generate DOT/D2 clock-tree diagrams. Defaults to True.
sdtgen_timeout – Maximum seconds to wait for sdtgen to finish generating the base DTS. Default 300 s — adequate for AD9084+VCU118 XSA processing.
reference_dts – Optional path to a reference DTS for parity checking. When provided, “map” and “coverage” keys are added to the result.
strict_parity – When True and reference_dts is provided, raise an error if the merged DTS is missing required roles, links, or properties.

Returns:

Dict with paths to generated artifacts (overlay, merged, report, clock_dot, etc.) or an error dict if the operation fails.

adidt.mcp_server.list_xsa_profiles() → list[str]

List all available built-in XSA board profiles.

Returns:: Sorted list of profile names (e.g. [“ad9081_zcu102”, “adrv9009_zc706”, …]).

adidt.mcp_server.show_xsa_profile(name: str) → Dict[str, Any]

Show the full configuration for a named XSA board profile.

Parameters:: name – Profile name (e.g. “ad9081_zcu102”). Use list_xsa_profiles to see available names.
Returns:: Profile dict with ‘defaults’ key containing board configuration, or an error dict if the profile is not found.

adidt.mcp_server.read_dt_property(node_name: str, property_name: str | None = None, filepath: str | None = None) → Dict[str, Any]

Read a devicetree property from a DTS/DTB file or the running system.

Parameters:

node_name – Name (or compatible string) of the devicetree node to look up.
property_name – Specific property to read. If omitted, all properties are returned.
filepath – Path to a .dts or .dtb file. If omitted, reads from the running system (local_sysfs).

Returns:

Dict with property values, or an error dict if the node/property is not found.

adidt.mcp_server.lint_devicetree(dts_path: str) → Dict[str, Any]

Run the structural DTS linter on a generated DTS file.

Checks for unresolved phandle references, clock-cell mismatches, duplicate SPI chip selects, and missing compatible strings.

Parameters:: dts_path – Path to a .dts file to lint.
Returns:: Dict with ‘diagnostics’ list and ‘summary’ counts by severity.

adidt.mcp_server.main(): Entry point for the adidt-mcp console script.