内容
# 理事会MCP服务器
**理事会MCP服务器** 为人工智能（如opencode）提供内存、状态和推理框架，以通过 **5个有序阶段** 解决复杂问题——所有这些都无需内部LLM调用。它使用纯确定性逻辑 + JSON文件持久性。
> 由 [**riflxz**](https://github.com/riflxz) 创建
---
## 目录
- [工作原理](#工作原理)
- [功能](#功能)
- [架构](#架构)
- [安装](#安装)
- [快速入门](#快速入门)
- [MCP工具参考](#MCP工具参考)
- [council_init](#council_init)
- [council_save](#council_save)
- [council_recall](#council_recall)
- [council_verify](#council_verify)
- [council_continue](#council_continue)
- [council_score](#council_score)
- [阶段和角色](#阶段和角色)
- [三大原则](#三大原则)
- [评分系统](#评分系统)
- [测试](#测试)
- [项目结构](#项目结构)
- [许可证](#许可证)
---
## 工作原理
```
任务输入
│
▼
┌──────────────────────────────────────────────────────────┐
│ council_init │
│ • 解析任务和评估复杂性 │
│ • 生成自适应管道深度 │
│ • 分配第一个角色 │
│ • 初始化会话状态 │
└──────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────┐
│ 角色： │ ◄── 每个阶段都有一个
│ 分析师 │ 独特的角色，定义权限
│ 建筑师 │ 边界
│ 审计员 │
│ 工程师 │
│ 质量保证 │
└────────┬────────────┘
│
┌─────────────┴─────────────┐
│ council_save │
│ • 验证权限 │
│ • 评分输出 │
│ • 检查矛盾 │
│ • 构建握手协议 │
│ • 解锁下一阶段 │
└─────────────┬─────────────┘
│
▼
┌──────────────────┐
│ 评分 ≥ 70? │
└──────┬───┬───────┘
是 │ │ 否
│ └──→ 改进并重新保存
▼
┌──────────────────────┐
│ 解锁下一阶段 │
│ 移交给下一个角色 │
└──────────────────────┘
│
┌───────────┴───────────┐
│ 循环通过5个 │
│ 阶段： │
│ 反编译 → 设计 │
│ → 审查 → 综合 │
│ → 验证 │
└───────────┬───────────┘
│
▼
┌──────────────────────┐
│ council_score │
│ 最终评估 │
└──────────────────────┘
```
---
## 功能
| 功能 | 描述 |
|---------|-------------|
| **🧠 5阶段推理管道** | 反编译 → 设计 → 审查 → 综合 → 验证 |
| **👤 基于角色的执行** | 每个阶段都有一个独特的角色（分析师、建筑师、审计员、工程师、质量保证） |
| **📊 自适应管道** | 根据任务复杂性评分自动选择轻/标准/完整管道 |
| **🔍 矛盾检测** | 跨阶段的数值和极性矛盾检测 |
| **📝 透明度日志** | 确定性级别（5个层级）、知识边界、假设标志 |
| **🔐 权限强制** | 每个角色都有严格的权限边界 — 违规行为会生成警告 |
| **🤝 握手协议** | 结构化的阶段间移交，具有上下文传递和冲突解决 |
| **💾 JSON持久性** | 零依赖的JSON文件存储 — 集合：会话、阶段、决策、声明、透明度日志、阶段移交 |
| **📈 多维评分** | 完整性、一致性、决策质量、结构、透明度、代理 — 加权聚合 |
| **🔌 MCP协议** | 6个工具通过stdio MCP传输暴露 — 与任何MCP主机兼容 |
---
## 架构
```
src/
├── index.js # 入口点 — McpServer + StdioServerTransport
├── tools.js # 所有6个MCP工具处理程序（约600行）
├── db/
│ └── json-store.js # 通用JSON文件CRUD（getAll, insert, updateWhere等）
├── memory/
│ ├── session.js # 会话CRUD和生命周期
│ ├── phase.js # 阶段状态机和转换
│ ├── decision.js # 决策跟踪存储
│ └── recall.js # 上下文编译器（完整/摘要/决策格式）
├── analysis/
│ └── parser.js # 任务结构解析器（句子分割、关键词提取）
├── prinsip/
│ ├── adaptive.js # 复杂性检测器 + 管道生成器
│ ├── transparency.js # 确定性验证、知识边界、假设标志
│ └── agentic.js # 角色定义、权限验证、握手构建器
├── verify/
│ ├── contradiction.js # 数值 + 极性矛盾检测
│ └── grounding.js # 声明源验证
└── score/
├── completeness.js # 每个阶段的字段需求检查器
├── consistency.js # 基于矛盾的一致性评分
├── transparency.js # 3维透明度评分
├── agentic.js # 权限违规 + 角色匹配评分
└── index.js # 加权聚合器 -> 最终分数 + 裁决 + 建议
```
### 数据流
```
工具调用 → tools.js处理程序 → memory/* → analysis/* → prinsip/*
↓ ↓
verify/* ←─────────────── score/*
↓
JSON响应到MCP客户端
```
### JSON存储
`./data/`中的六个集合：
| 集合 | 目的 |
|-----------|---------|
| `sessions.json` | 会话元数据、状态、复杂性评分 |
| `phases.json` | 阶段记录，包含输出、置信度、权限警告 |
| `decisions.json` | 每个阶段的决策跟踪 |
| `claims.json` | 具有置信度和来源的声明 |
| `transparency_log.json` | 透明度日志条目 |
| `phase_handoffs.json` | 阶段间握手记录 |
---
## 安装
```bash
# 全局安装
npm install -g mcp-council-server
# 或使用npx直接运行（快速 — 捆绑的单个文件，无需npm安装）
npx -y mcp-council-server
# 或克隆并在本地运行
git clone https://github.com/riflxz/mcp-council-server.git
cd mcp-council-server
npm install
npm run build
npm start
```
### 要求
- Node.js >= 18.0.0
- 无需本地编译 — 在arm64 Linux（Node.js v26+）上运行
- 无数据库 — 纯JSON文件持久性
---
## 快速入门
### 1. 与opencode集成（推荐）
在 `~/.config/opencode/opencode.json` 中添加：
```json
{
"mcp": {
"council": {
"type": "local",
"command": ["npx", "-y", "mcp-council-server"]
}
}
}
```
或使用克隆后的本地路径：
```json
{
"mcp": {
"council": {
"type": "local",
"command": ["node", "/path/to/mcp-council-server/dist/bundle.cjs"]
}
}
}
```
然后重启opencode。Council将自动被检测为MCP服务器。
### 2. 或通过CLI（MCP检查器）
```bash
git clone https://github.com/riflxz/mcp-council-server.git
cd mcp-council-server
npm install
# 使用MCP检查器启动
npm run inspect
# 或直接启动
npm start
```
### 3. 完整会话示例 — 数据库迁移
这是一个使用Council + opencode的真实会话示例。每个步骤都显示了调用的工具和AI接收的响应。
#### 步骤1：初始化 — 启动会话
AI调用 `council_init` 并带有用户任务：
```
任务： "将MySQL数据库迁移到PostgreSQL。2GB数据，
停机时间 <30分钟。处理JSON和ENUM类型。"
```
**Council响应：**
```
复杂度：中等（49/100）→ 5阶段管道
角色： 系统分析师
活动阶段： 反编译
```
AI现在知道：必须以 **系统分析师** 的身份开始 **反编译** 阶段。
#### 步骤2：反编译 — 问题分析
AI以 **系统分析师** 的身份工作，生成反编译阶段的输出，然后调用 `council_save`：
```
sessionId: "xxx"
phase: "decompile"
output: {
summary: "三个子问题：2GB数据迁移策略...",
decisions: [...],
constraints: ["downtime_30_minutes", "data_2GB", ...],
claims: [{ text: "pg_dump适合2GB", certainty: "confirmed", ... }],
knowledgeBoundary: { whatIKnow: [...], whatIAssume: [...], ... }
}
```
**Council响应：**
```
分数：93（优秀）✓
canProceed: true
nextPhase: design
handoff: 系统分析师 → 解决方案架构师
```
#### 步骤3–6：继续到下一阶段
Council锁定已完成的阶段并解锁下一阶段。AI在每个阶段都遵循新的角色：
| 阶段 | 角色 | 示例输出 |
|------|---------|--------------|
| **设计** | 解决方案架构师 | 评估2种方法、权衡、建议 |
| **审查** | 安全和质量审计员 | 漏洞、风险级别、缓解措施 |
| **综合** | 实现工程师 | 实现步骤、测试计划、警告 |
| **验证** | 质量保证 | 检查、通过/失败计数、APPROVED/REJECTED决定 |
#### 步骤7：最终评分
在所有阶段完成后，AI调用 `council_score`：
```
overall: 87（良好）
quality: 89 | adaptability: 85 | transparency: 100 | agentic: 71
```
### 4. 故障排除
| 问题 | 解决方案 |
|---------|--------|
| **服务器超时** | 如果opencode报告超时，请使用本地路径（`node /path/src/index.js`）而不是`npx`。Npx需要先下载包，这可能会很慢。 |
| **数据目录错误** | 确保工作目录可写入。服务器创建 `./data/` 目录来存储JSON会话文件。 |
| **工具未找到** | 在修改 `opencode.json` 后重启opencode。运行 `tools/list` 进行验证。 |
| **会话突然丢失** | 会话存储在 `./data/` 作为JSON文件。如果目录被删除，会话将丢失。 |
---
## MCP工具参考
### council_init
创建新的推理会话。解析任务，评估复杂性，生成自适应管道，分配第一个角色。
**参数：**
| 字段 | 类型 | 必需 | 描述 |
|-------|------|----------|-------------|
| `task` | 字符串 | ✅ | 要解决的问题或任务 |
| `title` | 字符串 | ❌ | 可选的会话标题 |
| `context` | 字符串 | ❌ | AI的附加上下文 |
**响应：**
```json
{
"type": "council_init",
"sessionId": "uuid",
"adaptation": {
"complexity": { "raw": 49, "normalized": 49, "level": "moderate", "pipelineDepth": "standard" },
"pipeline": [
{ "name": "decompile", "persona": "analyst", "depth": "standard", "order": 1 },
{ "name": "design", "persona": "architect", "depth": "standard", "order": 2 },
{ "name": "critique", "persona": "auditor", "depth": "standard", "order": 3 },
{ "name": "synthesis", "persona": "engineer", "depth": "standard", "order": 4 },
{ "name": "verify", "persona": "qa", "depth": "standard", "order": 5 }
],
"adaptiveReason": "Complexity score 49/100 (moderate). Pipeline: standard."
},
"personas": { "current": { "name": "Systems Analyst", "identity": "...", "authority": [...], "notAuthority": [...], "handoffMessage": "..." } },
"phase": "decompile",
"phasePlan": [ { "name": "decompile", "status": "active" }, { "name": "design", "status": "locked" }, ... ],
"instructions": "DECOMPOSE阶段（标准）：将任务分解为组件...",
"memorySlots": { "originalTask": "...", "decompositions": [], "decisions": [], "constraints": [], "criticalQuestions": [] },
"transparencyLog": { "entries": [], "count": 0 }
}
```
---
### council_save
保存阶段输出，评分，检测矛盾，构建下一阶段的握手协议。
**参数：**
| 字段 | 类型 | 必需 | 描述 |
|-------|------|----------|-------------|
| `sessionId` | 字符串 | ✅ | 来自 `council_init` 的会话ID |
| `phase` | 字符串 | ✅ | 阶段名称（decompile/design/critique/synthesis/verify） |
| `output` | 对象 | ✅ | 阶段特定输出字段 |
**阶段特定输出字段：
| 阶段 | 必需字段 | 可选字段 |
|-------|----------------|-----------------|
| `decompile` | summary, decisions, constraints, confidence, criticalQuestions, claims | knowledgeBoundary |
| `design` | summary, approaches, justification, tradeoffs, recommended, decisions | claims, knowledgeBoundary, confidence |
| `critique` | summary, vulnerabilities, riskLevel, mitigation, confidence | claims, knowledgeBoundary, constraints |
| `synthesis` | summary, implementation, testing, warnings | decisions, claims, knowledgeBoundary, confidence |
| `verify` | summary, checks, passedCount, failedCount, finalConfidence | decision, recommendations, claims, knowledgeBoundary |
**响应：
```json
{
"type": "council_save",
"status": "saved",
"phase": "decompile",
"scoring": {
"finalScore": 93,
"verdict": "excellent",
"dimensions": {
"completeness": { "score": 100, "passed": [...], "failed": [] },
"consistency": { "score": 100, "contradictions": [], "warnings": [] },
"transparency": { "score": 87, "details": { "certainty": 35, "knowledgeBoundary": 32, "assumptions": 20 } },
"agentic": { "score": 100, "violations": [] }
}
},
"canProceed": true,
"handoff": {
"from": "decompile",
"to": "design",
"personaTransition": { "fromPersona": "Systems Analyst", "toPersona": "Solution Architect" },
"conflicts": [],
"handshake": { "fromAuthority": [...], "toAuthority": [...], "context": [...] }
},
"nextPhase": "design",
"phasePlan": [ { "name": "decompile", "status": "locked" }, { "name": "design", "status": "active" }, ... ],
"sessionComplete": false
}
```
---
### council_recall
检索会话上下文，以便AI保持状态连续性。
**参数：**
| 字段 | 类型 | 必需 | 描述 |
|-------|------|----------|-------------|
| `sessionId` | 字符串 | ✅ | 会话ID |
| `format` | 字符串 | ❌ | `"full"`（默认）、`"summary"`或`"decisions"` |
**响应：
```json
{
"type": "council_recall",
"sessionId": "uuid",
"status": "active",
"progress": "2/5",
"currentPhase": { "name": "design", "persona": "Solution Architect", "status": "active" },
"phases": [{ "name": "decompile", "status": "done", "score": 93 }, { "name": "design", "status": "active", "score": null }],
"summary": "...",
"decisions": [...],
"warnings": [],
"transparencyLog": { "entries": [...], "count": 2 }
}
```
---
### council_verify
验证会话存储中的声明 — 检测矛盾并检查基础。
**参数：**
| 字段 | 类型 | 必需 | 描述 |
|-------|------|----------|-------------|
| `sessionId` | 字符串 | ✅ | 会话ID |
| `claims` | 数组 | ✅ | 要验证的声明数组：`[{ text, source }]` |
| `mode` | 字符串 | ❌ | `"contradiction"`、`"grounding"`或`"all"`（默认） |
**响应：
```json
{
"type": "council_verify",
"mode": "all",
"results": {
"contradictions": [...],
"grounding": { "verified": 1, "unverified": 1, "verifiedPct": 50 }
},
"summary": { "total": 2, "passed": 1, "failed": 1 }
}
```
---
### council_continue
在会话暂停的地方继续 — 恢复完整上下文。
**参数：**
| 字段 | 类型 | 必需 | 描述 |
|-------|------|----------|-------------|
| `sessionId` | 字符串 | ✅ | 会话ID |
**响应：
```json
{
"type": "council_continue",
"sessionId": "uuid",
"status": "active",
"currentPhase": { "name": "critique", "persona": "Security & Quality Auditor", "status": "active" },
"personas": { "current": { ... } },
"phasePlan": [...],
"instructions": "...",
"memorySlots": { ... },
"transparencyLog": { ... }
}
```
---
### council_score
为已完成的会话生成最终的多维质量评估。
**参数：**
| 字段 | 类型 | 必需 | 描述 |
|-------|------|----------|-------------|
| `sessionId` | 字符串 | ✅ | 会话ID |
**响应：
```json
{
"type": "council_score",
"sessionId": "uuid",
"overall": {
"finalScore": 87,
"verdict": "good",
"qualityScore": 89,
"adaptabilityScore": 85,
"transparencyScore": 100,
"agenticScore": 71
},
"phaseScores": {
"decompile": { "score": 93, "verdict": "excellent" },
"design": { "score": 93, "verdict": "excellent" },
"critique": { "score": 82, "verdict": "good" },
"synthesis": { "score": 91, "verdict": "excellent" },
"verify": { "score": 82, "verdict": "good" }
}
}
```
---
## 阶段和角色
| 阶段 | 角色 | 权限 | 无权限 |
|-------|---------|-----------|---------------|
| **反编译** | 系统分析师 | 分解任务，识别约束和隐藏需求，提出澄清问题 | ❌ 无解决方案 ❌ 无技术评估 ❌ 无设计决策 |
| **设计** | 解决方案架构师 | 定义方法，评估权衡，推荐解决方案 | ❌ 无实施 ❌ 无代码 ❌ 无详细测试 |
| **审查** | 安全和质量审计员 | 识别风险，验证约束，检查安全 | ❌ 无解决方案 ❌ 无设计 ❌ 无实施 |
| **综合** | 实现工程师 | 编写实现步骤，创建测试计划 | ❌ 无架构更改 ❌ 无需求更改 |
| **验证** | 质量保证 | 运行检查，验证完整性，批准/拒绝 | ❌ 无重新设计 ❌ 无重新实施 |
### 握手协议
每个阶段转换都包含正式的握手：
1. **来自当前角色** 的上下文 + 未解决项
2. **移交给新角色** 确认上下文
3. **文档化阶段间冲突**
4. **评分 ≥ 70** 需要继续下一阶段
---
## 三大原则
* **确定性**：所有推理和决策过程都是确定性的，以确保可重复性和可靠性。
* **透明度**：所有阶段和决策都是透明的，具有清晰的责任和可追溯性。
* **适应性**：管道根据任务的复杂性和具体需求进行调整。
## 测试
* **单元测试**：确保每个组件和功能都能正确运行。
* **集成测试**：验证整个管道的端到端功能。
## 项目结构
* **模块化设计**：确保易于维护、升级和扩展。
## 许可证
* **开源许可证**：促进协作、透明度和社区参与。
## 评分系统
* **多维评分**：评估任务完成的质量、适应性和透明度。
## 工具
* **MCP 工具**：提供一套全面的工具，用于支持整个推理和决策过程。
### 🔄 自适应 — 自适应流程深度
服务器评估任务复杂性并调整流程深度：
| 复杂度评分 | 级别 | 流程深度 | 描述 |
|------------|-------|-----------|-------------|
| 0–20 | 简单 | 轻量 | 反编译 → 综合 → 验证 |
| 21–60 | 中等 | 标准 | 反编译 → 设计 → 评估 → 综合 → 验证 |
| 61–100 | 复杂 | 完整 | 反编译 → 设计 → 评估 → 综合 → 验证（深度）+ 循环 |
**复杂度因素：**
- 基线：10
- 关键词命中次数：+8（迁移、安全、Kubernetes、性能等）
- 领域提升：+10（迁移/安全/Kubernetes/性能）
- 检测到的数字：+5
### 👁️ 透明度 — 确定性和知识边界
**5个确定性级别：**
| 级别 | 标签 | 描述 |
|-------|-------|-------------|
| 1 | 已确认 | 来自可靠来源的验证 |
| 2 | 可能 | 高置信度，尚未验证 |
| 3 | 不确定 | 需要进一步调查 |
| 4 | 未知 | 无可用信息 |
| 5 | 假设 | 作为工作假设使用 |
**知识边界跟踪：**
- `whatIKnow` — 自信已知
- `whatIAssume` — 工作假设
- `whatIDontKnow` — 已知未知
- `whatNeedsVerification` — 需要外部验证
### 🤖 代理 — 角色权限
每个角色都有定义：
- **身份** — 他们是谁
- **权限** — 他们可以做什么
- **非权限** — 他们不能做什么
- **交接消息** — 他们传递给下一个角色
权限违规（例如，反编译建议解决方案）会被标记为警告和惩罚评分。
---
## 评分系统
### 每个阶段的评分
| 维度 | 权重 | 描述 |
|-----------|--------|-------------|
| 完整性 | 25% | 必要字段存在，正确类型，最小长度 |
| 一致性 | 25% | 与前面的阶段没有矛盾（数值、极性、约束遵守） |
| 决策质量 | 15% | 阶段中做出的决策质量 |
| 结构 | 10% | 输出的结构组织 |
| 透明度 | 15% | 确定性级别、知识边界、假设标志 |
| 代理 | 10% | 无权限违规、角色身份关键词存在 |
### 评分阈值
| 评分范围 | 裁决 | 操作 |
|-------------|---------|--------|
| ≥ 90 | 优秀 | 自动进入下一阶段 |
| 70–89 | 良好 | 进入下一阶段 |
| 50–69 | 需要改进 | 仍可进入下一阶段，但需要审查建议 |
| < 50 | 不足 | 必须改进后才能进入下一阶段 |
### 最终会话评分
所有阶段评分的加权聚合加上跨阶段评估：
- **质量评分** — 平均阶段质量
- **适应性评分** — 流程深度与任务的匹配程度
- **透明度评分** — 跨阶段透明度的一致性
- **代理评分** — 跨阶段权限合规性
---
## 测试
```bash
# 运行完整集成测试（5个阶段 + 最终评分）
node test_full.mjs
```
测试脚本：
1. 创建一个迁移任务的会话
2. 运行所有5个阶段（反编译 → 设计 → 评估 → 综合 → 验证）
3. 验证阶段门控（不能跳过阶段）
4. 测试召回和继续工具
5. 生成最终的council_score
6. 报告每个步骤的通过/失败
示例输出：
```
1. 初始化 → 中等（49）5阶段角色：系统分析师
2. 反编译 → 93（优秀）继续：true → 设计
3. 设计 → 93（优秀）继续：true → 评估
4. 评估 → 82（良好）继续：true → 综合
5. 综合 → 91（优秀）继续：true → 验证
6. 验证 → 82（良好）继续：true 完成：true
7. 评分 → 87（良好）q：89 a：85 t：100 ag：71
✅ 7/7 通过
```
---
## 项目结构
```
mcp-council-server/
├── package.json
├── README.md
├── .env.example
├── .gitignore
├── src/
│ ├── index.js # 入口点
│ ├── tools.js # MCP 工具处理程序
│ ├── db/
│ │ └── json-store.js # JSON 文件持久性
│ ├── memory/
│ │ ├── session.js # 会话生命周期
│ │ ├── phase.js # 阶段状态机
│ │ ├── decision.js # 决策跟踪
│ │ └── recall.js # 上下文编译器
│ ├── analysis/
│ │ └── parser.js # 任务解析器
│ ├── prinsip/
│ │ ├── adaptive.js # 复杂度检测
│ │ ├── transparency.js # 确定性和知识边界
│ │ └── agentic.js # 角色和权限
│ ├── verify/
│ │ ├── contradiction.js # 矛盾检测
│ │ └── grounding.js # 声明验证
│ └── score/
│ ├── completeness.js # 完整性检查器
│ ├── consistency.js # 一致性评分
│ ├── transparency.js # 透明度评分
│ ├── agentic.js # 代理评分
│ └── index.js # 聚合器
├── test_flow.mjs # 测试脚本
├── test_debug.mjs # 调试工具
└── test_full.mjs # 完整集成测试
```
---
## 为什么不使用内部LLM？
委员会 不会内部调用任何LLM。相反：
1. **AI（opencode/Claude等）** 是推理者 — 它读取工具响应，生成阶段输出，并做出决策
2. **委员会** 提供脚手架 — 内存、状态、结构、评分和防护措施
3. **纯确定性逻辑** — 无API成本，无延迟，无黑盒行为
4. **完全透明** — 每个评分、矛盾和权限警告都是可解释的
这种责任分离意味着：
- AI专注于推理
- 委员会专注于结构和质量
- 无供应商锁定 — 与任何MCP兼容的AI一起工作
---
## 许可证
MIT © [riflxz](https://github.com/riflxz)
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器