@centr-ai/mcp

⚡ The 2-Minute Executive Summary

Related MCP server: ContextAtlas

🏛️ Core Architecture

"Store everything useful. Send almost nothing."

The Two-Tier Architecture:

1. Deterministic Core (The Authority):

   • AST Indexer: Parses TypeScript/JavaScript into symbols (functions, classes, interfaces, types) in ~20ms.

   • SQLite 3 + FTS5: Ranked BM25 full-text search across symbols, paths, and memories in < 2ms.

   • Token Budgeter: Greedy relevance sorting that strictly respects context limits (e.g. 4,000 tokens).

   • Project Memory: Project-isolated institutional memory (.centr/centr.db).

   • Global Learning: Evidence-based cross-project knowledge (~/.centr/learning.db).

2. Optional Local Brain (The Advisor):

   • Powered by local Small Language Models (0.5B–7B parameters via Ollama or custom local providers).

   • Semantic re-ranking, failure analysis, and memory extraction.

   • Hallucination Guard: The Brain cannot invent files or edit source code; all candidates are bounded by Core retrieval.

   • Deterministic Fallback: Automatically falls back to Core heuristics if the local SLM is absent, slow, or times out.

🚀 Quick Start

1. Installation

# Global installation
npm install -g @centr-ai/cli

# Or run directly via npx
npx @centr-ai/cli init

2. Initialize in Your Repository

cd my-project

# Initialize CentR index (takes ~20-50ms)
centr init

# Check intelligence status
centr status

3. Generate Context for an Agent

# Get the smallest useful context for a task
centr context "Add rate limiting to authentication routes"

# Search code symbols and files
centr search "verifyToken"

# Lookup exact symbol details and references
centr symbol "AuthService"

🔄 Lifecycle Workflow

🛠️ CLI Command Reference

🔌 Model Context Protocol (MCP) Integration

CentR provides a native stdio MCP server (@centr-ai/mcp) supported by Claude Code, OpenAI Codex, and Cursor.

Claude Code Setup

claude mcp add centr -- npx @centr-ai/mcp

Or add to your ~/.claude/claude.json:

{
  "mcpServers": {
    "centr": {
      "command": "npx",
      "args": ["-y", "@centr-ai/mcp"]
    }
  }
}

Cursor Setup (.cursor/mcp.json)

{
  "mcpServers": {
    "centr": {
      "command": "npx",
      "args": ["-y", "@centr-ai/mcp"]
    }
  }
}

Exposed MCP Tools:

• get_context: Returns token-budgeted project intelligence for a task.

• search_code: Ranked full-text search over indexed repository symbols.

• lookup_symbol: Complete definition, references, and related imports.

• get_memory & record_memory: Project-isolated memory retrieval and creation.

• get_learning: Cross-project validated engineering lessons.

🧠 Project Memory vs. Global Learning

CentR maintains a strict boundary between repository-specific facts and reusable engineering wisdom:

Project Memory (docs/MEMORY.md)

• Scope: Isolated to the current repository (.centr/centr.db).

• Answers: "What happened in this specific project?"

• Categories: Architecture patterns, decisions, constraints, discoveries, API contracts, dependencies, workflows, warnings.

Global Learning (docs/LEARNING.md)

• Scope: Reusable across all repositories on the machine (~/.centr/learning.db).

• Answers: "What should the agent do differently next time?"

• Lifecycle: candidate (0.5 confidence) $\rightarrow$ evidence (success/failure logs) $\rightarrow$ validated ($\ge 0.7$ confidence with $\ge 3$ validations) or rejected.

📊 Real-Agent Benchmark Results

CentR includes an objective, reproducible Agent A/B Benchmark Harness (@centr-ai/benchmark-ab) evaluating 27 real-world coding tasks.

Summary Results (7 Tasks, 21 Verified Runs)

Key Empirical Findings:

1. Suppression of Blind Grep Turns: In tested Baseline runs, the agent performed initial exploratory file reads. CentR supplied relevant symbol and file context immediately, eliminating initial exploratory searching in observed runs.

2. Sub-2ms Core Latency: CentR V1 retrieval added only 1.2 ms to overall task execution.

3. Zero Cloud Tokens: All runs consumed 0 cloud tokens and incurred $0.00 API costs.

Full methodology and reproduction steps are documented in docs/AGENT-BENCHMARKING.md and benchmarks/agent-ab/reports/latest-report.md.

🔒 Security & Privacy

CentR is built with a zero-trust approach toward telemetry and sensitive files:

• Zero Cloud Dependency: Never connects to remote cloud endpoints for core features.

• Strict Secret Redaction: Built-in regex filters (DEFAULT_SECRET_PATTERNS) ignore .env, .pem, .key, AWS keys, tokens, and credentials during indexing.

• Path Traversal Defense: All file lookups are strictly verified within the project root via sanitizePath.

• Parameterized SQL: All database operations use SQLite parameterized placeholders (?) to prevent SQL injection.

• Sandboxed Brain: The optional local Brain cannot execute shell commands, edit files directly, or persist ungrounded candidates.

See docs/SECURITY.md for our full security specification.

💻 Hardware Requirements

CentR is engineered for low-end hardware:

📚 Detailed Documentation

• Architecture Deep Dive

• Local Brain Guide

• Project Memory Specification

• Global Learning Specification

• Model Context Protocol (MCP)

• Security Policy

• Testing & Quality Assurance

• Agent Benchmarking Methodology

• Changelog

• Contributing Guide

🤝 Contributing & Community

Contributions are welcome! Please review CONTRIBUTING.md and our CODE_OF_CONDUCT.md before submitting pull requests.

# Setup for development
git clone https://github.com/chiragpgauswami/CentR.git
cd CentR
npm install
npm run build
npm test

📄 License

MIT © 2024–2026 CentR Contributors. See LICENSE for details.