# Agent Guide

Use Vivado Context MCP before reading large FPGA project folders.

## MCP Server

Use `scripts/run_vivado_context_mcp.cmd` as the MCP server command on Windows.

## Recommended Flow

1. Call `index_project_tool` or run `vivado-context index`.
2. Call `get_entry_points_tool` to identify the design top, simulation top, and key files.
3. Call `get_clock_reset_summary_tool` for clock and reset context.
4. Call `get_bd_summary_tool` when the project uses Block Design.
5. Call `get_bd_connection_summary_tool` to inspect BD interface flows.
6. Call `get_relevant_files_tool` with the user's current question.
7. Optionally call `get_context_report_tool` when the user needs a compact project handoff.
8. Read only the specific source files or line ranges needed next.

## Evidence Store

Project-local evidence is stored under:

```text
.vivado_ai_mcp/
  context/
```

Read `.vivado_ai_mcp/context/project_summary.json` or
`.vivado_ai_mcp/context/agent_summary.md` before rescanning a large project.
Older `.vivado_context/` cache files may exist in projects created by earlier
versions, but new output should use `.vivado_ai_mcp/context/`.

## Avoid

- Do not read `.runs`, `.cache`, `.sim`, `.gen`, `.hw`, `.ip_user_files`, `.vivado_ai_mcp`, or `xsim.dir` unless the user asks about generated evidence or generated Vivado outputs.
- Do not treat static parser results as Vivado elaboration results.
- Do not return full source files by default.

## Escalate To Vivado Tools

Use `vivado_mcp_pro` or Vivado Tcl when the user asks about:

- synthesis or implementation status
- timing reports
- utilization
- bitstream generation
- hardware programming
- authoritative IP or BD elaboration details
