# mcp-law-server

审计法规智能检索 **MCP Server** —— 面向审计 Agent 的法规/条款/审计事项检索与核实服务。

> Milvus 向量检索（法规名 / 条款 / 审计事项）+ MySQL 关系查询（层级 / 分类）+ Hermes Agent 编排 + Agent 核实

## 技术栈

| 层 | 选型 |
|---|---|
| 语言 / 运行时 | Python 3.12 |
| 包管理 / 构建 | uv + hatchling（src-layout） |
| MCP 框架 | FastMCP >=2.3（stdio + HTTP 双传输） |
| MySQL 访问 | SQLAlchemy 2.x async + asyncmy（双库：audit_corpus / auditkm_factory） |
| 向量库 | Milvus（pymilvus），库 `sys_law_title`，10 个 Collection |
| Embedding | BGE-large-zh-v1.5，1024 维（本地 FlagEmbedding 推理） |
| LLM | Qwen3.5-27B（vLLM，OpenAI-compatible HTTP） |
| 缓存 | Redis / 内存双后端（TTL + 多轮对话上下文） |
| 配置 | pydantic-settings + `.env` |
| 编排 | Hermes Python 编排引擎（`src/mcp_law_server/hermes/`，14 Agent） |

## 目录结构

```
mcp_law_server/
├── pyproject.toml                # 元数据 / 依赖 / 入口 / 工具配置
├── .env.example                  # 环境变量模板（复制为 .env 填写）
├── Dockerfile                    # Docker 镜像构建（python:3.12-slim）
├── docker-compose.yaml           # 单服务编排（stdio/http 双传输）
├── src/mcp_law_server/           # ── 应用代码（src-layout）──
│   ├── main.py                   # CLI 入口（stdio / http 双传输 + 优雅关闭）
│   ├── config/                   # 配置层 —— Settings 单例（pydantic-settings）
│   ├── models/                   # 数据模型层 —— enums / schemas / errors / error_codes
│   ├── interfaces/               # 接口层 —— 13 个 Protocol 定义（embedding/db/vector/cache）
│   ├── db/                       # MySQL 数据访问层 —— connection + 5 个 DAO
│   ├── vector/                   # Milvus 向量访问层 —— client + 3 个 Searcher
│   ├── embedding/                # Embedding 层 —— BGEEncoder 本地推理
│   ├── cache/                    # 缓存层 —— 内存/Redis 双后端 + TypedCache
│   ├── tools/                    # MCP 工具层 —— 11 个 tool handler（核心业务）
│   ├── hermes/                   # Hermes 编排层 —— 10 文件 Python 包（14 Agent DAG）
│   ├── observability/            # 可观测性 —— logging + degradation + log_format
│   ├── registry/                 # MCP Registry —— 12 文件 7 模块（工具注册/语义匹配/网关）
│   ├── chat/                     # Chat 服务 —— export/law/stats/sse 4 模块
│   └── server/                   # MCP Server 注册 —— mcp_app + error_boundary
├── scripts/                      # ── 运维脚本（验证/演示/向量化/性能测试）──
└── tests/                        # ── 测试（14 子目录，1066 测）──
```

依赖方向（从下到上，禁止反向引用）：
`config → models → {db, vector, embedding, cache} → tools → server → main`

横切层 `observability/`、`registry/`、`interfaces/` 被多层依赖。

## 核心能力（11 个 MCP 工具）

| 类型 | 工具 | 说明 |
|------|------|------|
| 编排入口 | `agent_query` | Hermes DAG 综合查询（意图→路由→三通道并行→融合） |
| 编排入口 | `decompose_query` | Agent 00 问题拆解 + 逐题验证 + 可信度聚合 |
| 路由入口 | `smart_query` | 按意图路由到对应原子工具 |
| 原子工具 | `search_law_name_vector` | 法规名称向量检索（MySQL 三形态 + Milvus 语义） |
| 原子工具 | `search_clause_vector` | 条款内容向量检索（Milvus 6 collection 联合） |
| 原子工具 | `issue_to_law` | 审计问题→法规映射（bge 双路 RRF 合并） |
| 原子工具 | `law_lookup` | 按法规 ID 查六要素详情 |
| 原子工具 | `law_article_search` | 法规全文条款检索 |
| 原子工具 | `get_regulation_hierarchy` | 法规层级关系查询（上位法/相关法/历史版本/废止） |
| 原子工具 | `get_clause_classifications` | 条款法定属性分类（7 类法律规范属性） |
| 原子工具 | `verify_law_reference` | 法规引用 4 轮 Loop 核实 |

## 快速开始

```bash
# 1. 安装核心 + 开发依赖（uv 会自动准备 Python 3.12 解释器）
uv sync

# 2. （按需）安装 ML 依赖（FlagEmbedding / torch，体积较大）
uv sync --extra ml

# 3. 配置环境变量
cp .env.example .env          # 然后编辑 .env 填写真实值

# 4. 启动 MCP Server（stdio 模式）
uv run mcp-law-server

# 5. 启动 MCP Server（HTTP 模式）
MCP_TRANSPORT=http uv run mcp-law-server
```

## 常用命令

| 命令 | 说明 |
|---|---|
| `uv sync` | 安装核心 + 开发依赖 |
| `uv sync --extra ml` | 额外安装 ML 依赖 |
| `uv run mcp-law-server` | 启动 MCP server（stdio） |
| `uv run mcp-law-server http` | 启动 MCP server（HTTP） |
| `uv run python -m pytest tests/ -v` | 运行全部测试（1066 测） |
| `uv run ruff check .` | 代码风格检查 |
| `uv run mypy src/` | 类型检查 |
| `uv run docker compose up --build` | Docker 部署 |

## 环境变量

见 [.env.example](.env.example)，字段与 [src/mcp_law_server/config/settings.py](src/mcp_law_server/config/settings.py) 一一对应。