Skip to main content
Glama

πŸ”₯ GeniusMCP

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

Node 20+ Tests License MIT MCP

Not another grep. An intelligence layer.

Quick Start Β· How It Works Β· Soul Β· Tools Β· Architecture

GeniusMCP in action


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.


Related MCP server: Acemcp

✨ 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 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 archetypes<br/>with explanations"]

    OUT --> MEM[(Evidence Graph<br/>SQLite)]
    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, <100ms response
            β†’ Compound intelligence

πŸ› οΈ Tools (28 MCP Tools)

🎯 Hunt Intelligence (flagship)

Tool

Description

genius.hunt

Find best implementations with archetype clustering, quality scoring, coverage report

genius.explain

Full signal breakdown: why this ranked #1

genius.compare

Head-to-head comparison with bucket deltas

genius.import

Policy-aware import with provenance manifest

🧠 Memory (compound intelligence)

Tool

Description

memory.recall

Search past patterns by concept

memory.store

Save pattern to persistent memory

memory.evolve

Create improved version linked to parent

memory.related

Find connected patterns

memory.link

Create relationships between patterns

memory.stats

Memory size, coverage, confidence distribution

memory.forget

Remove outdated patterns

🧭 Code Navigation (1 call = 10 Read/Greps)

Tool

Description

code.reach

Jump to symbol with full context: callers, callees, deps

code.map

Instant project architecture map

code.trace

Call chain between functions

code.understand

Compressed module understanding

code.symbols

All exports with signatures

πŸ”¬ Research (persistent reasoning chains)

Tool

Description

research.archaeology

Trace code evolution

research.deep_compare

Structured comparison with metrics

research.start_chain

Begin research thread

research.add_step

Record reasoning step

research.conclude

Mark chain completed

research.recall_chain

Search past research

πŸ™ GitHub

Tool

Description

github.search_repos

Search by query, language, stars

github.search_code

Code search across GitHub

github.repo_overview

Stars, CI, license, health

github.repo_file

Get file content

github.repo_tree

Recursive file tree


πŸ—οΈ Architecture

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                   GeniusMCP Server                   β”‚
β”‚                                                     β”‚
β”‚  Layer 1: DISCOVERY                                 β”‚
β”‚    grep.app MCP Β· GitHub Code Search API            β”‚
β”‚                                                     β”‚
β”‚  Layer 2: HYDRATION                                 β”‚
β”‚    GitHub Trees/Contents Β· searchcode analysis      β”‚
β”‚                                                     β”‚
β”‚  Layer 3: EVIDENCE GRAPH                            β”‚
β”‚    SourceHit β†’ Blob β†’ SymbolSlice β†’ PatternFamily   β”‚
β”‚                                                     β”‚
β”‚  Layer 4: PATTERN INTELLIGENCE                      β”‚
β”‚    3-level dedup Β· archetype classifier Β· scorer    β”‚
β”‚                                                     β”‚
β”‚  Layer 5: IMPORT & POLICY                           β”‚
β”‚    License gate Β· provenance Β· dep closure          β”‚
β”‚                                                     β”‚
β”‚  Layer 6: EVALUATION                                β”‚
β”‚    Coverage confidence Β· blind spots Β· metrics      β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

Quality Scoring (RFC v2)

overall = 0.35 Γ— queryFit + 0.50 Γ— qualityComposite + 0.15 Γ— evidenceConfidence

qualityComposite = weights[preset] Γ— {durability, vitality, importability, codeQuality}

Presets: battle_tested Β· modern_active Β· minimal_dependency Β· teaching_quality

Hard caps: snippet_only β†’ evidence ≀ 0.60 Β· archived β†’ vitality ≀ 0.20 Β· license_unknown β†’ importability ≀ 0.20


πŸ“¦ Monorepo Structure

forgemcp/
  packages/
    core/              β€” Types, config, errors (Zod-validated)
    db/                β€” SQLite WAL, blob store, search index, evidence graph
    ast-intelligence/  β€” Symbol extraction, call graph, architecture detection
    repo-memory/       β€” Bayesian confidence + Ebbinghaus decay engine
    github-gateway/    β€” Octokit + 4-bucket rate governor + ETag cache
    data-sources/      β€” grep.app + searchcode + source orchestrator
    hunt-engine/       β€” Winnowing, clustering, scoring, archetype classifier
    importer/          β€” License policy + provenance + style adaptation
  apps/
    mcp-server/        β€” MCP server + 5 skill modules + hook daemon + dynamic tools
  hooks/               β€” Claude Code auto-capture scripts
  tests/               β€” 252 tests (vitest)
  .github/workflows/   β€” CI (Node 20/22, build + typecheck + test)

