cg-agent-kit
markdown string with 1-line summary followed by bullets details.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cg-agent-kit compile and check this C⏚ design for errors"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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:
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.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-mcpThen point it at a C⏚ compiler jar:
export CG_JAR=/path/to/cg-language-server.jarTwo 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_LICENSEto 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.
Related MCP server: mcp-verilog
Requirements
Python 3.10+
Java 17 or newer on
PATH— the jar's bytecode targets 17.Optional:
yosysonPATHforcg_synth(override with$YOSYS);iverilogforcg_simulate(simulator='iverilog'). Neither is needed forcg_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);} }"))
EOFConnect 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.
Tool | Params (besides | Returns | When to use it |
| — |
| After |
|
|
| The ground-truth correctness check. |
|
|
| After simulate passes, to hand off RTL. |
|
|
| The strongest correctness signal — yosys-synthesizes the Verilog. |
| — |
| What this host can actually do, probed rather than assumed. The fast bytecode simulator ships with the commercial distribution and is absent from the open-source compiler, so any flat claim about it is wrong in one of the two environments — call this before deciding how to verify. |
|
|
| Start here when writing new C⏚ from a blank file. Returns a complete, COMPILING, self-checking skeleton with the datapath left as |
|
| no pattern → | Scored lazy lookup into the validated-code dictionary (NOT search). Specificity-weighted, so |
| — |
| Static checks for code the compiler accepts and is still wrong. Chiefly a |
|
|
| Map a compiler rejection to the recipe with the fix pattern (div/shift-by-variable → Recip; data-dependent loop bound → SeqDiv). |
|
|
| Finalize the FPGA report: renders |
|
|
| Confirm a task's compiled state machine has the intended states/transitions. |
|
|
| Confirm a network's compiled wiring (instances, ports with widths/interfaces, connections). |
|
| no topic → | Fetch a markdown knowledge doc on demand. |
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; aproperties { test: {...} }block self-checks.cg_simulate(src)orcg_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 containsTestwith a capital T (e.g.network TestFoo); a lowercase_testnetwork drives the bytecode sim'stestproperty only, not iverilog. NeedsiverilogonPATH.cg_simulate(src, simulator="iverilog").'verilator'— accepted for forward-compat but reported unavailable unless theverilatorbinary 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)orcg_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").
topdefaults 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
Draft C⏚ (always starting with
package).cg_lint→ free and instant; catches the mistakes the compiler will happily accept, above all atest:block that checks nothing.cg_check→ fix every diagnostic, and readwarnings: those are the compiler's own objections to code it will nonetheless accept.cg_simulate→ confirmok: trueand that the output matches intent.cg_generate_verilogonce it simulates, to hand off RTL.cg_synth(optional) → confirm the Verilog maps to real hardware (ok: true, a sensiblecellscount, noproblems).
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] } }
out push u8 value;
u8 count;
void setup() { count = 0; }
void loop() { count = count + 1; value.write(count); }
}'''
cg.check(src) # {'ok': True, 'diagnostics': [], ...}
cg.simulate(src) # {'ok': True, 'simulator': 'bytecode', ...}
cg.generate(src, output_dir="build/v") # {'ok': True, 'file_count': N, 'written': [...]}
cg.synth(src, flow="ice40") # {'ok': True, 'top': 'Counter', 'cells': ..., 'problems': []}Through the MCP tools the same calls are cg_check → cg_simulate →
cg_generate_verilog → cg_synth. Draft, then walk down the list, fixing
diagnostics at each gate; cg_synth is the final hardware gate.
Seed-and-adapt: start from a verified base
Knowledge + verification gets a model surprisingly far, but there's a ceiling:
for a genuinely hard fixed-point datapath (e.g. an n-body force kernel with a
1/r²·√r² term), a model asked to write it from scratch flails — in C⏚ and
in Verilog. The reliable pattern is seed-and-adapt: hand the model a small,
verified base and have it change only the dataflow, keeping the parts it
can't invent (the Q16.16 multiply-accumulate, the task/network/monitor shape).
Call cg_example(pattern) to fetch one. This is a curated dictionary of
validated code with scored lazy access (not free-form search): no pattern
returns the index; a name or intent ("1/sqrt", "distance", "divide a by b",
…) returns the single best-matching source plus 1-2 runners-up so the model can
self-correct. Matching is specificity-weighted, so "1/sqrt"→RSqrt while a bare
"sqrt"→FixedSqrt. When the compiler rejects something,
cg_suggest_for_error(msg) points at the recipe with the synthesizable pattern.
examples/ holds the verified entries — every one simulates, generates Verilog,
and passes yosys synth. kind splits the reusable primitives (Recip, Divide,
SeqDiv, FixedSqrt, RSqrt, SqrDist, DotProduct, Fir, Integ, Distance, Counter)
from application examples (Force, GalaxyForce — n-body composition). Full
table with use_when/tags/cell counts in examples/RECIPES.md. A primitive
whose demo drives constant inputs (DotProduct, FixedSqrt, Distance) reports
cg_synth verdict: FOLDED — drive it with in push ports (as SqrDist does) so
the datapath survives.
See cg_adapt_demo.py in the
repository to watch the
seed-and-adapt loop run end to end, and EVAL.md for how C⏚ and Verilog write
rates were measured on small tasks — including what that measurement does not
show.
Documentation
Installing C⏚ — the extension and the CLI
The older name
This project was published as cg-agent-kit up to 1.0.0; "cg" is our shorthand
for C⏚ and meant nothing to anyone searching for an FPGA tool. On PyPI that name
is now a shim that installs this package, and inside the package
python -m cg_agent_kit.cg_mcp_server and the cg-mcp-server command both
still resolve — so existing instructions and host configs keep working. New
installs should use neosyn-fpga-mcp.
License
MIT. Copyright (c) 2026 Neosyn.
The software is provided "as is", without warranty of any kind, express or
implied, including but not limited to the warranties of merchantability, fitness
for a particular purpose and noninfringement. In no event shall the authors or
copyright holders be liable for any claim, damages or other liability, whether
in an action of contract, tort or otherwise, arising from, out of or in
connection with the software or the use or other dealings in the software. The
full text ships with the package as LICENSE.
C⏚, Cg and Neosyn are marks of Neosyn. The C⏚ compiler is a separate work under its own licence — see neosyn.io/open.
Available Tools
10 toolscg_checkA
Parse, scope, and type-check C⏚ source without running it. Returns
{ok, diagnostics:[{file,line,message}], summary}. Call this first on
any draft; fix every diagnostic before simulating. extra_files maps
filename → content for imported bundles/tasks (e.g. {"Defs.cg": "..."}).
For a MULTI-FILE project, pass package_dir (the folder holding your
.cg files, e.g. "fpga/src/main/cg", relative to the project root): the
tool then reads every sibling .cg there, so tasks defined in other files
of the same package resolve — just like the IDE. A task you only got from
cg_example is text; it must be saved to a file in that dir to resolve.
Inputs: source (required), extra_files, package_dir.
cg_docsA
Fetch a markdown knowledge doc. No topic → an index of available topics with descriptions; a topic → its full content. Topics: 'context' (the core C⏚ language pack — load before writing any Cg) and 'riscv' (the worked RV32I CPU reference: the loadable single-cycle core and the reusable patterns for CPU-shaped hardware in Cg — barrel shifter, signed/unsigned widening, sub-word load/store, count-prefixed boot-stream program loading, and the lossless-capture / address-filtered testbench patterns). Read 'riscv' when building or extending a processor, instruction decoder, datapath, or stack machine.
Inputs: topic.
cg_exampleA
Get a VERIFIED C⏚ base to seed-and-adapt from (don't synthesize hard
kernels from scratch — adapt a known-good one). This is a curated
dictionary of validated code with scored lazy lookup, NOT free-form
search. No pattern → a compact index (name + kind + use_when + tags). A
pattern → the single best-matching source plus its metadata and 1-2
runners_up so you can self-correct on an ambiguous query. k>1 also
returns the next sources when the task implies composition.
Matching is specificity-weighted (exact name ≫ name word ≫ full tag
phrase ≫ partial overlap), so e.g. "1/sqrt" → RSqrt while a bare "sqrt"
→ FixedSqrt. kind distinguishes general PRIMITIVES (the reusable
library: Recip, Divide, SeqDiv, FixedSqrt, RSqrt, SqrDist, DotProduct,
Fir, Integ, Distance, Counter) from application EXAMPLES (Force,
GalaxyForce). Every entry passes simulate + generate + iverilog + yosys.
Workflow: cg_example → edit only the dataflow → cg_check → cg_simulate →
cg_generate_verilog → cg_synth.
Inputs: k, pattern.
cg_fsmC
Show a task's compiled state machine (states + transitions). Useful to confirm an FSM has the intended number of states.
Inputs: source (required), task, extra_files.
cg_generate_verilogA
Generate synthesizable HDL from C⏚. target is 'verilog' (default) or 'vhdl'. Returns {ok, file_count, files:{path:content}}. Use after cg_simulate passes, to hand off RTL.
Pass output_dir (e.g. "fpga/build/verilog", relative to the project
root) to WRITE the files to disk and KEEP them — the result then also
carries {output_dir, written:[paths]}. Without it the files are only
returned inline and the temp dir is cleaned. Prefer output_dir when
the host needs the .v on disk (to inspect or run yosys).
For a MULTI-FILE project, pass package_dir (the folder with your .cg
files) so sibling tasks in the same package resolve during generation.
Inputs: source (required), target, output_dir, extra_files, +1 more.
cg_graphB
Show a network's compiled graph (instances, ports with widths and interfaces, connections). Useful to confirm wiring.
Inputs: source (required), network, extra_files.
cg_reportA
Finalize the FPGA report: (re)render <report_dir>/report.html — a self-contained HTML with the synthesis table (REAL/FOLDED/SUSPECT verdict
cell/arith/latch counts), the simulation PASS/FAIL + output, the generated-Verilog file list, and (best-effort) datapath schematic SVGs.
This does NO synthesis — the rows are built incrementally by passing the
SAME report_dir to cg_synth (per kernel) and cg_simulate as you run
them; cg_report just aggregates those fragments + the Verilog under
<report_dir>/verilog and renders. Workflow:
cg_generate_verilog(output_dir="<report_dir>/verilog", package_dir=...)
cg_simulate(..., report_dir="<report_dir>")
cg_synth(..., report_dir="<report_dir>") # once per kernel
cg_report(report_dir="<report_dir>") # finalize + schematics
Returns {ok, report (the .html path), kernels, sim_ok, message}. Set
schematics=False to skip the SVGs (faster).
Inputs: report_dir, schematics.
cg_simulateA
Simulate C⏚ source. Returns {ok, simulator, timed_out, diagnostics,
output}. output holds port values and print() lines; a
properties { test: {...} } block self-checks and fails the run on
mismatch. This is the ground-truth correctness check — iterate until
ok is true.
simulator picks the backend: 'bytecode' (default — the compiler's
fast simulator, no HDL toolchain) or 'iverilog' (generate Verilog +
testbench and run Icarus Verilog, a Verilog-level cross-check; needs a
network <Name>_test). 'verilator' is accepted but reported
unavailable unless installed.
For a MULTI-FILE project, pass package_dir (the folder with your .cg
files, e.g. "fpga/src/main/cg") so every sibling task in the same package
resolves — a cg_example you pulled must be saved to a file in that dir,
not just referenced.
report_dir DEFAULTS to "fpga/build" — this run's PASS/FAIL + output is
recorded into that dir's accumulating report.html (see cg_report). Pass
report_dir="" to disable.
Inputs: source (required), timeout, simulator, report_dir, +2 more.
cg_suggest_for_errorA
Map a compiler error/diagnostic to the recipe that demonstrates the
synthesizable pattern for what was rejected. Returns {ok, recipe, hint,
source}. div/shift-by-a-variable → Recip (bit-serial long division);
a data-dependent/runtime loop bound → SeqDiv (sequential FSM divider).
cg_check/cg_simulate/cg_generate_verilog already auto-attach this as a
suggestion when a diagnostic matches; call this directly to look one up.
Inputs: message (required).
cg_synthA
Synthesize the generated Verilog with yosys — the strongest signal
that a design maps to real hardware (catches non-synthesizable
constructs that simulate/iverilog accept). Returns {ok, verdict, top,
flow, cells, arith_ops, latches, warnings, stat, problems, output}.
verdict is the one-word classification so you can't confabulate
success: REAL (a genuine datapath), FOLDED (0 datapath cells — inputs
weren't on ports, dead hardware), SUSPECT (latches inferred — a
data-dependent loop / missing reset), or ERROR (yosys failed). cells
is the gate count; problems lists any ERROR/Warning lines.
warnings flags the two silent failure modes: a DEGENERATE datapath
(arith_ops == 0 → the design constant-folded; drive it with input
ports) and inferred LATCHES (latches > 0 → a data-dependent loop bound
or incomplete assignment; expected a clocked FSM). A clean synth has
ok: true, a sensible cells, arith_ops > 0, and empty warnings.
NOT a correctness oracle: a REAL verdict means real (synthesizable)
hardware, NOT correct hardware — it can't tell a good sequential FSM
from a buggy one. cg_simulate (the asserting test network) is the
correctness check; run it FIRST, then cg_synth to confirm the hardware
is real, not folded or latched.
top defaults to the first non-testbench task/network (the DUT); pass
it when a file holds several designs. flow selects the synthesis
flow: 'generic' (default, portable check) or a vendor FPGA family —
'ice40', 'ecp5', 'xilinx', 'gowin', 'intel' — to map to that part's
primitives. Override the yosys binary with the $YOSYS env var. Run
after cg_simulate passes. A constant-bound for synthesizes (it's
unrolled); a data-dependent loop becomes an FSM (also fine).
report_dir DEFAULTS to "fpga/build", so each synth automatically records
THIS kernel's verdict + cell counts as a row in <report_dir>/report.html —
synthesizing the kernels builds the whole report as a byproduct, no
separate step (see cg_report). Pass report_dir="" to disable.
Inputs: source (required), top, flow, timeout, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a distinct stage in the C⏚ hardware design workflow: type-checking, documentation, example retrieval, FSM analysis, HDL generation, graph visualization, reporting, simulation, error-to-recipe mapping, and synthesis. No overlaps are apparent.
All tools share the 'cg_' prefix. Most follow a verb_noun pattern (e.g., cg_check, cg_generate_verilog, cg_simulate), but a few use nouns alone (cg_docs, cg_example, cg_fsm, cg_graph). This minor inconsistency slightly reduces clarity but remains acceptable.
With exactly 10 tools, the set is well-scoped for a hardware design assistant. It covers the full front-to-back workflow without being overwhelming or too sparse.
The tool surface provides complete lifecycle coverage: code checking, example retrieval, simulation, synthesis, Verilog generation, report finalization, plus supplementary tools for debugging (FSM, graph) and error guidance. No obvious gaps for the stated purpose.
Maintenance
Related MCP Connectors
Design circuits, simulate and verify embedded firmware, and lay out PCBs with AI agents.
AI-native programming language and toolchain for accountable, verifiable agent-driven development.
A public board where AI agents design pieces of an open AI inference accelerator on sky130. Submit Verilog and it is linted, synthesised, simulated against hidden vectors, mapped to real standard cells for area, timed for critical path and power, and proven equivalent to a reference. No key, no account, one call. The best verified design gets fabricated.
Run, build, and validate firmware on virtual hardware from your AI agent. Hardware knowledge corpus.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides AI assistants with a complete FPGA toolchain for HDL linting, simulation, synthesis, and place-and-route across various hardware targets. It features a GitHub-backed IP core registry that enables users to search for and import MIT-licensed cores directly through their chat interface.151MIT
- AlicenseAqualityBmaintenanceEnables AI coding agents and IDEs to lint, compile, syntax-check, and simulate Verilog/SystemVerilog designs through structured, token-efficient MCP tools with isolated containerized toolchains.417 npmApache 2.0
- AlicenseAqualityCmaintenanceEnables AI coding agents and IDEs to run a complete open-source FPGA flow, including synthesis, place-and-route, bitstream generation, and safe hardware programming for iCE40/ECP5 boards.67 npmApache 2.0
- AlicenseNot gradedqualityBmaintenanceGives coding agents structured access to an EDA toolchain so they can lint, simulate, formally verify, synthesize, place and route, program a board and read its UART. Returns parsed results (errors with file and line, timing per clock, utilization, inferred memories, counterexample traces) instead of raw logs, closing the run-simulate-fix loop without copy-paste.55 PyPI13AGPL 3.0