4NEC2 MCP Server

把 4NEC2 自带的 NEC-2 引擎包装成 MCP server， 让 DeepSeek Harness（DSH）或任意 MCP 客户端用自然语言驱动天线建模与仿真： 建 Yagi 模型、算阻抗/SWR/增益/前后比、扫频、读 .out 文件、按目标做几何优化。

• 传输方式：stdio（DSH 等客户端拉起的默认方式）与 streamable-http

• 10 个工具，全部返回 JSON（错误统一为 {"status": "error", "error": "..."}）

• 除数值结果外还能直接出图：极坐标方向图、3-D 波瓣、SWR/增益/阻抗/Smith 圆图扫频面板（PNG）

• 引擎是交互式 exe，server 内部已用临时目录 + input.inp / output.out 正确驱动，并屏蔽黑窗

• 不修改 4NEC2 的安装文件；--4nec2-dir 可指向任意 4NEC2 安装目录

🏆 成果展示：10 / 15 / 20 m 三波段单 boom 八木

用本项目的工具从零设计并优化出来的一套三波段嵌套八木（10 m 3 单元、15/20 m 各 2 单元，直接 50 Ω 馈电）： 带内 SWR ≤ 1.8、增益 5.7–7.0 dBi、效率 99.7 %，附带几何图、驻波/效率曲线、方向图与架高对比。

→ 完整成果页 docs/showcase-triband.md · 工程细节 designs/triband_10_15_20

Related MCP server: Mechanical MCP Server

典型输出（nec_plot_pattern / nec_plot_sweep 直接返回 PNG 路径）

1. 环境要求

4NEC2 不在默认目录时，用 NEC4NEC_DIR 环境变量或 --4nec2-dir 指定，例如 D:\4nec2。 引擎也可用 NEC2_ENGINE 指定具体 exe。

2. 目录结构

C:\4nec2-mcp-server
├─ mcp_4nec2_server.py       # MCP server 入口（FastMCP，10 个工具 + CLI 参数）
├─ nec2core\                 # 与 MCP 无关的核心库，可单独 import 使用
│  ├─ engine.py              #   发现引擎、校验/清洗 deck、以临时目录驱动引擎
│  ├─ model.py               #   .nec 卡片解析、SY 符号求值、改频
│  ├─ output.py              #   .out 解析（FREQUENCY 分块、阻抗、方向图、功率）
│  ├─ metrics.py             #   SWR/回波损耗/增益/前后比/切面统计
│  ├─ yagi.py                #   YagiDesign → NEC deck 生成
│  ├─ plots.py               #   matplotlib 出图：极坐标/3-D 方向图、扫频面板
│  └─ optimize.py            #   坐标下降优化（SY 符号或 element_length 等变量）
├─ scripts\
│  ├─ install.ps1            # 一键安装：venv + 依赖 + 启动器 + 打印 DSH 条目
│  ├─ start-stdio.bat        # 用绝对路径拉起 stdio 版（install.ps1 生成）
│  ├─ start-http.bat         # 用绝对路径拉起 HTTP 版（install.ps1 生成）
│  ├─ check-tools.py         # MCP 握手自检：列出/调用工具
│  ├─ design_triband.py      # 三波段八木：生成/评估/优化 NEC deck + 几何图
│  ├─ ground_study.py        # 自由空间 vs 真实地面（5/8/10 m）仰角方向图对比
│  └─ check-links.py         # 检查所有 Markdown 相对链接/图片是否存在
├─ docs\
│  ├─ DSH-接入说明.md         # 接入 DeepSeek Harness 的完整步骤
│  ├─ showcase-triband.md    # 成果展示：三波段八木（指标 + 全部图）
│  └─ images\                # README / 展示页引用的示例图
├─ dsh\cordis.mcp-nec2.yml   # 可直接插入的 DSH 配置条目（参考副本）
├─ designs\                  # 示例天线工程（含 NEC deck、几何图、仿真结果）
├─ tests\                    # pytest 用例与夹具（.nec / .out）
├─ plots\                    # nec_plot_* 默认输出目录（生成物，已 gitignore）
├─ pytest.ini                # engine / server 集成测试标记
├─ requirements.txt
└─ .gitignore

