使用说明

统一MCP服务器

将记忆增强推理与人工智能助手的工作流自动化相结合的协议强制学习系统

概述

统一MCP服务器是一个模型上下文协议服务器，它强制执行基于研究的工作流程，以提高人工智能助手的可靠性。基于最近的代理故障研究（AgentErrorTaxonomy，ChatDev研究），它确保AI助手在更改代码之前从经验中学习。

主要特点：

🧠 记忆增强推理：从过去的经验中寻找和学习
🔒 协议执行：钩子可以防止文件操作而不进行学习
📚 知识库：按项目/领域组织经验
🔄 体验迁移：从旧数据库格式导入
✅ 全面的测试覆盖率：所有测试必须通过，无故障

快速开始

系统要求

运行时间：

Node.js：>=18.0.0（请与 node --version)
- 推荐：18.x、20.x或22.x
npm：8.x或更高
磁盘空间：约50 MB用于安装
记忆：最小100 MB

操作系统：

✅ macOS（英特尔和苹果硅）
✅ Linux（x64，arm64）
✅ Windows 10/11（x64）

不需要本机构建工具（自v1.8.5以来使用WASM SQLite）。

安装

# Via NPX (recommended)
npx mpalpha/unified-mcp-server --init

# Or clone and install
git clone https://github.com/mpalpha/unified-mcp-server.git
cd unified-mcp-server
npm install
node index.js --init

备注：如果遇到本机模块错误，请使用 --build-from-source 旗或看故障排除在......下面

安装向导

这 --init 向导将指导您完成以下操作：

数据库初始化
吊钩安装（可选）
预设选择（严格/平衡/建议）

npx unified-mcp-server --init

配置

v1.5.2+：自动配置！ MCP服务器自动配置 ~/.claude/settings.json 每次跑步。无需手动设置。

如果需要手动配置（例如自定义参数），请添加到MCP设置中：

{
  "mcpServers": {
    "unified-mcp": {
      "command": "npx",
      "args": ["unified-mcp-server"]
    }
  }
}

手动更改后，重新启动Claude Code以使设置生效。

v1.9.0中的变化：确定性存储系统

v1.9.0用确定性、治理强制的内存系统取代了REASON阶段。

生命周期变更

Before: TEACH → LEARN → REASON → ACT
After:  TEACH → LEARN → GUARDED_REASON → ACT

新工具（6）

工具	目的
`compliance_snapshot`	进行合规性快照（快照阶段）
`compliance_router`	路线合规性检查（ROUTER阶段）
`context_pack`	字节预算上下文打包
`guarded_cycle`	执行保护推理阶段
`finalize_response`	信任感知响应最终确定
`run_consolidation`	确定性整合引擎

废弃工具（4）

旧工具	更换
`analyze_problem`	`compliance_snapshot` + `compliance_router`
`gather_context`	`context_pack`
`reason_through`	`guarded_cycle`
`finalize_decision`	`finalize_response`

传统工具仍然有效，但会返回 deprecated: true 在更换指导下。

建筑

13个模块 src/memory/
通过以下方式新增9个数据库表 migrations/002_memory_system.sql
总共34个MCP工具（28个）
HMAC-SHA256签名收据和令牌
确定性显著性评分和哈希链调用分类账

看建筑.md 和工具参考.md 了解详情。

v1.4.0：项目范围经验

破坏性变更：v1.4.0将所有数据存储从全局移动 ~/.unified-mcp/ 在当地进行项目 .claude/ 目录。

关键变化

所有经验现在都存储在 {project}/.claude/experiences.db
没有全局存储-每个项目都有自己的独立数据库
使用 export_experiences 和 import_experiences 用于跨项目共享
老的 ~/.unified-mcp/ 目录不再使用（请参阅下面的迁移）

好处

可移植性: .claude/ 文件夹随项目一起移动
隔离：零跨项目污染
清晰度：一个需要了解和管理的地点

从v1.3.x迁移

v1.4.0是一个全新的版本。要保存旧体验：

# 1. Export from old global database (while running v1.3.x)
# Use export_experiences tool to create a JSON file

# 2. Upgrade to v1.4.0
npm install unified-mcp-server@latest

# 3. Initialize in your project
npx unified-mcp-server --init

# 4. Import old experiences
# Use import_experiences({ filename: "exported-experiences.json" })

这 --init 向导将检测旧 ~/.unified-mcp/ 数据并建议删除。

工具

研究工作流程（6个工具）

主要工作流程 -在更改代码之前使用：

