AmanMCP

Local RAG for your codebase. Zero config. Privacy-first.

---

Alpha Software - Use at your own risk. Full disclaimer

---

Quick Start

Prerequisite: Ollama installed (brew install ollama)

# Install
brew tap Aman-CERP/amanmcp && brew install --cask amanmcp

# Initialize (auto-starts Ollama, pulls model, indexes)
cd your-project && amanmcp init

# Restart Claude Code. Done.

Ask Claude: "Search my codebase for authentication"

---

What It Does

flowchart LR
    subgraph Local["Your Machine (100% Local)"]
        Code[(Codebase)]
        AmanMCP["AmanMCP<br/>BM25 + Vector"]
    end

    Claude["Claude AI"]

    Code -->|index| AmanMCP
    Claude <-->|query| AmanMCP
    AmanMCP -->|context| Claude

    style Local fill:#d5f4e6,color:#000
    style AmanMCP fill:#27ae60,color:#fff
    style Claude fill:#3498db,color:#fff

Key features: Hybrid search (BM25 + semantic) | AST-aware chunking | AmanGraph relationship overlay | PDF text extraction | explicit language-support tiers | < 100ms queries

---

Essential Commands

| Command | Description | |---------|-------------| | amanmcp init | Initialize project | | amanmcp index [path] | Build search indexes and AmanGraph | | amanmcp search "query" | Search codebase | | amanmcp doctor | Troubleshoot issues | | amanmcp status | Check index health |

Full command reference →

---

What Claude Can Do

When connected via MCP, Claude has these tools:

| Tool | Purpose | |------|---------| | search | Hybrid search across codebase | | search_code | Find functions, classes, types | | search_docs | Search documentation |

The structured SDK-registered MCP tools are the canonical integration path. The legacy in-process Server.CallTool markdown wrapper remains available for older tests and compatibility callers, but it is deprecated and targeted for removal after v1.0.0.

Try: "Find the function that handles database connections"

---

Documentation

| I want to... | Go here | |--------------|---------| | Get started step-by-step | Quick Start Guide | | See all CLI commands | Command Reference | | Configure settings | Configuration | | Use MLX (Apple Silicon) | MLX Setup | | Understand how search works | Hybrid Search Guide | | Contribute code | Contributing |

Explore the Documentation

Browse our comprehensive documentation organized by topic. Each category highlights key documents to help you quickly find what you need.

---

Articles - Deep Dives & Insights

| Document | Topic | Problem/Question | Key Insight | |----------|-------|------------------|-------------| | AI Engineering Guide | Learning Roadmap | How to learn AI/ML engineering efficiently? | 80/20 approach - focus on fundamentals that transfer across tools | | AI-Native Project Management | Human-AI Collaboration | How to manage projects when AI does most coding? | Human Director / AI Executor model with context management and session workflows | | AI-Native Documentation Lessons | Documentation Strategy | How to prevent documentation sprawl? | Internal docs can accumulate faster than they're useful - consolidation strategies matter | | Black Box Architecture Case Study | Modular Design | How to build systems that remain maintainable at scale? | Eskil Steenberg's principles - stable interfaces + hidden complexity = decades of durability | | Claude Code Search vs AmanMCP Benchmark | Tool Comparison | When to use built-in tools vs specialized search? | Tools are complementary, not competing - each has strengths | | Debugging MCP Protocol | Protocol Debugging | Why does MCP integration fail mysteriously? | Stdout contamination breaks protocol - MCP uses stdio for communication | | Smaller Models, Better Search | Model Selection | How to choose embedding models under resource constraints? | 0.6B models can outperform 8B for specific tasks through quality-focused tuning | | Static Embeddings Explained | Fallback Patterns | When should you use static vs dynamic embeddings? | Zero-dependency embeddings enable instant startup and graceful degradation | | Zero Friction Lessons | Developer UX | How to achieve "it just works" philosophy? | Every manual step is a leaky abstraction - auto-detection beats configuration |

→ Articles documentation overview

---

Concepts - Core Ideas & Theory

