# Vitis MCP

Generic Vitis/XSCT MCP adapter when registered.

This server exposes Vitis build/run and XSCT tools. It is not a required
wrapper over a customer project's local scripts. Missing project-local
helpers are not a failed smoke or a blocked debug path. On-board ILA capture
and CSV summary belong to Vivado Debug MCP (`live-capture` /
`ila-csv-summary` / `capture-summary`).

## Run

```powershell
$env:VITIS_MCP_CONFIG="<REPOKEY_HOME>\tools\ai_vitis_vivado_stack\vitis_mcp\configs\sample.vitis_mcp_config.json"
<REPOKEY_HOME>\repokey-client.cmd vitis
```

Vitis MCP is built into `repokey.exe`; no `pip install` and no separate Python
runtime are required.

Replace `<REPOKEY_HOME>` with the installed package root. In the customer
package, the per-project config is generated under the project's
`.vivado_ai_mcp\configs\customer.vitis_mcp_config.json`.

The package pins `mcp==1.28.1`. Do not upgrade to `mcp` 2.x without updating
`src/vitis_mcp/server.py`, because the `FastMCP` import path changed in 2.x.

## Bitstream Ownership

The bitstream is a PL-side deliverable (produced by RepoKey Vivado MCP
`write_bitstream`), not something the Vitis side should hardcode. The Vitis
MCP only *consumes* a configured path:

- `bit_path` in the Vitis MCP config (or `VITIS_BIT_PATH` env, or `--bit` on
  the helper CLI). Per-project; customers set it after the PL bitstream exists.
- When unset, `vitis_status` reports "bit not configured" as a warning and
  still returns ok; only `vitis_run` (which must program the FPGA) fails with
  a clear message.

## Tools

- `vitis_status`
- `vitis_build`
- `vitis_run`
- `set_test_mode`
- `read_test_mode`
- `debug_status`
- `handoff_consume_check`
- `ps_context_summary`
- `generate_ila_capture` (optional project-local helper if present)
- `analyze_ila_csv` (optional project-local CSV analyzer if present; prefer
  Debug MCP `ila-csv-summary` / `capture-summary`)
- `ila_capture_server_start` / `ila_capture_server_capture` /
  `ila_capture_server_stop` (optional persistent-session helper if present;
  prefer Debug MCP `live-capture`)

## PS Context

`ps_context_summary` is a static, project-local evidence tool. It does not run
XSCT, program hardware, or parse PL. It scans PS-side C/C++ headers and source
files for:

- `xparameters.h` interrupt, base address, and high address macros.
- `XScuGic_Connect(...)` interrupt consumers.
- `Xil_In*/Xil_Out*` register accesses tied to `XPAR_*_BASEADDR` macros.
- likely driver entry points such as `main`, init functions, and interrupt
  handlers.

When `write=true`, outputs are written under the target project:

```text
.vivado_ai_mcp/ps_context/
  project_summary.json
  agent_summary.md
```

This complements RepoKey PL context. RepoKey owns PL/Vivado hard facts;
`ps_context_summary` owns PS code consumption facts. Handoff/Radar layers can
link the two, but this tool does not copy PL handoff JSON or infer business
semantics.
