Elite Reasoning MCP

Model Context Protocol workflow memory, evaluation, and reasoning-safety layer for AI coding agents.

Why Elite Reasoning?

Every AI coding assistant makes the same mistakes twice. Elite Reasoning fixes that.

It's a Model Context Protocol server for AI IDEs and coding agents. It adds a persistent workflow layer with evidence-gated execution, quality-gated memory, release verification, local monitoring, and prevention guidance.

Elite Reasoning does not claim to make a smaller model frontier-capable. It makes bounded coding workflows more reliable by reducing tool-selection noise, preserving trusted context, requiring evidence before completion, and returning typed MCP contracts.

One install. Zero config. Works with Cursor, Antigravity, VS Code + Continue, Windsurf, and any MCP-compatible IDE.

Who This Is For

• Developers who use Cursor, Claude Desktop, Gemini CLI, VS Code + Continue, Windsurf, or another MCP-compatible AI IDE.

• AI coding-agent users who want persistent memory without blindly injecting stale, low-trust, or sensitive context.

• Maintainers who need auditable multi-step execution, release gates, risk checks, and repeatable eval scaffolds.

• Teams building agentic development workflows that need reasoning safety, confidence calibration, and workflow evidence.

The Problem

Related MCP server: Clear Thought 1.5

⚡ Quick Start

One-Line Install

pip install elite-reasoning-mcp

For an isolated CLI installation:

uv tool install elite-reasoning-mcp

# Verify the actual binary your IDE will run
elite-reasoning-mcp --version
elite-reasoning-mcp doctor --json

# Preview a safe standalone upgrade command
elite-reasoning-mcp upgrade --dry-run

Add to your IDE

Antigravity / Gemini CLI (~/.gemini/config/mcp_config.json):

{
  "mcpServers": {
    "elite-reasoning": {
      "command": "elite-reasoning-mcp",
      "args": [],
      "env": {
        "ELITE_BRAIN_DIR": "~/.elite-reasoning/brain",
        "ELITE_TOOL_PROFILE": "core"
      }
    }
  }
}

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "elite-reasoning": {
      "command": "elite-reasoning-mcp",
      "env": {
        "ELITE_BRAIN_DIR": "~/.elite-reasoning/brain",
        "ELITE_TOOL_PROFILE": "core"
      }
    }
  }
}

VS Code + Continue (~/.continue/config.yaml):

mcpServers:
  - name: elite-reasoning
    command: elite-reasoning-mcp
    env:
      ELITE_BRAIN_DIR: ~/.elite-reasoning/brain
      ELITE_TOOL_PROFILE: core

Activate the Pipeline

Add this to your IDE's system prompt (e.g., ~/.gemini/GEMINI.md or Cursor Rules):

## ⚡ RULE #0 — ELITE MCP PIPELINE

For non-trivial build, debug, research, audit, or release tasks, start with:

elite_prepare(user_prompt="<the user's exact message>")

Update each step with evidence before claiming completion:

elite_progress(run_id="<run id>", action="update", step_index=1, step_status="passed", evidence="<proof>")

Before shipping, call:

elite_verify(check="doctor")

Skip tool calls for trivial acknowledgements like "ok", "thanks", "yes", "no".

That's it. Restart your IDE and every conversation automatically benefits from the reasoning pipeline.

🚀 Features

🧠 Evidence-Gated Workflow

When the IDE calls elite_prepare, the server creates a durable plan with risk-aware validation gates, trusted memory context, and a compact typed response. elite_progress rejects out-of-order completion and terminal claims without evidence.

🛡️ Anti-Pattern Memory

Past mistakes are recorded with root-cause analysis and automatically surfaced when similar patterns appear. Your AI literally learns from its errors.

📊 Confidence Calibration

Track prediction accuracy with proper Brier scores. Know when your AI is overconfident vs. well-calibrated. Every prediction gets a confidence score and outcome tracking.

⚖️ Decision Council

Critical decisions get a 5-perspective adversarial review — optimist, pessimist, pragmatist, innovator, and devil's advocate — before committing.

🔒 Prevention Rules

Custom auto-triggered rules for your workflow. Define patterns that should trigger warnings, blocks, or automatic corrections. Rules self-improve through a learning pipeline.

📈 8-Layer Middleware Chain

Every tool call passes through usage logging, latency measurement, prevention rules, anti-pattern injection, periodic scanning, cost tracking, fallback guidance, and real transient retries. Structured gateway responses retain a stable warnings field rather than receiving ad-hoc text wrappers.

🧪 Risk Analysis

FMEA (Failure Mode & Effects Analysis), Swiss Cheese audits, smoke test gates, and pre-mortem simulations — all built-in, all callable as MCP tools.

💾 Persistent Memory

Cross-session knowledge stays scoped, trust-weighted, and privacy-gated. Secret-like content is redacted before storage; low-trust, sensitive, expired, and remotely imported items remain quarantined until an explicit approval action promotes them. Sensitive records cannot be promoted, and elite_memory(action="forget") permanently removes a selected local item.

🧭 Workflow Flight Recorder

elite_prepare records a durable execution contract, while elite_progress requires ordered evidence before completion. This gives agent work a recoverable audit trail without pretending the server executed the task itself.

🏥 Release Doctor And Local Monitoring

elite_verify(check="doctor") checks runtime identity, protocol version, dependencies, DB schema, capability routing, exposed tool count, active IDE mismatch, and release blockers before shipping. elite_admin(action="monitoring") returns local aggregate latency, workflow, and memory health without exporting prompt content.

🧪 Eval Harness Exports

