Neuroverse MCP Server: Neural Data Analysis for AI Models

Explore

Neuroverse

#null .Python

rating : 2 points

downloads : 5.6K

update time : 2026-06-17

Open Site

Installation

Copy the following command to your Client for configuration

{
  "mcpServers": {
    "neuroverse": {
      "command": "npx",
      "args": ["neuroverse"]
    }
  }
}

{
  "mcpServers": {
    "neuroverse": {
      "command": "python",
      "args": ["mcp/server.py"],
      "cwd": "/path/to/neuroverse"
    }
  }
}

Note: Your key is sensitive information, do not share it with anyone.

NeuroVerse Integration

Use neuroverse_process to handle any user request — it auto-detects language, extracts intent, checks safety, and executes.
Use neuroverse_reason for complex tasks requiring analytical reasoning (powered by OpenRouter).
Use neuroverse_store / neuroverse_recall for persistent context across sessions.
Use neuroverse_execute for any potentially dangerous action — it will block destructive operations.


That's it. Two commands your agent needs to know:

| Command | When | What Happens |
|---|---|---|
| `neuroverse_process(text, user_id)` | Any user request | Detects language, extracts intent, safety-checks, executes |
| `neuroverse_store(user_id, intent, ...)` | End of work | Saves context for next session |

Next session, your agent picks up exactly where it left off — like it never forgot.

### 📋 Requirements

- **npm edition:** Node.js 18+ (zero database deps — uses JSON files)
- **Python edition:** Python 3.10+ + PostgreSQL (for persistent memory)

---

## 🤔 Why NeuroVerse?

| Without NeuroVerse | With NeuroVerse |
|---|---|
| Agent only understands English | Agent understands Tamil, Hindi, Telugu, Kannada + English code-switching |
| `"anna file ah csv convert pannu"` → ❌ error | `"anna file ah csv convert pannu"` → ✅ converts file to CSV |
| Every session starts from zero | Agent remembers what it did — across sessions, across agents |
| `DROP DATABASE` → 💀 your data is gone | `DROP DATABASE` → 🛡️ blocked in < 1ms, zero tokens |
| Locked to one LLM provider | Routes to the best model for each task automatically |
| Two agents = chaos | Agent A hands off to Agent B seamlessly |

### 💰 Token Efficiency

NeuroVerse's safety layer runs at **zero token cost** — pure regex and rule matching, no LLM calls wasted:

| Safety Approach | Cost per Check | Latency |
|---|---|---|
| LLM-based safety | 500–2,000 tokens | 1–5 seconds |
| Embedding-based | 100–500 tokens | 200–500ms |
| **NeuroVerse Kavach** | **0 tokens** | **< 1ms** |

Over 100 tool calls per session, that's **50,000–200,000 tokens saved** compared to LLM-based safety.

---

## ⚙️ How It Works

User Input (any language) │ ┌────┴────┐ │ Vani │ ← Language detection + keyword normalisation │ (भाषा) │ Tamil/Hindi/Telugu → normalised internal format └────┬────┘ │ ┌────┴────┐ │ Bodhi │ ← LLM intent extraction + rule-based fallback │ (बोधि) │ Returns structured JSON with confidence └────┬────┘ │ ┌────┴────┐ │ Kavach │ ← 3-layer safety: blocklist → risk → LLM judge │ (कवच) │ Blocks dangerous actions at zero token cost └────┬────┘ │ ┌────┴────┐ │ Marga │ ← Routes to best model (OpenAI/Anthropic/Sarvam/Ollama) │ (मार्ग) │ Based on task type: multilingual/reasoning/local └────┬────┘ │ ┌────┴────┐ │ Smriti │ ← Stores/recalls from tiered memory │ (स्मृति) │ Short-term + Episodic + Semantic (PostgreSQL) └────┬────┘ │ Tool Execution + Response


---

## 🌐 Multilingual Intelligence — Vani

> 🎯 **The Problem:** Every MCP server speaks only English. 70% of India code-switches daily.

"anna indha file ah csv convert pannu" ↓ "anna this file ah csv convert do" ← keyword normalisation (not full translation) ↓ Intent: convert_format { output_format: "csv" }


