oss-search MCP server

oss-search

Fast local + federated OSS code search and repo discovery, built for AI agents (MCP) with a CLI twin.

Not recreating the wheel is a superpower. oss-search answers two questions for an agent:

1. Which library already solves this? — multi-signal repo ranking (dependents, centrality, maintenance, security posture), not just star count.
2. Show me real code that does this — sub-50ms regex search over a local hot-set corpus, federated with live backends (GitHub code search, grep.app) for the long tail.

Highlights

• 7 MCP tools (osssearchrepos, osssearchcode, ossrepoprofile, ossrepotree, ossfetchfile, ossfetchdocs, oss_guide) over stdio, plus a byte-identical CLI.
• Local trigram index: pure-Rust positional-trigram engine. Measured p50 ≈ 34ms over a 13,408-file / 100-repo hot-set; incremental reindex touches only changed blobs.
• Hybrid semantic layer: tree-sitter function-level chunking (Rust/Python/JS/TS/Go/C), local embeddings (fastembed, BGE-small), RRF fusion with lexical-first routing — identifier queries never pay model latency.
• Repo discovery ranking: dependents count, dependency-graph PageRank (CSR power iteration), OpenSSF-style maintenance/security signals, awesome-list membership, archived/stale gates — with per-signal contributions inspectable in every result.
• Corpus pipeline: blobless depth-1 clones → BLAKE3 content-addressed zstd store → 3-tier dedup (content / token / MinHash-LSH with exact Jaccard verification) → SPDX license detection.
• Strict agent-facing contract: structured filters, typed pre-execution errors (unknownfield / regexerror / not_indexable) that echo the input and name the correction, declared total/hasMore/partial, ~25KB response cap, never silent degradation.
• Security posture: RE2-class regex only (linear time, ReDoS-immune), file admission gates, output escaping (ANSI/control chars, bidi overrides) — all verified by test.

Install

Two front doors: oss-mcp (MCP server) and oss-cli (CLI twin). Three ways to get them:

1. npm — an oss-search shim that downloads the platform-matched prebuilt binary on first run and caches it under ~/.cache/oss-search/bin/ (override with OSSSEARCHCACHE_DIR):

npx -y oss-search --version

Status (pre-publish): the oss-search npm package and its matching GitHub

release (v0.2.0) are being published now. Until they land, npx will fail

with a 404 on the release asset — use option 2 or 3 below.

2. cargo install from git (requires a Rust toolchain):

cargo install --git https://github.com/sblattj/oss-search oss-mcp
cargo install --git https://github.com/sblattj/oss-search oss-cli

Binaries land in ~/.cargo/bin/.

3. Prebuilt binaries — every release publishes oss-search--.tar.gz plus checksums.txt (sha256) at , for targets aarch64-apple-darwin, x8664-apple-darwin, aarch64-unknown-linux-gnu, x8664-unknown-linux-gnu:

curl -fsSL https://github.com/sblattj/oss-search/releases/latest/download/oss-search-0.2.0-aarch64-apple-darwin.tar.gz | tar xz

From a checkout instead:

cargo build --release
# binaries: target/release/oss-mcp  target/release/oss-cli

Quickstart (CLI)

oss-cli mirrors the 7-tool surface one-to-one (offline stub engine by default; --live switches to the real backends):

# Probe-writing and query-syntax playbook — offline, zero setup
oss-cli guide

# Repo discovery — which wheel exists?
oss-cli search-repos --query "express" --limit 5

# Code search by distinctive idioms (federated; GITHUB_TOKEN unlocks the github backend)
GITHUB_TOKEN=... oss-cli --live search-code --probe "retry_with_backoff" --limit 3

All commands emit the same structured JSON envelope (results, total, hasmore, partial, backendstatus) that the MCP tools return.

Quickstart (MCP)

Shortened. The full README is on GitHub.