内容
# 欧几里得-MCP
[](https://glama.ai/mcp/servers/meob/Euclid-MCP)
**逻辑推理的MCP服务器** — 将事实转化为形式化证明。
<!-- mcp-name: io.github.meob/euclid-mcp -->
欧几里得-MCP是一种混合认知架构：一个轻量级的LLM用事实描述世界，而一个确定性引擎执行实际的推导。LLM永远不需要进行推理 — 它只需要描述。
使用欧几里得-MCP，一个80亿参数的模型可以解决甚至4000亿+云模型都难以解决的推理任务 — 因为引擎确定性地处理推导。每个答案都附带一个证明树，因此您可以追溯*为什么*一个结论成立，而不仅仅是*是什么*。将其用于强制执行RBAC策略、审计云合规性、验证贷款资格规则或推理任何需要可解释和可验证答案的领域。
欧几里得-MCP使用Python编写，并使用**欧几里得-IR**，一种人类可读的中间语言，适用于AI代理和人类。它目前使用**SWI-Prolog**作为其推理引擎，可以通过多种方式进行调用：通过**MCP**由AI代理（OpenCode、Claude、Cursor）、通过**HTTP**由工具和自动化平台（n8n、Zapier、Make）以及通过**Python API**进行直接集成。欧几里得-IR规则也可以用于通过确定性策略执行增强RAG流水线。
## 工作原理
```
┌──────────────┐ ┌──────────────────┐ ┌──────────────┐ ┌──────────────┐
│ LLM/代理 │────▶│ 欧几里得-MCP │────▶│ 翻译器 │────▶│ SWI-Prolog │
│ （MCP客户端）│◀────│ （FastMCP） │◀────│ + 元解释器 │◀────│ （子进程） │
└──────────────┘ └──────────────────┘ └──────────────┘ └──────────────┘
```
1. 在简单的中间语言中接收事实、规则和查询
2. 使用元解释器将其翻译成Prolog以捕获证明树
3. 通过SWI-Prolog子进程执行
4. 以结构化JSON返回解决方案+证明树
附加工具（`diagnose`、`what_if`、`check_kb`）通过分析、场景测试和验证扩展此核心流程。
LLM描述。欧几里得MCP证明。
## 中间语言
即使目前欧几里得-MCP使用Prolog引擎，也不需要Prolog语法。
**欧几里得-IR**（中间表示）是一种用于逻辑推理的声明式中间表示。
变量使用 `$name`，蕴涵使用 `IF`，合取使用 `AND`。
**文本格式：**
```
human(socrates)
mortal($x) IF human($x)
? mortal($who)
```
**YAML格式：**
```yaml
facts:
- parent(tom, bob)
- parent(bob, ann)
- parent(tom, liz)
rules:
- ancestor($x, $y) IF parent($x, $y)
- ancestor($x, $y) IF parent($x, $z) AND ancestor($z, $y)
query: ancestor(tom, $who)
```
完整语言参考：[`docs/EUCLID_IR.md`](docs/EUCLID_IR.md)
### 欧几里得-IR语法参考
| 元素 | 语法 | 示例 |
|---------|--------|---------|
| 事实 | `predicate(args)` | `parent(tom, bob)` |
| 变量 | `$name` （小写） | `$who`， `$x`， `$count` |
| 蕴涵 | `IF` （大写） | `mortal($x) IF human($x)` |
| 合取 | `AND` （大写） | `p($x) AND q($x)` |
| 否定 | `NOT` （大写） | `NOT active($user)` |
| 查询 | `? predicate` | `? ancestor(tom, $who)` |
| 多行规则 | 在下一行写主体 | `rule($x) IF\n body($x)` |
### 算术比较
规则支持在推导过程中计算的算术比较：
```
# 过时访问：用户在90天以上未登录
stale_access($user) IF
user($user) AND last_login_days($user, $days) AND $days > 90
# 过度权限：超过15个直接权限
excessive_permissions($user, $count) IF
user($user) AND permission_count($user, $count) AND $count > 15
# 清除检查：用户清除 >= 资源分类
can_access($user, $resource) IF
user($user) AND resource($resource, _, _, _, _, $cls) AND
classification($cls, $cls_level, _) AND
user_clearance($user, $user_level) AND $user_level >= $cls_level
```
**支持的操作符：** `>`， `>=`， `<`， `=<`， `=:=`， `=\=`， `is`
### 多行规则
规则可以跨多行以提高可读性：
```
can_deploy($user, $env) IF
user($user) AND
has_role($user, $role) AND
deploy_requires_level($env, $min) AND
deploy_role_level($role, $level) AND
$level >= $min AND
user_has_permission($user, deploy_code)
```
### 查询中的合取
查询可以组合多个谓词：
```
? can_access_resource($who, $res) AND resource($res, _, _, _, _, secret)
```
这将返回同时满足两个条件的解决方案。
## 为什么使用外部推理？
外部推理带来了几个优势：
- 确定性
- 可解释性
- 可验证性
- 低成本
- 可替换的后端
在当前的实现中，欧几里得-MCP使用Prolog。
Prolog是一种已有50年历史的经过实战验证的逻辑引擎。使用它作为“推导协处理器”可以让小型LLM在不需要更大、更昂贵的模型的情况下执行复杂的多步骤推理。中间语言剥去了Prolog的语法奇特之处，同时保留了其逻辑核心。
一些内部[基准](benchmarks/BENCHMARKS.md)表明了差异：拥有1000+个事实，LLM单独得分2/5，而欧几里得-MCP得分5/5 — 并比输出少14倍的令牌快7倍。
## 工具
欧几里得-MCP公开了**4种工具**，每种工具都有特定的用途：
| 工具 | 用途 |
|------|---------|
| `reason` | 主要推导 — 获取解决方案 + 证明树 |
| `diagnose` | 了解查询为什么成功或失败 |
| `what_if` | 在应用修改前测试修改 |
| `check_kb` | 在推理前验证知识库一致性 |
### `reason`
可验证的确定性推理的主要工具。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `knowledge` | `string` | — | 文本或YAML格式的事实和规则 |
| `query` | `string?` | — | 可选地覆盖查询 |
| `max_solutions` | `int` | `5` | 返回的最大解决方案数 |
| `max_depth` | `int` | `30` | 最大证明树深度 |
**返回** `ReasonResult`包含`solutions[]` — 每个包含变量绑定和证明树。
### `diagnose`
查询分析 — 了解查询为什么成功或失败。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `knowledge` | `string` | — | 文本或YAML格式的事实和规则 |
| `query` | `string` | — | 要诊断的查询 |
| `mode` | `string` | `why` | 以下之一：`why`，`why_not`，`what_needs` |
| `max_solutions` | `int` | `5` | 返回的最大解决方案数 |
| `max_depth` | `int` | `30` | 最大证明树深度 |
**模式：**
- `why` — 解释查询为什么成立（或不成立）
- `why_not` — 解释查询为什么失败（缺少的事实/规则）
- `what_needs` — 建议使假查询为真所需的内容
**返回** `DiagnosisResult`包含`holds`，`findings[]`，`conclusion`，以及可选的`proof`.
### `what_if`
场景分析 — 在应用修改前测试修改。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `base_knowledge` | `string` | — | 基础事实和规则 |
| `modifications` | `string` | — | `+ fact(...)` 添加，`- fact(...)` 删除 |
| `query` | `string` | — | 要评估的查询 |
| `max_solutions` | `int` | `5` | 返回的最大解决方案数 |
| `max_depth` | `int` | `30` | 最大证明树深度 |
**返回** `WhatIfResult`包含`before_count`，`after_count`，`delta`，`solutions_before`，`solutions_after`，`conclusion`.
### `check_kb`
知识库验证器 — 在运行推导前检查一致性。
| 参数 | 类型 | 默认值 | 描述 |
|-----------|------|---------|-------------|
| `knowledge` | `string` | — | 文本或YAML格式的事实和规则 |
**返回** `KBCheckResult`包含`valid`，`errors[]`，`warnings[]`，`facts_count`，`rules_count`，`predicates_count`.
## 安装
### pip
```bash
# 依赖项：Python ≥ 3.10，SWI-Prolog
brew install swi-prolog
# 安装
pip install euclid-mcp
```
### 从源码
```bash
git clone https://github.com/meob/Euclid-MCP
cd Euclid-MCP
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
```
### Docker
不需要本地SWI-Prolog安装 — 镜像包含所有内容。
```bash
# 构建
docker build -t euclid-mcp .
# MCP stdio 模式（适用于本地MCP客户端）
docker compose run --rm euclid-mcp
# HTTP API 模式（适用于n8n，Zapier，远程访问）
docker compose up euclid-api
# API 可在 http://localhost:8080 访问
```
参见 [Docker in Integrations](#docker) 以获取完整详细信息。
## 用例
- **小型LLM推理**：将LLM的推导卸载到确定性引擎
- **可解释的决策**：每个答案都附带证明树，允许解释、推理轨迹和证明
- **业务规则**：验证逻辑链（权限、工作流、合规性）
- **依赖分析**：循环依赖检测、拓扑排序
- **教育**：具有可见证明链的交互式逻辑辅导
- **知识预加载**：复杂的业务规则可以加载到欧几里得中，而不是使用向量数据库
- **查询诊断**：了解查询失败的原因以及缺少哪些事实/规则
- **场景分析**：在应用修改前测试“what-if”修改
- **知识库验证**：在推理前检查知识库的一致性
### 现实世界的例子
安装后（通过pip或从源码，并在激活虚拟环境后）：
```bash
# 家谱 — 递归的家庭树推理
python examples/01_genealogy.py
# RBAC — 基于角色的访问控制
python examples/02_rbac.py
# 分类 — 生物分类
python examples/03_classification.py
# 业务规则 — 贷款资格
python examples/04_loan_eligibility.py
# 合规审计员 — 云资源策略执行
python examples/05_compliance_auditor/auditor.py
# 贷款官员 — 带有详细分解的CSV驱动资格
python examples/06_loan_eligibility/loan_officer.py
# IT安全和合规 — 多层策略推理
python examples/07_it_security_compliance/demo.py --small
```
每个示例都运行一个完整的推理会话，并打印带有证明树的解决方案 — 不需要LLM。
将它们用作将欧几里得-MCP集成到您自己的代理中的模板。
### 示例 07：IT 安全和合规
最先进的示例演示：
- **3层架构**：标准（CIS，AWS IAM）→ 公司政策 → 数据事实
- **算术比较**：`$days > 90` 用于过期访问检测
- **多行规则**：跨多行拆分复杂策略
- **合取查询**：组合多个谓词
- **负面测试**：验证无效访问模式的空结果
```bash
# 快速测试（30个用户，50个资源，约578个事实）
python3 examples/07_it_security_compliance/demo.py --small
# 完整数据集（200个用户，300个资源，约3,872个事实）
python3 examples/07_it_security_compliance/demo.py
```
## 集成
### OpenCode
欧几里得-MCP在`.opencode.json`中包含一个预配置的代理：
```json
{
"mcpServers": {
"euclid-mcp": {
"command": "python3",
"args": ["-m", "euclid_mcp"],
"cwd": "."
}
},
"agents": {
"reasoning-engine": {
"description": "确定性逻辑引擎",
"instructions": "编写欧几里得IR事实，使用reason工具...",
"mcpServers": ["euclid-mcp"]
}
}
}
```
### n8n / Zapier / Make
运行HTTP API：
```bash
python3 integrations/euclid_api.py --port 8080
```
| 端点 | 方法 | 用途 |
|----------|--------|---------|
| `/reason` | POST | 推导证明树 |
| `/diagnose` | POST | 查询失败分析 |
| `/what-if` | POST | 场景测试 |
| `/check-kb` | POST | 知识库验证 |
| `/health` | GET | 健康检查 |
```bash
# 推理
curl -X POST http://localhost:8080/reason \
-H "Content-Type: application/json" \
-d '{"knowledge": "human(socrates)\nmortal($x) IF human($x)\n? mortal($who)"}'
# 诊断
curl -X POST http://localhost:8080/diagnose \
-H "Content-Type: application/json" \
-d '{"knowledge": "human(socrates)\nmortal($x) IF human($x)", "query": "mortal(plato)", "mode": "why_not"}'
# What-if
curl -X POST http://localhost:8080/what-if \
-H "Content-Type: application/json" \
-d '{"base_knowledge": "human(socrates)\nmortal($x) IF human($x)", "modifications": "+ human(plato)", "query": "mortal($who)"}'
# 知识库验证
curl -X POST http://localhost:8080/check-kb \
-H "Content-Type: application/json" -d '{"knowledge": "human(socrates)\nmortal($x) IF human($x)"}'
```
### Docker
Docker镜像包含SWI-Prolog + Python，因此不需要本地依赖项。
基础镜像：[`swipl:stable`](http://hub.docker.com/_/swipl) (Debian Bookworm).
**Docker镜像大小：** ~370 MB（SWI-Prolog + Python script + 依赖项）。
### 命令行
```bash
echo '{"knowledge": "red(apple)\\n? red($x)"}' | python3 integrations/euclid_cli.py
```
详见`integrations/README.md`以获取完整详细信息。
## 贡献
感谢您的兴趣！请随时提出问题或提交PR。
## 许可
Apache 2.0
