neuro-mcp

它为 AI Agent 提供统一接口，覆盖完整的临床/研究 EEG 工作流：信号处理和源成像（通过 MNE-Python）、持久化数据集和 EHR 存储 （Postgres + BIDS），以及 NeuroII 网络 可视化。

概念

flowchart LR
    Clinician(["🩺 Clinician"])
    Researcher(["🔬 Researcher"])
    Agent[["🤖 AI Agent"]]
    Server(("neuro-mcp<br/>FastMCP · 54 tools"))

    Clinician -- talks to --> Agent
    Researcher -- talks to --> Agent
    Agent -- MCP --> Server

    Server --> Processing["Processing &amp; Source Imaging<br/>MNE-Python + ESI"]
    Server --> Data["Data &amp; EHR Store<br/>Postgres + BIDS<br/>versioned &amp; audited"]
    Server --> NeuroII["NeuroII<br/>Web Visualization"]

    classDef proc fill:#4f8cff,stroke:#2f5fbf,color:#fff
    classDef data fill:#2fb380,stroke:#1c7a55,color:#fff
    classDef viz fill:#b06fe0,stroke:#7c3fae,color:#fff
    class Processing proc
    class Data data
    class NeuroII viz

临床医生或研究人员从不直接调用工具——他们用日常语言与 Agent 对话，由 Agent 在底层调用 neuro-mcp 的 54 个工具。 如需了解完整流程，请参阅教程。

参与者和工作流

• 临床医生 — 查看记录、添加/编辑注释并修改 EHR（记录诊断/观察结果、更正数值），然后签署确认。
• 研究人员 — 查找数据集、导入到 BIDS、运行 MNE 处理和源成像。
• Agent — 通过工具调用协调上述工作。

临床安全模型（EHR 和注释）

EHR 记录和注释均为版本化记录，不会被覆盖或永久删除：

• 修改 = 新建经过审计的版本。 amend_ehr_record / update_annotation 会插入新版本；先前版本会保留，状态为 amended。因此，临床医生可以修改 EHR——当前视图会更新，同时保留原始记录及其作者。
• 撤回 = 软作废。 void_ehr_record / void_annotation 会将状态设为 entered-in-error；记录仍保留在历史记录中。
• 每次变更都会记录审计信息（audit_log：操作者、操作、变更前/后内容）。
• 修改类工具要求明确提供 actor，以便记录作者信息。 （计划在 v0.2 中加入 Auth/RBAC 执行机制；相关字段和审计轨迹已就绪。）

每个工具都会返回一个表示操作的 outcome 字段（created/amended/voided/…），它与记录的临床 status 不同，因此两者不会冲突。

工具（54 个）

• 处理（load_neuro、filter_neuro、resample_neuro、set_montage、 set_reference、detect_bad_channels、run_ica/apply_ica、find_events、 epoch_neuro、compute_psd、compute_erp、time_frequency、plot_*）以及 源成像 / ESI（fetch_template_head … extract_label_timecourses）。
• 数据/EHR：register_subject、get_subject、add_ehr_record、 amend_ehr_record、get_ehr_history、void_ehr_record；import_recording、 register_dataset、query_datasets、list_recordings；add_annotation、 update_annotation、list_annotations、void_annotation；get_audit_log。
• neuroii：neuroii_push_recording、neuroii_create_viz_session、 neuroii_pull_annotations。
• neuroii 可视化（独立交互式 HTML，Plotly）：visualize_timeseries （堆叠式多通道 EEG，支持滚动和振幅按钮，并显示注释标记）、visualize_averaging （ERP 蝴蝶图 + 头皮地形图，可通过时间滑块浏览）、visualize_esi （源估计 ROI 时间序列 + 按时间显示的激活条形图）。

安装

conda create -n neuro-mcp python=3.11 -y   # or any Python >=3.10 env
conda activate neuro-mcp
pip install neuro-mcp              # core, from PyPI
pip install "neuro-mcp[postgres]"  # + PostgreSQL driver (LGPL-3.0)
pip install "neuro-mcp[viz3d]"     # + 3D source rendering (PySide6, LGPL-3.0)

