Unified MCP Server

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

Node License

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:

Database initialization
Hook installation (optional)
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:

informed_reasoning - Multi-phase reasoning with context
search_experiences - Find related past experiences
record_experience - Save new learnings
export_experiences - Export experience library
import_experiences - Import experiences from another project (v1.4.0)
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:

user_prompt_submit - Runs when user submits a prompt
- Enforces research workflow for file operations
- Cites research on agent failure modes
pre_tool_use - Runs before each tool call
- Validates protocol compliance tokens
- Blocks Write/Edit without authorization
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

Fork the repository
Create a feature branch
Write tests for new features
Ensure all tests pass (npm test)
Update documentation
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

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