MCP-Brain: Multi-agent Cognitive Processing Framework

A lightweight AI framework that runs locally on your machine using MiniMax API. Three specialized agents — Analyst, Creator, and Critic — collaborate through a structured cognitive pipeline to solve complex problems.

User Task
   │
   ▼
┌──────────┐   Analyst breaks it down
│ Analyst ├─────────────────────────┐
└──────────┘                       │
   │                                │
   ▼                                │
┌──────────┐   Creator drafts   ┌──────────┐
│ Creator  │◄──────────────────┤ Analyst  │
└──────────┘                    │ Context  │
   │                            └──────────┘
   │                                │
   ▼                                │
┌──────────┐   Critic evaluates  ┌──────────┐
│ Critic   │◄────────────────────┤ Creator  │
└──────────┘                     │ Draft    │
   │                            └──────────┘
   │                                │
   ▼                                │
┌──────────┐   Creator improves   ┌──────────┐
│ Creator  │◄────────────────────┤ Critic   │
└──────────┘                     │ Feedback │
   │                            └──────────┘
   │
   ▼
┌──────────┐   Critic final     ┌──────────┐
│ Critic   │◄──────eval─────────│ Improved │
└──────────┘                    │ Solution │
   │                            └──────────┘
   ▼
Final Solution + Evaluation

Features

• Local-only — API key and data never leave your machine
• Multi-agent cognition — mimics human collaborative problem-solving
• Persistent memory — sessions saved to ~/.mcp/ for review
• Simple CLI — mcp setup, mcp process, mcp sessions
• Streaming support — stream responses token-by-token
• OpenAI-compatible HTTP server — use as a drop-in LLM provider for any OpenAI client
• Hermes integration — works as both an MCP tool server and a full LLM provider

Installation

# Install from PyPI
pip install mcp-brain

# Or install with pipx (recommended on Ubuntu)
pipx install mcp-brain

# Or install from source
git clone https://github.com/MC80s/mcp.git
cd mcp
pip install -e .

Quick Start

# 1. Configure your MiniMax API key
mcp setup

# 2. Process your first task
mcp process "Design a logo for a tech startup called Quantum Leap"

# 3. View previous sessions
mcp sessions

# 4. Check config status
mcp status

How It Works

Step	Agent	Role
1	Analyst	Breaks down the problem into components
2	Creator	Generates an initial creative solution
3	Critic	Evaluates the draft, identifies flaws
4	Creator	Improves the solution based on critique
5	Critic	Final evaluation and rating

Cost Estimation

MiniMax API is pay-per-use. Each task runs 5 agent calls.

Complexity	Est. Cost
Simple task	~$0.02–0.05
Medium task	~$0.05–0.15
Complex task	~$0.15–0.30

No subscription fees. You control your usage.

Project Structure

mcp-brain/
├── src/mcpbrain/
│   ├── minimax_client.py   # MiniMax API client
│   ├── agents.py            # Creator/Critic/Analyst agents
│   ├── memory.py            # Working memory
│   ├── mcp_core.py          # Orchestration engine
│   ├── http_server.py       # OpenAI-compatible HTTP server
│   ├── server.py            # MCP stdio server
│   ├── tools.py             # Local tool registry
│   └── cli.py               # CLI commands
├── scripts/
├── tests/
├── setup.py
├── pyproject.toml
├── install.sh
└── README.md

CLI Commands

mcp setup              Interactively configure API key
mcp process "task"    Run a task through the cognitive pipeline
mcp sessions          List recent sessions
mcp session <id>      View full session details
mcp status            Check configuration

HTTP Server (OpenAI-compatible)

The HTTP server exposes POST /v1/chat/completions in OpenAI format, making mcp-brain usable as a drop-in LLM provider for any OpenAI-compatible client.

Two Routing Modes

Mode 1: Passthrough (tools present) — When the request includes tools or functions, the cognitive pipeline is bypassed. The full messages array is forwarded directly to MiniMax with the tool definitions. The LLM decides whether to call a tool or respond with text. This is the mode used by Hermes agent integration.

Mode 2: Cognitive Pipeline (no tools) — When no tools are present, the full adaptive pipeline runs. Tasks are classified as SIMPLE (1 step), MODERATE (2 steps), or COMPLEX (5 steps) and routed accordingly.

Starting the server

