forgemcp
Provides tools for searching GitHub repositories and code, retrieving repository overviews, files, and trees, enabling code discovery and intelligence.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@forgemcp find the best retry with backoff implementation"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
π₯ GeniusMCP
Quality-aware code intelligence that turns GitHub search into ranked, explainable, import-ready recommendations.
Not another grep. An intelligence layer.
Quick Start Β· How It Works Β· Soul Β· Tools Β· 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.83That'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 |
|
π¦ Signature Compression | Repomix-style 70% token reduction β strips bodies, keeps signatures |
π Dynamic Discovery |
|
π 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_tokenAdd 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 signalsImport 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 commentCompare 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 signalsRemember 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 neededExplore unfamiliar repository
You: "How does Hono handle errors?"
Agent calls: research.archaeology("honojs/hono", "error handling")
β Found .onError() handler, JWT error middleware, 29K stars, TypeScriptRead 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"| QThe 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 |
| Find best implementations with archetype clustering, quality scoring, coverage report |
| Full signal breakdown: why this ranked #1 |
| Head-to-head comparison with bucket deltas |
| Policy-aware import with provenance manifest |
π§ Memory (compound intelligence)
Tool | Description |
| Search past patterns by concept |
| Save pattern to persistent memory |
| Create improved version linked to parent |
| Find connected patterns |
| Create relationships between patterns |
| Memory size, coverage, confidence distribution |
| Remove outdated patterns |
π§ Code Navigation (1 call = 10 Read/Greps)
Tool | Description |
| Jump to symbol with full context: callers, callees, deps |
| Instant project architecture map |
| Call chain between functions |
| Compressed module understanding |
| All exports with signatures |
π¬ Research (persistent reasoning chains)
Tool | Description |
| Trace code evolution |
| Structured comparison with metrics |
| Begin research thread |
| Record reasoning step |
| Mark chain completed |
| Search past research |
π GitHub
Tool | Description |
| Search by query, language, stars |
| Code search across GitHub |
| Stars, CI, license, health |
| Get file content |
| 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
Evidence, not opinions β every score has signals you can inspect
Local-first β works offline for indexed repos
Zero ML in core β lexical + structural, semantic is opt-in
Provenance always β every import traced to source + license
Progressive learning β every search enriches the evidence graph
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.
Available Tools
30 toolscode.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.linkC
Create a relationship between two patterns
Inputs: toId (required), fromId (required), relation (required).
memory.recallC
Search code memory for patterns, solutions, and insights from past sessions
Inputs: query (required), limit, language, minConfidence.
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
Scored across 30 tools
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.
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.
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.
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
Related MCP Connectors
Code intelligence for coding agents: semantic, AST, graph, and full-text search. 279+ languages.
Code intelligence platform for AI agents. 20 tools for architecture, security & impact analysis.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Capability-matched AI coding tool recommendations from a hand-checked catalog of 470 tools
Related MCP Servers
- AlicenseAqualityDmaintenanceAI-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.13966TypeScriptMIT
- AlicenseAqualityDmaintenanceProvides code repository indexing and semantic search capabilities, allowing natural language queries to find relevant code snippets with automatic incremental indexing and multi-language support.1361ISC
- AlicenseNot gradedqualityDmaintenanceEnables searching and retrieving knowledge extracted from GitHub PR reviews to help developers avoid repeating mistakes.MIT
- AlicenseNot gradedqualityCmaintenanceAST-aware semantic code search engine for AI agents, enabling code retrieval by intent with call-graph context and optional LLM enrichment.60 PyPI2MIT