3. 快速开始

3.1 一键安装（推荐）

cd C:\4nec2-mcp-server
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install.ps1

脚本会依次：检查项目与 4NEC2 → 复用/创建 .venv → pip install -r requirements.txt → python mcp_4nec2_server.py --version 冒烟 → 生成 scripts\start-stdio.bat 与 scripts\start-http.bat（绝对路径） → 打印 DSH 配置条目。

默认只打印 DSH 条目，不改任何 DSH 配置。 确认要写入时：

powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install.ps1 -ApplyDsh

-ApplyDsh 会：备份为 cordis.patch.yml.bak-yyyyMMdd-HHmmss → 幂等检查（已存在 id: mcp-nec2 / mcp-4nec2 或 serverName: nec2 则跳过）→ 以 UTF-8 无 BOM、沿用原文件换行风格追加条目。

常用参数：

3.2 手动安装

cd C:\4nec2-mcp-server
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe mcp_4nec2_server.py --version    # 期望输出: 2.1.0

3.3 自检（不经过 DSH）

# 启动 server、握手、列出 10 个工具
.\.venv\Scripts\python.exe scripts\check-tools.py

# 顺便调用一个工具（--arg 每个参数写一项，PowerShell 5.1 下最稳）
.\.venv\Scripts\python.exe scripts\check-tools.py --call nec_list_engines
.\.venv\Scripts\python.exe scripts\check-tools.py --call nec_run --arg path=478MHz_8El_Yagi.nec --arg freq_mhz=478.875

# 在清单之后追加 serverInfo 与全部工具的 JSON schema
.\.venv\Scripts\python.exe scripts\check-tools.py --json

check-tools.py 支持 --nec2-dir <dir>（默认 C:\4nec2）；工具返回 isError 时脚本以退出码 1 结束。 参数也可以用 --args '<JSON>' 一次性传入，但 Windows PowerShell 5.1 会在传给原生 exe 前吃掉 JSON 里的双引号， 所以要给 --args 时请用 pwsh 7，或改用可重复的 --arg name=value（值能按 JSON 解析就按 JSON，否则当字符串）。 输出里夹带的 Processing request of type ListToolsRequest 是 MCP server 写到 stderr 的日志， 在 PowerShell 中会显示成红色 NativeCommandError，属正常现象，不影响结论。

3.4 接入 DSH（三步）

1. 备份：Copy-Item $env:USERPROFILE\.dsh\profiles\desktop\cordis.patch.yml "$env:USERPROFILE\.dsh\profiles\desktop\cordis.patch.yml.bak-manual"（install.ps1 -ApplyDsh 会自动备份）。

2. 追加条目：把 dsh/cordis.mcp-nec2.yml 里的 - insert: 块粘到该文件末尾， 或直接运行 scripts\install.ps1 -ApplyDsh 让它完成追加（幂等，已有条目会跳过）。

3. 生效：保存后 DSH 会原地重载该 MCP 连接，新对话里即可看到 mcp__nec2__* 工具；没出现就重启 DSH。

之后在 DSH 里可以直接说（自然语言）：

用 mcp__nec2__nec_run 跑 C:\4nec2\models\478MHz_8El_Yagi.nec 的 478.875 MHz，告诉我阻抗、SWR 和增益

或要求它做更复杂的操作：

列出可用引擎，然后用 nec_sweep 扫 470–486 MHz、步进 4，再用 nec_build_yagi 生成 478.9 MHz 的 8 元 Yagi
（默认参数），最后对比前后比

要看图就直接说（工具会把 PNG 路径返回，DSH 会把图贴在对话里）：

用 nec_plot_pattern 画 478MHz_8El_Yagi.nec 在 478.875 MHz 的方向图，带 3-D 波瓣
用 nec_plot_sweep 扫 468–492 MHz、步进 1，看看 SWR 和阻抗怎么变

完整步骤、字段含义与回滚方式见 docs/DSH-接入说明.md。

4. 命令行用法

python mcp_4nec2_server.py [--4nec2-dir DIR] [--transport {stdio,streamable-http}]
                           [--host HOST] [--port PORT] [--version]

HTTP 模式：

