Neosyn Fpga MCP

neosyn-fpga-mcp

An MCP server that hands the C⏚ FPGA toolchain to an AI agent. The model writes hardware; the server compiles, simulates and synthesis-checks it against the real compiler, and hands back structured diagnostics the model can act on.

That is the difference worth caring about. An LLM asked for Verilog will confidently emit something that does not build, does not synthesize, or silently folds away to nothing. Here every step is judged by the same compiler a human uses.

Two parts work together:

1. `cg_context.md` — a knowledge pack. Load it as the system prompt and the model can write plausible C⏚: the mental model, types, ports, structs/enums/generics, the standard library, and the gotchas that sink first drafts.
2. the MCP server — the compiler as tools, so the model verifies its own output instead of recalling it.

Knowledge gives a good first draft; the compiler in the loop makes it right. Both are model-agnostic — any stdio-MCP host (Claude Desktop, Claude Code, Cursor, Cline) works, and the context pack works with any LLM at all.

Why not fine-tune? C⏚ is a niche language with little public code, and it gains features every release. A fine-tuned model is expensive and goes stale. In-context knowledge plus a verification loop costs nothing to retrain, tracks the language as the compiler evolves, and converges by *running* code rather than recalling it.

Install

pip install neosyn-fpga-mcp

Then point it at a C⏚ compiler jar:

export CG_JAR=/path/to/cg-language-server.jar

Two ways to get that jar:

• Open source — a prebuilt jar from cg-compiler releases, or build it from source.
• Commercial — the jar inside an installed Neosyn C⏚ extension, which adds the fast bytecode simulator and VHDL output. It needs your licence file: set NEOSYN_CG_LICENSE to it, or keep it at the default path the extension uses. Without one, every tool reports the licence problem instead of running.

cg_capabilities reports which one you have and what it can do, probed rather than assumed.

Requirements

• Python 3.10+
• Java 17 or newer on PATH — the jar's bytecode targets 17.
• Optional: yosys on PATH for cg_synth (override with $YOSYS); iverilog for cg_simulate(simulator='iverilog'). Neither is needed for cg_check, cg_generate_verilog, or the bytecode simulator.

Smoke-test the verification core without an MCP client:

python3 - <<'EOF'

from neosyn_fpga_mcp import cg_mcp_server as cg print(cg.simulate("package d;\ntask T { properties { test: { v:[1,2,3] } }\n" " out push u8 v; u8 c; void setup(){c=0;}\n" " void loop(){c=c+1; v.write(c);} }")) EOF

Connect it to an MCP host

Add a server entry. Use absolute paths.

{

"mcpServers": { "cg": { "command": "neosyn-fpga-mcp", "args": [], "env": { "CG_JAR": "/abs/path/to/cg-language-server.jar" } } } }

The same command/args/env shape works for Claude Desktop, Claude Code, Cursor, Cline and other stdio-MCP hosts.

Then load `cg_context.md` as the system prompt (or paste it at the top of the conversation). The model now knows the language *and* can verify it.

Tools the server exposes

13 tools. Every tool that takes source accepts source (a C⏚ string) and an optional extra_files map ({"Defs.cg": "..."}) for imported bundles/tasks.

These are the only names that exist, and the server says so rather than hoping you read this table: a call to a tool that does not exist comes back with the whole list and the closest real name (cg_compile → "did you mean cg_check?"), cg_capabilities carries the list, and the first call of a session carries it once. The list is generated from the tool registry, so it cannot drift out of step with the table below.

Choosing a backend

Two tools take a backend selector:

• `cg_simulate(source, simulator=…)` — which simulator runs the design:
• 'bytecode' *(default)* — the compiler's fast bytecode simulator. No HDL toolchain needed; a properties { test: {...} } block self-checks. cg_simulate(src) or cg_simulate(src, simulator="bytecode").
• 'iverilog' — generate Verilog + a testbench and run Icarus Verilog (vvp), a Verilog-level cross-check. A testbench is emitted only for a network whose name contains `Test` with a capital T (e.g. network TestFoo); a lowercase _test network drives the bytecode sim's test property only, not iverilog. Needs iverilog on PATH. cg_simulate(src, simulator="iverilog").
• 'verilator' — accepted for forward-compat but reported unavailable unless the verilator binary is installed. cg_simulate(src, simulator="verilator").

• `cg_synth(source, flow=…)` — which yosys synthesis flow runs:
• 'generic' *(default)* — portable synthesizability check (synth). cg_synth(src) or cg_synth(src, flow="generic").
• a vendor FPGA family — 'ice40', 'ecp5', 'xilinx', 'gowin', 'intel' — maps to that part's primitives (LUTs/BRAM/DSP). cg_synth(src, flow="ice40").

top defaults to the first non-testbench task/network (the synthesizable DUT); pass it when a file holds several designs. Override the yosys binary with $YOSYS.

How the model should use it

1. Draft C⏚ (always starting with package).
2. cg_lint → free and instant; catches the mistakes the compiler will happily accept, above all a test: block that checks nothing.
3. cg_check → fix every diagnostic, and read warnings: those are the compiler's own objections to code it will nonetheless accept.
4. cg_simulate → confirm ok: true and that the output matches intent.
5. cg_generate_verilog once it simulates, to hand off RTL.
6. cg_synth (optional) → confirm the Verilog maps to real hardware (ok: true, a sensible cells count, no problems).

Step 2 exists because steps 3–4 can BOTH pass on a design that does nothing: a fixture with no output vector is green against a dead DUT. cg_lint is the only step that catches that, and it costs nothing to run.

The loop in steps 2–3 is the point: the model writes, the compiler judges, the model fixes. cg_context.md ends with the same protocol so the model follows it even without separate instruction.

The loop, end to end

from neosyn_fpga_mcp import cg_mcp_server as cg

src = '''package com.example.demo; task Counter { properties { test: { value: [1, 2, 3] } }