# Auto-start on boot (systemd user service)
systemctl --user enable mcp-brain-http
systemctl --user start mcp-brain-http

# Or run manually
mcp-brain-http --port 8080

systemd user service

# ~/.config/systemd/user/mcp-brain-http.service
[Unit]
Description=MCP Brain HTTP Server (OpenAI-compatible)
After=network.target

[Service]
ExecStart=/home/YOUR_USERNAME/.local/share/pipx/venvs/mcp-brain/bin/mcp-brain-http --host 127.0.0.1 --port 8080
Restart=always
RestartSec=10

[Install]
WantedBy=default.target

Verify

curl http://127.0.0.1:8080/health                    # {"status":"ok"}
curl http://127.0.0.1:8080/v1/models                # {"object":"list","data":[{"id":"mcp-brain",...}]}

Test a completion

curl -X POST http://127.0.0.1:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"mcp-brain","messages":[{"role":"user","content":"What is 2+2?"}],"stream":false}'

Hermes Integration

mcp-brain integrates with Hermes in two ways:

Option A — MCP Tool Server (manual invocation)

Connect mcp-brain as a native MCP tool server. Hermes can delegate complex reasoning tasks to the multi-agent pipeline by calling the process_task tool.

# ~/.hermes/config.yaml
mcp_servers:
  mcp-brain:
    command: "/home/YOUR_USERNAME/.local/bin/mcp-brain-server"

Option B — Full LLM Provider (recommended, automatic)

Route all LLM conversations through the cognitive pipeline. Every message goes through the adaptive multi-agent architecture automatically.

# ~/.hermes/config.yaml
custom_providers:
  - name: "mcp-brain"
    base_url: "http://127.0.0.1:8080/v1"
    api_key: "local"      # any value — the server ignores it
    provider: "openai"     # OpenAI-compatible endpoint

Why Option B: With Option A, you manually invoke mcp-brain tools. With Option B, every conversation automatically benefits from the cognitive pipeline — no explicit invocation needed.

Configuration

Config file: ~/.mcp/config.json

{
  "api_key": "...",
  "model": "MiniMax-M2.7",
  "max_tokens": 2000,
  "temperature": 0.7
}

Run setup: mcp setup

Important: MiniMax API base URL is https://api.minimax.io/v1 (NOT .chat — that returns 401 on everything).

Working model names: MiniMax-M2.7, MiniMax-M2, MiniMax-M2.5.

Changelog

v0.9.2 (2026-04-26)

• _read_code_files: fair per-file budget — pre-calculates equal allocation across all discovered files instead of sequential-first-wins. Prevents large files from starving subsequent files in the context window.
• _classify_task: code_pattern_confidence now factored into return confidence via max(); strong pattern-only matches return MODERATE instead of UNKNOWN.
• find_code_patterns: Jaccard threshold raised from score > 0 to score >= 0.15 (matches threshold already used in _classify_task).
• record_pattern: deduplication window expanded from patterns[-50:] to patterns[-200:] to match retention limit.
• _STOPWORDS: removed "file","files","code","mcp","brain" — too generic for a code-analysis fingerprinting system.

v0.7.4 — Tool Schema Fix + Memory Error Handling

• Tool schema normalization: TOOL_REGISTRY.list() returned flat {name, description, parameters} dicts but MiniMax API expects {type:'function', function:{...}}. Added _normalize_to_api_format() to wrap schemas. This fixed "invalid tool type (2013)" errors and enabled tool execution.
• Passthrough error handling: _stream_passthrough had no try/except while _stream_pipeline did. Uncaught exceptions now yield SSE error chunk instead of crashing the FastAPI route.
• memory.py error handling: mkdir() in __init__, json.dump() TypeError in save(), and PermissionError/OSError in load() are now all caught.

Changelog

v0.9.2 (2026-04-26)

• _read_code_files: fair per-file budget — pre-calculates equal allocation across all discovered files instead of sequential-first-wins. Prevents large files from starving subsequent files in the context window.
• _classify_task: code_pattern_confidence now factored into return confidence via max(); strong pattern-only matches return MODERATE instead of UNKNOWN.
• find_code_patterns: Jaccard threshold raised from score > 0 to score >= 0.15 (matches threshold already used in _classify_task).
• record_pattern: deduplication window expanded from patterns[-50:] to patterns[-200:] to match retention limit.
• _STOPWORDS: removed "file","files","code","mcp","brain" — too generic for a code-analysis fingerprinting system.