.\.venv\Scripts\python.exe mcp_4nec2_server.py --transport streamable-http --host 127.0.0.1 --port 8765

端点固定为 http://127.0.0.1:8765/mcp（FastMCP 默认路径 /mcp）。客户端示例（已实测）：

import asyncio
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client

async def main():
    async with streamablehttp_client("http://127.0.0.1:8765/mcp") as (r, w, _):
        async with ClientSession(r, w) as s:
            await s.initialize()
            print([t.name for t in (await s.list_tools()).tools])

asyncio.run(main())

scripts\start-http.bat 是可双击/计划任务使用的启动器（绝对路径，MCP_HTTP_HOST / MCP_HTTP_PORT 可覆盖）。

5. 工具参考

所有工具都是同步返回 dict；角度单位是度，增益单位 dBi，阻抗单位 Ω，SWR 以 z0（默认 50 Ω）为基准。 path 可以是绝对路径，也可以是相对 C:\4nec2\models 的文件名。

5.1 nec_list_engines()

无参数。返回 status、nec4nec_dir、preferred（首选 exe 路径）、 engines[]（path / name / folder / size_bytes / preferred）。 本机实测首选 C:\4nec2\exe\nec2dxs11k.exe。

5.2 nec_list_models(directory=None, pattern="*.nec", limit=200)

directory 缺省先扫 C:\4nec2\models，再扫 C:\4nec2\necfile。返回 status、count、 files[]（path / name / size_bytes / modified）。

5.3 nec_describe(path, include_cards=False)

返回 status、path、comment、frequency_mhz[]、ground、excitation[]、wires[]、elements[]、 total_segments、bounding_box、radiation_patterns、symbols、symbol_count、errors、warnings； include_cards=True 时附带解析后的卡片列表。

示例（本机模型）：

.\.venv\Scripts\python.exe scripts\check-tools.py --call nec_describe --arg path=478MHz_8El_Yagi.nec

实测：478.875 MHz、8 个单元、GN -1（自由空间）、电压源激励在 tag 2。

5.4 nec_run(path=None, deck=None, freq_mhz=None, engine=None, z0=50.0, timeout_s=120.0, save_out_path=None, include_pattern=False)

path 与 deck 二选一；freq_mhz 会先改写模型的 FR 卡；save_out_path 保留原始 NEC 输出（否则用临时文件）； include_pattern=True 时返回每个方向图采样点 pattern[]（theta_deg / phi_deg / total_db）。

返回字段：status、engine、duration_s、segments、source、freq_mhz、z_real、z_imag、 z_magnitude、swr、return_loss_db、feed_impedance_ohm、gain_max_db、gain_max_theta_deg、 gain_max_phi_deg、front_gain_db、rear_gain_db、fb_db、polarization、efficiency_percent、 input_power_w、radiated_power_w、cuts[]（kind / fixed_deg / peak_gain_db / peak_angle_deg / samples / rear_gain_db / fb_db），以及 model、frequency_override_mhz、engine_warnings。

实测（C:\4nec2\models\478MHz_8El_Yagi.nec，478.875 MHz，50 Ω）：

{
  "freq_mhz": 478.88, "z_real": 17.227, "z_imag": -19.203, "z_magnitude": 25.798,
  "swr": 3.379, "return_loss_db": 5.3, "gain_max_db": 13.47,
  "gain_max_theta_deg": 0.0, "gain_max_phi_deg": 90.0,
  "front_gain_db": 13.47, "rear_gain_db": -9.13, "fb_db": 22.53,
  "polarization": "vertical", "efficiency_percent": 100.0,
  "engine": "nec2dxs11k.exe", "duration_s": 0.086, "status": "ok"
}

一个 8 元 Yagi 峰值在仰角 0°（φ=90°）——这正是它该有的样子：方位面（θ=90°）切面峰值只有 -12.77 dBi， 因为主瓣朝天线轴向而不是水平面。

5.5 nec_sweep(path=None, deck=None, start_mhz=None, stop_mhz=None, step_mhz=1.0, freqs_mhz=None, engine=None, z0=50.0, timeout_s=180.0)

