Unified MCP Server

Protocol-enforced learning system combining memory-augmented reasoning with workflow automation for AI assistants

Overview

Unified MCP Server is a Model Context Protocol server that enforces research-based workflows to improve AI assistant reliability. Based on recent agent failure research (AgentErrorTaxonomy, ChatDev studies), it ensures AI assistants learn from experience before making changes to code.

Key Features:

• 🧠 Memory-augmented reasoning: Search and learn from past experiences
• 🔒 Protocol enforcement: Hooks prevent file operations without learning
• 📚 Knowledge libraries: Organize experiences by project/domain
• 🔄 Experience migration: Import from old database formats
• ✅ Comprehensive test coverage: All tests must pass with 0 failures

Quick Start

System Requirements

Runtime:

• Node.js: >=18.0.0 (check with node --version)
  • Recommended: 18.x, 20.x, or 22.x
• npm: 8.x or higher
• Disk Space: ~50 MB for installation
• Memory: 100 MB minimum

Operating Systems:

• ✅ macOS (Intel & Apple Silicon)
• ✅ Linux (x64, arm64)
• ✅ Windows 10/11 (x64)

No native build tools required (uses WASM SQLite since v1.8.5).

Installation

# 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

Note: If you encounter native module errors, use --build-from-source flag or see Troubleshooting below.

Setup Wizard

The --init wizard guides you through:

1. Database initialization
2. Hook installation (optional)
3. Preset selection (strict/balanced/advisory)

npx unified-mcp-server --init

Configuration

v1.5.2+: Auto-configured! The MCP server automatically configures ~/.claude/settings.json on every run. No manual setup needed.

If you need to manually configure (e.g., custom args), add to your MCP settings:

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

After any manual changes, restart Claude Code for settings to take effect.

What Changed in v1.9.0: Deterministic Memory System

v1.9.0 replaces the REASON phase with a deterministic, governance-enforced memory system.

Lifecycle Change

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

New Tools (6)

Tool	Purpose
compliance_snapshot	Take compliance snapshot (SNAPSHOT phase)
compliance_router	Route compliance check (ROUTER phase)
context_pack	Byte-budgeted context packing
guarded_cycle	Execute guarded reasoning phase
finalize_response	Trust-aware response finalization
run_consolidation	Deterministic consolidation engine

Deprecated Tools (4)

Old Tool	Replacement
analyze_problem	compliance_snapshot + compliance_router
gather_context	context_pack
reason_through	guarded_cycle
finalize_decision	finalize_response

Legacy tools still work but return deprecated: true with replacement guidance.

Architecture

• 13 modules in src/memory/
• 9 new database tables via migrations/002_memory_system.sql
• 34 total MCP tools (was 28)
• HMAC-SHA256 signed receipts and tokens
• Deterministic salience scoring and hash-chained invocation ledger

See ARCHITECTURE.md and TOOL_REFERENCE.md for details.

v1.4.0: Project-Scoped Experiences

Breaking Change: v1.4.0 moves all data storage from global ~/.unified-mcp/ to project-local .claude/ directories.

Key Changes

• All experiences are now stored in {project}/.claude/experiences.db
• No global storage - each project has its own isolated database
• Use export_experiences and import_experiences for cross-project sharing
• Old ~/.unified-mcp/ directory is no longer used (see migration below)

Benefits

• Portability: .claude/ folder travels with your project
• Isolation: Zero cross-project pollution
• Clarity: One location to understand and manage

Migration from v1.3.x

v1.4.0 is a clean slate. To preserve old experiences:

# 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" })

The --init wizard will detect old ~/.unified-mcp/ data and suggest removal.

Tools

Research Workflow (6 tools)

Primary workflow - Use before making code changes:

1. informed_reasoning - Multi-phase reasoning with context
2. search_experiences - Find related past experiences
3. record_experience - Save new learnings
4. export_experiences - Export experience library
5. import_experiences - Import experiences from another project (v1.4.0)
6. check_protocol_compliance - Verify workflow completion

Protocol Enforcement (2 tools)

Hooks use these to validate workflows:

• verify_protocol_compliance - Check mandatory steps completed
• authorize_file_operation - Issue operation tokens

Memory Management (5 tools)

Organize knowledge by project/context:

• create_memory_library - Create named libraries
• list_memory_libraries - List all libraries
• switch_memory_library - Change context
• get_current_library_info - Current library status
• query_reasoning_memory - Search memory graph

Advanced Reasoning (1 tool)

• advanced_reasoning - Enhanced reasoning with meta-cognition and hypothesis testing

System Configuration (8 tools)

Store structured data and configure protocols:

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

Project Context (2 tools)

