{
  "markdown": "<div align=\"center\">\n\n<img src=\"https://raw.githubusercontent.com/Muvon/octocode/master/logo.svg\" width=\"240\" alt=\"Octocode\">\n\n### **Structural Code Intelligence for AI Agents — MCP Server + Knowledge Graph + Semantic Search**\n\n[![CI](https://github.com/Muvon/octocode/actions/workflows/ci.yml/badge.svg)](https://github.com/Muvon/octocode/actions/workflows/ci.yml)\n[![Coverage](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fmuvon%2Foctocode%2Fbadges%2Fcoverage.json&style=flat-square)](https://github.com/Muvon/octocode/actions/workflows/ci.yml)\n[![Crates.io](https://img.shields.io/crates/v/octocode)](https://crates.io/crates/octocode)\n[![GitHub stars](https://img.shields.io/github/stars/Muvon/octocode?style=social)](https://github.com/Muvon/octocode/stargazers)\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Rust](https://img.shields.io/badge/Rust-1.95%2B-orange.svg)](https://www.rust-lang.org)\n[![Release](https://img.shields.io/github/v/release/Muvon/octocode)](https://github.com/Muvon/octocode/releases)\n\n**Give your AI assistant a brain for your codebase.** Octocode transforms your project into a navigable knowledge graph that Claude, Cursor, and other AI agents can search, understand, and navigate.\n\n[🚀 Quick Start](#-quick-start) • [🤖 MCP Integration](#-mcp-server-integration) • [📖 Documentation](#-documentation) • [🌐 Website](https://octocode.muvon.io)\n\n<a href=\"https://glama.ai/mcp/servers/Muvon/octocode\">\n  <img width=\"300\" src=\"https://glama.ai/mcp/servers/Muvon/octocode/badge\" alt=\"Octocode MCP server\" />\n</a>\n\n</div>\n\n---\n\n## 🤖 Built for AI Agents\n\n**The Problem:** AI assistants are blind to your codebase. They can't search your files, understand dependencies, or remember context across sessions.\n\n**The Solution:** Octocode's MCP server gives AI agents:\n- 🔍 **Semantic search** — Find code by meaning, not keywords\n- 🕸️ **Knowledge graph** — Navigate imports, calls, and dependencies\n- 📝 **Code signatures** — View structure without reading entire files\n- 🧭 **LSP precision** — Go-to-definition, find-references, and hover docs via your language server\n\n**Works with:** Claude Desktop • Cursor • Windsurf • Any MCP-compatible AI\n\n\nNow your AI assistant can:\n```\nYou: \"Where is authentication handled?\"\nAI: *searches your codebase* \"Authentication is in src/middleware/auth.rs,\n    which imports jwt.rs for token validation and calls user_store.rs for lookup.\"\n\nYou: \"What files depend on the payment module?\"\nAI: *queries knowledge graph* \"src/api/handlers/payment.rs imports payment/mod.rs,\n    which is also used by src/workers/refund.rs and src/cron/billing.rs\"\n\nYou: \"Find every call site of this function\"\nAI: *uses LSP find-references* \"process_payment() is called from 4 places:\n    checkout.rs:87, refund.rs:134, billing.rs:56, and tests/payment_test.rs:23\"\n```\n\n## 🤔 Why Octocode?\n\n**Standard RAG treats your code as flat text chunks.** It finds similar-sounding snippets but has no idea that `auth_middleware.rs` imports `jwt.rs`, calls `user_store.rs`, and is wired into `router.rs`. Octocode understands *structure*.\n\n```\n# Semantic search finds the right code\noctocode search \"authentication middleware\"\n→ src/middleware/auth.rs — Similarity: 0.9234\n\n# The GraphRAG CLI queries the optional persisted graph\noctocode config --graphrag-enabled true\noctocode index\noctocode graphrag get-relationships --node-id src/middleware/auth.rs\nOutgoing:\n  imports → jwt (src/auth/jwt.rs): token validation logic\n  calls   → user_store (src/db/user_store.rs): user lookup by token\nIncoming:\n  imports ← router (src/router.rs): wires auth into the request pipeline\n```\n\nOctocode uses **tree-sitter AST parsing** to build a live graph of files, symbols, imports, calls, inheritance, and implementations. The MCP `graphrag` tool builds this graph lazily from the current source tree, without an index, embeddings, or an LLM. Optional indexed GraphRAG adds semantic file discovery, descriptions, and broader architectural relationships.\n\n## 🔬 How It Works\n\n```\nCurrent Source → Tree-sitter AST → Live Symbol Graph ──────────────→ MCP `graphrag`\n                                           ↑                              ↑\nIndexed Code → Embeddings + Optional LLM → Persisted File Enrichment ─────┘\n```\n\n1. **Live AST Graph** — tree-sitter extracts file and symbol nodes plus deterministic `contains`, `imports`, `calls`, `extends`, and `implements` relationships directly from current source\n2. **Always-on Graph Navigation** — MCP graph lookup, relationship traversal, path finding, and overview work with `[graphrag].enabled = false`\n3. **Optional Enrichment** — enabling indexed GraphRAG overlays semantic file matches, LLM descriptions, and broader file-level architectural relationships; symbols are never embedded or LLM-generated\n4. **Hybrid Search** — semantic similarity + BM25 full-text search + reranking handles meaning-based code retrieval separately\n5. **MCP Server** — exposes `semantic_search`, `view_signatures`, `graphrag`, and `structural_search` to any MCP-compatible client\n\n## ✨ What Makes It Different\n\n| | Standard RAG | Doc Lookup Tools | **Octocode** |\n|---|---|---|---|\n| **Indexes** | Text chunks | External library docs | Your codebase structure (AST) |\n| **Understands** | Similar text | API specs & usage | Functions, imports, dependencies |\n| **Cross-file** | No | No | Yes — navigates the dependency graph |\n| **Relationships** | No | No | `imports`, `calls`, `implements`, `extends`... |\n| **AI integration** | Varies | MCP | Native MCP server + LSP |\n\n> **Doc tools give AI the manual for libraries you use. Octocode gives AI the blueprint of how you put them together.**\n\n**Built with Rust** for performance. **Local-first** for privacy. **Open source** (Apache 2.0) for transparency.\n\n## 📊 Retrieval Quality\n\nOctocode ships a **reproducible retrieval benchmark** ([`benchmark/`](benchmark/)): 127 curated code-search queries with line-range ground truth, run against octocode's own source (pinned at `b1771ba` so annotations never drift). The numbers below use a **fully local, no-API-key** stack — `jina-embeddings-v2-base-code` via fastembed, **no reranker** — so they are a floor, not a ceiling:\n\n| Config | Hit@5 | Hit@10 | MRR | NDCG@10 | Recall@10 |\n|---|---|---|---|---|---|\n| Dense vector only | 0.598 | 0.717 | 0.485 | 0.528 | 0.671 |\n| Hybrid, default RRF weights (0.7/0.3) | 0.598 | 0.717 | 0.485 | 0.528 | 0.671 |\n| **Hybrid, keyword-tuned (0.3/0.7)** | **0.732** | **0.835** | **0.572** | **0.620** | **0.807** |\n\nTilting RRF fusion toward the BM25/keyword signal — which carries disproportionate weight for code's exact identifiers — lifts **Hit@5 by +22%** and **Recall@10 by +20%** at zero added cost.\n\nThe benchmark also flags what _doesn't_ help here (full 6-variant matrix in [`benchmark/RESULTS.md`](benchmark/RESULTS.md)): a **generic** local cross-encoder reranker (`bge-reranker-base`) actually **regressed** results (Hit@5 0.732 → 0.598) — code retrieval needs a _code-aware_ reranker (e.g. `voyage:rerank-2.5`), not an off-the-shelf one.\n\n```bash\ngit clone https://github.com/Muvon/octocode && cd octocode\ngit worktree add /tmp/corpus b1771ba   # pin the corpus to the ground-truth commit\nCORPUS=/tmp/corpus python3 benchmark/run_matrix.py   # set OCTO_BIN to use a custom binary\n```\n\nSee [benchmark/README.md](benchmark/README.md) for methodology and metric definitions.\n\n## 🚀 Quick Start\n\n### 1. Install\n\n```bash\n# Universal installer (Linux, macOS, Windows)\ncurl -fsSL https://raw.githubusercontent.com/Muvon/octocode/master/install.sh | sh\n\n# macOS with Homebrew\nbrew install muvon/tap/octocode\n```\n\n<details>\n<summary><strong>Other installation methods</strong></summary>\n\n```bash\n# From crates.io\ncargo install octocode\n\n# Or from source (latest)\ncargo install --git https://github.com/Muvon/octocode\n\n# Download binary from releases\n# https://github.com/Muvon/octocode/releases\n```\n\nSee [Installation Guide](INSTALL.md) for platform-specific instructions.\n</details>\n\n### 2. Set Up API Keys\n\n```bash\n# Required: Embedding provider (Voyage AI has a free tier)\nexport VOYAGE_API_KEY=\"your-voyage-api-key\"\n\n# Optional: LLM for commit messages, code review\nexport OPENROUTER_API_KEY=\"your-openrouter-api-key\"\n```\n\n**Get your Voyage API key:** [voyageai.com](https://www.voyageai.com/) (free tier available)\n\n<details>\n<summary><strong>Other embedding providers</strong></summary>\n\nOctocode supports multiple embedding providers:\n\n```bash\n# OpenAI\nexport OPENAI_API_KEY=\"your-key\"\noctocode config --code-embedding-model \"openai:text-embedding-3-small\"\n\n# Jina AI\nexport JINA_API_KEY=\"your-key\"\noctocode config --code-embedding-model \"jina:jina-embeddings-v3\"\n\n# Google\nexport GOOGLE_API_KEY=\"your-key\"\noctocode config --code-embedding-model \"google:text-embedding-005\"\n```\n\nSee [API Keys guide](doc/API_KEYS.md) for all supported providers.\n</details>\n\n### 3. Index Your Codebase\n\n```bash\ncd /your/project\noctocode index\n# → ✓ Indexing complete! 342 of 342 files processed (342 new, 0 unchanged)\n```\n\n### 4. Search Your Code\n\n```bash\n# Natural language search\noctocode search \"authentication middleware\"\n\n# Multi-query for broader results\noctocode search \"auth\" \"middleware\" \"session\"\n\n# Filter by language\noctocode search \"database connection pool\" --lang rust\n\n# Search commit history\noctocode search \"authentication refactor\" --mode commits\n```\n\n### 5. Connect Your AI Assistant\n\nAdd to your MCP client config (Claude Desktop, Cursor, Windsurf):\n\n```json\n{\n  \"mcpServers\": {\n    \"octocode\": {\n      \"command\": \"octocode\",\n      \"args\": [\"mcp\", \"--path\", \"/your/project\"]\n    }\n  }\n}\n```\n\nDone! Your AI assistant now understands your codebase structure.\n\n## 🔌 MCP Server Integration\n\nOctocode includes a **built-in MCP server** that exposes your codebase as tools to AI assistants. This is the primary way to use Octocode — give your AI assistant direct access to search and navigate your code.\n\n### Available Tools\n\n| Tool | What It Does |\n|------|--------------|\n| `semantic_search` | Find code by meaning — \"authentication flow\", \"error handling\", \"database queries\" |\n| `view_signatures` | View file structure — function signatures, class definitions, imports |\n| `graphrag` | Always-on file/symbol graph — search nodes, inspect relationships, and find paths without indexing |\n| `structural_search` | AST pattern matching — find `.unwrap()` calls, `new` instantiations, specific patterns |\n| `lsp_goto_definition` | Jump to a symbol's definition (requires `--with-lsp`) |\n| `lsp_find_references` | Find all usages of a symbol across the workspace (requires `--with-lsp`) |\n| `lsp_hover` | Type info and documentation for a symbol (requires `--with-lsp`) |\n| `lsp_document_symbols` / `lsp_workspace_symbols` / `lsp_completion` | File symbols, workspace-wide symbol search, completions (requires `--with-lsp`) |\n\nEnable the LSP tools by starting the server with your language server:\n\n```bash\noctocode mcp --path /your/project --with-lsp=\"rust-analyzer\"\n```\n\n### Conversational AI Examples\n\nOnce connected, your AI assistant can answer questions about your codebase:\n\n```\nYou: \"Where is user authentication implemented?\"\nAI: *uses semantic_search* \"Found in src/auth/login.rs. The authenticate() function\n    validates credentials against the database, generates a JWT token, and stores\n    the session in Redis.\"\n\nYou: \"What files depend on the payment module?\"\nAI: *uses graphrag* \"src/api/handlers/payment.rs imports payment/mod.rs, which is also\n    used by src/workers/refund.rs and src/cron/billing.rs. The payment module exports\n    process_payment() and validate_transaction() functions.\"\n\nYou: \"Show me all error handling in the API layer\"\nAI: *uses structural_search* \"Found 23 error handling patterns in src/api/:\n    - 15 use Result<T, ApiError> with explicit error types\n    - 8 use .unwrap() (potential panics in handlers/user.rs:42, handlers/auth.rs:87)\n    - 3 use .expect() with custom messages\"\n```\n\n### Quick Setup\n\n**Octomind (Recommended)** — Zero setup, Octocode pre-configured:\n```bash\ncurl -fsSL https://raw.githubusercontent.com/muvon/octomind/master/install.sh | bash\noctomind run developer:rust\n```\n\n**Claude Code (CLI)** — Command-line setup:\n```bash\nclaude mcp add octocode -- octocode mcp --path /path/to/your/project\n```\n\n**Claude Desktop / Cursor / Windsurf** — Add to config:\n```json\n{\n  \"mcpServers\": {\n    \"octocode\": {\n      \"command\": \"octocode\",\n      \"args\": [\"mcp\", \"--path\", \"/path/to/your/project\"]\n    }\n  }\n}\n```\n\n**Config locations:**\n- Claude Desktop: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)\n- Cursor: `~/.cursor/mcp.json` or Settings → MCP Servers\n- Windsurf: Settings → MCP\n\n📖 **[Complete MCP Client Setup Guide](doc/MCP_CLIENTS.md)** — Detailed instructions for 15+ clients including VS Code (Cline/Continue), Zed, Replit, and more.\n\n## 🌐 Supported Languages\n\n16 languages with full tree-sitter AST parsing:\n\n| Language | Extensions | Features |\n|----------|------------|----------|\n| **Rust** | `.rs` | Full AST parsing, pub/use detection, module structure |\n| **Python** | `.py` | Import/class/function extraction, docstring parsing |\n| **TypeScript/JavaScript** | `.ts`, `.tsx`, `.js`, `.jsx` | ES6 imports/exports, type definitions |\n| **Go** | `.go` | Package/import analysis, struct/interface parsing |\n| **PHP** | `.php` | Class/function extraction, namespace support |\n| **C++** | `.cpp`, `.cc`, `.cxx`, `.c++`, `.c`, `.h`, `.hpp`, `.hxx`, `.cppm`, `.ixx`, `.mxx`, `.ccm`, `.cxxm` | Include analysis, class/function extraction, C++20 module support |\n| **Ruby** | `.rb` | Class/module extraction, method definitions |\n| **Elixir** | `.ex`, `.exs` | Module/protocol extraction, function and macro definitions |\n| **Java** | `.java` | Import analysis, class/method extraction |\n| **Swift** | `.swift` | Class/struct/protocol extraction, import analysis |\n| **Svelte** | `.svelte` | Component structure, script/style block extraction |\n| **Lua** | `.lua` | Function and table extraction |\n| **CSS** | `.css` | Rule and selector extraction |\n| **JSON** | `.json` | Structure analysis, key extraction |\n| **Bash** | `.sh`, `.bash` | Function and variable extraction |\n| **Markdown** | `.md` | Document section indexing, header extraction |\n\n## 📚 Documentation\n\n- **[Getting Started](doc/GETTING_STARTED.md)** — First steps and basic workflow\n- **[Installation Guide](INSTALL.md)** — Detailed methods and building from source\n- **[MCP Client Setup](doc/MCP_CLIENTS.md)** — Connect to Claude, Cursor, Windsurf, and 15+ clients\n- **[MCP Integration](doc/MCP_INTEGRATION.md)** — MCP server details and advanced configuration\n- **[Commands Reference](doc/COMMANDS.md)** — Complete CLI reference\n- **[Configuration](doc/CONFIGURATION.md)** — Templates and customization\n- **[API Keys](doc/API_KEYS.md)** — Provider setup guide\n- **[Architecture](doc/ARCHITECTURE.md)** — How it works under the hood\n- **[Contributing](doc/CONTRIBUTING.md)** — Development setup\n\n## 🔒 Privacy & Security\n\n- **🏠 Local-first** — fully local embedding via fastembed (no API key required); cloud providers optional\n- **🔐 Secure** — API keys stored locally, env vars supported\n- **🚫 Respects .gitignore** — Never indexes sensitive files\n- **🛡️ MCP security** — Local-only server, no external network for search\n- **📤 Cloud-safe** — cloud providers receive only the code chunks being embedded; use local models for fully offline indexing\n\n<details>\n<summary><strong>📊 Retrieval Quality Benchmark</strong></summary>\n\nWe measure semantic search quality using a hand-annotated ground truth dataset of 254 queries (127 code + 127 docs) with precise line-range annotations. Each query has 1–3 expected results scored by relevance.\n\nThese numbers use the **full cloud stack** — contextual retrieval, Voyage reranker, RaBitQ quantization — on commit [`b1771ba`](https://github.com/Muvon/octocode/commit/b1771ba) with [benchmark config](benchmark/config.toml). For the fully local baseline and the complete variant matrix, see [Retrieval Quality](#-retrieval-quality) above and [`benchmark/RESULTS.md`](benchmark/RESULTS.md).\n\n<details>\n<summary><strong>Documentation search</strong> (<code>--mode docs</code>) — Hit@10: 0.953, MRR: 0.776</summary>\n\n| Metric | Score |\n|--------|-------|\n| Hit@5 | 0.929 (118/127) |\n| Hit@10 | 0.953 (121/127) |\n| MRR | 0.776 |\n| NDCG@10 | 0.801 |\n| Recall@5 | 0.902 |\n| Recall@10 | 0.921 |\n\n**Missed queries** (6 of 127):\n\n| # | Query | Expected | Got (top 1) |\n|---|-------|----------|-------------|\n| 43 | how to set up MCP proxy for managing multiple repositories | `doc/MCP_INTEGRATION.md:286-311` | `doc/MCP_INTEGRATION.md:286-4` |\n| 51 | what are the prerequisites before using octocode | `doc/GETTING_STARTED.md:6-12` | `doc/CONTRIBUTING.md:7-33` |\n| 59 | what to do when hitting API rate limits | `doc/GETTING_STARTED.md:209-216` | `doc/PERFORMANCE.md:304-356` |\n| 75 | typical performance metrics for small medium and large projects | `doc/PERFORMANCE.md:4-13` | `doc/PERFORMANCE.md:414-14` |\n| 112 | how to install octocode on different operating systems | `INSTALL.md:4-14` | `INSTALL.md:49-70` |\n| 115 | how to fix macOS Gatekeeper blocking the binary | `INSTALL.md:199-206` | `INSTALL.md:198-119` |\n\n</details>\n\n<details>\n<summary><strong>Code search</strong> (<code>--mode code</code>) — Hit@10: 0.992, MRR: 0.895</summary>\n\n| Metric | Score |\n|--------|-------|\n| Hit@5 | 0.992 (126/127) |\n| Hit@10 | 0.992 (126/127) |\n| MRR | 0.895 |\n| NDCG@10 | 0.906 |\n| Recall@5 | 0.962 |\n| Recall@10 | 0.974 |\n\n**Missed queries** (1 of 127):\n\n| # | Query | Expected | Got (top 1) |\n|---|-------|----------|-------------|\n| 105 | how does the system ensure two developers get the same database path | `src/storage.rs:60-83` | `src/mcp/proxy.rs:631-644` |\n\n</details>\n\nMetrics: **Hit@k** (did the answer appear?), **MRR** (how high?), **NDCG@10** (are best results ranked first?), **Recall@k** (how many found?). See [benchmark/](benchmark/) for methodology, scoring script, and the full dataset.\n\n</details>\n\n## 🤝 Community & Support\n\n- ⭐ **Star us on GitHub** — It really helps!\n- 🐛 [Report Issues](https://github.com/Muvon/octocode/issues)\n- 💬 [Discussions](https://github.com/Muvon/octocode/discussions)\n- 📧 [opensource@muvon.io](mailto:opensource@muvon.io)\n- 🌐 [muvon.io](https://muvon.io)\n\n## ⚖️ License\n\nApache License 2.0 — See [LICENSE](LICENSE) for details.\n\n---\n\n<div align=\"center\">\n\n**Built with 🦀 Rust by [Muvon](https://muvon.io) in Hong Kong**\n\n[⭐ Star](https://github.com/Muvon/octocode) • [🍴 Fork](https://github.com/Muvon/octocode/fork) • [📣 Share](https://twitter.com/intent/tweet?text=Octocode%20-%20AI-powered%20code%20intelligence%20with%20built-in%20MCP%20server&url=https://github.com/Muvon/octocode)\n\n</div>\n\n<!-- mcp-name: io.github.Muvon/octocode -->\n",
  "bytes": 18896,
  "sha": "6cd296f7d945742a21ddb7d49c24484ff9232795ba6977950339ace8455cc90f",
  "repo_slug": "muvon/octocode",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_muvon_octocode_26197166/readme"
}