πŸ§ͺ Testing

npx vitest run
# 22 test suites, 252 tests, all passing (<1s)

Suite

Tests

What it covers

foundation

19

ForgeResult, Logger, Health, Context

blob-store

10

Content-addressable storage, dedup, file refs

blob-lifecycle

11

GC, pinning, integrity scrub

symbol-extractor

13

TypeScript, Python, Go extraction + fingerprinting

parser-registry

6

Multi-backend precision routing

search-index

4

FTS5 trigram, BM25, RRF fusion

simhash

14

Near-duplicate detection, Hamming distance

chunker

8

Semantic code chunking, symbol boundaries

query-planner

14

Query classification, lane planning

ranking-v2

13

BM25F weights, retrieval scoring, lexical+structural

memory-engine

15

Store, recall, capture, Bayesian confidence, Ebbinghaus decay

memory-v2

6

L1/L2/L3 capsule builder, token estimation

call-graph

9

2-pass resolution, BFS reachability, path tracing

winnowing

12

Fingerprints, Jaccard similarity, clone clustering

policy-engine

11

4-mode import policy, license gates, provenance

evidence-graph

8

v2 schema: query runs, slices, families, versioned scores

job-queue

10

Durable job queue, priority, backoff, dead-letter

circuit-breaker

19

Circuit breaker state machine, bulkhead, resilient search

token-budget

22

Token estimation, tier selection, truncation, compression

source-selector

5

Thompson Sampling, convergence, discounting

early-terminator

6

Welford online stats, adaptive saturation

sac

17

Subword Affine Canonicalization, cross-convention matching


🎯 Design Principles

  1. Evidence, not opinions β€” every score has signals you can inspect

  2. Local-first β€” works offline for indexed repos

  3. Zero ML in core β€” lexical + structural, semantic is opt-in

  4. Provenance always β€” every import traced to source + license

  5. Progressive learning β€” every search enriches the evidence graph

  6. Transparent uncertainty β€” blind spots shown, not hidden


πŸ“Š Tech Stack

Component

Technology

Protocol

MCP SDK 1.28 (stdio + Streamable HTTP)

Database

SQLite (WAL mode, better-sqlite3)

Search

FTS5 trigram + BM25F + Reciprocal Rank Fusion

AST

Regex multi-language + ast-grep upgrade path

Dedup

Winnowing fingerprints (Schleimer 2003) + Jaccard clustering

GitHub

Octokit + throttling + retry + 4-bucket rate governor

External

grep.app MCP + searchcode.com

Validation

Zod

Resilience

Circuit breakers + bulkheads + decorrelated jitter

Ranking

SAC cross-convention matching + Thompson Sampling source routing

Token Efficiency

L1/L2/L3 tiered responses + signature compression

Tests

Vitest (252 tests, <1s)

Monorepo

pnpm + Turborepo


πŸ“„ License

MIT


Built for AI agents that never forget.

Report Bug Β· Request Feature Β· Discussions

Available Tools

30 tools
code.mapC

Get instant project architecture map β€” modules, dependencies, hot paths, entry point. Understands MVC, layered, microservices patterns automatically.

Inputs: root.

code.reachA

Jump to any symbol β€” returns definition, signature, callers, callees, deps in ONE call. Replaces 5-10 Read/Grep calls.

Inputs: symbol (required), limit, scope.

code.symbolsB

List all exported symbols (functions, classes, types) in a path scope with signatures

Inputs: scope (required), limit.

code.traceB

Trace a call chain from one function to another. Shows the shortest path through the call graph.

Inputs: to (required), from (required), maxDepth.

code.understandA

Get compressed understanding of a file or directory β€” purpose, key exports, data flow, dependencies, complexity hotspots. Replaces reading 10+ files.

Inputs: path (required).

forge_describeA

Get full input schema and usage example for a ForgeMCP tool. Call forge_discover first to find tool names.

Inputs: tool_name (required).

forge_discoverA

Search ForgeMCP capabilities by intent. Returns matching tool names with one-line descriptions. Example: forge_discover('find rate limiter code') β†’ genius.hunt, genius.find_best

Inputs: query (required).

genius.explainB

Explain why a code result ranked where it did. Full signal breakdown with per-factor scores.

Inputs: path (required), repo (required), query (required), preset, +2 more.

genius.find_bestA

Find the best implementations of a concept across GitHub. Returns ranked archetypes with explanations, not raw search results. Example: genius.find_best('rate limiter', language: 'typescript')

Inputs: concept (required), limit, preset, language, +1 more.