Customize workflow reminders with project-specific context:

• update_project_context - Store project context as JSON data (summary, highlights, reminders)
• get_project_context - Retrieve current project context configuration

Total: 34 tools (see TOOL_REFERENCE.md for full list)

Hooks

Available Hooks

The system provides 3 integration points:

1. user_prompt_submit - Runs when user submits a prompt

   • Enforces research workflow for file operations
   • Cites research on agent failure modes

2. pre_tool_use - Runs before each tool call

   • Validates protocol compliance tokens
   • Blocks Write/Edit without authorization

3. stop - Runs when session ends

   • Cleanup and state management

Hook Presets

Choose enforcement level during setup:

• Strict - Blocks all file operations without research
• Balanced - Blocks Write/Edit, warns on others
• Advisory - Warnings only, no blocking

Installation

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

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

# Uninstall
node index.js --uninstall-hooks

See docs/ARCHITECTURE.md for hook file organization.

Research Foundation

Based on 2024-2025 agent failure research:

• AgentErrorTaxonomy (arXiv:2509.25370) - 5 failure categories
• ChatDev Analysis (arXiv:2503.13657) - 25% correctness baseline
• Multi-Agent Fragility (Cognition.ai) - Decomposition failures
• ALFWorld/WebShop/GAIA - Real-world benchmark failures

Our enforcement approach addresses:

• Action failures (blocked Write/Edit without research)
• Memory failures (accumulated knowledge base)
• Reasoning failures (informed_reasoning workflow)
• Tool hallucination (validated tool descriptions)

Testing

Run All Tests

npm test
# Expected: all tests passing with 0 failures

Test Suites

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

Additional 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

Run npm test to verify all tests pass with 0 failures.

CLI Commands

# 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

Available Presets

• three-gate (Recommended): Standard TEACH → LEARN → REASON workflow
• minimal: Lightweight with optional gates
• strict: Strict enforcement with all validations
• custom: Template for custom workflows

Documentation

• MIGRATION_GUIDE.md - Migrate old databases
• IMPLEMENTATION_PLAN.md - Development roadmap
• ARCHITECTURE.md - System design and hook files
• TOOL_REFERENCE.md - Tool documentation
• CHANGELOG.md - Release history

Architecture

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

Configuration

Database Location (v1.4.0+)

Project-local: {project}/.claude/experiences.db

All data is stored per-project in the .claude/ directory:

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

Hook Files

Hooks are installed globally to ~/.claude/hooks/ (v1.5.0+):

• user-prompt-submit.cjs - Workflow guidance + universal search prompt
• pre-tool-use.cjs - Token validation (only for initialized projects)
• post-tool-use.cjs - Universal record prompt
• stop.cjs - Session cleanup + record reminder
• session-start.cjs - CHORES display

Note: Hooks are immutable infrastructure. Customize behavior via update_project_context().

Claude Code Settings

Hooks automatically update: ~/.claude/settings.json

Development

Requirements

• Node.js >= 18.0.0
• npm
• node-sqlite3-wasm (WASM, no native build tools needed)

Build & Test

# 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

Contributing

1. Fork the repository
2. Create a feature branch
3. Write tests for new features
4. Ensure all tests pass (npm test)
5. Update documentation
6. Submit a pull request

Troubleshooting

Database / SQLite Issues

v1.8.5+: WASM-Only SQLite

Starting with v1.8.5, the server uses WebAssembly-based SQLite (node-sqlite3-wasm) exclusively. This provides:

• ✅ Universal compatibility across Node.js 18, 20, 22+
• ✅ No build tools required
• ✅ No native module ABI issues when switching Node versions
• ✅ Works identically on all platforms (macOS, Linux, Windows)

Note: Earlier versions (v1.7.2-v1.8.4) used a hybrid approach that could cause issues when switching between Node versions. Upgrade to v1.8.5+ to resolve these issues.

Required Node Versions: 18.x or higher

Check Your Node Version:

node --version

Migration Issues

See docs/MIGRATION_GUIDE.md

Hook Installation Issues

# 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

Database Issues

# 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"

Test Failures

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

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

# Run tests again
npm test

License

MIT © Jason Lusk

Support

• Issues: https://github.com/mpalpha/unified-mcp-server/issues
• Documentation: docs/
• Migration Guide: docs/MIGRATION_GUIDE.md

Acknowledgments

Built on research from:

• AgentErrorTaxonomy (arXiv:2509.25370)
• ChatDev Analysis (arXiv:2503.13657)
• Multi-Agent Systems Research (Cognition.ai)
• ALFWorld, WebShop, GAIA benchmarks

---

Ready to enforce research-based workflows?

npx mpalpha/unified-mcp-server --init