The explicit legacy profile retains export_eval_harness for optional Promptfoo, DeepEval, and Inspect AI scaffolds. The default profile stays compact so agents can select the correct workflow actions reliably.

🏗️ Architecture

Your Task
    ↓
elite_prepare (typed workflow contract)
    ↓
┌──────────────────────────────────────────────┐
│  Intent and risk      → bounded workflow     │
│  Trusted memory       → scoped context       │
│  Prevention engine    → phase guidance       │
│  Validation gates     → evidence requirements │
│  Typed output         → stable MCP contract  │
└──────────────────────────────────────────────┘
    ↓
elite_progress (ordered evidence updates)
    ↓
elite_verify / elite_admin (release + monitoring)
    ↓
┌──────────────────────────────────────────────┐
│ Local-first telemetry and memory boundaries    │
│ Metadata by default; raw retention opt-in      │
│ Remote memory remains quarantined until review │
└──────────────────────────────────────────────┘

🔧 Core Tools (default)

The default v2 profile intentionally exposes five task-oriented tools. This improves tool selection, output-contract reliability, and safety for every MCP client.

Legacy Catalog (explicit opt-in)

Existing installations can retain the full legacy tool catalog by setting ELITE_TOOL_PROFILE=legacy. It is not the default because a broad discovery surface makes selection less reliable for agents. The legacy profile includes the following 90+ tools and resources:

Plus 7 MCP Resources (elite://profile, elite://anti_patterns, elite://decisions, elite://quality, elite://health, elite://goals, elite://benchmarks) for real-time dashboards.

⚙️ Configuration

Environment Variables

The local profile is created with owner-only permissions at ~/.elite-reasoning/config.json; it is not read from the repository checkout and must never be committed. Neutral configuration and team-memory shapes are available in docs/examples/local-profile.example.json and docs/examples/team-memory.example.json. Keep credentials in process environment variables or an OS keychain, not in JSON.

Development Setup

# Clone the repo
git clone https://github.com/Snehgabani/elite-reasoning-mcp.git
cd elite-reasoning-mcp

# Install with dev dependencies
uv sync --extra dev

# Run the release gate used by CI
uv run python scripts/release_check.py

# Build package
uv build

🧪 Testing

# Run all tests
ELITE_BRAIN_DIR=/tmp/elite-test uv run pytest tests/ -v --tb=short

# Run the full release gate: tests, lint, types, high-severity scan,
# package privacy/content inspection, wheel CLI, and MCP smoke
uv run python scripts/release_check.py

# Run with coverage
uv run pytest tests/ --cov=core --cov-report=html

The test suite covers:

• ✅ Persistent store (CRUD, FTS, graph, goals, benchmarks)

• ✅ Graph store (nodes, edges, temporal queries, hypotheses)

• ✅ Connection pooling and stale connection recovery

• ✅ FTS sanitization (injection prevention)

• ✅ Workflow flight recorder and MCP tool exposure

• ✅ stdio MCP protocol identity, structured output, and isError=true failures

• ✅ privacy-safe telemetry, secret migration, approved sync, and memory quarantine

• ✅ ordered workflow evidence, prevention events, retry, fallback, and local monitoring

• ✅ Quality-gated memory quarantine

• ✅ Release doctor and eval harness exporters

🔐 Security & Trust

Elite Reasoning MCP is local-first by default: memory is stored under ELITE_BRAIN_DIR, telemetry stores metadata rather than prompt content, and external API access is opt-in through environment configuration.

The default profile does not expose network sync tools. In the explicit legacy profile, every sync request requires confirm=true, an allowlisted endpoint, redirect blocking, and environment grants for external or outbound traffic. The optional sync hub binds to localhost by default; external binding needs configured credentials and ELITE_SYNC_BIND_ALL_INTERFACES=1. For multi-user deployments, configure distinct credentials with SYNC_USER_KEYS_JSON; the hub derives contributor attribution from the credential and never trusts a caller-supplied user ID. Imported remote records are stored as low-trust quarantined memory until an operator explicitly approves them. External LLM judging is disabled unless both GEMINI_API_KEY and ELITE_SYNC_ENABLE_LLM_JUDGE=1 are set.

Public repository hardening includes:

• SECURITY.md with supported versions, private vulnerability reporting, and memory/privacy boundaries

• Dependabot for Python, GitHub Actions, and telemetry UI dependencies

• CodeQL scanning for Python security issues

• Dependency Review on pull requests

• OpenSSF Scorecard visibility for supply-chain posture

• Immutable GitHub Action and Docker image pins, with Dependabot update coverage

• GitHub build provenance and PyPI digital attestations for release distributions

• An allowlisted source distribution plus a release gate that rejects local profiles, generated UI output, databases, and credential-like files

• A checksum-verified, read-only Gitleaks workflow that scans full Git history and the checked-out files with redacted findings

• Release-gate evidence via scripts/release_check.py

Security reports should use GitHub private vulnerability reporting, not public issues.

For the next tracking and monitoring layer, see the Elite Telemetry Roadmap.

🤝 Contributing

Contributions are welcome. Start with CONTRIBUTING.md, GOVERNANCE.md, and the security boundaries in SECURITY.md.

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Run the release gate (uv run python scripts/release_check.py)

4. Document MCP behavior, privacy impact, and validation evidence in your PR

5. Commit your changes (git commit -m 'feat: add amazing feature')

6. Push to the branch (git push origin feature/amazing-feature)

7. Open a Pull Request

Commit Convention

We use Conventional Commits:

• feat: — New features

• fix: — Bug fixes

• chore: — Maintenance

• docs: — Documentation

📄 License

MIT © Sneh Gabani