如果你要开发 neuro-mcp 本身，可以克隆仓库，并用 pip install -e . 替换上面的命令行——完整的从零开始配置指南（包括 Claude Code/Codex CLI/Claude Desktop 注册）请参阅安装。

配置（环境变量）

变量	默认值	用途
DATABASE_URL	sqlite:///~/.neuro-mcp/neuro_mcp.db	存储。生产环境：postgresql+psycopg://user:pass@host/db
BIDS_ROOT	~/.neuro-mcp/bids	磁盘上 BIDS 记录目录树的根目录
NEUROII_API_URL	(未设置)	neuroii 基础 URL；未设置时 → 工具返回文档中定义的契约
NEUROII_API_TOKEN	(未设置)	neuroii 的可选 Bearer 令牌
NEURO_MCP_HOME	~/.neuro-mcp	SQLite + BIDS 默认值的基础目录

默认配置（SQLite + 临时 BIDS 目录）无需任何配置即可运行；如需用于多用户／临床部署，请将 DATABASE_URL 指向 Postgres。

运行／注册到 MCP 宿主

python -m neuro_mcp     # stdio transport

{
  "mcpServers": {
    "neuro-analysis": {
      "command": "/path/to/envs/neuro-mcp/bin/python",
      "args": ["-m", "neuro_mcp"],
      "env": { "DATABASE_URL": "sqlite:////data/neuro_mcp.db", "BIDS_ROOT": "/data/bids" }
    }
  }
}

neuroii Web 可视化

三个工具将 NEUROII 的主要视图移植为自包含的交互式 HTML文件（内嵌 Plotly，无需服务端，离线可用）。每个工具都会返回 .html 路径；交互在客户端运行：

• visualize_timeseries（RawView）——MNE 风格的堆叠通道，支持分页导航（⏮ ◀ ▶ ⏭）、页面长度输入框、滚动缩放振幅、网格切换，以及以带标签标记线绘制的记录注释（可切换）。
• visualize_averaging（EvokedView）——以堆叠通道显示平均 ERP，带绿色时间光标和头皮地形图；时间滑块可同时控制二者，另有摘要侧栏（nave / peak / tmin / tmax）。
• visualize_esi（EsiView）——将体积源估计（fsaverage 模板）渲染到画布上，显示三个正交 MRI 切片（矢状面／冠状面／轴向面），叠加黑－蓝－白－红激活图层，并显示十字准线、左右侧及 MNI 坐标标签；切面会以每一帧的峰值为中心重新定位。下方的 ERP 蝴蝶图带有红色当前时间光标和蓝色半峰值标记。控件包括时间滑块、全局／逐帧颜色映射缩放切换，以及掩码阈值滑块。忠实移植 NEUROII 的视图；需要 epochs（epoch_neuro + set_montage）。

visualize_averaging(session_id="s") -> {"out_path": ".../averaging_s.html", ...}

neuroii 集成（从零开始）

neuroii 集成尚未接通。工具会定义并返回预期的 REST 契约（参见 neuro_mcp/neuroii/client.py）；在设置 NEUROII_API_URL 之前，工具会响应 {"status": "not_configured", "contract": {…}}，为 neuroii 应用提供固定的实现目标（POST /api/v1/recordings、POST /api/v1/viz-sessions、GET /api/v1/recordings/{id}/annotations）。

测试

python testing/verify.py     # in-memory MCP client, temp SQLite + BIDS, synthetic EEG

覆盖重命名完整性、处理核心、完整的临床医生 EHR／注释生命周期（添加 → 修订 → 历史记录 → 作废，并包含审计），以及 neuroii 存根。要在 Postgres 上运行全栈测试，请使用 testing/docker-compose.yml。

许可条款

neuro-mcp 采用 BSD-3-Clause 许可，且未捆绑任何第三方源代码。所有必需依赖项均采用宽松许可（BSD/MIT/Apache-2.0/PSF）。可选扩展各自适用其许可条款——psycopg（LGPL-3.0）、PySide6（LGPL-3.0；选择它而非 GPL 的 PyQt6）。完整的署名和合规说明请参阅 NOTICE。

许可证

BSD-3-Clause——请参阅 LICENSE。