AI IDE integration — vyges mcp

vyges mcp starts a local, no-auth MCP server that exposes your installed Loom engines to an AI IDE (Claude Code, the VS Code Claude extension, or any MCP client). The agent calls the engines as tools; the engines run on your machine, over stdio — no port, no auth, nothing leaves your box (your own binaries, your own agent).

It is the execution companion to the CLI’s “deterministic core, agent tail” philosophy (vyges agents): instead of the agent shelling vyges <tool>, the tools are MCP tools.

Do you need an LLM? Two ways if you do

The engines and tools are plain, deterministic CLIs — run them directly (vyges drc run …) or script them, no LLM required. That is one of three ways to reach the same Loom engines — manual, your own model via an AI IDE, or a model vyges drives for you:

   1. MANUAL                2. AI IDE  (Mode 1)         3. vyges model run  (Mode 2)
   no LLM · scriptable      bring your own model        registered model, headless
        │                          │                            │
        │                   Claude Code / Cursor          vyges driver
        │                   (any MCP host)                (openai-compat | anthropic)
        │                          │                            │
        │                          └────────────┬───────────────┘
        │                                        ▼
        │                        ┌──────────────────────────────┐
        │                        │   vyges mcp  ·  tool server   │
        │                        │       (model-agnostic)        │
        │                        └──────────────────────────────┘
        │                                        │
        ▼                                        ▼
   ┌────────────────────────────────────────────────────────────┐
   │        Loom engines  —  the deterministic core             │
   │   ground truth · the same engines every path drives,       │
   │   with or without an LLM on top · reproducible             │
   └────────────────────────────────────────────────────────────┘

The two AI paths go through the model-agnostic vyges mcp tool server; the manual path calls the engines directly. Reach for an LLM only when you want reasoning over the tools («which engine, why, and fix the violations»), not a fixed sequence — then there are two ways to connect one:

• Mode 1 — bring your own AI IDE (available today). Point Claude Code, Cursor, or any MCP client at vyges mcp. Your IDE’s model reasons and calls the tools — you bring the model, vyges brings the tools. This is the recommended interactive path, and the rest of this page covers it.
• Mode 2 — register a model, vyges drives it (headless). Register a local or cloud model with vyges model, then vyges model run <name> "<task>" runs the reason → tool-call → observe loop over these tools itself, with no IDE — for headless / CI / air-gapped / autonomous flows. Because the model is a registered, swappable choice, point it at a local model so nothing leaves your machine. (v1 uses JSON tool-calling and passthrough tool args; native provider tool-calling and finer controls are refinements.)

Both modes drive the same vyges mcp tools below — the tool server is model-agnostic.

Quickstart — hook your AI IDE to your local Loom

# 1. Install the engines (once).
vyges install loom

# 2. Register with every AI IDE on your machine (user scope).
vyges mcp setup

vyges mcp setup detects the AI IDEs you have installed — Claude Code, Cursor, and VS Code — and registers vyges mcp with each (merge-safe: it never disturbs your other MCP servers, e.g. VyContext). Preview it with vyges mcp setup --dry-run; reverse it with vyges mcp setup --uninstall.

First-run prompt: the very first time you run vyges interactively, it offers to do this for you (once). Decline and it won’t ask again; run vyges mcp setup yourself anytime. Set VYGES_NO_PROMPT=1 to silence it.

Now open a project in your IDE — the installed engines appear as tools. Verify with:

claude mcp list        # → vyges: … ✔ Connected
vyges mcp --list       # the tools this server advertises

Just one project instead? vyges mcp install writes a project-scoped .mcp.json in the current directory (equivalently: claude mcp add vyges -- vyges mcp).

What you get

• One tool per installed engine (drc, lvs, sta-si, gds-view, …). The tool set is discovered from vyges modules — install more engines and they appear; nothing to configure.