### 🔀 Hybrid Pipeline (Rule + LLM)

Input → Language Detect (langdetect) → Code-Switch Split → Keyword Normalise → Output


> 💡 **Key insight:** Don't fully translate. Only normalise domain-critical keywords. The rest stays untouched — preserving context, tone, and nuance.

### 🌍 Supported Languages

| Language | Keywords Mapped | Example |
|---|---|---|
| 🇮🇳 Tamil | `pannu` → do, `maathru` → change, `anuppu` → send | `"file ah csv convert pannu"` |
| 🇮🇳 Hindi | `karo` → do, `banao` → create, `bhejo` → send | `"report banao sales ka"` |
| 🇮🇳 Telugu | `cheyyi` → do, `pampu` → send, `chupinchu` → show | `"data chupinchu"` |
| 🇮🇳 Kannada | Support coming in v2 | — |
| 🇬🇧 English | Pass-through | `"convert json to csv"` |

### 🔍 Code-Switch Detection

```json
{
  "languages": ["ta", "en"],
  "confidence": 0.92,
  "is_code_switched": true,
  "original_text": "anna indha file ah csv convert pannu",
  "normalized_text": "anna this file ah csv convert do"
}

🧠 Intent Extraction — Bodhi

📌 LLM-first. Rule-based fallback. Never fails.

LLM succeeds (confidence ≥ 0.5)?
   ├─ Yes → use LLM result
   └─ No  → rule-based parser (deterministic)

🤖 LLM Strategy

# Prompt to LLM:
"Extract structured intent from the following input.
 Return ONLY valid JSON: {intent, parameters, confidence}"

📐 Rule-Based Fallback (7 Patterns)

Pattern	Intent	Trigger Keywords
Format conversion	`convert_format`	convert, csv, json, excel, pdf
Summarisation	`summarize`	summarise, summary, brief, tldr
Report generation	`generate_report`	report, generate report
Deletion	`delete_data`	delete, remove, drop, clean
Data query	`query_data`	query, search, find, fetch, get
Communication	`send_message`	send, share, email, notify
Explanation	`explain`	explain, describe, what is, how to

📤 Output

{
  "intent": "convert_format",
  "parameters": { "input_format": "json", "output_format": "csv" },
  "confidence": 0.87,
  "source": "rule"
}

💡 The key difference: the code decides — not the LLM. If the LLM fails, hallucinates, or returns garbage, the rule engine takes over. Deterministic. Reliable.

💾 Tiered Memory — Smriti

🎯 The Problem: Raw logs are useless. Storing everything wastes resources. No relevance scoring.

💡 NeuroVerse's approach: Score → Filter → Compress → Store.

🗂️ Three Tiers

Tier	Storage	Lifetime	Use
Short-term	In-process dict	Current session	Active context, capped at 50 per user
Episodic	PostgreSQL	Recent actions	What the agent did recently
Semantic	PostgreSQL	Long-term facts	Persistent knowledge about users, projects, entities

📊 Importance Scoring

if importance_score >= 0.4:
    persist_to_database()   # worth remembering
else:
    skip()                  # noise

Only important memories survive. No bloat. No irrelevant recall.

🗜️ Context Compression

❌ Bad:  "The user asked about sales data three times in the last hour and seemed frustrated..."
✅ Good: { "intent": "sales_query", "frequency": 3, "sentiment": "frustrated" }

Structured JSON payloads, NOT raw text dumps. Compressed. Indexable. Queryable.

🗄️ Memory Schema (PostgreSQL)

CREATE TABLE memory_records (
    id          TEXT PRIMARY KEY,
    user_id     TEXT NOT NULL,
    tier        TEXT NOT NULL,          -- short_term | episodic | semantic
    intent      TEXT NOT NULL,
    language    TEXT DEFAULT 'en',
    data        JSONB DEFAULT '{}',     -- compressed structured payload
    importance  REAL DEFAULT 0.5,
    created_at  TIMESTAMPTZ DEFAULT NOW(),
    updated_at  TIMESTAMPTZ DEFAULT NOW()
);
-- Indexed: user_id, intent, tier

🛡️ Safety Layer — Kavach

"The shield that never sleeps."

🧱 Three Layers — Defense in Depth

Agent calls tool  →  MCP Server receives request
                            │
                ┌───────────┴───────────┐
                │   Layer 1: Blocklist  │  ← regex + keywords, < 0.1ms
                └───────────┬───────────┘
                            │ pass
                ┌───────────┴───────────┐
                │  Layer 2: Risk Score  │  ← intent → risk classification
                └───────────┬───────────┘
                            │ pass
                ┌───────────┴───────────┐
                │  Layer 3: LLM Judge   │  ← optional model-based check
                └───────────┬───────────┘
                            │ pass
                     Execute handler

Layer 1 — Rule-Based Blocklist (Zero Cost)

Runs inside the MCP server. Pure regex. No network. No tokens.

Blocked keywords:

delete_all_data, drop_database, drop_table, system_shutdown,
format_disk, rm -rf, truncate, shutdown, reboot, erase_all, destroy

Blocked patterns (regex):

DROP (DATABASE|TABLE|SCHEMA)
DELETE FROM *
TRUNCATE TABLE
FORMAT [drive]:
rm (-rf|--force)

Layer 2 — Intent Risk Classification

Risk Level	Intents	Action
🟢 LOW	`convert_format`, `summarize`, `generate_report`, `query_data`, `explain`	✅ Allow
🟡 MEDIUM	`send_message`, `unknown`	⚠️ Block if strict mode
🔴 HIGH	`delete_data`	❌ Block always
⛔ CRITICAL	`drop_database`, `system_shutdown`	❌ Block always

Layer 3 — LLM Safety Judge (Optional)

If Layers 1–2 pass, optionally ask an LLM: "Is this safe?"

// LLM returns:
{ "safe": false, "reason": "This action would delete all user data." }

✅ Safety Verdict

{
  "allowed": false,
  "risk_level": "critical",
  "reason": "Blocked keyword detected: 'drop_database'",
  "blocked_by": "rule"
}

💰 Token Cost: Zero

Most AI safety:  Agent → "rm -rf /" → Safety LLM → 2,000 tokens burned
NeuroVerse:      Agent → "rm -rf /" → regex match → BLOCKED (0 tokens, < 1ms)

🔒 Strict Mode

# .env
SAFETY_STRICT_MODE=true    # Also blocks MEDIUM risk (unknown/send)
SAFETY_STRICT_MODE=false   # Only blocks HIGH and CRITICAL

🤖 Multi-Model Router — Marga

🎯 The Problem: Vendor lock-in. One model for everything. Overpaying.

💡 NeuroVerse's approach: Route each task to the best model. Automatically.

🧭 Routing Logic

def route_task(task):
    if task.type == "multilingual":
        return sarvam_model        # Best for Indian languages
    elif task.type == "reasoning":
        return claude_or_openai    # Best for complex analysis
    elif task.type == "local":
        return ollama              # Free, on-device, private
    else:
        return best_available      # Fallback chain

🔌 Supported Providers

Provider	Default Model	Best For	Cost
🇮🇳 Sarvam AI	`sarvam-2b-v0.5`	Indian languages, multilingual	Low
🧩 OpenRouter	`stepfun/step-3.5-flash:free`	High-performance reasoning	Free
🧠 Anthropic	`claude-sonnet-4-20250514`	Reasoning, analysis	Medium
🤖 OpenAI	`gpt-4o`	General tasks, code	Medium
🦙 Ollama	`llama3`	Local, private, offline	Free

🎁 Benefits

	Without Marga	With Marga
Cost	Pay GPT-4 for everything	Use Ollama for simple tasks
Speed	Same latency for all tasks	Local models for fast tasks
Privacy	Everything goes to cloud	Sensitive data stays local
Vendor lock-in	Stuck with one provider	Switch anytime

🔄 Fallback Chain

If your preferred provider is down or unconfigured:

OpenRouter → Anthropic → OpenAI → Sarvam → Ollama (local, always available)

🔗 Agent-to-Agent — Setu

🤝 Agents calling agents calling agents.

📇 Agent Registry

register_agent({
    "agent_name": "report_agent",
    "endpoint": "http://localhost:8001/generate",
    "capabilities": ["generate_report", "sales_analysis"]
})

🚦 Routing

{
  "target_agent": "report_agent",
  "task": "generate_sales_report",
  "payload": { "quarter": "Q1", "year": 2026 }
}

🛟 Fallback

If the target agent is unreachable:

{
  "success": false,
  "error": "Agent unreachable: ConnectError",
  "fallback": true
}

The caller can fall back to local execution. No hard failures.

🧩 MCP Tools

NeuroVerse exposes 6 tools via the Model Context Protocol:

#	Tool (npm)	Tool (Python)	Description
1	`neuroverse_process`	`india_mcp_process_multilingual_input`	Full pipeline: detect → normalise → intent → safety → execute
2	`neuroverse_store`	`india_mcp_store_memory`	Store a memory record in the tiered system
3	`neuroverse_recall`	`india_mcp_recall_memory`	Retrieve memories by user, intent, or tier
4	`neuroverse_execute`	`india_mcp_safe_execute`	End-to-end safe execution (convenience)
5	`neuroverse_route`	`india_mcp_route_agent`	Route a task to a registered downstream agent
6	`neuroverse_model`	`india_mcp_model_route`	Query the multi-model router (optionally invoke)
7	`neuroverse_transcribe`	`india_mcp_transcribe_audio`	Transcribe audio to text via Whisper STT
8	`neuroverse_synthesize`	`india_mcp_synthesize_speech`	Synthesize speech from text via Coqui TTS
9	`neuroverse_reason`	N/A	High-performance reasoning via OpenRouter

🌟 Real-World Example

── Session 1 (Agent Alpha, 2pm) ───────────────────────────
india_mcp_process_multilingual_input({
    text: "anna indha sales data ah csv convert pannu",
    user_id: "alpha",
    execute: true
})
→ Language: Tamil+English (code-switched)
→ Intent: convert_format { output_format: "csv" }
→ Safety: ✅ allowed (LOW risk)
→ Execution: ✅ success

india_mcp_store_memory({
    user_id: "alpha",
    intent: "convert_format",
    tier: "episodic",
    data: { "file": "sales_q1.json", "output": "csv" },
    importance_score: 0.8
})

── Session 2 (Agent Beta, next day) ───────────────────────
india_mcp_recall_memory({
    user_id: "alpha",
    intent: "convert_format",
    limit: 5
})
→ "Agent Alpha converted sales_q1.json to CSV yesterday"
→ Beta picks up exactly where Alpha left off

🌐 REST API

NeuroVerse also ships with a FastAPI REST layer — for non-MCP clients:

python app/main.py
# → http://localhost:8000/docs (Swagger UI)

Endpoint	Method	Description
`/health`	GET	Health check
`/api/process`	POST	Full multilingual pipeline
`/api/memory/store`	POST	Store memory
`/api/memory/recall`	POST	Recall memories

⚙️ Configuration

All settings via environment variables (.env):

# Database (PostgreSQL required for persistent memory)
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/neuroverse

# AI Model API Keys (configure the ones you have)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
SARVAM_API_KEY=...

# Ollama (local, free)
OLLAMA_BASE_URL=http://localhost:11434

# Safety
SAFETY_STRICT_MODE=true     # Block MEDIUM risk actions too

# MCP Transport
MCP_TRANSPORT=stdio          # or streamable_http
MCP_PORT=8000

🧪 Testing

python -m pytest tests/ -v

tests/test_intent.py     — 10 passed  (rule-based + async + mock LLM + fallback)
tests/test_language.py   — 10 passed  (keyword normalisation + detection + code-switch)
tests/test_pipeline.py   —  8 passed  (full e2e: English, Tamil, Hindi, dangerous, edges)
tests/test_safety.py     — 12 passed  (blocklist, regex, risk classification, pipeline)

============================= 40 passed in 0.87s ==============================

🔬 What's Tested

Category	Tests	Coverage
Language Detection	10	Tamil, Hindi, English, empty input, code-switch flag
Intent Extraction	10	All 7 rule patterns, LLM mock, LLM failure, empty
Safety Engine	12	Keywords, regex, risk levels, full pipeline, strict mode
Full Pipeline	8	E2E English, Tamil, Hindi, dangerous commands, edge cases

🏗️ Architecture

📦 npm Edition (Node.js / TypeScript)

npm/
├── src/
│   ├── core/
│   │   ├── language.ts       # Vani  — Language detection (zero deps)
│   │   ├── intent.ts         # Bodhi — Intent extraction (LLM + fallback)
│   │   ├── memory.ts         # Smriti — Tiered memory (JSON files)
│   │   ├── safety.ts         # Kavach — 3-layer safety engine
│   │   └── router.ts         # Marga — Multi-model AI router
│   ├── services/
│   │   ├── executor.ts       # Tool registry + retry engine
│   │   └── agent-router.ts   # Setu — Agent-to-Agent routing
│   ├── types.ts              # TypeScript interfaces & enums
│   ├── constants.ts          # Shared constants
│   └── index.ts              # MCP Server — 6 tools (McpServer + Zod)
├── package.json              # npm publish config
├── tsconfig.json
└── LICENSE                   # Apache-2.0

🐍 Python Edition

app/
├── core/
│   ├── language.py           # Vani  — Language detection (langdetect)
│   ├── intent.py             # Bodhi — Intent extraction (LLM + fallback)
│   ├── memory.py             # Smriti — Tiered memory (PostgreSQL)
│   ├── safety.py             # Kavach — 3-layer safety engine
│   └── router.py             # Marga — Multi-model AI router
├── models/schemas.py         # 12 Pydantic v2 models
├── services/
│   ├── executor.py           # Tool registry + retry engine
│   └── agent_router.py       # Setu — Agent-to-Agent routing
├── config.py                 # Settings from environment
└── main.py                   # FastAPI REST entry point
mcp/server.py                 # MCP Server (FastMCP) — 6 tools
tests/                        # 40 tests (pytest)

📦 Dependencies — Minimal

npm (3 packages):

Package	Purpose
`@modelcontextprotocol/sdk`	MCP protocol
`zod`	Schema validation
`axios`	HTTP requests

Python (7 packages):

Package	Purpose
`mcp[cli]`	Model Context Protocol SDK
`fastapi` + `uvicorn`	REST API layer
`pydantic`	Input validation (v2)
`langdetect`	Statistical language identification
`asyncpg` + `sqlalchemy[asyncio]`	PostgreSQL async driver
`httpx`	Async HTTP for model APIs

🗺️ Roadmap

Phase	Status	What
v1.0	✅ Done	Multilingual parsing + intent extraction + 5 tools
v1.0	✅ Done	Tiered memory system (PostgreSQL)
v1.0	✅ Done	3-layer safety engine (Kavach)
v1.0	✅ Done	Multi-model router (Marga) + Agent routing (Setu)
v2.0	✅ Done	Voice layer (Whisper/Coqui) + Extended Multilingual
v3.0	✅ Done	Redis caching + Embedding-based semantic retrieval
v4.0	✅ Done	Reinforcement learning (RLHF) + Arachne contextual indexing
v4.1	✅ Done	OpenRouter Reasoning Layer Integration
v5.0	🔮 Future	Agent marketplace & external system plugins

🔐 Security

Measure	Implementation
API key management	Environment variables only — never in code
Input sanitisation	Pydantic v2 with field constraints on all inputs
Rate limiting	Planned for v2.0
Path traversal	N/A — no file system access by tools
SQL injection	Parameterised queries via SQLAlchemy
Encrypted storage	Delegated to PostgreSQL TLS

🤝 Contributing

Contributions are welcome! Here's how to get started:

Fork the repo
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'feat: add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

🛠️ Development Setup

# npm edition
git clone https://github.com/joshua400/neuroverse.git
cd neuroverse/npm
npm install
npm run build

# Python edition
cd neuroverse
python -m pip install -e ".[dev]"
python -m pytest tests/ -v    # All 40 should pass