内容
# mcp-contracts
[模型上下文协议](https://modelcontextprotocol.io/) 服务器，允许 AI 代理处理法律合同（DOCX/MD）而无需支付将 30 页文档倒入上下文窗口的往返成本。
## 为什么
LLM 代理擅长推理合同文本，但文件格式却很敌对：DOCX 是二进制的，有跟踪的更改和审阅者评论，MD 是纯文本，没有结构意识。直接将两者输入模型既昂贵又嘈杂。
该服务器弥合了这一差距。它提供了有针对性的工具 - 读取单个条款，列出审阅者评论，验证交叉引用，总结结构 - 以便代理仅获取所需的内容。它还处理常见的作者任务（DOCX ↔ MD，DOCX → PDF），以便同一个代理可以在无需离开其工具的情况下编辑和发布。
## 用例
### 1. 审阅带有审阅者评论的 DOCX
对方发送回带有评论和跟踪更改的 DOCX。你希望代理提取评论，找到相应的条款，并提出回应。
```
agent: list_comments(file_path)
→ "律师@对方.com 的 5 条评论"
agent: find_clause(file_path, query="4.2") # 被评论的条款
agent: list_tracked_changes(file_path) # 他们在内联编辑的内容
→ 代理根据每条评论起草回复，您审查并回复
```
无需将整个文档加载到上下文中 - 代理只需获取正在争论的条款。
### 2. 通过 AI 代理迭代编辑
当合同频繁编辑时，请将其保留在 MD（代理可以干净地编辑的格式）中，并在发送给同事时仅转换为 DOCX。
```
1. 代理编辑 contract.md（条款、价格、日期 - 明文差异）
2. md_to_docx(contract.md) # → contract.docx
3. 您将 contract.docx 发送给对方
4. 他们用评论版本回复 → 参见用例 #1
5. 代理将接受的更改应用回 contract.md
6. 循环
```
源代码保持基于文本且可差异；DOCX 是线格式。
### 3. 仓库中的 MD，发布为 PDF
对于面向公众的法律文档（服务条款、隐私政策、服务条件），在仓库中保留主版本为 MD，并自动生成实际上在网站上提供的 PDF。
```
1. 您编辑 terms.md 并提交到 git
2. CI / 预部署钩子调用：
md_to_docx(terms.md) → terms.docx （中间件，带有适当的样式）
docx_to_pdf(terms.docx) → terms.pdf （用户下载的文件）
3. 差异在 PR 中可审查（文本），但读者获得精致的 PDF
```
版本控制、责备、分支审查 - 都像处理常规代码一样；二进制 DOCX/PDF 工件是副产品。
## 工具
### 转换
| 工具 | 方向 | 备注 |
|------|-----------|-------|
| `docx_to_md` | DOCX → MD | 保留跟踪的更改（`{++ins++}`，`{--del--}`）和审阅者评论为 `[^N]` 脚注。 |
| `md_to_docx` | MD → DOCX | 多级编号（1.，1.1.，1.1.1.），A4，Times New Roman。 |
| `docx_to_pdf` | DOCX → PDF | 无头 LibreOffice。尝试本地 `soffice`；如果失败则回退到 docker 镜像（参见[设置](#setup)）。 |
### 节省令牌的读取器
| 工具 | 返回内容 |
|------|-----------------|
| `read_contract` | 完整文本（DOCX 自动转换为 MD）。 |
| `read_sections` | 仅请求的章节，例如 `sections="2,4,9"`。 |
| `find_clause` | 按编号（`"4.2"`）或按关键词（`"payment"`）查找特定条款。 |
| `contract_summary` | 当事方、主题、价格、期限、目录 - 紧凑的概述。 |
### 审查助手
| 工具 | 执行操作 |
|------|--------------|
| `list_comments` | 带有作者、日期、文本的审阅者评论。 |
| `list_tracked_changes` | 插入和删除带有作者、日期、文本。 |
| `validate_references` | 查找损坏的内部引用（例如，当 7.4 不存在时，`см. п. 7.4`）。 |
所有工具都接受绝对的 `file_path`。有关完整模式，请参见 `server.py`。
## 安装
### 1. 克隆
```bash
git clone https://github.com/IntelionCloud/mcp-contracts.git
cd mcp-contracts
```
### 2. Python 依赖项
需要 Python 3.10+。
```bash
pip install -r requirements.txt
```
### 3. PDF 转换（可选，仅当使用 `docx_to_pdf` 时）
在主机上安装 LibreOffice：
```bash
# Debian/Ubuntu
sudo apt install libreoffice-core libreoffice-writer fonts-open-sans
# macOS
brew install --cask libreoffice
```
… 或构建捆绑的 docker 镜像（当找不到本地 `soffice` 时自动用作回退）：
```bash
docker build -t mcp-docx-soffice:latest docker/
```
### 4. 在您的 MCP 客户端中注册
服务器作为 stdio 进程运行。将它添加到您的客户端配置中。
**Claude Code / Claude Desktop** - 添加到项目的 `.mcp.json`（或对于 Claude Desktop，添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"docx-contracts": {
"command": "python3",
"args": ["/absolute/path/to/mcp-contracts/server.py"]
}
}
}
```
重启 MCP 客户端；工具（`docx_to_md`、`md_to_docx`、`docx_to_pdf`等）现在应该出现在工具列表中。
### 5. 烟雾测试
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
| python3 server.py
```
您应该看到一个 JSON 响应，列出所有工具。如果进程抱怨缺少模块，请在正确的虚拟环境中重新运行步骤 2。
## 本地化
工具通过 Cyrillic-vs-Latin 字符比率在前 50 KB 文本中自动检测合同语言。识别三种模式：
| 检测到 | 何时 | 效果 |
|----------|------|--------|
| `ru` | 西里尔字符 ≥ 字母的 70% | 俄语模式 + 俄语标签（`Цена`，`Срок`，`Структура`，`п.`） |
| `en` | 西里尔字符 ≤ 30% | 英语模式 + 英语标签（`Price`，`Deadline`，`Structure`，`Clause`） |
| `ru+en` | 中间范围（典型的双列 EN-RU 合同） | 应用两个模式集并去重；双语标签（`Цена / Price`，`Структура / Structure`） |
通过将 `language="ru" | "en" | "ru+en"` 传递给以下任意一个，可以覆盖自动检测：`find_clause`、`contract_summary`、`validate_references`、`read_sections`。
要添加第三种语言：扩展 `PATTERNS` 和 `LABELS` 在 `core/i18n.py` 中，更新 `Lang` `Literal`，并在需要时调整 `detect_lang` 中的阈值。
## 旧版 `.doc` 支持
所有读取/转换工具（`docx_to_md`、`read_contract`、`find_clause`等）都透明地接受旧版二进制 `.doc` 文件（Word 97-2003）- 它们通过无头 LibreOffice 自动转换为 `.docx` 并在 `tempfile.gettempdir()` 中缓存，键为文件修改时间，因此重复工具调用不会重新调用 `soffice`。需要本地 `soffice` 安装或 `mcp-docx-soffice` docker 镜像（参见上面的 PDF 设置）。
存储在 NFD 格式中的西里尔文件名（从 macOS 复制时常见）也得到处理 - 路径在边界处标准化为 NFC。
## 测试
```bash
pip install -r requirements-dev.txt
pytest
```
## 许可证
此包装代码**仅限非商业使用**：免费用于个人、学术或内部工具目的。商业使用（转售、SaaS 或在创收产品中使用）需要从 Intelion Cloud 获得书面许可。
捆绑的依赖项保留其原始许可证 - 特别是 [`adeu`](https://github.com/dealfluence/adeu) 是 **MIT 许可**的，不受此限制的影响。非商业条款仅涵盖此存储库中的包装层（MCP 服务器、工具模式和 `core/` 下的帮助模块）。