• Calling a tool runs the real vyges-<engine> and returns a structured result: the engine’s own --json output, wrapped in a loom-result envelope (status, engineering, a content-addressed input_hash, provenance). Errors come back as a structured envelope too — a bad call never crashes the session.

• Two independent status axes. status says whether the process ran (ok | error); engineering.status says what the evidence supports about your design (pass | fail | unknown | not_applicable). They are deliberately separate: a DRC run that exits cleanly having found 3 violations is status: "ok" with engineering.status: "fail" — a successful call reporting a failed check. An engine that crashes is unknown, never fail, because a tooling defect is not a design defect; so is an engine that declares no assertion. Nothing is ever reported as passing on absent evidence.

  { "status": "ok",
    "engineering": { "status": "fail", "assertion": "drc-clean",
                     "summary": "3 rule violation(s) found" } }
  

• Typed arguments. Engines self-describe (vyges-<engine> --describe), so their tools expose real per-parameter schemas — drc takes gds, deck, top, not an opaque string. Tools without a descriptor (and external tools like yosys) fall back to an args array of the engine’s own CLI arguments; --json is added automatically either way. The descriptor format is documented in Tool descriptor — --describe, and the result shape in Result envelope — loom-result.

Read-only vs mutating tools — VYGES_MCP_PROFILE

Not every engine is equal: sign-off, verification, and query engines only read your design (sta-si, drc, lvs, extract, power, em-ir, thermal, cdc, glitch, lec, gds-view), while optimizers edit it (resize, vt-swap, buffer-insert, hold-fix, remap). vyges mcp classifies each tool automatically — from what it produces — and lets you choose how much of the surface an agent sees:

VYGES_MCP_PROFILE=core vyges mcp     # read-only surface: the agent can run sign-off, never edit

vyges mcp --list shows each tool’s read/mutate classification and whether it’s exposed under the active profile. (External and passthrough tools — which can write — are treated as mutating, so a core surface is strictly the engines proven read-only.)

Approving a change — transactions (pro)

Under pro, a mutating engine runs only inside an open transaction — opening one is your explicit go-ahead to let the agent change the design this session:

txn.begin      # authorize mutations for this session
   … agent runs resize / hold-fix / … — each change is staged, not adopted …
txn.status     # review what's staged
txn.commit     # accept the staged changes      —or—     txn.rollback   # discard them
audit.events   # the full trail of what ran this session

Because the optimizers are non-destructive (they write a new netlist and never touch your input), txn.rollback simply discards the candidates — there is nothing to restore.

Keep-best timing closure — flow.close_timing

flow.close_timing runs the safe loop for you: it signs off the design, then tries each optimizer in turn, re-signs-off the result, and keeps a candidate only if timing did not regress — threading the adopted netlist into the next step. The agent proposes; the deterministic engine decides. You give it a sign-off job (and optionally the steps to try); it returns baseline vs final and which steps were kept:

flow.close_timing  { "job": "counter.sta", "steps": ["resize", "hold-fix"] }
   → { baseline: {wns_ns …}, final: {wns_ns …}, improved_ns, kept_any, steps:[…] }

It writes candidate netlists, so it runs under the same gate as the optimizers (an open transaction under pro).

Commands

vyges mcp                       start the stdio server (an MCP client spawns this)
vyges mcp setup [--dry-run] [--uninstall]
                                register with every detected AI IDE (user scope)
vyges mcp install [dir]         register in <dir>/.mcp.json (one project)
vyges mcp uninstall [dir]       remove the project registration
vyges mcp --list                list the tools this server would advertise

Both setup and install are safe to run alongside VyContext and any other MCP servers — they read-modify-write each config, preserving existing entries. (Antigravity is detected but not yet wired — its MCP config path is being confirmed.)

Your tools, your workflow — open or commercial

vyges mcp is tool-agnostic: beyond the Loom engines, any resolvable non-Vyges EDA tool is advertised too, so an agent drives your whole flow, not just Loom.

