Reasoning Engine

An MCP server that brings difficulty-adaptive, multi-path reasoning to Claude Code. It implements the Actor-Critic-Planner-Reflexion (ACPR) pipeline for deep research synthesis.

What It Does

You give it a research question. It decides how hard the question is, allocates compute accordingly, explores multiple reasoning paths in parallel, scores each path, self-corrects weak paths, and synthesizes the best results into a coherent report.

"What is a Process Reward Model?"
  -> difficulty 0.21 -> single pass -> done in seconds

"How do PRMs interact with MCTS for test-time compute scaling?"
  -> difficulty 0.71 -> forest strategy -> 8 branches, 3 reflexion rounds

Related MCP server: Consult LLM MCP

Architecture

Two components work together:

Claude Code (LLM-powered orchestrator)
  |  runs the ACPR loop sequentially in one context — no subagents
  |  calls MCP tools for algorithmic decisions and evidence retrieval
  v
Reasoning Engine MCP Server (deterministic Python backend)
  - Difficulty estimation
  - DORA budget allocation (explore vs exploit)
  - UCB branch selection
  - Dual-signal PRM scoring (Promise + Progress)
  - Research angle planning and evidence-gap checks
  - Real academic search: OpenAlex, Crossref, arXiv, Semantic Scholar,
    Europe PMC, DOAJ, DBLP (free, no auth), deduplicated and ranked
  - Verifiable pipeline: claim extraction, evidence verification,
    quality gate, attested run-pack export
  - Tree state management (SQLite)
  - Episodic memory for cross-session learning
  - Content sanitization (prompt injection protection)

No API key required for the reasoning loop or academic search. Runs on your Claude Code Max subscription.

How It Works

The ACPR Pipeline

The entire loop runs sequentially in one Claude Code conversation — no subagent spawning required.

Difficulty-Adaptive Scaling

Installation

1. Clone and install

git clone https://github.com/Raoof128/reasoning-engine.git
cd reasoning-engine
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

2. Run tests

pytest -v

3. Configure Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "reasoning-engine": {
      "command": "/path/to/reasoning-engine/.venv/bin/reasoning-engine",
      "args": ["mcp"]
    }
  }
}

Or register it for every project at once:

claude mcp add reasoning-engine -s user -- /path/to/reasoning-engine/.venv/bin/reasoning-engine mcp

4. Install the skill (optional)

Copy skill/deep-research.md to ~/.claude/skills/deep-research.md for the /deep-research slash command.

Required Skills and MCP Servers

This agent works with the following Claude Code components:

Required MCP Servers

No external web-crawling MCP server is required — evidence retrieval uses the reasoning engine's own scholar_search_tool, backed by OpenAlex, Crossref, arXiv, Semantic Scholar, Europe PMC, DOAJ, and DBLP.

Required Skills (for full pipeline)

Optional Skills

Install the deep-research skill:

cp skill/deep-research.md ~/.claude/skills/

The stop-slop and docx skills are third-party — see their repos for installation.

MCP Tools

Project Structure

reasoning-engine/
  src/reasoning_engine/
    server.py       # MCP server wiring all tools
    cli.py          # reasoning-engine CLI (mcp, serve, research, scholar)
    transport.py    # MCP transport factory and local HTTP safety checks
    db.py           # SQLite schema and connections
    difficulty.py   # Heuristic difficulty estimator
    dora.py         # DORA budget allocation + branch selection
    ucb.py          # UCB1 explore/exploit selection
    sessions.py     # Session and branch lifecycle management
    memory.py       # Episodic memory for Reflexion learnings
    research.py     # Research angle and evidence-gap planning
    sanitizer.py    # Content sanitization for web data
    validation.py   # Shared MCP tool input validation helpers
    verifiable/      # Claim extraction, verification, quality gate, run-pack export
      aggregator.py  # Fan-out academic search across all sources, dedup + rank
      sources/       # OpenAlex, Crossref, arXiv, Semantic Scholar, Europe PMC,
                      #   DOAJ, DBLP, and optional Scholar Gateway adapters
  tests/            # 143 tests, all passing
  skill/            # Claude Code skill file

Background

This project implements ideas from three research documents on AI reasoning architectures:

• Process Reward Models score individual reasoning steps (not just final answers), enabling dense feedback for tree search.

• DORA (Direction-Oriented Resource Allocation) uses score variance to dynamically switch between exploring many paths and exploiting the best one.

• Reflexion injects textual critiques back into the prompt, enabling self-correction without weight updates.

• UCB1 selection balances trying promising branches against exploring undervisited ones.

• ReAct / Self-RAG style evidence checks keep retrieval and verification explicit before synthesis.

The key insight: a Claude Code skill can orchestrate this entire pipeline sequentially in a single conversation on a Max subscription, with a lightweight Python MCP server handling the deterministic math and real academic retrieval. No separate API key needed.

Documentation

• Architecture Overview

• API Reference

• Usage Examples

• Contributing

• Security Policy

• Code of Conduct

Verifiable Research Engine MVP

Academic search is live by default — no API key needed. It fans out concurrently across seven free sources (OpenAlex, Crossref, arXiv, Semantic Scholar, Europe PMC, DOAJ, DBLP), deduplicates by DOI/title, and ranks the results:

reasoning-engine scholar search "MCP prompt injection" --limit 3

Run the full verifiable research pipeline (search, claim extraction, verification, quality gate, attested run-pack export):

reasoning-engine research "Retrieval augmented generation reduces hallucination" \
  --draft "Retrieval augmented generation reduces hallucination in large language models."

Useful environment variables:

The paid Scholar Gateway connector remains available as one more source when configured:

export SCHOLAR_GATEWAY_LIVE=1
export SCHOLAR_GATEWAY_ACCESS_TOKEN="<token>"
reasoning-engine scholar search "literature synthesis evaluation" --limit 5

Tokens are read from environment or local credential mechanisms and are never stored in SQLite or run packs. Claim verification uses deterministic lexical overlap as an MVP placeholder verifier, so it is suitable for pipeline testing and audit workflow validation rather than final semantic claim verification.

Local HTTP MCP

STDIO remains the default MCP workflow. To start a local Streamable HTTP MCP server:

reasoning-engine serve --transport http --host 127.0.0.1 --port 8765

The MCP endpoint is available at:

http://127.0.0.1:8765/mcp

Public binding is blocked unless explicitly acknowledged:

reasoning-engine serve --transport http --host 0.0.0.0 --unsafe-bind-public

For Notion AI Custom MCP testing through a Cloudflare HTTPS tunnel, use the laptop launcher:

chmod +x ./run-notion-mcp-laptop.sh
./run-notion-mcp-laptop.sh

On macOS, you can also double-click run-notion-mcp-laptop.command from Finder to start the same launcher in Terminal.

The launcher keeps the MCP server bound to 127.0.0.1, creates a local bearer token file at ~/.reasoning-engine/notion-http.env, starts a temporary Cloudflare Tunnel, and prints the Notion MCP URL. See Notion Laptop MCP Tunnel.

The project requires mcp>=1.24.0,<2, which is above the 1.23.0 safety floor for default FastMCP DNS rebinding protection.

License

MIT