convez.ai
MCP ServerBusca & PesquisaIntermediário
SuarezPM

Apohara CodeSearch

SuarezPM/apohara-codesearch

Busca de código offline em um binário — sem modelo, sem BD, puro hash

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP em Rust que oferece busca híbrida de código totalmente offline, sem modelo de IA, sem banco de dados externo. Executa como um único binário, indexa em SQLite e fornece resultados estruturados (assinaturas, importações, exportações) para Rust, TypeScript, Python e Go.

Instalação

$npx convez-ai SuarezPM/apohara-codesearch

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
85%
Último commit
há 2 meses
Versão
v0.3.0
Issues abertas
20
Contribuidores
2

Casos de uso

  • Encontrar definições e referências de funções em grandes repositórios
  • Integrar busca estruturada em agentes de código IA
  • Ambiente air-gapped ou sem acesso à internet durante desenvolvimento

Veredito

Ferramenta sólida e minimalista para busca offline de código. Ideal para integração com agentes Claude quando privacidade e velocidade são críticas; trade-off é que a busca semântica fica limitada ao hash determinístico em vez de embedding.

README

A tradução para o português deste README ainda está na fila.

apohara-codesearch

Hybrid code search for your coding agent — one offline binary, no model, no database.

CI License Rust crates.io npm MCP

OpenSSF Scorecard OpenSSF Best Practices

Quick Start · Features · Where it fits · How it works

Latest release: v0.2.0 — 2026-06-07 — published to crates.io and npm; SLSA Build L3 provenance on every artifact.

A single Rust binary that runs as a Model Context Protocol server, giving a coding agent fast, fully-offline hybrid search over any local repository — no embedding model to download, no external vector or graph database. It installs in seconds, runs air-gapped in a few megabytes of RAM, and keeps its entire state in one SQLite file.


# Your agent calls the search_code MCP tool:
search_code(path=".", query="where does the runtime block on a future?")

# → top hit — a chunk WITH its structure, not just a line number:
{
  "file": "src/runtime/handle.rs",
  "start_line": 241, "end_line": 341,
  "kind": "method",
  "signature": "block_on<F: Future>(&self, future: F) -> F::Output",
  "snippet": "/// Runs a future to completion on this Handle's associated Runtime...",
  "imports": [{ "source": "crate::runtime::task::JoinHandle", "line": 17 }],
  "exports": []
}

Structure (signatures, imports/exports, and struct/enum/class/type symbols) is extracted for Rust, TypeScript, Python, and Go. Any other language is still searchable — indexed as overlapping text windows.


💡 Concept

[!NOTE] A hash, not a model. The dominant code-intelligence tools are heavy: Node plus native bindings, a C/C++ toolchain for some grammars, an embedded graph or vector database, and a learned embedding model that downloads on first run. Their strength is deep understanding; their cost is that they are anything but lightweight.

apohara-codesearch takes the other side of that trade. The embedding is a deterministic blake3 feature-hash, not a learned model — so there is nothing to download, nothing to serve, and the same input always produces the same vector. That makes semantic recall weaker than a model-based tool; we compensate with hybrid retrieval (lexical + vector, fused) rather than pretending the hash is semantic. It is a Claude Code MCP plugin, and works with any MCP client.


✨ Features

🔌 MCP stdio serverTwo tools — search_code (hybrid) and reindex (incremental) — over plain JSON-RPC. Works with Claude Code or any MCP client.
🦀 One static binaryNo Node, no native bindings, no toolchain, no service. cargo install or npx, then run. The only state is one SQLite file.
🧠 Hybrid rankingBM25 (SQLite FTS5) + a feature-hash vector (sqlite-vec), merged with Reciprocal Rank Fusion, then MMR-diversified. Optional adaptive weighting biases the fusion by query shape (opt-in, off by default).
🌳 Structural extractionPer-symbol chunks with signatures + file imports/exports for Rust, TS, Python, Go; everything else indexed as text.
📴 Offline & air-gappedZero network at runtime AND at build. No model fetch, no telemetry, no API keys.
🪶 Near-zero footprint~22 MB resident memory indexing a 224k-LOC repo — flat with repo size (memory-bounded pipeline).
🗂️ Multi-repo awareEach repo keeps its own SQLite index (PRIMARY KEY(repo_id, path)); a sidecar JSON registry tracks the path→index map, with versioned, backward-compatible migrations.
⚡ Incremental + watchreindex does blake3 content-hash deltas; the watch subcommand keeps the index current as files change (a plain CLI loop, not a plugin hook).
🔁 DeterministicSame input ⇒ same vector ⇒ byte-stable recall@k/MRR. Re-indexing is stable.
🔏 Signed releasesEvery release artifact carries a SLSA Build L3 provenance attestation; see SECURITY.md for the threat model.