informed_reasoning -基于上下文的多阶段推理
search_experiences -查找相关的过去经历
record_experience -保存新知识
export_experiences -导出体验库
import_experiences -从另一个项目导入经验（v1.4.0）
check_protocol_compliance -验证工作流完成情况

协议执行（2个工具）

钩子使用这些来验证工作流：

verify_protocol_compliance -检查已完成的强制步骤
authorize_file_operation -发行操作令牌

内存管理（5个工具）

按项目/背景组织知识：

create_memory_library -创建命名库
list_memory_libraries -列出所有库
switch_memory_library -更改上下文
get_current_library_info -当前库状态
query_reasoning_memory -搜索内存图

高级推理（1个工具）

advanced_reasoning -通过元认知和假设检验增强推理

系统配置（8个工具）

存储结构化数据并配置协议：

create_system_json, get_system_json, search_system_json, list_system_json
initialize_protocol_config, get_protocol_config, get_compliance_status

项目背景（2个工具）

使用项目特定上下文自定义工作流提醒：

update_project_context -将项目上下文存储为JSON数据（摘要、突出显示、提醒）
get_project_context -检索当前项目上下文配置

总计：34个工具 （参见工具参考.md 完整列表）

钩子

可用挂钩

该系统提供3个集成点：

user_prompt_submit -当用户提交提示时运行
- 强制执行文件操作的研究工作流程
- 引用代理失效模式的研究
pre_tool_use -在每次工具调用之前运行
- 验证协议合规性令牌
- 阻止未经授权的写入/编辑
stop -会话结束时运行
- 清理和状态管理

挂钩预设

在安装过程中选择执行级别：

严格 -无需研究即可阻止所有文件操作
平衡的 -阻止写入/编辑，警告他人
咨询 -仅警告，无阻塞

安装

# Via --init wizard (recommended)
npx unified-mcp-server --init

# Manual installation
node index.js --install-hooks

# Uninstall
node index.js --uninstall-hooks

看 docs/ARCHITECTURE.md 用于挂钩文件组织。

研究基金会

基于2024-2025年代理故障研究：

代理错误分类 （arXiv:2509.25370）-5个故障类别
ChatDev分析 （arXiv:2503.13657）-25%正确性基线
多智能体脆弱性 （Cognition.ai）-分解失败
ALFWorld/WebShop/GAIA -现实世界基准测试失败

我们的执法方法涉及：

操作失败（未经研究而阻止写入/编辑）
内存故障（累积知识库）
推理失败（知情推理工作流）
工具幻觉（经过验证的工具描述）

测试

运行所有测试

npm test
# Expected: all tests passing with 0 failures

测试套件

npm run test:version-sync    # Version sync
npm run test:tools           # Tool tests
npm run test:workflows       # Workflow tests
npm run test:compliance      # Compliance tests
npm run test:config          # Config tests
npm run test:integration     # Integration tests
npm run test:enforcement     # Enforcement tests
npm run test:agent-workflows # Agent workflow tests
npm run test:hook-execution  # Hook execution tests
npm run test:tool-guidance   # Tool guidance tests
npm run test:project-context # Project context tests
npm run test:npx             # NPX compatibility test
npm run test:cli             # CLI tests
npm run test:database        # Database tests
npm run test:memory          # Memory system tests

附加测试

# Research-based compliance scenarios
node test/test-agent-compliance.js

# Experience usage scenarios
node test/test-experience-usage.js

# Edge scenarios
node test/test-edge-scenarios.js

# Migration tests
node test/test-migration.js

跑 npm test 验证所有测试均通过，无故障。

CLI命令

# Show help
npx unified-mcp-server --help

# Show version
npx unified-mcp-server --version

# Non-interactive setup (works in CI, Claude Code, piped input)
npx unified-mcp-server --install
npx unified-mcp-server --install --preset strict

# Interactive setup wizard (requires TTY)
npx unified-mcp-server --init

# Apply preset (non-interactive)
npx unified-mcp-server --preset three-gate
npx unified-mcp-server --preset minimal
npx unified-mcp-server --preset strict
npx unified-mcp-server --preset custom

# Health check
npx unified-mcp-server --health

# Validate hooks configuration
npx unified-mcp-server --validate

# Hook management
npx unified-mcp-server hooks install    # Install hooks globally
npx unified-mcp-server hooks uninstall  # Remove hooks
npx unified-mcp-server hooks list       # Show installed hooks
npx unified-mcp-server hooks status     # Health check for hooks

# Advanced install options
npx unified-mcp-server --install --dry-run   # Preview changes
npx unified-mcp-server --install --repair    # Fix corrupted installation

