NVivo Headless MCP

用标准 MCP stdio 在 Windows 后台创建、导入、编码、保存和重新打开 NVivo 工程。适用于支持本地 MCP 的智能体客户端，模型可由 DeepSeek、Qwen、Kimi 或其他提供方驱动。

作者：Shalom。版本：0.1.0。真实验证环境：Windows、NVivo 15.6.1.3、LocalDB QSRNVivo20.6、Python 3.13。软件运行时与有效许可由使用者本机提供。本仓库提供适配器源码；NVivo 商业软件及 DLL 由本机安装提供。其他 NVivo 版本需先运行自检及真实测试。

安装

git clone https://github.com/youngiry/nvivo-headless-mcp.git
cd nvivo-headless-mcp
.\install.ps1 -NvivoInstallDir "D:\QSR\NVivo 15"

安装器生成 config.local.json。把其中的 mcpServers.nvivo_headless 合入客户端 MCP 设置。已有设置保留，再新增这一项。客户端若采用 TOML，转换同名 command、args、env 字段即可。

$env:NVIVO_INSTALL_DIR = "D:/QSR/NVivo 15"
.\.venv\Scripts\python.exe doctor.py
.\.venv\Scripts\python.exe verify_live.py

真实测试创建独立测试工程，验证中文、emoji后的引文位置、重复句定位、父子代码、编码重试、备忘及保存重开；测试输出在 results/native_mcp_acceptance.json。运行前关闭目标测试工程。

Related MCP server: Agent Gateway MCP

使用

先调用 nvivo_doctor，再调用 nvivo_create_project。通过 nvivo_sync_coding 批量导入 sources、memos、codes、cases、codings，最后调用 nvivo_checkpoint。sources 放完整可读材料，memos 放研究判断过程，codes 放主题和初码，cases 放案例及属性。编码通过 source、code、quote 和零起点 occurrence 指向精确原文。父代码排在子代码之前，各对象使用唯一名称。最小输入见 examples/bundle.json。

现有研究项目需要完整替换时使用 pipeline.py --input 输入.json --project 最终.nvp --report 验收.json --author Shalom。该入口创建候选、原生验证、备份、替换、从最终路径重开，再更新最近项目。MCP 的 sync 为增量合并，同名正文变化时要求先明确处理；完整替换适用于已经整理好的全量输入。

13个工具覆盖环境检查、创建、项目检查、来源列表/读取、代码列表/新增、文本导入、备忘、精确编码、引用读取、批量同步和保存核验。

在 NVivo 的代码树中点击上级节点左侧“＋”查看下级编码。上级节点自身的参考点可为0，下级节点承载实际编码；双击具体代码查看原文参考点。

范围和恢复

材料清洗是独立插件：Material Cleaning MCP。本工具接收已经准备好的文本。组合方法见 工作流。

NVivo 插件运行于安装软件的 Windows 机器，支持同机 stdio MCP；云端聊天网页需要能连接本地工具的客户端。DeepSeek 是模型提供方，实际 MCP 接入由 Harness/客户端实现，配置字段以客户端版本为准。标准协议测试通过代表传输兼容；各品牌客户端的端到端适配另行验证。

NVIVO_WORKSPACE 限定 MCP 工程目录；默认作者为 Shalom，可通过 NVIVO_AUTHOR 设置。安装目录使用 NVIVO_INSTALL_DIR，LocalDB 可通过 NVIVO_LOCALDB_EXE 与 NVIVO_LOCALDB_INSTANCE 配置。备份位于 workspace/native_runs 或报告旁的 native_runs。并发使用同一个工程应由客户端串行排队，NVivo前台打开的工程应先关闭。资料、报告及备份保留在本机。

每次换机、升级 NVivo 或变更运行时后先执行真实测试，报告通过后再处理正式项目。备忘记录实际研究过程及整理时间。

DeepSeek Harness专用示例见 接入说明 和 examples/dsh.patch.yml。