freqs_mhz 优先于 start/stop/step。等间距频点会走"一次多频运行"路径；间距不均匀时对每个频点单独跑引擎。

返回 status、model、points、requested_points、rows[]（每条 status / freq_mhz / z_real / z_imag / swr / gain_max_db / fb_db / efficiency_percent）、best_swr、best_gain、bandwidth_swr2_mhz （没有 SWR≤2 的点时为 null）。

实现细节：4NEC2 在"一次多频运行"里只为最后一个频点打印第二张方向图（仰角切面），其余频点只有方位切面。 因此服务端先检查每个频点块的方向图是否完整，不完整就自动回退为逐频点运行——增益始终按全部方向图样本取峰， 等间距扫频与逐点 nec_run 的结果一致（代价是耗时约为一次多频运行的 N 倍，N 为频点数）。

实测（等间距 470–486 MHz，步进 4；阻抗/SWR 已与逐点 nec_run 核对一致）：

{"status":"ok","points":5,"requested_points":5,
 "rows":[{"freq_mhz":470.0,"z_real":15.466,"z_imag":-32.541,"swr":4.699,"gain_max_db":12.92,"fb_db":17.47,"efficiency_percent":100.0},
         {"freq_mhz":474.0,"swr":4.2,"gain_max_db":13.2,"fb_db":19.15},
         {"freq_mhz":478.0,"swr":3.57,"gain_max_db":13.42,"fb_db":21.68},
         {"freq_mhz":482.0,"swr":2.457,"gain_max_db":13.59,"fb_db":27.52},
         {"freq_mhz":486.0,"z_real":52.476,"z_imag":-5.082,"swr":1.117,"gain_max_db":13.63,"fb_db":28.4,"efficiency_percent":100.0}],
 "best_swr":{"freq_mhz":486.0,"swr":1.117,"gain_max_db":13.63},
 "best_gain":{"freq_mhz":486.0,"gain_max_db":13.63},
 "bandwidth_swr2_mhz":null}

5.6 nec_parse_out(path, z0=50.0)

解析已存在（或 4NEC2 GUI 生成）的 .out。返回 status、path、blocks[]（每块 summarize_block 的 freq_mhz / 阻抗 / swr / gain_max_db / fb_db / efficiency_percent / cuts[] 等）、errors、warnings。 不跑引擎，可用来回读历史结果。

5.7 nec_build_yagi(freq_mhz, n_elements=8, boom_length_m=None, radius_m=0.004, element_lengths_m=None, element_positions_m=None, ground="free", z0=50.0, run=True, save_path=None, timeout_s=120.0)

单元竖直（沿 Y）、boom 沿 Z、第 1 单元为反射器（索引从 0 开始计数时是 elements[0]）， 激励默认加在第 2 个单元（driven，紧接反射器）中心。boom_length_m 默认按 0.2 λ 间距取 0.2·(n-1)·λ（8 元即 1.4 λ），反射器 0.460 λ、驱动 0.430 λ、末位引向器 0.370 λ，中间按间距线性收缩； ground 取 free（GN -1）或 perfect（GN 1）。返回 status、frequency_mhz、elements[] （length_m / position_m）、saved_model、deck（完整 NEC 卡片文本）、run=True 时的 simulation （同 nec_run 结构）。

默认参数实测（478.875 MHz、8 元、free）：boom 0.8771 m（1.4 λ），单元长度 0.2882 / 0.2694 / 0.2631 / 0.2569 / 0.2506 / 0.2443 / 0.2381 / 0.2318 m，馈电卡 EX 0 2 4 0 1 0， 共 56 段；仿真 Z = 23.68 − j11.63 Ω、SWR 2.256、增益 12.34 dBi、前后比 12.63 dB。想压低 SWR 可 微调驱动单元长度或加 nec_optimize 让它在 50 Ω 上收敛。

5.8 nec_optimize(path=None, deck=None, variables=None, objective="score", max_evals=40, z0=50.0, engine=None, timeout_s=240.0)

对模型做有界坐标下降搜索。variables 是列表，每项支持：

objective：gain（增益最大）、fb（前后比最大）、swr（SWR 最小）、score（综合，默认）。 max_evals 是引擎运行次数上限，timeout_s 是总墙钟预算。

