内容
# ERDL MCP 服务器
> **停止提醒你的代理人要表现良好。教它。**
> **一句简单的规则即可实现。**
[](https://www.npmjs.com/package/@openoba-ai/erdl-mcp)
[](https://www.npmjs.com/package/@openoba-ai/erdl-mcp)
[](https://github.com/OpenOBA/erdl-mcp-server/blob/master/LICENSE)
[](https://github.com/OpenOBA/erdl-mcp-server/actions)
[](https://modelcontextprotocol.io)
[](https://github.com/OpenOBA/erdl-mcp-server/blob/master/LICENSE)
> 📖 [中文版](./README.zh.md)
```bash
npx -y @openoba-ai/erdl-mcp
```
**30 条规则。5 种工具。零配置。无限自定义规则。永久免费。**
---
## 问题
你告诉你的代理人“不要使用 `any`”，“保持简短”，“添加依赖前请询问”。它点头同意。五次对话后，它又恢复了旧有的习惯。
**基于提示的规则不起作用。** 大型语言模型（LLM）会忘记。它们会重新解释。它们会合理化。你不是在指导它们 — 你是在与它们谈判。
---
## 解决方案
ERDL（实体规则定义语言）是一种 **确定性规则引擎** ，作为 MCP 服务器运行。你的代理人不是“尝试”遵循规则 — 引擎在每次工具调用前 **强制执行** 规则。
| 你说的话 | 实际发生的情况 |
|---------|----------------------|
| “绝不使用 `any`” | **被阻止**。引擎拦截 `write_file` 调用，扫描内容，并在写入发生前拒绝 `any`。 |
| “不要以‘在今天的世界’开头” | **被拒绝**。写入规则在每次输出前触发。代理人收到纠正后才发言。 |
| “添加 npm 依赖前请询问” | **被拦截**。`npm install` 的 `exec` 调用被停止。你批准后，它才会发生。 |
| “你为什么这么做？” | **被解释**。`erdl_explain` 显示触发的规则、匹配的条件和发生的情况。 |
---
## 工作原理
```
┌─────────────────────────────────────────────────────────┐
│ 代理人工作流 │
│ │
│ 用户说：“为我写一个函数” │
│ │ │
│ ▼ │
│ LLM 计划：使用 write_file(path, code) │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────┐ │
│ │ ERDL 动作守卫（MCP 服务器） │ ← 协议层 │
│ │ │ │
│ │ 1. 加载 30 条内置规则 │ │
│ │ 2. 评估：字段/运算符/值 │ │
│ │ 3. 决策：允许 / 拒绝 / 纠正 │ │
│ │ 4. 返回徽章卡 + 说明 │ │
│ └──────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ 工具执行（或被阻止） │
│ │
│ 无需提示工程。无需协商。协议层。 │
└─────────────────────────────────────────────────────────┘
```
---
## 快速开始
```bash
# 一条命令。30 条规则立即生效。
npx -y @openoba-ai/erdl-mcp
```
就是这样。无需账户。无需 API 密钥。无需配置。
**中文 / 中文：**
```bash
npx -y @openoba-ai/erdl-mcp --lang zh
```
将其添加到你的 MCP 客户端：
```json
{
"mcpServers": {
"erdl": {
"command": "npx",
"args": ["-y", "@openoba-ai/erdl-mcp@latest"]
}
}
}
```
或者让 ERDL 生成配置：
```bash
npx @openoba-ai/erdl-mcp@latest --setup
```
**支持的客户端：** Claude Desktop · Cursor · VS Code / Copilot · OpenClaw · WorkBuddy · 任何 MCP 兼容的客户端。
---
## ERDL 与提示规则
| | 提示 / SKILL.md | ERDL |
|---|:---:|:---:|
| **强制执行** | LLM “尝试”遵循 | **确定性引擎** — 保证执行 |
| **可靠性** | 可能在 5 次对话后忘记 | 条件匹配是数学运算 — **零幻觉** |
| **可见性** | 无法判断是否生效 | `erdl_explain` 显示每次决策和规则 |
| **测试** | 手动验证 | `erdl_simulate` — 3 个自动生成的场景 |
| **可移植性** | 与一个平台绑定 | **所有 MCP 兼容代理人** |
| **可覆盖性** | LLM 可以“重新解释” | **协议层阻止** — 代理人无法绕过 |
---
## 包含的内容
### 30 条内置规则
| 类别 | 数量 | 涵盖范围 |
|----------|:-----:|--------|
| `工程` | 13 | 管道门控、无捷径、自验证、决策日志、无强制推送、无储物 |
| `编码` | 6 | 无 `any`、 无 `@ts-ignore`、命名约定、一提交一更改、依赖卫生 |
| `安全` | 6 | 无输入评估、无硬编码秘密、无字符串 SQL、验证所有输入、安全标头、无堆栈跟踪 |
| `测试` | 2 | 覆盖率从不下降、无测试行为 |
| `写作` | 2 | 直接语气、无 AI 专业术语 |
| `可观察性` | 1 | 日志中无秘密 |
### 5 种 MCP 工具
| 工具 | 使用场景 |
|------|-------------|
| `erdl_evaluate` | **每次工具调用前** — 必备动作守卫 |
| `erdl_simulate` | 在创建规则前测试规则是否适用于 3 个场景 |
| `erdl_create_rule` | 用户说“记住这一点” → 从自然语言创建规则 |
| `erdl_list_rules` | 用户询问“有哪些规则生效？” |
| `erdl_explain` | 用户询问“你为什么这么做？” → 完整的决策轨迹 |
### 2 种资源
| 资源 | 目的 |
|----------|---------|
| `erdl://rules/list` | 所有生效规则的 JSON |
| `erdl://status` | 运行时状态：按类别划分的规则数量、代理人角色 |
---
## 创建规则
> **将你的痛点转化为规则，一句一句 — 禁止，彻底。**
> **将你的经验转化为规则，一句一句 — 共享，永久。**
每个痛点都是一句 `when(…) then(…)` 语句：
> 当 [触发器] · 然后 [动作]
| 变量 | 含义 | 示例 |
|----------|---------|---------|
| **when** | 触发条件 | 代码包含 `any` · 日志包含秘密 · 使用 `git stash` |
| **then** | 发生的情况 | **阻止** · **纠正** · **允许** 并发出警告 · **暂停** 等待批准 |
填空：
> **当** 代码包含 `any` **然后** 阻止它。
这就是一条规则。
```
你 → “在 TypeScript 中绝不使用 `any`。”
代理人 → 1. erdl_simulate → 测试 3 个场景
2. erdl_create_rule → 保存到 ~/.openoba/rules/
3. 规则生效。 → 下一个 `any` 被阻止。
你 → “为什么我的代码被拒绝？”
代理人 → erdl_explain → 完整的决策轨迹：
✅ no_any: tool.name in [write_file, edit, apply_patch] AND content contains "any"
→ DENY: 不要使用 `any` 类型。
```
或者在 `~/.openoba/rules/` 中手动编写规则（ERDL SPEC §5 格式）：
```yaml
protocol: "erdl/v1"
version: "1.0.0"
rules:
- name: "no_console_log"
description: "不要提交 console.log 语句"
priority: 10
when:
logic: AND
conditions:
- field: "tool.name"
operator: in
value: ["write", "edit", "apply_patch"]
- field: "tool.args"
operator: match
value: "console\\.log"
then: DENY
message: "提交前请删除 console.log"
```
[📚 完整教程 →](./docs/tutorial-create-rules.md) · [📖 规则参考（30 条规则）→](./docs/rule-reference.md)
---
## 免费与专业版
| | 免费 | 专业版 |
|------|:---:|:---:|
| 5 种 MCP 工具 | ✅ | ✅ |
| 30 条预设规则 | ✅ | ✅ |
| 无限个人规则 | ✅ | ✅ |
| 中文 / 英文 | ✅ | ✅ |
| 所有 11 种运算符 | ✅ | ✅ |
| MIT 开源 | ✅ | ✅ |
| **执行环 1-2** （REQUEST_HUMAN, ESCALATE, ROLLBACK, QUARANTINE） | — | ✅ |
| **守护代理角色** | — | ✅ |
| **审计导出** （OCSF / OTLP） | — | ✅ |
| **团队规则** | — | ✅ |
| **仪表盘** （命中统计） | — | ✅ |
| **企业合规** （GB/Z 185, NIST, EU AI Act） | — | 企业 |
[获取专业版许可证 →](https://openoba.com/erdl-mcp/pro)
---
## CLI 参考
```bash
npx @openoba-ai/erdl-mcp@latest # 启动（自动最新版 via npx）
npx @openoba-ai/erdl-mcp@latest --lang zh # 中文模式
npx @openoba-ai/erdl-mcp@latest --upgrade # 强制升级
npx @openoba-ai/erdl-mcp@latest --uninstall # 干净卸载
npx @openoba-ai/erdl-mcp@latest --setup # 显示 MCP 配置
npx @openoba-ai/erdl-mcp@latest --help # 完整用法
```
---
## 从源码构建
```bash
git clone https://github.com/OpenOBA/erdl-mcp-server.git
cd erdl-mcp-server
npm install
npm run build
npm test # 92 个测试
node bin/erdl-mcp.js
```
---
## 贡献
ERDL MCP 服务器采用 MIT 许可证，欢迎贡献。参见 [CONTRIBUTING.md](./CONTRIBUTING.md) 获取指南。
---
## 星级历史
如果 ERDL 帮助了你的工作流，[在 GitHub 上给我们一个 ⭐](https://github.com/OpenOBA/erdl-mcp-server) — 它帮助其他人发现该项目。
[](https://star-history.com/#OpenOBA/erdl-mcp-server&Date)
---
## 许可证
MIT · [OpenOBA](https://openoba.com) · [@OpenOBA](https://github.com/OpenOBA)
> 确定性架构，而非提示工程。
