leam-opt-mcp
This server exposes a staged, review-gated MCP workflow for antenna source analysis, versioned HFSS Python code generation, and optional simulation/optimization.
Check server health, workspace, optional backend availability, and execution gate.
Create and run staged antenna modeling jobs from natural-language descriptions, PDFs, and images; inspect job state and artifacts.
Analyze, refine, recheck, and approve antenna source evidence such as topology, dimensions, materials, and uncertainties with hash-frozen review.
Propose and approve engineering assumptions for unresolved parameters, then compile reviewed artifacts.
Generate offline-safe, versioned HFSS Python models; submit HFSS/image feedback and regenerate new model versions.
Prepare artifact review hashes and build HFSS projects only after explicit approval.
Create and run isolated HFSS optimization jobs when the simulation gate is enabled, preserving trial history and source projects.
Drive end-to-end antenna pipelines through source understanding, artifact review, approved build, and optimization.
Provides tools for generating, reviewing, and versioning HFSS Python modeling code, building HFSS projects, running parameter studies, and automating antenna design optimization via PyAEDT.
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., "@leam-opt-mcp Turn the antenna figure and dimensions in paper.pdf into HFSS Python code."
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.
LEAM Opt MCP
从论文、天线结构图和自然语言要求生成可审核、可版本化、可反馈修正的 HFSS Python 建模代码,并在模型确认后选择性进入仿真和自动优化。
当前版本:
0.1.0-alphaHFSS 是当前实现的后端;CST 接口已预留,但尚未实现。
这个项目解决什么问题
论文复现通常不是简单的“识别几个数字”:尺寸可能分散在图片、图注和正文中,部分参数没有公开,不同案例还可能出现在同一页。让大模型直接操作 HFSS,容易把识别错误直接变成不可追踪的模型错误。
本项目把这个过程拆成可检查的流水线:
PDF / 图片 / 文字描述
↓
识别天线拓扑、尺寸、材料和布尔关系
↓
固定规则评估论文可复现性(A / B / C)
↓
区分论文证据、视觉解释、工程假设和未确定项
↓
人工审核与内容哈希确认
↓
generated_model_v001.py
↓
用户在 HFSS 中运行并与来源图片对照
↓
文字或截图反馈
↓
generated_model_v002.py
↓
可选:HFSS 求解和参数自动优化生成 Python 代码是默认终点。识别和代码生成不会自动启动 AEDT,也不需要 HFSS 许可证。
Related MCP server: hfss-agent-native
核心能力
项目提供 LEAM 天线复现与评估 skill,作为现有 Python 后端的对话入口。加载该 skill 后,可以输入“评估这篇论文第 4 章的天线”或“第 32 页已有 损耗角,请复核这项扣分”,由 skill 调用后端、解释证据,并按修订流程处理反馈。
在 Codex 中,将 skills/leam-reconstruct 连接或安装到项目的 .agents/skills/ 发现目录,
然后通过 $leam-reconstruct 调用。仓库源文件是维护入口;本机的发现目录使用指向源文件的
junction,因此编辑源文件会同步反映到发现目录。skill 不包含 Python 依赖或模型凭据,
仍需完成下文的系统安装与模型配置。
修改交互方式和报告组织时编辑 skill;修改评分规则时编辑 src/antenna_mcp/reproducibility.py。
当前评分为待校准的资料完整度指标,不能解释为复现成功概率。历史评估需保留来源与规则版本,
再对比修改前后的分数。
接收自然语言、PNG/JPEG 和论文 PDF;
使用本地视觉模型或云端视觉模型读取结构图;
将识别结果保存为参数、材料、实体、尺寸和布尔操作等中间工件;
对图文冲突、跨案例尺寸污染、低置信度结构和未公开参数执行质量检查;
按固定 100 分规则评估几何、材料、馈电、求解和验证证据,输出 A/B/C 可复现性等级;
用内容哈希冻结人工审核结果,工件修改后旧批准自动失效;
生成 import-safe 的
generated_model_vNNN.py,只暴露build(hfss);保存用户的 HFSS 对照意见和截图,生成新的代码版本而不覆盖旧版本;
在显式授权后构建 HFSS 工程、运行参数试验并保存最优结果;
同时提供 MCP 和命令行接口。
快速安装
需要 Python 3.10–3.13。仅使用离线建模流程时不需要安装 AEDT。
git clone https://github.com/jacksonnnzzz/leam-opt-mcp.git
cd leam-opt-mcp
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev,local-vision]"需要通过外部 Python 连接 HFSS 时,再安装 PyAEDT:
python -m pip install -e ".[hfss,dev,local-vision]"检查当前配置;报告只显示密钥是否存在,不显示密钥内容:
antenna-doctor配置视觉与文本模型
下面的组合使用本机 Ollama 识图、DeepSeek 处理文本和生成代码:
ollama pull qwen3-vl:8b
$env:ANTENNA_VISION_PROVIDER = "ollama"
$env:OLLAMA_BASE_URL = "http://localhost:11434"
$env:OLLAMA_VISION_MODEL = "qwen3-vl:8b"
$env:ANTENNA_TEXT_PROVIDER = "deepseek"
$env:DEEPSEEK_API_KEY = "<your-key>"
$env:DEEPSEEK_BASE_URL = "https://api.deepseek.com"
$env:DEEPSEEK_MODEL = "<your-text-model>"
# 可选:只覆盖本次进程使用的文本模型,包括续跑已有任务。
$env:ANTENNA_TEXT_MODEL = "<your-text-model>"
$env:ANTENNA_MCP_WORKSPACE = ".antenna-mcp"环境变量只对当前 PowerShell 进程及其子进程生效。不要把真实 API Key 写入 README、配置样例、任务 JSON 或 Git 提交。
ANTENNA_TEXT_MODEL 是显式的运行时覆盖项,优先级高于任务创建时保存的
request.model,但不会改写任务 JSON。它只传给 ANTENNA_TEXT_PROVIDER;本地视觉仍由
ANTENNA_VISION_PROVIDER 和 OLLAMA_VISION_MODEL 独立控制。没有设置该变量时,继续使用
原有的任务模型/提供方默认模型行为,因此旧任务和旧配置保持兼容。
UTF-8 JSON、Markdown、CSV 等纯文本附件会在明确的不可信证据边界内嵌入文本提示,并由
ANTENNA_TEXT_PROVIDER 处理;图片和 PDF 才路由至 ANTENNA_VISION_PROVIDER。文本附件的
总字符数默认限制为 250000,可用 ANTENNA_TEXT_ATTACHMENT_MAX_CHARS 调整。
也可以将视觉提供方设置为 openai,具体变量见 .env.example。
最短建模流程
1. 创建任务
antenna-workflow model-create `
--description "只复现目标图中的天线,不得混用论文其他案例的尺寸" `
--template paper_reconstruction `
--attachment "C:\path\to\paper.pdf"命令会返回一个 mdl-... 任务编号,后续命令都使用这个编号。
2. 识别并审核来源
antenna-workflow model-run <job-id> --through-stage source_analysis
antenna-workflow reproducibility-audit --job-id <job-id>
antenna-workflow source-refine <job-id> `
--description "列出全部实体、独立尺寸、派生关系、材料和未确定项"检查任务目录中的:
source_analysis_candidate.json;reproducibility_assessment.json和reproducibility_report.md;source_refinement_report.json;source_review_packet.json;裁切后的视觉输入和视觉审计文件。
确认内容后,把命令返回的哈希原样提交:
antenna-workflow source-approve <job-id> <source-approval-hash>3. 生成建模代码
antenna-workflow model-run <job-id> --through-stage boolean
antenna-workflow codegen <job-id>生成流程在落盘前同时检查跨阶段结构一致性、model/boolean/simulation 职责隔离,以及
PyAEDT 0.26.3 关键方法和参数名。failed 状态下不要运行 codegen 或 AEDT;completed
也只代表生成门禁通过,最终正确性仍需 benchmark contract 和独立 HFSS/S11 验证。
如果旧任务曾把 qwen3-vl:8b 保存到 request.model,并在 model_3d 阶段失败,可在
同一个 PowerShell 中只覆盖续跑所用的文本模型:
$env:ANTENNA_TEXT_PROVIDER = "deepseek"
$env:ANTENNA_TEXT_MODEL = "<your-deepseek-text-model>"
$env:DEEPSEEK_API_KEY = "<your-key>"
$env:ANTENNA_VISION_PROVIDER = "ollama"
$env:OLLAMA_VISION_MODEL = "qwen3-vl:8b"
antenna-doctor
antenna-workflow model-run <job-id> --through-stage boolean续跑会复用失败阶段之前已经验证并保存的工件,从失败的 model_3d 重新开始;文本覆盖
不会把 Ollama 的视觉模型改成 DeepSeek 模型。
主要输出:
文件 | 作用 |
| 不可变的第一版建模代码 |
| 指向当前最新内容的稳定文件名 |
| 在 AEDT 内运行对应几何版( |
| 在 AEDT 内运行当前最新几何版模型的稳定入口 |
| 记录输入工件、哈希和执行边界 |
| 参数及单位 |
| 材料定义 |
| 实体和拓扑 |
| 坐标和尺寸关系 |
| 固定规则计算的来源完整性评分与逐项缺口 |
| A/B/C 等级及人工可读的后续建议 |
导入 generated_model_v001.py 不会启动 AEDT。只有主动调用其中的 build(hfss),才会修改传入的 HFSS 设计。
在 HFSS 中查看模型
仓库提供两种方式。
方式 A:AEDT 内运行 wrapper
codegen --through-stage boolean 会在该任务目录自动生成 run_in_aedt_vNNN.py
和 run_in_aedt.py;论文案例目录也包含相同形式的入口。打开目标工程,然后在
AEDT 中选择:
Tools > Run Script > run_in_aedt.pywrapper 会调用仓库或安装包中统一维护、带哈希校验的 native adapter,新建一个
唯一命名的 HFSS Design,只构建几何,不保存、不求解。不要直接选择
generated_model_vNNN.py。若移动任务目录,应保留完整 GitHub 仓库,或重新运行
codegen 以记录当前安装位置的 adapter。
包含 simulation_setup 的导出不会生成或覆盖 native wrapper,因为 native adapter
只实现几何接口,不实现 setup、端口或边界 API。此类完整仿真代码必须使用下方的
外部 CPython/PyAEDT 方式执行。
方式 B:外部 PyAEDT
python .\tools\apply_generated_model.py `
".\.antenna-mcp\<job-id>\generated_model_v001.py" `
--validate-only去掉 --validate-only 前,应先打开目标 AEDT 工程和空的 HFSS Design。可以使用 --expect-project 与 --expect-design 防止连接到错误对象。
用户反馈与版本迭代
在 HFSS 中对照论文图片后,提交具体修改意见和可选截图:
antenna-workflow feedback <job-id> `
"馈线需要向左移动 0.5 mm;不得修改已经审核的其他尺寸" `
--comparison-image ".\hfss-comparison.png"
antenna-workflow regenerate <job-id>系统会生成 generated_model_v002.py,不会覆盖 v001。反馈附件会复制到任务目录并记录 SHA-256。
可选:仿真和自动优化
模型确认后,才能考虑端口、边界、空气区域、网格、扫频与优化范围。这些信息不能仅凭结构图片静默猜测。
论文参考模型尚未通过论文门槛时,先使用版本化工程假设搜索。它会锁定论文明确参数, 只改变标记为“来源未披露”的端口、导体、介质或边界假设,并把每次 S11、收敛证据、 哈希和排名保存为不可覆盖版本:
antenna-workflow assumption-plan `
--space ".\examples\validation\wifi_patch_5250\assumption_space.json" `
--output-dir ".\examples\validation\wifi_patch_5250\local_results\assumption_search_v1" `
--limit 10完整的 AEDT 附加、恢复和失败重试命令见
docs/ASSUMPTION_SEARCH.md。只有工程假设版本通过参考门槛
G3 后,才能进入独立候选 G4/G5 和后续性能优化。
若要让系统按 HFSS 反馈自动选择并运行下一条有界假设,可使用 iteration-run:
antenna-workflow iteration-run `
--curve ".\path\to\baseline_s11.csv" `
--target ".\path\to\iterative_target.json" `
--space ".\path\to\assumption_space.json" `
--adapter ".\path\to\assumption_adapter.py" `
--output-dir ".\path\to\iterative_reconstruction" `
--study-output-dir ".\path\to\iterative_assumption_study" `
--grpc-port 50051 `
--active-project <open-aedt-project>命令可从不可变账本恢复,不会重复求解已完成候选,并生成机器可读 JSON 与 Markdown
迭代报告。达到论文门槛、预算上限、假设耗尽或执行失败时自动停止。详见
docs/ITERATIVE_RECONSTRUCTION.md。
执行 HFSS 前需要最终审核哈希和显式执行门:
antenna-workflow artifact-review <job-id>
$env:ANTENNA_MCP_ALLOW_SIMULATION = "1"
antenna-workflow hfss-build <job-id> <artifact-approval-hash> `
--project-name "antenna.aedt"优化器会复制输入工程,在隔离任务目录中运行试验:
先验证每个优化变量确实会改变 HFSS 几何;
未通过自适应收敛或扫频收敛门禁的试验不会参与最优排名;
每次试验追加到
trials.jsonl;当前最优参数写入
best.json;最优工程单独保存;
原始
.aedt文件不会被覆盖;中断后可从已有试验继续,已完成任务重复执行不会再求解。
建议先执行不求解的预检,再正式运行:
antenna-workflow optimization-create .\optimization_request.json
antenna-workflow optimization-preflight <optimization-job-id>
$env:ANTENNA_MCP_ALLOW_SIMULATION = "1"
antenna-workflow optimization-run <optimization-job-id>官方探针贴片已完成一次 12 组真实 HFSS 回归:12/12 组均收敛,目标小频段内最差
S11 从 −9.9348 dB 改善到 −11.4999 dB,源工程 SHA-256 前后一致。可复核记录见
optimization_study_2026_08_28.json。
完整参数格式见 docs/PIPELINE.md。
MCP Server
启动 stdio MCP Server:
leam-opt-mcpMCP 客户端配置示例:
{
"mcpServers": {
"leam-opt": {
"command": "C:/path/to/repository/.venv/Scripts/python.exe",
"args": ["-m", "antenna_mcp.server"],
"env": {
"ANTENNA_TEXT_PROVIDER": "deepseek",
"ANTENNA_VISION_PROVIDER": "ollama",
"DEEPSEEK_API_KEY": "${DEEPSEEK_API_KEY}",
"OLLAMA_VISION_MODEL": "qwen3-vl:8b",
"ANTENNA_MCP_WORKSPACE": ".antenna-mcp"
}
}
}
}主要 MCP 工具:
analyze_antenna_sourcerefine_antenna_sourceapprove_antenna_sourcegenerate_antenna_pythonsubmit_antenna_model_feedbackregenerate_antenna_python_from_feedbackbuild_hfss_projectcreate_hfss_optimization_jobpreflight_hfss_optimization_jobrun_hfss_optimization_jobvalidate_antenna_modelget_antenna_job
论文复现案例
examples/leam_paper_cases 包含四个离线案例:
案例 | 来源 | 当前状态 |
| Fig. 3 | 图中导体尺寸已解析 |
| Fig. 4 | 拓扑和公开尺寸已解析;样条点为显式假设 |
| Fig. 5 | 公开尺寸已解析;基板、馈线等保留工程假设 |
| Fig. 7 | 七实体拓扑、修正式和 FR-4 数据已整理;铜厚为显式假设 |
论文 PDF 不随仓库分发。请把合法获取的 PDF 放入案例的 references/,或在请求文件中填写自己的本地路径。
项目结构
src/antenna_mcp/ 核心 Python 包与 MCP Server
examples/ 论文案例、证据与生成代码
tools/ AEDT native/PyAEDT 执行适配器
tests/ 不需要 API、AEDT 或许可证的测试
docs/ 架构、完整流程和发布说明
.github/ CI、Dependabot 与 Issue 模板正确性验证
论文几何复现案例与正确性基准严格分开。仓库以 Ansys 官方 PyAEDT 探针馈电 贴片作为已求解本地基线,并加入三篇开放论文的六个独立参考设计;它们都可分别 执行离线结构检查和完整 S11 对比:
antenna-workflow validate `
--benchmark ".\examples\validation\ansys_pyaedt_probe_patch\benchmark.json" `
--candidate ".\examples\validation\ansys_pyaedt_probe_patch\candidate_contract.example.json" `
--contract-only `
--report ".\tmp\probe-patch-contract-report.json"没有参考与候选两条 S11 CSV 时,完整验证只会返回 incomplete,不会把几何相似
误报为电磁正确。完整格式与本地参考求解流程见
docs/VALIDATION.md 和
examples/validation。
多论文验证活动的当前状态、论文目标、未决假设和下一道验收门槛见
examples/validation/CAMPAIGN.md。其中离线测试通过、
HFSS 参考求解通过和独立生成候选通过是三个不同结论,不会互相替代。
面向汇报的总体结论见
examples/validation/CORRECTNESS_REPORT.md。
7 个“一案例一文件夹”的运行入口见
examples/validation/cases/CASE_INDEX.md。
测试和打包
pytest
python -m build测试默认使用 fake provider 和 fake HFSS 对象,不会调用云端模型,不会启动 AEDT,也不会消耗 HFSS 许可证。
安全与工程边界
大模型生成的 Python 不是安全沙箱,执行前必须人工检查;
AST 检查只能阻止部分明显危险构造,不能证明电磁模型正确;
图片相似不代表端口、边界、网格、频扫和材料设置正确;
自动优化依赖有效的 AEDT 安装、HFSS 许可证和可求解工程;
项目不提供、修改或绕过任何 Ansys 许可证;
.env、API Key、论文 PDF、.aedt和求解结果默认不提交 Git。
更多信息:
上游工作与资料
本项目不复制 LEAM 源码,而是实现相似的分阶段、可检查建模思想,并增加 MCP、离线代码版本、人工反馈和 HFSS 优化层。
License
Available Tools
22 toolsanalyze_antenna_sourceC
Recognize topology, labels, dimensions, materials, and uncertainties in antenna images/PDFs.
Inputs: attachments (required), description (required), model, template. Returns: object
antenna_server_healthA
Report configured workspace, optional backend availability, and execution gate.
Inputs: no named parameters. Returns: object
approve_antenna_engineering_assumptionB
Approve the exact hash-frozen engineering assumption candidate after user review.
Inputs: job_id (required), approval_hash (required). Returns: object
approve_antenna_sourceB
Approve the reviewed source candidate before downstream model/code generation.
Inputs: job_id (required), approval_hash (required). Returns: object
build_approved_antenna_pipelineC
Build the approved pipeline model and stop before expensive optimization.
Inputs: job_id (required), approval_hash (required). Returns: object
build_hfss_projectC
Build reviewed artifacts; any edit after review invalidates the supplied approval hash.
Inputs: job_id (required), approval_hash (required), grpc_port, project_name, +1 more. Returns: object
compile_reviewed_antenna_modelC
Deterministically compile approved evidence and assumptions into reviewed HFSS artifacts.
Inputs: job_id (required), assumption_approval_hash (required), profile. Returns: object
create_antenna_modeling_jobB
Create a staged prompt-driven modeling job without running the LLM or simulator.
Inputs: description (required), model, backend, template, +4 more. Returns: object
create_antenna_pipelineC
Create one end-to-end job spanning multimodal understanding, HFSS build, and optimization.
Inputs: description (required), model, backend, template, +5 more. Returns: object
create_hfss_optimization_jobB
Copy an existing HFSS project into an isolated job and prepare black-box optimization.
Inputs: request (required). Returns: object
generate_antenna_pipelineC
Run source understanding through optimization planning, then stop at the artifact review gate.
Inputs: job_id (required). Returns: object
generate_antenna_pythonA
Generate a complete Python model artifact without starting AEDT or using a license.
The returned file is safe to import offline. It exposes build(hfss); calling that
function later requires an explicitly supplied, licensed PyAEDT HFSS object.
Inputs: job_id (required), through_stage. Returns: object
get_antenna_jobB
Read current job state and artifact paths.
Inputs: job_id (required). Returns: object
optimize_antenna_pipelineC
Run the planned HFSS optimization and produce the best project plus complete trial history.
Inputs: job_id (required). Returns: object
prepare_antenna_artifact_reviewA
Hash every generated artifact and return the approval token required for HFSS execution.
Inputs: job_id (required). Returns: object
propose_antenna_engineering_assumptionB
Propose a value for a null/unresolved source parameter and return its review hash.
Inputs: unit (required), value (required), job_id (required), symbol (required), +1 more. Returns: object
recheck_antenna_sourceB
Apply a reviewed source audit deterministically and issue a new hash-frozen candidate.
Inputs: job_id (required), visual_audit_path. Returns: object
refine_antenna_sourceB
Reconcile raw visual evidence with extracted text; produces a hash-frozen review candidate.
Inputs: job_id (required), visual_audit_path, target_description. Returns: object
regenerate_antenna_python_from_feedbackB
Use recorded feedback to produce the next versioned Python model, still without AEDT.
Inputs: job_id (required). Returns: object
run_antenna_modeling_jobB
Run modeling stages through the requested stage and save all intermediate artifacts.
Inputs: job_id (required), through_stage. Returns: object
run_hfss_optimization_jobB
Run HFSS trials. Requires ANTENNA_MCP_ALLOW_SIMULATION=1 and never overwrites the source project.
Inputs: job_id (required). Returns: object
submit_antenna_model_feedbackA
Record the user's HFSS/image comparison notes without running or changing AEDT.
Inputs: job_id (required), feedback (required), comparison_images. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 22 tools
Multiple tools involve approval hashes and source refinement, making boundaries unclear (e.g., approve_antenna_source vs approve_antenna_engineering_assumption vs prepare_antenna_artifact_review). Pairs like refine_antenna_source and recheck_antenna_source appear to do nearly the same thing, causing likely misselection.
Naming mixes antenna and hfss prefixes (create_antenna_modeling_job vs build_hfss_project) and includes a noun-phrase tool (antenna_server_health). Verb forms vary (create, generate, build, compile) and long names like regenerate_antenna_python_from_feedback break any clean pattern.
With 22 tools, the server is on the heavy side, though the complexity of the domain (source analysis, modeling, simulation, optimization) justifies many steps. However, the number feels bloated due to overlapping tools that could be consolidated.
The toolset covers a full pipeline from source analysis through approval, Python generation, feedback, and HFSS optimization. Minor gaps exist (e.g., no job listing/cancellation, no pipeline status), but the core workflow is thoroughly covered.
Maintenance
Related MCP Connectors
Design circuits, simulate and verify embedded firmware, and lay out PCBs with AI agents.
Text-to-CAD: build exact STEP or 3MF/STL on the server, each stated requirement measured.
Turn datasheets into source-backed JSON contracts, pinout matrices, and KiCad CAD for AI agents.
Create RF signal projects from prompts, inspect graphs, and export IQ data.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI-assisted design of antennas and electromagnetic structures using openEMS FDTD simulation, with analytical dimension calculators and full-wave script generation.164AGPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables natural language control of HFSS (v2019-2025) for antenna modeling, simulation, and result extraction via win32com without PyAEDT.11MIT
- AlicenseBqualityDmaintenanceEnables closed-loop RF passive design from natural-language requirements to EM-verified Altium boards, automating parametric layout, HFSS simulation, and Optuna optimization via MCP tools.123Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to drive RF/microwave design and simulation workflows, including geometry synthesis, multi-solver execution, quality checks, and optimization, with sandboxed draft-and-validate edits.47GPL 3.0