genius.huntB

Find the best implementations of a concept across GitHub, grep.app, and searchcode. Returns ranked archetypes (not raw search results) with quality explanations. Example: genius.hunt('rate limiter', language: 'typescript')

Inputs: query (required), mode, tier, preset, +2 more.

github.compareC

Compare implementations from different repos side-by-side with quality breakdown

Inputs: repos (required), concept (required).

github.repo_fileC

Get file content from a GitHub repo

Inputs: path (required), repo (required), ref.

github.repo_overviewC

Get comprehensive repo intelligence: stars, health, CI, topics, license

Inputs: repo (required).

github.repo_treeC

Get file tree of a GitHub repo (recursive)

Inputs: repo (required), maxDepth.

github.search_codeC

Search code across GitHub. Returns file matches with text fragments.

Inputs: query (required), repo, limit, language.

github.search_reposC

Search GitHub repositories by query, language, stars, topics

Inputs: query (required), sort, limit, language, +1 more.

import.extractA

Extract a function/module from a GitHub repo with provenance. License-checked, dependency-resolved, style-adapted. Returns ready-to-paste code with attribution.

Inputs: path (required), repo (required), ref, symbol, +1 more.

memory.evolveC

Create an improved version of an existing pattern (links to parent)

Inputs: code (required), parentId (required), description.

memory.forgetA

Remove a pattern from memory (cascades to tags, links, embeddings)

Inputs: patternId (required).

memory.recallC

Search code memory for patterns, solutions, and insights from past sessions

Inputs: query (required), limit, language, minConfidence.

memory.relatedB

Find patterns related to a given pattern (by explicit links)

Inputs: patternId (required), limit.

memory.statsA

Show code memory statistics: size, coverage, top patterns

Inputs: no named parameters.

memory.storeC

Save a code pattern, solution, or insight to persistent memory

Inputs: kind (required), name (required), code, tags, +6 more.

research.add_stepC

Add a reasoning step to an active research chain. Records: what you searched, what you found, key insight, decision made.

Inputs: chainId (required), queryText (required), queryType (required), resultSummary (required), +4 more.

research.archaeologyB

Trace how a concept evolved in a repo over time. Analyzes git commit history and code changes. No external AI required.

Inputs: repo (required), aspect (required), limit, pathHint.

research.concludeC

Mark a research chain as completed with final synthesis.

Inputs: chainId (required), conclusion (required).

research.deep_compareC

Deep comparison of implementations across repos. Returns structured metrics and quality signals for the calling LLM to reason about.

Inputs: repos (required), concept (required), language.

research.recall_chainB

Search past research chains by topic. Answer questions like 'why did we choose Orama?' from stored reasoning.

Inputs: query (required), limit.

research.start_chainA

Start a new research chain to track reasoning across multiple steps. Chains persist across sessions for future recall.

Inputs: title (required), intent (required), modelUsed.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.8/5.0

    Scored across 30 tools

    Disambiguation2/5

    Multiple tools have overlapping purposes with near-identical descriptions: genius.find_best vs genius.hunt, github.compare vs research.deep_compare, and code.reach vs code.understand are easy to confuse. While some descriptions contain differentiating details, several boundaries remain unclear enough that an agent could misselect.

    Naming Consistency3/5

    Most tools use dot-namespaced names (memory.recall, github.search_code, code.reach), but the pattern is broken by forge_discover/forge_describe and subcommands mix single words, verbs, and snake_case (e.g., research.archaeology vs research.deep_compare). Readable but not fully consistent.

    Tool Count2/5

    With 30 tools, this exceeds the 25+ threshold for 'too many'. Several tools are redundant variations (e.g., two 'find best implementations' tools, two comparison tools), suggesting the surface could be consolidated rather than each tool earning its place.

    Completeness4/5

    The surface covers code memory CRUD (store, recall, evolve, forget, link, related, stats), research chain lifecycle, GitHub search/retrieval, local code understanding, and implementation discovery. Minor gaps like local full-text code search or exact-ID memory retrieval are workable, but not fatal.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      AI-powered code assistant that provides advanced search and discovery capabilities across GitHub and NPM ecosystems, helping users understand code patterns, implementations, and connections between repositories.
      13
      966
      TypeScript
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides code repository indexing and semantic search capabilities, allowing natural language queries to find relevant code snippets with automatic incremental indexing and multi-language support.
      1
      361
      ISC
    • A
      license
      Not graded
      quality
      C
      maintenance
      AST-aware semantic code search engine for AI agents, enabling code retrieval by intent with call-graph context and optional LLM enrichment.
      60 PyPI
      2
      MIT