预置模式

三扇门 （推荐）：标准教学→ 学习→ REASON工作流程
最小：重量轻，带可选门
严格：严格执行所有验证
定制：自定义工作流模板

文档

MIGRATION_GUIDE.md -迁移旧数据库
实施_计划.md -发展路线图
建筑.md -系统设计和挂钩文件
工具参考.md -工具文档
更改日志.md -发布历史

建筑

unified-mcp-server/
├── index.js                 # Main MCP server (~880 lines, dispatches to src/)
├── bootstrap.js             # NPX entry point
├── src/                     # Modular source (v1.7.0+)
│   ├── validation.js        # Validators, dice coefficient
│   ├── database.js          # Database init, schema, helpers
│   ├── database-wasm.js     # WASM SQLite wrapper
│   ├── errors.js            # Structured error classes
│   ├── cli.js               # CLI commands and post-install prompt
│   ├── tools/               # 34 MCP tools across 6 modules
│   └── memory/              # 13 memory system modules
├── migrations/              # Flyway-style numbered SQL
├── scripts/                 # Utilities
├── test/                    # 17 test suites
└── docs/                    # Architecture, tools, workflows, contributing

配置

数据库位置（v1.4.0+）

项目本地: {project}/.claude/experiences.db

每个项目的所有数据都存储在 .claude/ 目录：

your-project/
├── .claude/
│   ├── experiences.db       # Project experiences
│   ├── config.json          # Preset configuration
│   ├── project-context.json # Custom context
│   └── tokens/              # Session tokens

钩子文件

挂钩在全球范围内安装 ~/.claude/hooks/ （v1.5.0+）：

user-prompt-submit.cjs -工作流程指导+通用搜索提示
pre-tool-use.cjs -令牌验证（仅适用于已初始化的项目）
post-tool-use.cjs -通用记录提示
stop.cjs -会话清理+记录提醒
session-start.cjs -CHORES显示

注：钩子是不可变的基础设施。通过以下方式定制行为 update_project_context().

Claude代码设置

挂钩会自动更新： ~/.claude/settings.json

发展

需求

Node.js>=18.0.0
npm
node-splite3-wasm（wasm，不需要本地构建工具）

构建与测试

# Install dependencies
npm install

# Run all tests
npm test

# Run specific test suite
npm run test:tools

# Test migration
node test/test-migration.js

# Lint/format (if configured)
npm run lint

贡献

分叉存储库
创建要素分支
为新功能编写测试
确保所有测试通过(npm test)
更新文档
提交拉取请求

故障排除

数据库/SQLite问题

v1.8.5+：仅WASM SQLite

从v1.8.5开始，服务器使用基于WebAssembly的SQLite(node-sqlite3-wasm)独家。这提供了：

✅ 跨Node.js 18、20、22的通用兼容性+
✅ 无需构建工具
✅ 切换节点版本时没有本机模块ABI问题
✅ 适用于所有平台（macOS、Linux、Windows）

备注：早期版本（v1.7.2-v1.8.4）使用了一种混合方法，在节点版本之间切换时可能会导致问题。升级到v1.8.5+以解决这些问题。

所需节点版本：18.x或更高

检查您的节点版本:

node --version

移民问题

看 docs/MIGRATION_GUIDE.md

吊钩安装问题

# Check hook status
npx unified-mcp-server --validate

# Reinstall hooks
npx unified-mcp-server --init
# Select "Install hooks"

# Manual uninstall + reinstall
node index.js --uninstall-hooks
node index.js --install-hooks

数据库问题

# v1.4.0+: Database is in project's .claude/ directory
# Check database exists
ls -lh .claude/experiences.db

# Verify schema
sqlite3 .claude/experiences.db ".schema experiences"

# Check experience count
sqlite3 .claude/experiences.db "SELECT COUNT(*) FROM experiences"

测试失败

# Clean test databases
rm -f test/fixtures/*.db

# Regenerate test data
node test/fixtures/create-test-migration-db.js

# Run tests again
npm test

许可证

支持

问题：https://github.com/mpalpha/unified-mcp-server/issues
文档： docs/
迁移指南： docs/MIGRATION_GUIDE.md

致谢

基于以下研究：

AgentError分类法 (档案:2509.25370)
聊天发展分析（arXiv:2503.13657）
多智能体系统研究（Cognition.ai）
ALFWorld、WebShop、GAIA基准测试

准备好实施基于研究的工作流程了吗？

npx mpalpha/unified-mcp-server --init