# Vitis MCP

Thin MCP wrapper around project-local Vitis/XSCT helpers.

This server intentionally does not reimplement Vitis or XSCT logic. It exposes
stable MCP tools that call an existing project's `tools/vitis/*.py` helpers.

## 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 内置到 repokey.exe，无需 pip install，也不需要 Python。

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`
- `analyze_ila_csv` (pass `ila_name` to dispatch: `hw_ila_1`/`hw_ila_2` ->
  `adc_signal_analyze.py`, `hw_ila_4` -> `timer_ila_analyze.py`, otherwise
  generic `ila_analyze.py`)
- `ila_capture_server_start` / `ila_capture_server_capture` /
  `ila_capture_server_stop` (persistent Vivado ILA capture server; one
  startup, captures in a few seconds each)

## 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.