🚀 Quick Start

Register it with your MCP client. For Claude Code, add to .mcp.json:

{ "mcpServers": { "codesearch": { "command": "npx", "args": ["-y", "@apohara/codesearch-mcp"] } } }

The npx wrapper downloads the matching prebuilt binary for your platform on first run. That is the whole install — no model, no database, no daemon.

# Install from crates.io:
cargo install apohara-codesearch

# Or build + install from a checkout (lowest-trust path):
cargo install --path crates/apohara-codesearch

# Run the binary directly as a stdio MCP server:
apohara-codesearch serve

# Keep the index current as files change (plain CLI loop, NOT a Claude Code hook):
apohara-codesearch watch <path>

Prebuilt, per-OS binaries are also published on Releases (built by cargo-dist). It installs as a Claude Code plugin via the apohara marketplace too.

[!WARNING] Downloading a prebuilt binary is itself a supply-chain surface. Verify the checksum from the Release, or prefer cargo install and build from source.

Every release artifact carries a signed SLSA Build L3 provenance attestation, generated by cargo-dist at build time. Verify it with the GitHub CLI:

gh attestation verify <artifact> --repo SuarezPM/apohara-codesearch

This proves the binary was built by this repo's release workflow on GitHub-hosted runners — a stronger guarantee than a plain checksum, which only proves the file matches what the Release page claims.

Tools

ToolWhat it does
search_codeHybrid BM25 + vector search over a repo path. Lazily indexes on first call. Returns the top-k hits with structural context. Optional knobs: bm25_weight/vector_weight (explicit fusion weights), adaptive (query-shape weighting, off by default), diversify (MMR), boost_imports.
reindexRe-index a repo. Incremental by default (blake3 content-hash deltas); force: true rebuilds from scratch.

🧭 Where it fits

Lighter than the graph tools, structure-aware where ripgrep is text-only. It does not match a model-based tool on conceptual recall, and it does not build a call graph — those are deliberately out of scope.

apohara-codesearchgraph / embedding toolsripgrep
Runtime dependenciesone static binaryNode + native bindings + toolchainone binary
Model downloadnonehundreds of MBnone
External DB / servicenoneembedded graph / vector DBnone
Offline / air-gapped✓usually requires a fetch✓
Structural contextsignatures + imports/exports (4 langs)call graphs, deeptext only
Rankinghybrid BM25 + vector (RRF)learned embeddingsexact / regex

