# Geniusmcp

> Code Intelligence OS for AI Agents — persistent memory, GitHub intelligence, structural search

- **Type:** MCP server
- **Install:** `agentstack add mcp-geniussigmaskibidi-gif-geniusmcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [geniussigmaskibidi-gif](https://agentstack.voostack.com/s/geniussigmaskibidi-gif)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [geniussigmaskibidi-gif](https://github.com/geniussigmaskibidi-gif)
- **Source:** https://github.com/geniussigmaskibidi-gif/geniusmcp

## Install

```sh
agentstack add mcp-geniussigmaskibidi-gif-geniusmcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🔥 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

```bash
# 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)

```json
{
  "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)

```json
{
  "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

```mermaid
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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-geniussigmaskibidi-gif-geniusmcp
- Seller: https://agentstack.voostack.com/s/geniussigmaskibidi-gif
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.