# Reasoning Engine MCP Server

MCP (Model Context Protocol) server for deep algorithmic and mathematical reasoning via [Hermes Agent](https://hermes-agent.nousresearch.com).

## Overview

`reasoning_engine` is a **generic OpenAI-compatible chat completions wrapper** that calls any LLM endpoint to produce **only the final distilled answer** — no chain-of-thought, no reasoning traces exposed. Designed for complex computational problems where you need the result, not the process.

By default it's configured for `vibethinker-3b` via LM Studio, but can target **any model on any endpoint** — per-call or server-level.

## Use Cases

- Algorithm design & optimization
- Data structure complexity analysis
- Competitive programming challenges
- Mathematical proofs & derivations
- Multi-step logical deduction tasks
- Any deep technical reasoning requiring compressed output

## Installation

### Prerequisites

- Python 3.10+
- LM Studio running with `vibethinker-3b` model loaded (or any OpenAI-compatible LLM server)

### Setup

```bash
# Test the server directly
python3 src/reasoning_engine_mcp/server.py --print-config
```

## Configuration

Add to your Hermes Agent `~/.hermes/config.yaml` under `mcp_servers`:

```yaml
mcp_servers:
  reasoning_engine:
    command: python3
    args:
    - /path/to/reasoning-engine-mcp/src/reasoning_engine_mcp/server.py
    env:
      REASONING_ENGINE_MODEL: vibethinker-3b
      REASONING_ENGINE_BASE_URL: http://127.0.0.1:1234/v1
```

### Server-Level Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `REASONING_ENGINE_MODEL` | `vibethinker-3b` | Model name in your LLM server |
| `REASONING_ENGINE_BASE_URL` | `http://127.0.0.1:1234/v1` | OpenAI-compatible API endpoint |
| `REASONING_ENGINE_API_KEY` | (empty) | API key if your server requires one |

### Per-Call Overrides

The tool accepts additional parameters that override the server-level defaults for a single call:

| Parameter | Type | Description |
|-----------|------|-------------|
| `model` | string | Model identifier. Example: `'qwen/qwen3.6-35b-a3b'`, `'anthropic/claude-sonnet-4'` |
| `base_url` | string | Endpoint URL. Example: `'http://127.0.0.1:11434/v1'`, `'https://api.openai.com/v1'` |
| `api_key` | string | API key for this call only. Leave empty if no auth needed |

**Resolution order:** tool params → env vars → hardcoded defaults.

## Usage

Once configured, the `reasoning_engine` tool is available in Hermes Agent sessions. Call it with a detailed problem prompt:

```python
# Example: Algorithm design (using server-level defaults)
call_tool("reasoning_engine", {
    "prompt": """
    Problem: Find the minimum number of operations to convert array A to array B
    where each operation can increment or decrement an element by 1.
    
    Constraints:
    - Array length up to 10^5
    - Elements range from -10^9 to 10^9
    
    Input Format: Two arrays of equal length
    Output Format: Single integer (minimum operations)
    """,
    "max_tokens": 4096,
    "temperature": 0.3
})

# Example: Override model per-call
call_tool("reasoning_engine", {
    "prompt": "Prove that the sum of two even numbers is always even.",
    "model": "qwen/qwen3.6-35b-a3b",
    "max_tokens": 4096,
    "temperature": 0.1
})

# Example: Use OpenAI API instead of local server
call_tool("reasoning_engine", {
    "prompt": "Design an O(n log n) sorting algorithm with detailed complexity analysis.",
    "model": "anthropic/claude-sonnet-4",
    "base_url": "https://api.openai.com/v1",
    "api_key": "sk-...",
    "max_tokens": 8192,
    "temperature": 0.5
})
```

### Core Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `prompt` | string | **required** | Complete problem statement with constraints and specifications |
| `max_tokens` | int | 4096 | Response length limit (256-8192) |
| `temperature` | float | 0.7 | Creativity vs determinism (0.1-1.5). Use lower for math/proofs, higher for creative approaches |

## Architecture

```
Hermes Agent
    │
    ▼
MCP Client (stdio transport)
    │
    ▼
reasoning-engine-mcp server.py
    │  (reads JSON-RPC from stdin)
    │  (writes JSON-RPC to stdout)
    │
    ▼
OpenAI-compatible API (HTTP POST /chat/completions)
    │
    ▼
Any LLM model (vibethinker-3b, Claude, GPT, Qwen, etc.)
```

The MCP server is a lightweight stdio bridge — no external dependencies, pure Python standard library.

## Language Enforcement

All responses are strictly in English regardless of the prompt language. This is enforced via:
1. System prompt with explicit LANGUAGE ENFORCEMENT section
2. Footer appended to every user message

## License

MIT License — feel free to fork, modify, and share.