# Vivado Context MCP

Vivado Context MCP is a low-token context layer between AI agents and local Vivado/FPGA projects. It does not try to replace Codex, Claude, Cursor, or Vivado. It gives those agents a compact project map before they decide which files or Vivado reports to inspect.

## Why It Saves Tokens

FPGA projects contain many generated files, run outputs, logs, reports, simulation artifacts, and IP products. A direct agent scan can waste most of its context on files that do not explain the design. This tool indexes the project locally, extracts the useful structure, and returns summaries instead of source dumps.

## Current MVP

- Detect a Vivado project from a folder or `.xpr`
- Parse basic `.xpr` file references and part metadata
- Classify RTL, constraints, simulation, IP, BD, and Tcl files
- Extract Verilog/SystemVerilog modules, ports, parameters, and instances
- Summarize XDC clocks, pins, IO standards, delays, and timing exceptions
- Summarize BD cells, ports, VLNVs, and project entry points
- Estimate raw scan tokens versus indexed summary tokens
- Provide a CLI and optional MCP server

## Install

本包已把 Vivado Context MCP 内置到 repokey.exe，无需 pip install。
CLI 用 `repokey-client.cmd context ...`，MCP 服务用
`repokey-client.cmd context serve`。

以下安装与测试说明仅适用于源码开发环境（客户包不附带源码）：
开发时从源码目录安装开发依赖后运行测试。

## CLI Examples

```bash
vivado-context index examples/demo_counter
vivado-context summarize examples/demo_counter --detail normal
vivado-context hierarchy examples/demo_counter --top top
vivado-context constraints examples/demo_counter
vivado-context bd-summary examples/demo_counter
vivado-context bd-connections examples/demo_counter
vivado-context clock-reset examples/demo_counter
vivado-context entry-points examples/demo_counter
vivado-context cache-status examples/demo_counter
vivado-context relevant examples/demo_counter "clock reset and top module"
vivado-context report examples/demo_counter --write
vivado-context tokens examples/demo_counter
```

## Guides

- [Customer Guide](docs/customer_guide.md): product positioning, usage, privacy, and limitations.
- [Agent Guide](docs/agent_guide.md): recommended workflow for AI agents using the MCP tools.
- [Tool Suite Matrix](docs/tool_suite_matrix.md): relationship and boundaries across the Vivado AI MCP tool suite.
- [Evidence Store](docs/evidence_store.md): shared `.vivado_ai_mcp/` layout for project context, simulation, implementation, and debug evidence.
- [Vivado Debug MCP MVP](docs/vivado_debug_mcp_mvp.md): proposed scope for headless ILA/VIO debug evidence.
- [Tool Suite Roadmap](docs/tool_suite_roadmap.md): staged plan for the full FPGA AI MCP suite.
- [RFDC MicroBlaze Demo](docs/rf_ip_mb_one_pager.md): one-page customer-facing case summary.
- `docs/wechat/`: Chinese content reserved for public-account or marketing material only.

The tool writes local cache-style outputs under:

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

Older `.vivado_context/` cache files are read as a legacy fallback, but new
outputs use `.vivado_ai_mcp/context/`.

## MCP Configuration Example

```json
{
  "mcpServers": {
    "vivado-context": {
      "command": "<REPOKEY_HOME>/tools/ai_vitis_vivado_stack/vivado_context_mcp/scripts/run_vivado_context_mcp.cmd",
      "args": []
    }
  }
}
```

In the RepoKey customer package, replace `<REPOKEY_HOME>` with the installed
package root (the same variable used by the other MCP entries).

For local CLI use on Windows:

```bat
scripts\vivado_context.cmd summarize examples\demo_counter
scripts\demo_report.cmd examples\demo_counter
scripts\build_release.cmd
```

## Relationship To vivado_mcp_pro

`vivado_mcp_pro` operates Vivado and retrieves authoritative state such as synthesis, implementation, timing, utilization, and hardware programming results.

Vivado Context MCP prepares the low-token project context first: file roles, module hierarchy, constraints, IP hints, and relevant files. Used together, the agent can understand the project before spending time and tokens on deeper Vivado operations.

## Limitations

This MVP is not a complete SystemVerilog or VHDL compiler. The RTL parser is intentionally lightweight and reports structural hints. For complex projects, use the output as a project map, then let the agent inspect specific files or ask `vivado_mcp_pro` for Vivado-authoritative details.

## Privacy

The tool runs locally and does not upload source code.