🔬 How it works / honesty

  1. Walk + chunk. A .gitignore-aware walk splits each file into per-symbol chunks (with the symbol's signature attached) plus bounded module-remainder and window chunks, so a giant file never collapses into one diluted chunk.
  2. Index. Each chunk gets a BM25 lexical row (SQLite FTS5) and a feature-hash vector row (sqlite-vec), keyed on a shared row id. Both sides share one identifier tokenizer, so parseString and parse_string match each other.
  3. Search. A query runs through both BM25 and vector k-NN; the two ranked lists are merged with Reciprocal Rank Fusion, diversified with MMR, then the survivors are hydrated with their structural context.
  4. Stay current. Re-indexing hashes each file and reprocesses only what changed, in a single transaction that keeps the three tables consistent.

Footprint at scale

Measured with the default feature-hash embedder on a Ryzen 5 3600 / 48 GB box, driven over the stdio MCP tools:

RepoLOCCold indexPeak RSSWarm queryIndex on disk
tokio174k Rust~10 s~22 MB~18 ms39 MB
hugo224k Go~26 s~24 MB~22 ms54 MB

Peak resident memory is flat across repo size — no OOM, no external process. One SQLite file is the only state.

[!WARNING] The vector is a robustness layer, not a semantic engine. Because the embedding is a feature-hash, a conceptual query that shares no tokens with the target will not surface it — and on a clean corpus where lexical search already wins, fusion can be a slight net negative. BENCHMARK.md publishes this (synthetic corpus + a one-off external comparison on real OSS, with ≥30% committed known-miss queries) rather than hiding it. Deep structural context (callers/callees, call graphs) is out of scope by design. A real local embedding model is an opt-in, user-supplied build feature — never downloaded — so the default install stays zero-dependency. That lever now exists and is measured: the gguf-embed feature runs EmbeddingGemma-300m in pure candle (no native deps) on user-supplied weights, and on CodeSearchNet it flips this picture entirely — the vector arm beats BM25-only and fusion stops being a tax (see BENCHMARK.md, v0.8 section). The default build is unchanged: still the deterministic feature-hash, still zero-model.

See BENCHMARK.md for the method, the reproduce command, and per-mode recall@k / MRR — across BM25-only, vector-only, hybrid, and hybrid+MMR — on a synthetic corpus, real OSS, and the standard CodeSearchNet {NL query → code} slices (Python/Go/TypeScript, env-pointed, never vendored).


🏗️ Repository layout

apohara-codesearch/
├── crates/
│   ├── apohara-indexer/        # the engine (library)
│   │   ├── src/
│   │   │   ├── walker.rs        # .gitignore-aware file walk (skips binary/minified)
│   │   │   ├── parser.rs        # tree-sitter structural extraction (Rust/TS/Python/Go)
│   │   │   ├── chunker.rs       # per-symbol + bounded module/window chunks
│   │   │   ├── tokens.rs        # shared snake/camel identifier tokenizer
│   │   │   ├── embeddings.rs    # deterministic blake3 feature-hash vector (default)
│   │   │   ├── embedder.rs      # pluggable Embedder trait + fallback decision
│   │   │   ├── embedder_gemma.rs # EmbeddingGemma-300m in pure candle (opt-in gguf-embed)
│   │   │   ├── storage.rs       # SQLite: chunks + FTS5 + sqlite-vec (dim-parametrized)
│   │   │   ├── schema.rs        # migrations + embedder refuse-to-mix meta
│   │   │   ├── search.rs        # BM25 + vector + RRF + MMR + adaptive weights + boost
│   │   │   ├── incremental.rs   # blake3-delta reindex in one transaction
│   │   │   └── registry.rs      # multi-repo path→index sidecar JSON registry
│   │   └── tests/              # integration · persistence · rrf_proof · robustness (hostile input)
│   └── apohara-codesearch/     # the MCP server + CLI
│       ├── src/{main,server,watch,dto}.rs
│       └── examples/           # bench-search (in-CI) · bench-external · bench-codesearchnet · bench-csn-identifier
├── fuzz/                        # cargo-fuzz targets (parse_source, chunk_file) — isolated crate
├── npm/                         # @apohara/codesearch-mcp wrapper (downloads the Release binary)
├── docs/                        # ASSURANCE.md (assurance case) · best-practices-silver.md (OpenSSF evidence)
├── .clusterfuzzlite/            # ClusterFuzzLite build (Dockerfile + build.sh) for PR fuzzing
├── .claude-plugin/ + marketplace.json   # Claude Code plugin manifest
├── CONTRIBUTING · CODE_OF_CONDUCT · GOVERNANCE · CHANGELOG · SECURITY · deny.toml
└── .github/
    ├── workflows/              # ci · release (cargo-dist) · codeql · scorecard · cflite_pr
    └── dependabot.yml          # weekly cargo + github-actions updates

🗺️ Roadmap

  • MCP stdio server (search_code + reindex) + watch subcommand
  • Structural extraction for Rust, TypeScript, Python, Go
  • Hybrid retrieval — BM25 + feature-hash vector, RRF + MMR + structural boost
  • Incremental reindex (blake3 content-hash deltas), one SQLite file
  • Honest benchmark — synthetic (in-CI) + external real-OSS, with committed known-miss
  • Large-OSS soak (Rust + Go ≥100k LOC) — flat ~22 MB peak RSS
  • Pluggable Embedder trait (opt-in, default stays zero-model)
  • Real local embedder backend (candle / safetensors, opt-in, user-supplied)
  • Skip generated/minified assets in the walker (DB-bloat hardening)
  • Per-language chunk-cap validation (TypeScript / Python)
  • End-to-end robustness over hostile untrusted input (parser + chunker fuzzed in CI, random/garbage files must not panic the indexer)
  • CodeSearchNet recall@5/MRR benchmark — 4 arms (BM25 / vector / hybrid / hybrid+MMR), env-pointed, never vendored
  • Adaptive query-shape fusion weighting (opt-in, default off)
  • SLSA Build L3 signed provenance on every release artifact (cargo-dist native attestation)
  • Multi-repo schema — composite PRIMARY KEY(repo_id, path) + sidecar JSON registry, versioned backward-compatible migration
  • SECURITY.md threat model + OpenSSF Scorecard workflow
  • Code-trained embedding model — EmbeddingGemma-300m in pure candle (opt-in gguf-embed, user-supplied weights, no native deps, parity 0.99998 vs the official ONNX reference). Measured on CodeSearchNet: the vector arm goes from feature-hash noise (recall@5 0.34/0.005/0.035) to 0.95/0.99/0.885, hybrid now beats BM25-only on all 3 slices, and the adaptive recovery gate (AC4) closes — see BENCHMARK.md. Default build stays zero-model/offline.
  • OpenSSF Best Practices — Silver (#13118); every Passing + Silver criterion mapped to evidence in docs/best-practices-silver.md, with governance (CONTRIBUTING/CODE_OF_CONDUCT/GOVERNANCE/CHANGELOG) + an assurance case
  • Supply-chain / OpenSSF Scorecard hardening — CodeQL SAST (Rust + Actions) · cargo-fuzz targets run via ClusterFuzzLite on PRs · cargo-deny + cargo-audit + Dependabot · all Actions pinned to commit SHAs · least-privilege workflow tokens · branch protection on main · signed crates.io + npm publishing

🔐 Security

Found a vulnerability? Please report it privately via GitHub Security Advisories — see SECURITY.md for the disclosure process, supported versions, and the threat model (what the tool defends and what is deliberately out of scope). The full assurance case (security requirements, trust boundaries, the secure-design argument, and how common weaknesses are countered) is in docs/ASSURANCE.md.

The project holds the OpenSSF Best Practices Silver badge (per-criterion evidence in docs/best-practices-silver.md) and is continuously hardened to the OpenSSF Scorecard:

  • CodeQL static analysis (Rust + GitHub Actions) on every push/PR;
  • cargo-fuzz targets over the untrusted-input parser/chunker, run via ClusterFuzzLite on PRs;
  • cargo-deny (licenses/advisories/sources) + cargo-audit (RUSTSEC) dependency gates + Dependabot;
  • all GitHub Actions pinned to commit SHAs, least-privilege workflow tokens, and branch protection on main;
  • SLSA Build L3 provenance on every release artifact (verify with gh attestation verify), with signed crates.io + npm publishing.

🤝 Contributing

Contributions are welcome. See CONTRIBUTING.md for the build/test/quality gate, coding standards, testing policy, Conventional Commits, and the DCO sign-off. Participation is governed by the CODE_OF_CONDUCT.md (Contributor Covenant 3.0); how the project is run and how it continues is in GOVERNANCE.md; release-by-release changes are in CHANGELOG.md.

  1. Fork the repository.
  2. Create a feature branch (git checkout -b feature/my-change).
  3. Make your change and run the suite: cargo test --workspace (clippy -D warnings + rustfmt --check gate CI).
  4. Open a pull request (sign off your commits with git commit -s).

Unless you state otherwise, any contribution you intentionally submit for inclusion in this work, as defined in the Apache-2.0 license, shall be dual-licensed as below, without any additional terms or conditions.


📄 License

Licensed under either of MIT or Apache-2.0, at your option. See NOTICE for third-party dependency licenses.

Maintained by SuarezPM.

Ver o original no GitHub

Bom para

Relacionados