v0.9.1 — Closed Learning Loop: Code-Change Patterns

• PatternExtractor: auto-extracts reusable code-change patterns from every successful session into ~/.mcp/learned/code_patterns.json (last 200). Classifies as refactor/fix/feature/audit/optimize. Extracts file paths, code snippets, and pattern summaries.
• Auto-extraction: _auto_record_pattern() fires at every pipeline completion (SIMPLE/MODERATE/COMPLEX). Also fires in report_outcome() for explicit feedback.
• Route-time matching: _classify_task() looks up similar code patterns by Jaccard fingerprint and injects [CODE PATTERN: prior fix on file.py — snippet: ...] into the Analyst prompt.
• Pattern stored as CodeChangePattern namedtuple with deduplication by (pattern_summary, task_keywords).

v0.9.0 — Learned-Data Routing + Code Audit Fixes

• New _classify_task() method: pre-classifies task using heuristics + learned history before Analyst runs. Combines similarity score, recency decay (30-day half-life), and outcome bonus into a weighted complexity prediction. High-confidence (>=0.85) SIMPLE seeds complexity_detected early and injects "answer directly" hint into the prompt.
• Now actively uses ~/.mcp/learned/: routing is informed by past session outcomes instead of just storing them
• agents.py: remove unused log, app_log imports; add try-except around json.dumps(tool_result) to prevent crashes from non-serializable tool results; fix misleading else: break comment on async-for; remove dead process_stream method (never called anywhere)
• tools.py: _read_file uses itertools.islice for O(1) memory instead of loading full file then slicing; _skill_view adds is_file() check and 500KB size cap; _web_search checks curl returncode before claiming success; _write_file removes redundant hardcoded /home/mc411 path check

v0.8.9 — agents.py + tools.py Audit Fixes

• agents.py: remove unused log, app_log imports; add try-except around json.dumps(tool_result); fix misleading else: break comment; remove dead process_stream method
• tools.py: _read_file O(1) memory via islice; _skill_view size cap + is_file() check; _web_search returncode check; _write_file redundant path removal

v0.8.8 — http_server.py Audit Fixes

• Removed unused MiniMaxAPIError, MiniMaxRateLimitError imports
• _build_token_chunk() now takes resolved model name instead of hardcoded "mcp-brain"
• Added get_api_key() startup-cached helper — eliminates per-request disk I/O on /health and /ready
• Fixed correlation ID reuse: endpoint now uses getattr(request.state, 'correlation_id', None) or new_correlation_id() instead of always overwriting
• Fixed _extract_user_message() to handle OpenAI list content blocks ([{"type": "text", "text": "..."}])
• Fixed error chunk schema in _stream_passthrough — now uses proper choices[0].error nested object
• Fixed error chunk schema in _stream_pipeline — same
• Removed dead done_result variable (assigned on every done event but never consumed)
• /health and /ready endpoints simplified to use cached get_api_key()

v0.8.7 — Dead Code Purge + Bare-Filename Extraction

• Added _BARE_CODE_FILE_PATTERN regex — matches mcp_core.py style bare filenames in addition to slash-prefixed paths
• _read_code_files() now resolves bare filenames relative to package source directory when cwd doesn't match
• exploration_note renamed to analyst_exploration_note — only Analyst agent receives the mandatory exploration directive; Creator and Critic no longer get redundant injection
• Removed _llm_tool_dispatch (~40 lines) — dead code with latent import requests in unreachable try block
• Removed _parse_local_tool (~55 lines) — phrasal tool patterns (run 'command', read "file"), never called
• Removed _parse_tool_invocation (~25 lines) — slash-command parser, never called
• Removed _run_step (~6 lines) — legacy blocking helper, dead
• session_id entropy doubled: str(uuid.uuid4())[:8] → [:16] (2¹²⁸ vs 2³²)

v0.8.6 — MCP-Brain Found 4 Real Bugs

• MCP-brain identified and fixed real bugs in its own codebase using the two-phase pipeline
• Fixed _write_file in tools.py: inconsistent path check (str(p).startswith("/tmp/") vs is_relative_to())
• Fixed report_outcome in mcp_core.py: saved stale result dict instead of updated — feedback fields were lost on re-save
• Fixed _find_result_on_disk: returned first matching file instead of latest by mtime
• Fixed _save_session_log: used self.session_id for filename instead of result["session_id"]