• Open source — yosys, verilator, klayout, openroad, magic, netgen.
• Commercial (COTS) — Synopsys (primetime, starrc, fusioncompiler), Cadence (genus, innovus, tempus, quantus), Siemens (calibre) — each advertised when it’s resolvable on your host.

Arguments pass through verbatim and output comes back as text (structured per-tool schemas are a later refinement). Point each tool at its install — including a licensed commercial tool on an NFS-mounted toolshed — in tools.json (next section), with license variables via env; paths, versions, and license settings depend on your site’s install layout and deployment architecture and are tuned to match. The agent then drives one interface across Loom, open-source, and commercial tools — your existing methodology wrapped, not replaced.

Pinning versions (and containers)

vyges mcp setup already drops a starter ~/.vyges/tools.json (carrying the $schema line) in place, so your editor and AI assistant can autocomplete pins immediately — nothing extra to run. (vyges mcp tools --init writes the same starter on demand.)

Hosts often carry several versions of a tool. Pin exactly which one an adapter uses in that tools.json — user-scope ~/.vyges/tools.json or project-scope .vyges/tools.json (project wins), with an env override VYGES_TOOL_<NAME> on top and PATH as the fallback:

{
  "env": { "SNPSLMD_LICENSE_FILE": "27020@lic.corp" },   // license servers (forwarded to every tool)
  "tools": {
    "yosys":     { "path": "/opt/yosys-0.40/bin/yosys" },
    "primetime": { "path": "/eda/synopsys/pt/T-2022.03/bin/pt_shell" },  // licensed tool on an NFS toolshed
    "klayout": {
      "container": {
        "runtime": "podman",
        "image": "klayout:0.28.17",
        "entrypoint": "klayout",
        "mounts": ["/pdk:/pdk:ro", "/data:/data"]
      }
    }
  }
}

A container-backed tool runs via podman/docker run with your working directory auto-mounted 1:1 (so paths in the args resolve inside), and the image tag is the pinned version:

• mounts — extra -v host:container[:ro] volumes. This is the common enterprise case: mount your PDK, a license directory, or a shared data volume into the container; append :ro for read-only.
• entrypoint — the command inside the container (default: the tool name). Set it to "" to use the image’s own ENTRYPOINT, or to a full in-container path.

Check how everything resolves on a host — engines and external tools, with the pinned path/image, version, and which source each came from — with:

vyges mcp tools

Safe to hand-edit. A malformed tools.json is never fatal — it’s validated and any problems (bad JSON, a container with no image, an unknown key, path and container together) are reported by vyges mcp tools and at server startup, with resolution simply falling back to PATH. For editor autocomplete + as-you-type checking, add a $schema line pointing at the shipped schema:

{ "$schema": "https://vyges.com/schema/v1/tools.schema.json", "tools": { … } }

The resolved binary/image and its version are recorded in every result and folded into the content hash, so swapping a version can never silently reuse a stale result.

Agentic feedback — loom.feedback

Beyond the per-engine tools, the server exposes loom.feedback — the agent’s “eyes” for a layout iteration: one bundle of a render (gds-view), categorized DRC verdicts, and a score (violation counts, and correlation to a golden if you pass one). It’s also a CLI:

vyges mcp feedback design.gds --rules sky130.drc [--top TOP] [--golden 0]

An agent calls loom.feedback, reads { render, verdicts, score }, decides the next edit, and re-runs — the closure loop, on your machine.

Trust & tiers

This is the free, local, no-auth tier: it exposes your own installed binaries to your own local agent — the same trust model as any local dev MCP server. Even here you stay in control of what an agent can touch: the read-only core profile and per-session transactions above are yours by default. Governed, distributed execution (RBAC, audit, running tools across a fleet) is a separate enterprise tier (Vyges Mill), not this server.

See the vyges mcp command reference for the generated help.