内容
# ACG MCP 服务器
[](https://opensource.org/licenses/MIT)
**独立 MCP 服务器**，用于 [审计上下文生成（ACG）协议](https://github.com/Kos-M/acg_protocol) — 可验证的事实核查和基于 MongoDB 的 RAG。
ACG 提供了一个双层标准，用于确保真实性：
- **UGVP（第 1 层）**：原子事实基础，带有声明标记和源哈希身份（SHI）
- **RSVP（第 2 层）**：逻辑综合验证，带有关系标记
## 功能
- **索引 URL** → 提取文本，按句子分段，生成嵌入，存储在 MongoDB 中
- **搜索来源** → 在索引内容中进行语义（向量）+ 关键词搜索
- **检查索引** → 置信度评分查询，避免不必要的 web_fetch 调用
- **生成基础文本** → 创建可验证的输出，带有内联声明标记
- **验证声明** → 重新获取来源，对声明进行模糊匹配
- **构建 VAR** → 生成机器可读的真实性审计注册表（SSR + RAR）
- **爬取和索引** → BFS URL 发现 + 自动 ACG 索引管道
- **重置数据库** → 删除所有 ACG 集合（需确认保护）
## 要求
- Python 3.11+
- MongoDB 实例（本地或 Atlas）
- Atlas 向量搜索是**可选的** — 如果没有嵌入模型，则降级为关键词搜索
## 安装
有两种安装方式 — 根据您的使用场景选择：
### 选项 A：本地开发（可编辑安装）
在本地开发时，您将编辑代码，请以可编辑模式安装：
```bash
# 克隆仓库
git clone https://github.com/Kos-M/acg_mcp.git
cd acg_mcp
# 在可编辑模式下全局安装（推荐用于代理/CLI 使用）
pip install -e .
# 或使用 venv：
# python -m venv venv && source venv/bin/activate && pip install -e .
```
这使得 `acg-mcp` 命令在**全局**（或 venv 范围内）可用，因此您可以从任何目录运行它。
### 选项 B：直接使用源代码
```bash
git clone https://github.com/Kos-M/acg_mcp.git
cd acg_mcp
pip install -r requirements.txt
# 然后运行：python -m src.server
```
## 配置
复制 `.env.sample` 到 `.env` 并配置：
```env
# MongoDB 连接字符串（必需）
MONGO_URI=mongodb://localhost:27017
# MongoDB 数据库名称（可选，默认为 acg_protocol）
MONGO_DB=acg_protocol
# 嵌入模型缓存目录（可选）
EMBEDDING_CACHE_DIR=
```
对于 MongoDB Atlas：
```env
MONGO_URI=mongodb+srv://<user>:<password>@<cluster>.mongodb.net/acg_protocol?retryWrites=true&w=majority
```
## 使用
### 运行 MCP 服务器（stdio 传输）
**编辑安装后（推荐用于全局使用）：**
```bash
# 从任何目录都可以使用 — 如果全局安装，则无需 venv 激活
acg-mcp
```
**未安装 CLI 时（仅限源代码目录）：**
```bash
cd /path/to/acg_mcp
python -m src.server
```
### 从 MCP 客户端连接
服务器通过 **stdio** 进行通信。这些示例适用于 Claude Desktop 和 Opencode（使用相同的 `mcpServers` JSON 格式）。
#### 全局安装（推荐用于代理和工具）
在 `pip install -e .` 后，`acg-mcp` 命令在全局范围内可用。直接在 MCP 配置中使用它 — 无需路径：
```json
{
"mcpServers": {
"acg-mcp": {
"command": "acg-mcp",
"env": {
"MONGO_URI": "mongodb+srv://..."
}
}
}
}
```
#### 从源代码目录运行
如果您尚未安装 CLI，请使用完整路径：
```json
{
"mcpServers": {
"acg-mcp": {
"command": "python",
"args": ["-m", "src.server"],
"env": {
"MONGO_URI": "mongodb+srv://..."
}
}
}
}
```
> **重要：** 当使用 `python -m src.server` 时，请从项目根目录 (`/path/to/acg_mcp`) 运行 MCP 客户端，或在 MCP 配置中设置 `cwd`。
### 配置文件位置
| 工具 | 配置文件 | 范围 |
|------|-------------|-------|
| Claude Desktop | `claude_desktop_config.json` | 用户范围 |
| Opencode | `~/.opencode/mcp.json` | 用户范围（全局） |
| Opencode | `.opencode/mcp.json` | 项目范围（本地） |
## 从其他工具和代理使用
在全局范围内安装 `pip install -e .` 后，机器上的任何工具或代理都可以通过在 MCP 配置中引用 `acg-mcp` 来使用它。
### 示例：WEBFORGE 代理设置
将以下内容添加到代理的 MCP 配置中（例如 `~/.opencode/mcp.json`）：
```json
{
"mcpServers": {
"acg-mcp": {
"command": "acg-mcp",
"env": {
"MONGO_URI": "mongodb://localhost:27017"
}
}
}
}
```
代理可以直接调用 ACG 工具：
- `acg_check_indexed()` — 检查索引来源中是否存在答案
- `acg_index_url()` — 索引新的 URL
- `acg_verify_claims()` — 验证基础文本声明
- `acg_search_sources()` — 搜索索引知识库
### 传递环境变量
通过 MCP 配置中的 `env` 字段传递 `MONGO_URI` 和其他配置。服务器还会加载项目目录中的 `.env` 文件（如果存在）。
## 可用工具
| 工具 | 描述 |
|------|-------------|
| `acg_index_url` | 为 ACG 索引 URL — 获取、分割、嵌入、存储 |
| `acg_check_indexed` | 检查查询在索引来源中是否有结果 |
| `acg_search_sources` | 按关键词搜索索引来源 |
| `acg_list_sources` | 列出所有索引来源 |
| `acg_count_sources` | 计算总索引来源 |
| `acg_generate_grounded_text` | 创建带有声明标记（UGVP）的文本 |
| `acg_verify_claims` | 验证声明与其来源（模糊匹配） |
| `acg_build_var` | 构建真实性审计注册表（SSR + RAR） |
| `acg_crawl_and_index` | 爬取 + 索引多个 URL（后台支持） |
| `acg_crawl_status` | 检查后台爬取任务状态 |
| `acg_crawl_list_tasks` | 列出所有后台爬取任务 |
| `acg_reset_database` | ⚠️ 删除所有索引数据（需确认=true） |
## 数据库集合
服务器使用标准 MongoDB 集合结构：
| 集合 | 用途 |
|------------|---------|
| `sources` | 来源元数据（url, shi_prefix, url_hash, total_chunks） |
| `data` | 带有嵌入的段落（source_id, text, sentences, embedding） |
| `claims` | 已验证的声明（claim_id, shi_prefix, claim_text, verified） |
| `relationships` | RSVP 关系记录（rel_id, rel_type, claim_ids） |
| `var_entries` | 真实性审计注册表条目 |
索引将在首次连接时自动创建。
## 许可证
MIT
