内容
<!-- SPDX-License-Identifier: Apache-2.0 -->
# Veqtor MCP
> **公开技术Alpha版：** 用于可验证的DOCX谈判历史和失败关闭的跟踪更改编辑的本地MCP服务器。在macOS和Linux上支持Python 3.12-3.14。
Veqtor为MCP兼容的AI客户端提供确定性工具，以读取合同红线、验证报价、预运行完整的反提案批次、创建具有实际跟踪更改的新DOCX文件，并保持可重新检查的本地来源。模型仍然是法律推理层；Veqtor处理文档事实和写入。
Veqtor不是法律建议、通用Word编辑器、托管服务或篡改证据审计系统。在使用它处理实际事务之前，请查看[已知限制](https://github.com/JohnDeer-ai/veqtor-mcp/blob/v0.1.2/KNOWN_LIMITATIONS.md)。
## 为Claude Code安装
一次性安装[uv](https://docs.astral.sh/uv/)，然后为您的用户帐户注册确切的Veqtor版本：
```bash
claude mcp add --transport stdio --scope user veqtor -- uvx veqtor-mcp@0.1.2
```
打开新的Claude Code会话并验证注册：
```bash
claude mcp get veqtor
```
`--scope user`使私有本地注册对您在此机器上的所有项目都可用。它不会发布配置或使Veqtor成为网络服务。要将Veqtor限制在当前项目中，请使用：
```bash
claude mcp add --transport stdio --scope local veqtor -- uvx veqtor-mcp@0.1.2
```
对于团队管理的配置，Claude Code还支持`--scope project`，它写入`.mcp.json`以供审查和版本控制。不要在作用域中使用机密或特定于事务的路径。
设置注册服务器时的跟踪更改作者：
```bash
claude mcp add --transport stdio --scope user veqtor -e VEQTOR_TRACKED_CHANGE_AUTHOR="您的姓名" -- uvx veqtor-mcp@0.1.2
```
如果未设置，作者为`Veqtor MCP`。该值在服务器启动时固定，模型无法在每次编辑时更改。
## 从终端运行或安装
在没有持久安装的情况下运行诊断：
```bash
uvx veqtor-mcp@0.1.2 doctor
```
用于持久隔离安装：
```bash
uv tool install "veqtor-mcp==0.1.2"
"$(uv tool dir --bin)/veqtor-mcp" --version
"$(uv tool dir --bin)/veqtor-mcp" doctor
```
使用`uv tool dir --bin`即使在uv工具目录未添加到shell `PATH`时也有效。`uv tool update-shell`可以为后续shell添加它。版本轮和sdist用于独立验证，也附加到匹配的[GitHub Release](https://github.com/JohnDeer-ai/veqtor-mcp/releases/tag/v0.1.2)。
## 五分钟演示
创建一个可用的四轮综合谈判：
```bash
uvx --from "veqtor-mcp==0.1.2" veqtor-demo-rounds ~/veqtor-demo-rounds
```
然后询问Claude：
> 使用veqtor工具，在~/veqtor-demo-rounds的各轮中，责任限制发生了什么变化？
对于写入工作流，询问：
> 准备我们的反提案为round-5-our-counter.docx：恢复150％影响的工作订单责任上限，并恢复对方删除的故意不当行为例外。验证措辞并预运行完整的批次，然后再应用。
预期的信任顺序是：
1. 提取当前红线；
2. 验证用作证据的每个引用；
3. 预运行完整的原子批次；
4. 仅在`batch_applicable`为真时应用；
5. 重新提取输出并导出决策记录。
Veqtor永远不会覆盖源文件或现有输出文件。使用可用的演示文件夹进行写入记录；成功写入会创建新的DOCX文件和私有`.veqtor`来源文件夹。
## Claude Desktop
GUI应用程序可能不会继承shell `PATH`。首先运行`command -v uvx`，然后在macOS Claude Desktop配置中的`~/Library/Application Support/Claude/claude_desktop_config.json`中使用该绝对路径：
```json
{
"mcpServers": {
"veqtor": {
"command": "/绝对路径/to/uvx",
"args": ["veqtor-mcp@0.1.2"],
"env": {
"VEQTOR_TRACKED_CHANGE_AUTHOR": "您的姓名"
}
}
}
}
```
在更改可执行文件、版本或环境后，请完全退出Claude Desktop并重新打开。
## 工具表面
- `list_rounds`：确定文件名顺序的本地DOCX文件发现。
- `extract_redlines`：具有哈希值、引用、限定段落上下文和保守手动标签的跟踪更改单元。
- `verify_quote`：锚定`exact`、`normalized`或`not_found`验证。
- `preflight_edits`：完整的适用管道作为内存预运行。
- `apply_edits`：原子跟踪替换、删除、计数和恢复写入。
- `export_decision_record`：紧凑的隐私感知本地来源。
完整的请求、响应和错误合约在[MCP Tool API](https://github.com/JohnDeer-ai/veqtor-mcp/blob/v0.1.2/API.md)中。
## 隐私和保障边界
服务器没有嵌入式模型调用，不会在后台上传整个文档。工具返回的文本进入MCP客户端对话，并可能根据提供商的条款发送到用户的模型提供商。
除非`VEQTOR_DISABLE_DECISION_RECORD=1`，否则工具会在`<matter>/.veqtor/decision-records.jsonl`追加私有本地日志。只读调用，包括`preflight_edits`和决策记录导出，仍通常写入来源。
决策记录是尽力而为的本地来源。它们的哈希值是可重新检查的指纹，而不是身份验证。支持的威胁模型是单个用户本地工作区。Veqtor绑定并验证每个接受的DOCX/ZIP成员的实际输出（DEFLATED数据的限定流式传输和STORED数据的限定直接范围），但这并不使其成为敌对同一用户进程的沙箱。
## 支持的表面
| 表面 | 公开Alpha版 |
|---|---|
| 操作系统 | macOS，Linux |
| Python | 3.12，3.13，3.14 |
| 传输 | 本地stdio MCP |
| 验证客户端 | Claude Code，Claude Desktop |
| DOCX部分 | `word/document.xml` |
| 写入 | 跟踪替换、删除、计数、恢复 |
| 分发 | PyPI加上匹配的GitHub轮/sdist工件 |
Windows、托管MCP、注释/页眉/页脚、接受/拒绝、语义跨轮谱系和加密审计保证不在Alpha版范围内。
## 支持
Veqtor MCP是一个社区支持的公开Alpha版。使用[GitHub Issues](https://github.com/JohnDeer-ai/veqtor-mcp/issues)进行可复制的错误和功能请求，仅使用综合文档。永远不要发布客户端措辞、本地路径、`.veqtor`日志、凭证或实际事务文件。私下报告疑似漏洞，如[安全策略](https://github.com/JohnDeer-ai/veqtor-mcp/security/policy)所述。
不提供响应时间、兼容性、正常运行时间或修复时间SLA。
## 开发和发布
```bash
uv lock --check
uv sync --frozen --all-extras
uv run --frozen pytest -q
uvx ruff==0.15.21 check .
LOCKED_REQUIREMENTS="$(mktemp)"
uv export --frozen --no-dev --no-emit-project \
--format requirements-txt --output-file "$LOCKED_REQUIREMENTS"
uvx pip-audit==2.10.1 --requirement "$LOCKED_REQUIREMENTS" \
--require-hashes --disable-pip --progress-spinner off
uv build --clear
uvx twine check dist/*
uv run --frozen python scripts/check_release_artifacts.py \
--source-root . --commit HEAD dist/*.whl dist/*.tar.gz
```
贡献使用DCO签名确认；请参阅[贡献指南](https://github.com/JohnDeer-ai/veqtor-mcp/blob/v0.1.2/CONTRIBUTING.md)。确切的SHA不可变发布合约在[发布指南](https://github.com/JohnDeer-ai/veqtor-mcp/blob/v0.1.2/RELEASING.md)中记录。
## 维护者
Veqtor MCP是一个独立的开源项目，由**Ilya Shilov** ([@JohnDeer-ai](https://github.com/JohnDeer-ai))创建和维护。
