# Material Cleaning MCP

独立的材料清洗工具，使用标准 MCP stdio，也可通过命令行运行。功能是清理采集头、网页标记、人工确认的导航行和无关段落，并保护引文、重算重复出现次序、输出清洗审计。作者 Shalom，版本0.1.0。

本工具独立于 NVivo，可用于论文材料、网页文本和其他定性研究输入。原件由调用方保留，输出为新文本和审计。默认保留源码、运行记录、JSON/XML等技术证据；CSV按完整记录转为字段阅读视图。

## 安装和接入

```powershell
git clone https://github.com/youngiry/material-cleaning-mcp.git
cd material-cleaning-mcp
.\install.ps1
```

安装器输出 `config.local.json`，将 `mcpServers.material_cleaning` 合并到支持 MCP 的客户端。也可使用 Python 3.11+ 创建虚拟环境并安装 requirements.txt，然后以该解释器启动 server.py。代码采用标准库清洗核心，Windows已实测，其他操作系统可先运行测试。

DeepSeek、Qwen、Kimi等模型通过支持本地 MCP 的 Harness/客户端使用该工具。工具本身无需模型 API key；具体客户端配置格式以其版本为准。

## 输入和输出

调用 `materials_clean(documents, passages, rules)`。documents 为 name/text 对象列表；passages 为 source/quote/occurrence/label 对象列表；occurrence从0开始，表示原文中第几次出现。rules按来源名称指定 `remove_lines` 或 `keep_lines`，行号从1开始且指向本次输入原文。

先阅读各来源并确认正文边界，再给出规则。自动规则仅处理常见采集头与格式；正文取舍仍依材料内容判断。被引文覆盖的删除行会受到保护并列入审计。输出 documents、passages 及 audit，审计包含前后哈希和字符数。完整示例见 examples/input.json。

```powershell
.\.venv\Scripts\python.exe cleaner.py --input examples/input.json --output results/cleaned.json
.\.venv\Scripts\python.exe verify_live.py
```

CLI要求新的输出文件路径，以保留原件。规则与原件版本成对保存；重新清洗时从原件开始。当前范围为已经提取的文本；PDF版面识别、扫描件OCR和网页下载由上游处理。

## 与 NVivo 组合

先用本工具清洗，再把 documents映射为NVivo的sources、passages映射为codings中的quote和occurrence。NVivo建工程、编码及保存由独立的[NVivo Headless MCP](https://github.com/youngiry/nvivo-headless-mcp)完成。组合步骤见 docs/workflow.md。

DeepSeek Harness专用示例见 [接入说明](docs/deepseek-harness.md) 和 `examples/dsh.patch.yml`。