返回 objective、best（各变量最优值）、score（目标的自然值）、fitness（内部最大化值）、metrics （最优点的完整指标，结构同 nec_run）、evaluations、max_evals、history[]（eval / accepted / values / score / best）、best_deck（最优 NEC 卡片）、variables、status、model。

实测（示例模型，只优化第 2 单元长度，objective="gain"，max_evals=10）：

{"status":"ok","objective":"gain","best":{"element_length_2":0.27},"score":13.48,"evaluations":8,
 "metrics":{"gain_max_db":13.48,"fb_db":22.64,"swr":3.703,"z_real":16.584,"z_imag":-22.785}}

history 里记录每次候选值与是否被接受；best_deck 是可直接另存为 .nec 的最优模型。

5.9 nec_plot_pattern(path=None, deck=None, freq_mhz=None, plane="both", include_3d=False, phi_deg=90.0, theta_deg=90.0, column="total", out_dir=None, engine=None, z0=50.0, timeout_s=120.0, dpi=140)

跑一次 deck，把增益方向图渲染成 PNG：

• plane：both（默认，仰角面 + 方位面两张极坐标子图）、elevation（φ 固定，扫 θ）、azimuth（θ 固定，扫 φ）。

• 角度约定：仰角面的极角就是 NEC 的 θ（0° = 沿 +Z，即 boom 正前方；90° = 垂直 boom）；方位面的极角是 φ （0° = +X）。注意 boom 沿 +Z 的八木，azimuth（θ 固定 90°）得到的是垂直 boom 的平面，主瓣不在这里—— 看主瓣请用 elevation 或 3-D。

• 极坐标按 peak − 40 dB 截断（DYNAMIC_RANGE_DB），免得零点把圆盘拉爆；峰值点会用红点标出并注记 dBi。

• include_3d: true 时会把 deck 里的 RP 卡替换成完整球面网格（RP 0 37 73 1000 0 0 5 5，37×73 点）再跑一次， 额外输出 3-D 波瓣图（按真实 dBi 着色）。deck 自带多张切面 RP 卡时也能正确出 3-D。

• column：total / vertical / horizontal。

• out_dir 默认 C:\4nec2-mcp-server\plots（可用 NEC_PLOTS_DIR 改）。

• 返回 status、model、freq_mhz、peak_gain_db、figures[]（kind / path / size_bytes / peak_gain_db / planes）、notes、engine、duration_s。图路径可直接给客户端显示。

实测（478MHz_8El_Yagi.nec、include_3d=true，引擎 0.07 s）：

{"status":"ok","freq_mhz":478.88,"peak_gain_db":13.47,
 "figures":[
   {"kind":"polar","path":"...\\plots\\478MHz_8El_Yagi_478.880MHz_polar.png","size_bytes":191364,
    "planes":["elevation","azimuth"]},
   {"kind":"3d","path":"...\\plots\\478MHz_8El_Yagi_478.880MHz_3d.png","size_bytes":159627}],
 "notes":["RP 卡已替换为完整球面网格（37×73，5° 步进）以绘制 3-D 方向图。"],
 "engine":"nec2dxs11k.exe","duration_s":0.074}

5.10 nec_plot_sweep(path=None, deck=None, start_mhz=None, stop_mhz=None, step_mhz=1.0, freqs_mhz=None, out_dir=None, engine=None, z0=50.0, timeout_s=180.0, dpi=150)

扫频并渲染 2×2 面板（PNG）：SWR（含 SWR=2/1.5 参考线）、增益 + 前后比（双 Y 轴）、 输入阻抗 R/X、Smith 圆图（含 SWR=1/2/3 圆、Γ 轨迹与频点注记）。扫频逻辑与 nec_sweep 完全一致 （均匀扫频优先单次多频运行，方向图不完整时自动回退逐频点）。

返回 status、points、frequency_range_mhz、figures[]、best_swr、best_gain、bandwidth_swr2_mhz。

实测（470–490 MHz、步进 1，21 点）：best_swr 486 MHz / SWR 1.117、best_gain 485 MHz / 13.64 dBi、 SWR≤2 带宽 484–487 MHz（3 MHz）。

