This is the short usage guide. For the complete reference, see
MCP_MANUAL.md.
From the repository root:
python3 -m venv .venv
.venv/bin/python -m pip install -e .On Windows PowerShell:
py -3.11 -m venv .venv
.\.venv\Scripts\python -m pip install -e .Set these variables before Codex starts the MCP server:
DNA_MAKER_WORKSPACE=<repository path>
DNA_MAKER_BIOLOGY_ADAPTER=dnamaker.service:create_biology_adapter
DNA_MAKER_SNAPGENE_ADAPTER=snapgene.adapter:create_service
On Windows, also set:
SNAPGENE_EXE=C:\Program Files\SnapGene\SnapGene.exe
Configure Codex to run this local stdio server from the repository root:
.venv/bin/python -m agent.server # macOS/Linux
.venv\Scripts\python.exe -m agent.server # Windows
The biology tools work on any supported platform. SnapGene conversion, map rendering, and opening require Windows with SnapGene installed.
Give Codex a request such as:
Use
inputs/pEGFP-N1.gbas the vector and replace theEGFPfeature with the mCherry CDS frominputs/mCherry.gb. Label itmCherry, validate the result, save it asoutputs/pEGFP-N1-mCherry.gb, convert it tooutputs/pEGFP-N1-mCherry.dna, render a map, and open the converted file last.
Codex will call the tools in this order:
start_workflow
read_construct
modify/analyze
validate_construct
save_construct
snapgene_convert
snapgene_render (optional)
snapgene_open (last)
workflow_status
Mutations execute immediately. Saving and SnapGene actions require successful
validation. SnapGene opening must use the exact reference returned by
snapgene_convert.
An MCP client or Python program can call the same tools directly. Always:
- call
start_workflowand keep itsworkflow_id; - call
read_constructbefore editing; - pass the same ID to every tool;
- stop when a response has
"ok": false; - validate before saving or using SnapGene;
- call
workflow_statusat the end.
Successful responses look like:
{"ok": true, "result": {}}Failures look like:
{"ok": false, "error": {"code": "...", "message": "...", "details": {}}}Run tests:
.venv/bin/python -m pytest -qPrepare a biology-only GenBank handoff:
.venv/bin/python -m dnamaker.handoff --workspace .Check SnapGene on Windows:
.\.venv\Scripts\python -m snapgene healthClose SnapGene before conversion or map rendering. Open the generated .dna
file last. Use new output paths for each run.