| Document | Topic | Problem/Question | Key Insight | |----------|-------|------------------|-------------| | Hybrid Search | Search Fundamentals | Why combine keyword and semantic search? | BM25 finds exact matches, vectors find meaning - fusion gets both strengths | | MCP Protocol | AI Integration | How does AmanMCP talk to Claude? | Model Context Protocol enables structured AI-tool communication via JSON-RPC | | Indexing Pipeline | Content Processing | What gets indexed, and how? | Code uses parser-backed chunks, markdown uses section chunks, and PDFs use page-aware text extraction | | Language Support Tiers | Language Support | Which languages are parser-backed vs fallback? | Results expose language_support_tier so parser support is explicit | | Tree-sitter Guide | Code Parsing | How to parse code with parser-backed chunking? | Tier 1 languages use AST-aware chunking; fallback languages use line chunks | | Two-Stage Retrieval | Search Optimization | Why search twice instead of once? | Fast filter (candidates) then precise ranking balances speed and accuracy | | Vector Search Concepts | Semantic Search | How does semantic search actually work? | Embeddings turn text into numbers that capture meaning geometrically |

→ Concepts documentation overview

---

Guides - Step-by-Step Instructions

| Document | Topic | Problem/Question | Key Insight | |----------|-------|------------------|-------------| | First-Time User Guide | Getting Started | How do I set up AmanMCP from scratch? | Five steps: install Ollama, install AmanMCP, init project, restart Claude, query | | Homebrew Setup Guide | Installation | How to install via Homebrew on macOS? | Homebrew provides automatic updates and dependency management | | MLX Setup | Performance | How to get faster embeddings on Apple Silicon? | MLX can be 16x faster than Ollama for local embedding generation | | Backend Switching | Configuration | How to switch between Ollama and MLX embeddings? | Simple config change enables comparing backends for your workload | | Auto-Reindexing | Workflow | How to keep search index in sync with code changes? | File watching enables real-time incremental updates without manual reindexing | | Thermal Management | Optimization | How to reduce CPU heat during indexing? | CPU temperature optimization through batch sizing and concurrency tuning |

→ Guides documentation overview

---

Research - Investigations & Decisions

| Document | Topic | Problem/Question | Key Insight | |----------|-------|------------------|-------------| | Search Quality Improvement Series | Synthesis | How to solve vocabulary mismatch comprehensively? | Contextual retrieval for vectors + query expansion for BM25 improved pass rate from 60% to 92% | | Contextual Retrieval Decision | Search Enhancement | How to bridge vocabulary mismatch between queries and code? | Prepend LLM-generated context to chunks before embedding with pattern fallback | | Contextual Retrieval Regression | Quality Analysis | How can enhancements cause regressions? | Small embedding models + contextual prefixes can cluster in embedding space | | Query Expansion Asymmetric | Query Processing | Should we expand queries for all search backends? | Expand for BM25 only - expansion helps keyword search but dilutes embeddings | | RRF Fusion Rationale | Search Fusion | How to combine BM25 and vector search results? | Reciprocal Rank Fusion (k=60) provides simple, effective combination without training | | Vocabulary Mismatch Analysis | Search Quality | Why does semantic search fail for code? | Users say "search function", code says func Search - root cause of 40% of failures | | Dogfooding Methodology | Quality Validation | How to validate RAG search quality? | Tiered query system with 5 Whys root cause analysis catches semantic gaps | | Embedding Models | Model Selection | Which embedding model for code search? | qwen3-0.6b balances quality and resources; code-specialized models improve retrieval 7-8% | | Embedding Backend Evolution | Backend Choice | Which embedding backend by default? | Ollama default (lower RAM), MLX opt-in (16x faster) - RAM matters more for development | | Embedding Optimization | Performance | How to optimize embedding performance? | MLX vs TEI benchmarking reveals batch size tuning and GPU utilization patterns | | Embedding Model Evolution | Evolution | How did our embedding choice evolve? | nomic → Hugot → Qwen3 - each transition taught lessons about tradeoffs | | SQLite vs Bleve | Storage Backend | Which BM25 backend for concurrent access? | SQLite FTS5 enables concurrent access (WAL mode) - pure Go, production-proven | | Vector Database Selection | Vector Storage | Which vector database for local-first? | USearch → coder/hnsw - pure Go, scales to 300K+ vectors | | Specialization vs Generalization | Model Strategy | Should we use specialized or general models? | Specialized models excel in domain but general models provide better fallback | | Tree-sitter Chunking | Code Parsing | How to chunk code intelligently? | AST-aware boundaries preserve semantic units - CGO required but worth it | | MLX Migration Case Study | Performance Migration | How to plan and execute performance migrations? | Validate before implementing, always have fal