出图依赖 matplotlib（含 numpy）。server 启动时会在主线程预加载 matplotlib（_preload_plotting()， 约 0.3 s）；这是必需的：若把首次 numpy C 扩展导入放到 MCP 的 anyio 工作线程里，导入会卡在 Windows 加载器锁上， 工具会一直不返回，直到客户端超时。设 NEC_PLOTS_PRELOAD=0 或加 --no-plots 可跳过预加载（不推荐）。

6. 返回结构与约定

• 成功：status == "ok"；失败：{"status": "error", "error": "<message>"}，可能附带 errors / warnings / problems / rows。

• source 为 temp 表示输出写在临时目录；给了 save_out_path 则是该路径。

• cuts[] 里 kind 为 azimuth（θ 固定 90°、扫 φ）或 elevation（φ 固定 90°、扫 θ）。

• 方向图采样过滤掉 total_db <= -998.99 的填充值。

7. 配置与集成

7.1 环境变量

7.2 DSH 配置条目

- insert:
    - id: mcp-nec2
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: nec2
        transport: stdio
        command: 'C:\4nec2-mcp-server\.venv\Scripts\python.exe'
        args:
          - 'C:\4nec2-mcp-server\mcp_4nec2_server.py'
          - '--4nec2-dir'
          - 'C:\4nec2'
        cwd: 'C:\4nec2-mcp-server'
        env:
          PYTHONUTF8: '1'
          PYTHONIOENCODING: 'utf-8'
          PYTHONDONTWRITEBYTECODE: '1'
          NEC4NEC_DIR: 'C:\4nec2'
          NEC2_ENGINE: 'C:\4nec2\exe\nec2dxs11k.exe'
        toolCallTimeoutMs: 300000
        failOnStartupError: false
        reconnect:
          enabled: true
          initialDelayMs: 500
          maxDelayMs: 30000
          maxAttempts: 10

要点：

• 新插件要用 - insert: 包一层；裸的 - id / name / config 条目只是覆盖"已存在"的 id（DSH 的 patch 语义）。

• id 可自定义（mcp-nec2 或 mcp-4nec2 都已支持）；真正决定工具名的是 serverName： serverName: nec2 → 工具名 mcp__nec2__<tool>，且 serverName 必须全局唯一。

• 路径用单引号：YAML 双引号里的 \4 会被当成非法转义（unknown escape sequence），导致整份配置解析失败。

• toolCallTimeoutMs: 300000：nec_optimize / nec_sweep 可能跑几分钟，默认 60 s 不够。

详见 docs/DSH-接入说明.md。

8. 测试

# 全部用例（含会真正调用 4NEC2 引擎、真正拉起 server 的集成用例）
.\.venv\Scripts\python.exe -m pytest -q

# 只跑不依赖引擎/子进程的单元用例
.\.venv\Scripts\python.exe -m pytest -q -m "not engine and not server"

pytest.ini 已配置 testpaths=tests、pythonpath=.，并定义两个标记：engine（调用真实引擎）、 server（以 stdio 拉起 server）。部分集成用例依赖本机 4NEC2 与夹具文件，在别的机器上跑之前请先确认 C:\4nec2\exe\nec2dxs11k.exe 可用。

9. 故障排查

10. 许可与致谢

• 本项目代码（mcp_4nec2_server.py、nec2core/、脚本与文档）以 MIT 许可证发布，见 LICENSE。

• 4NEC2 / NEC-2 引擎版权归原作者（Arie Voors 等）。本仓库不包含也不分发 4NEC2 的任何二进制文件或源码， 只调用用户本机已安装的 nec2d*.exe；商用或再分发前请阅读 4NEC2 自身的许可条款。

• 感谢 4NEC2 提供的免费天线建模工具，以及 Model Context Protocol 与 mcp Python SDK 让本地仿真能力可以被 AI 客户端直接调用。

11. 参考

• 4NEC2 官网 — NEC-2 引擎与 GUI、模型示例

• Model Context Protocol — 协议与 Python SDK mcp

• DSH MCP 客户端插件：@deepseek-ai/dsh-mcp-client（随 DSH 分发，配置字段见 docs/DSH-接入说明.md）