v0.8.5 — Hallucination Fix + Tool Call ID Format

• Two-phase pipeline: mandatory exploration phase forces agent to call read_file before generating analysis — eliminates hallucination for code reference tasks
• analyst_exploration_note injected when _extract_file_paths() finds file references
• Tool call ID format changed from call_0_0 to call_{round:02d}_{index:04d} (MiniMax compatible)
• Tool call arguments now use {"function": {"name": ..., "arguments": json.dumps(...)}} structure
• Analyst persona: code review tasks always route as MODERATE+
• Analyst max_tokens bumped to 12000, Creator to 4000
• report_outcome race condition fixed: atomic RMW with self.__class__._results_lock

v0.8.4 — Version Bump Fix

• Fixed version string mismatch: local files at 0.8.2, GitHub Actions build at 0.8.3 — bump silently failed in prior session
• Bumped to 0.8.4 and published to PyPI

v0.8.3 — Same pipx Venv Issue

• pipx venv not updated with editable install — same issue as v0.8.2

v0.8.2 — pipx Venv Path Mismatch

• pipx venv at ~/.local/share/pipx/venvs/mcp-brain/lib/python3.12/site-packages/mcpbrain/ was not updated after code changes
• Fixed: must run pipx install ~/mcp-work --force after every edit to update the venv

v0.8.1 — Streamlit Dashboard

• Added tab 10: Debate Log — view AI debate transcripts from completed sessions
• Added tab 12: Philosophy Mode — reasoning trace visualization

v0.8.0 — Learning Loop

• SessionIndex — fingerprints tasks by keywords, finds similar past sessions (Jaccard similarity >= 0.2)
• LearnedMemory — stores outcome patterns (success/partial/failed) with ratings
• report_outcome(session_id, outcome, rating, notes) — record feedback for a session
• ~/.mcp/learned/patterns.json — outcome records
• ~/.mcp/learned/session_index.json — session metadata with fingerprints
• ~/.mcp/learned/heuristics.json — extracted heuristics from successful solutions
• Similar sessions and patterns injected into Analyst context on every new task
• mcp feedback <session_id> <outcome> [rating] CLI command for recording outcomes
• mcp learned CLI command to view learned patterns

v0.7.x — See Architecture section above

v0.7.2 through v0.7.5 were minor fixes: version string cleanup, MiniMax reasoning tag leakage, unified _filter_think_tags() helper for streaming and non-streaming paths, file corruption修复.

v0.7.0 — Async Architecture

• httpx.AsyncClient replaces requests — true async streaming, connection pooling (100 max connections)
• structlog for structured logging with correlation IDs
• generate_stream() and generate_stream_from_messages() with retry/backoff
• /ready (readiness probe) and /metrics (Prometheus-compatible) endpoints
• get_shared_client() singleton — reused across HTTP requests
• Think-tag filter (_make_think_filter()) applied to pipeline mode
• Graceful shutdown with aclose()

v0.6.5 — Streaming Think Tag Fix

• Streaming responses now strip <think> and <tool_call> reasoning blocks from token stream
• State machine (_process_token) handles the stripping during streaming
• re.sub() stripping added for non-streaming responses

v0.6.4 — Streaming Bug Fixes

• Fixed streaming: each chunk is yielded separately instead of buffered
• Non-streaming: _strip_reasoning_tags() now runs on full response before returning

v0.6.3 — Passthrough Mode Think Tag Fix

• Think tags (<think>...</think>) were leaking into passthrough responses — stripped with re.sub()
• Both <tool_call>think> and <thinking> tag variants handled

v0.6.2 — Passthrough max_tokens Fix

• Fixed max_tokens hardcoded to 2000 in passthrough mode — now reads from request body (default 4096)

v0.6.1 — Passthrough Mode

• When tools are present in the request, the cognitive pipeline is bypassed and messages are forwarded directly to MiniMax API

v0.6.0 — Native Tool Calling

• Removed regex interceptors for tool invocations — tools passed directly to MiniMax API

Privacy

• All API calls go directly from your machine to MiniMax
• No intermediary servers
• Session logs stored locally in ~/.mcp/logs/
• Your API key stored in ~/.mcp/config.json (keep this file private)