Geniusmcp

🔥 GeniusMCP

Quality-aware code intelligence that turns GitHub search into ranked, explainable, import-ready recommendations.

[](https://nodejs.org) [](#testing) [](LICENSE) [](https://modelcontextprotocol.io)

Not another grep. An intelligence layer.

[Quick Start](#-quick-start) · [How It Works](#-how-it-works) · [Soul](soul.md) · [Tools](#%EF%B8%8F-tools-28-mcp-tools) · [Architecture](#%EF%B8%8F-architecture)

---

The Problem

Every code search tool answers "where is this string?"

None of them answer "what is the best implementation, why, and can I safely use it?"

When you ask genius.hunt("retry with backoff"), GeniusMCP returns:

Archetype 1 — Minimal inline helper
  ✅ 12 LOC, zero deps, copy-paste ready
  Exemplar: owner/repo — score 0.87 (battle_tested)
  Why: test-adjacent, MIT license, 3 years stable

Archetype 2 — Configurable utility
  ✅ Options-driven, max attempts + jitter strategy
  Exemplar: owner/repo2 — score 0.82
  Why: 14K stars, active maintenance, comprehensive docs

Archetype 3 — Middleware pattern
  ✅ Express/Fastify compatible, interceptor-based
  Exemplar: owner/repo3 — score 0.79
  Tradeoff: framework-coupled

Coverage: 3 sources searched, 2 blind spots, confidence: 0.83

That's the gap GeniusMCP fills.

---

✨ Key Features

| Feature | What it does | |---------|-------------| | 🎯 Archetype Search | Finds 3-5 structural families, not 200 raw matches | | 📊 6-Bucket Quality Scoring | queryFit · durability · vitality · importability · codeQuality · evidenceConfidence | | 🔍 Multi-Source Discovery | grep.app (free, 1M repos) + GitHub Code Search (200M repos) + searchcode (75B lines) | | 🧬 3-Level Dedup | Exact SHA → normalized AST hash → winnowing fingerprint families | | 📜 Provenance-First Import | License gate · dependency closure · policy checks · attribution | | 🧠 Persistent Memory | Every search enriches local evidence graph. Session 50 is smarter than session 1. | | 🪝 Auto-Capture Hooks | Claude Code hooks capture patterns from every file you read/write | | 💉 Pre-Prompt Injection | Relevant memories injected BEFORE the AI responds | | 🏗️ 7 Archetype Categories | minimal · configurable · middleware · context-aware · distributed · enterprise · wrapper | | 📋 Transparent Uncertainty | Every result shows blind spots + evidence confidence | | ⚡ Tiered Responses | L1 (80 tokens) / L2 (300) / L3 (2000) — adaptive detail level per result count | | 🛡️ Circuit Breakers | Per-source fault isolation: GitHub/grep.app/searchcode fail independently | | 🎰 Thompson Sampling | Multi-armed bandit learns which sources produce best results per query type | | 🔤 SAC Matching | getUserSession finds get_user_session — cross-convention identifier similarity | | 📦 Signature Compression | Repomix-style 70% token reduction — strips bodies, keeps signatures | | 🔍 Dynamic Discovery | forge_discover("search code") — find tools by intent, not memorize 28 names |

---

🏆 Why GeniusMCP

| | GitHub MCP | grep.app MCP | DeusData | GeniusMCP | |---|:---:|:---:|:---:|:---:| | Multi-source search | 1 source | 1 source | local only | 3 sources | | Quality scoring | no | no | no | 6-bucket | | License verification | no | no | no | yes | | Import with provenance | no | no | no | yes | | Persistent memory | no | no | knowledge graph | Bayesian + decay | | Cross-convention matching | no | no | no | SAC algorithm | | Fault tolerance | no | no | no | circuit breakers | | Token efficiency | no | no | no | L1/L2/L3 tiers |

---

🚀 Quick Start

# 1. Clone and install
git clone https://github.com/geniussigmaskibidi-gif/geniusmcp
cd geniusmcp && pnpm install && pnpm build

# 2. Optional: GitHub auth (enables GitHub Code Search + metadata)
export GITHUB_TOKEN=ghp_your_token

Add to Claude Code (.mcp.json in your project root)

{
  "mcpServers": {
    "forgemcp": {
      "command": "node",
      "args": ["/path/to/forgemcp/apps/mcp-server/dist/index.js"],
      "env": { "GITHUB_TOKEN": "ghp_your_token" }
    }
  }
}

Server auto-indexes your project on start. code.reach, code.map, code.symbols work immediately.

Optional: Claude Code Hooks (auto-capture + injection)

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Read|Write|Edit", "command": "node hooks/genius-capture.js" }
    ],
    "UserPromptSubmit": [
      { "command": "node hooks/genius-inject.js" }
    ]
  }
}

---

💡 Usage Examples

Find the best implementation of a concept

You: "Find me a good rate limiter implementation"
Agent calls: genius.hunt("rate limiter", language: "typescript", tier: "L1")
→ 5 ranked archetypes in 130 tokens, with stars/license/test signals

Import code with license verification

You: "Import that circuit breaker from the best result"
Agent calls: import.extract("owner/repo", "src/circuit-breaker.ts", symbol: "CircuitBreaker")
→ Full code + MIT license verified + provenance hash + attribution comment

Compare approaches across repos

You: "Should I use Zod or Ajv for validation?"
Agent calls: research.deep_compare("validation", ["colinhacks/zod", "ajv-validator/ajv"])
→ Side-by-side: Zod 42K stars vs Ajv 14K, both MIT+CI, structured quality signals

Remember and recall across sessions

Session 1: genius.hunt("retry backoff") → auto-stores top 3 results
Session 2: memory.recall("retry") → instant recall, no API calls needed

Explore unfamiliar repository

You: "How does Hono handle errors?"
Agent calls: research.archaeology("honojs/hono", "error handling")
→ Found .onError() handler, JWT error middleware, 29K stars, TypeScript

> Read [soul.md](soul.md) for the complete AI agent reasoning guide — search strategies, anti-patterns, and token budget optimization.

---

🔄 How It Works

graph TD
    Q["genius.hunt('retry backoff')"] --> C[QueryCompiler]
    C --> |grep.app queries| G[grep.app MCP]
    C --> |GitHub queries| GH[GitHub Code Search]
    C --> |hydration queries| SC[searchcode.com]

    G --> D[Dedup Engine]
    GH --> D
    SC --> D

    D --> |"180 hits → 60 blobs"| E[Symbol Extractor]
    E --> F[Winnowing Fingerprint]
    F --> |"60 → 8 families"| CL[Archetype Classifier]
    CL --> R[Quality Scorer]
    R --> |"6-bucket ranking"| OUT["3-5 ranked archetypeswith explanations"]

    OUT --> MEM[(Evidence GraphSQLite)]
    MEM --> |"next search: instant recall"| Q

The Magic Loop

Session 1: "Find best rate limiter" → searches 3 sources → 60 unique blobs → 5 archetypes
           → Results cached in evidence graph

Session 2: "Rate limiter for Express" → local memory: 40 instant hits + 20 new
           → Faster, smarter, more relevant

Session 10: "Throttle middleware" → 120 cached patterns, 

**Built for AI agents that never forget.**

[Report Bug](../../issues) · [Request Feature](../../issues) · [Discussions](../../discussions)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [geniussigmaskibidi-gif](https://github.com/geniussigmaskibidi-gif)
- **Source:** [geniussigmaskibidi-gif/geniusmcp](https://github.com/geniussigmaskibidi-gif/geniusmcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.