# efinityer

**Repository Path**: johnzchgrd/efinityer

## Basic Information

- **Project Name**: efinityer
- **Description**: Efinity MCP Tool
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-12
- **Last Updated**: 2026-08-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Efinityer

**Efinityer** is a Python [Model Context Protocol](https://modelcontextprotocol.io) server for **Efinix Efinity**. It runs **`efx_run`**, edits project **`*.xml`**, drives programming and LA/VIO debug, and exposes **agent-oriented composite workflows**. It does **not** modify your Efinity installation.

**Supported core target:** Efinity **2023.2**, **2024.2**, **2025.2** (and best-effort on newer installs). Call **`efinity_environment`** first to see detected version, flows, and feature flags.

## Requirements

- **Python 3.10+** for this package (PyPI **`mcp`**).
- A licensed **Efinity** install on the same machine.

Most FPGA benches use **Windows** for USB/JTAG. The **recommended remote setup** is Linux (Efinity + efinityer MCP + agent) with **`efx_hw_server` only** on the Windows bench — see **[Remote deployment](#remote-deployment-linux-dev--windows-bench)**. For a single machine with a local cable, see **[Local setup (USB on same host)](#local-setup-usb-on-same-host)**.

## Remote deployment: Linux dev + Windows bench

**Linux:** Efinity install, FPGA project, AI agent (Cursor), **efinityer MCP**.  
**Windows bench:** Efinity install, **`efx_hw_server`**, USB/JTAG — **no efinityer MCP** on Windows.

| Step | Where | Tool / action |
|------|--------|----------------|
| Compile / map / pnr | Linux | `efinity_build_project`, etc. |
| Program bitstream | Linux or Windows | **`efinity_program_project` on Linux** uses local `efx_run -f program` (needs USB on Linux). For a Windows-only cable, run **`efx_run -f program`** on the bench manually, or attach a Linux-accessible programmer. |
| LA / VIO debug | Linux MCP → Windows hw_server | `jtag_target` with `remote_url` from hw_server |
| Target discovery | Linux MCP | `efinity_hw_server_status`, `efinity_list_jtag_targets(hw_servers=[...])` |

### Linux — efinityer MCP

```bash
cd /path/to/efinityer
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
export EFINITY_HOME=/opt/Efinity/2025.2   # your Linux Efinity root
```

**Cursor `mcp.json`:**

```json
{
  "mcpServers": {
    "efinityer": {
      "command": "/path/to/efinityer/.venv/bin/python",
      "args": ["-m", "efinityer"],
      "env": {
        "EFINITY_HOME": "/opt/Efinity/2025.2"
      }
    }
  }
}
```

### Windows bench — start `efx_hw_server`

Efinity must be installed on the bench; efinityer is **not** required.

```powershell
cd C:\Efinity\2025.2
$env:PYTHONHOME = 'C:\Efinity\2025.2\python311'
$env:EFINITY_HOME = 'C:\Efinity\2025.2'
& 'C:\Efinity\2025.2\python311\bin\python.exe' -c "from efx_pgm.efx_hw_server.grpc_server import run_server; run_server('0.0.0.0', 8080)"
```

Open firewall **TCP 8080** on the bench. Default gRPC is **insecure** — lab LAN / VPN only. Close **Efinity Debugger** on that cable before remote debug (JTAG is exclusive).

efinityer does **not** start or stop hw_server from MCP; keep it running on the bench while debugging.

### Debug workflow (from Linux MCP)

1. `efinity_hw_server_status` with `server="win-bench:8080"` (or host:port)  
2. `efinity_list_jtag_targets` with `hw_servers=["win-bench:8080"]` — copy a device **`connect_url`**  
3. `efinity_debug_enable_and_compile` → `efinity_program_and_verify_artifacts` with `hw_servers=[...]` (remote bench) or local USB  
4. `efinity_debug_session_open` with `hw_servers=[...]` (omit `target_index` when only one target) or explicit `jtag_target`:

   ```json
   {"kind": "remote_url", "url": "http://win-bench:8080/device?id=1&dev_url=..."}
   ```

5. `efinity_debug_la_capture` / `efinity_debug_vio_read`  
6. `efinity_debug_session_close`

Optional per-project registry **`.efinityer/targets.json`**:

```json
{
  "remote_urls": [],
  "hw_servers": ["win-bench:8080"],
  "saved_targets": []
}
```

More: **[docs/JTAG_HW_SERVER.md](docs/JTAG_HW_SERVER.md)**, **[docs/DEBUG_LA_VIO.md](docs/DEBUG_LA_VIO.md)**.

### Hardware-in-the-loop pytest (remote bench)

Copy **`src/efinityer/testdata/ti60_debug_hil/hw_test.local.json.example`** to **`src/efinityer/testdata/ti60_debug_hil/.efinityer/hw_test.local.json`** (gitignored). Edit **`efinity_home`** and **`hw_servers`** for your machine. Then:

```bash
python -m pytest tests/integration/test_remote_debug.py -m hardware
```

The test compiles the bundled Ti60 fixture, programs via remote JTAG, opens a debug session, and captures LA samples.

## Install

**Linux / macOS:**

```bash
cd /path/to/efinityer
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

Set **`EFINITY_HOME`** to your install root (e.g. `/opt/Efinity/2025.2` on Linux).

## Local setup (USB on same host)

When the USB/JTAG cable is on the **same machine** as efinityer MCP (Linux or Windows), use `jtag_target` `local_sernum` — no hw_server required.

**Linux** — same install steps as [Remote deployment § Linux](#linux--efinityer-mcp).

**Windows (all-in-one bench PC):**

```powershell
cd C:\Efinity\2025.2\efinityer
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
```

Cursor **`mcp.json`:**

```json
{
  "mcpServers": {
    "efinityer": {
      "command": "C:/Efinity/2025.2/efinityer/.venv/Scripts/python.exe",
      "args": ["-m", "efinityer"],
      "env": {
        "PYTHONHOME": "C:/Efinity/2025.2/python311",
        "EFINITY_HOME": "C:/Efinity/2025.2"
      }
    }
  }
}
```

Verify with `efinityer-selfcheck`, then `efinity_list_jtag_targets` for local `sernum`. More: **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)**.

## Run as MCP server

```bash
python -m efinityer
```

On Windows (local all-in-one setup):

```powershell
.\.venv\Scripts\python.exe -m efinityer
```

**Cursor** example (Linux — remote workflow):

```json
{
  "mcpServers": {
    "efinityer": {
      "command": "/path/to/efinityer/.venv/bin/python",
      "args": ["-m", "efinityer"],
      "env": {
        "EFINITY_HOME": "/opt/Efinity/2025.2"
      }
    }
  }
}
```

Windows local MCP: see **[Local setup](#local-setup-usb-on-same-host)**. Remote bench: **[Remote deployment](#remote-deployment-linux-dev--windows-bench)**.

Full tool list and agent workflows: **[docs/MCP_TOOLS.md](docs/MCP_TOOLS.md)**.

## Agent quick start

1. **`efinity_environment`** — version, flows, debug/IP availability
2. **`efinity_create_project_scaffold`** — new unified project + optional RTL
3. **`efinity_build_project`** — compile with polling + artifact scan
4. **`efinity_program_and_verify_artifacts`** — program with pre-checks
5. **`efinity_debug_enable_and_compile`** then **`efinity_debug_session_open`** + **`efinity_debug_la_capture`** — LA validation (`remote_url` via Windows **`efx_hw_server`**, or `local_sernum` on same host)

**Remote debug (Linux dev + Windows bench):** efinityer MCP on **Linux**; start **`efx_hw_server`** on Windows; debug with **`jtag_target`** `remote_url`. See **[Remote deployment](#remote-deployment-linux-dev--windows-bench)**.

Simulation flows are **out of scope** for the current automation path; default builds use **`flow=compile`**, not **`full`**.

## Cursor Skill

Project skill: **`.cursor/skills/efinityer/SKILL.md`** — encodes recommended tool order for AI agents.

## Verify

```bash
efinityer-selfcheck
python -m pytest tests -m "not integration"
```

Optional local push gate (after `pip install -e ".[dev]"` && `pre-commit install`): **`git push`** runs ruff check + unit pytest and fails closed — see **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)**.

Multi-version integration matrix (when installs are present):

```bash
python -m pytest tests/integration/test_version_matrix.py -m integration
```

More: **[docs/DEVELOPMENT.md](docs/DEVELOPMENT.md)**, **[docs/HARDWARE_PROGRAMMING.md](docs/HARDWARE_PROGRAMMING.md)**, **[docs/DEBUG_LA_VIO.md](docs/DEBUG_LA_VIO.md)**.

## License

MCP server code: [MIT License](LICENSE). Sample RTL/XML under **`src/efinityer/testdata/`** remains **copyright Efinix** where noted.