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 核实

快速开始

# 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，字段与 src/mcp_law_server/config/settings.py 一一对应。