# Locus

> Local BM25 search for agents. Ranked chunks, on the machine, with no API key.

Locus is the `@sylphx/locus` MCP server from [SylphxAI/locus](https://github.com/SylphxAI/locus). You name the repository. It ranks code chunks with BM25. This path does not call an embedding API.

## Documentation

- What is Locus?: https://sylphxai.github.io/locus/guide/getting-started
- Installation: https://sylphxai.github.io/locus/guide/installation
- Quickstart: https://sylphxai.github.io/locus/guide/quickstart
- How Search Works: https://sylphxai.github.io/locus/guide/how-search-works
- Symbol chunks: https://sylphxai.github.io/locus/guide/ast-chunking
- BM25: https://sylphxai.github.io/locus/guide/tfidf
- Language Support: https://sylphxai.github.io/locus/guide/languages
- Vision: https://sylphxai.github.io/locus/vision
- Capabilities: https://sylphxai.github.io/locus/capabilities

## MCP Server

- Overview: https://sylphxai.github.io/locus/mcp/overview
- Installation: https://sylphxai.github.io/locus/mcp/installation
- Configuration: https://sylphxai.github.io/locus/mcp/configuration
- Tools: https://sylphxai.github.io/locus/mcp/tools
- IDE Integration: https://sylphxai.github.io/locus/mcp/ide-integration
- Defaults: https://sylphxai.github.io/locus/reference/defaults
- Tool arguments: https://sylphxai.github.io/locus/reference/tools

## Behavior

### Explicit root

Pass an absolute `--root`. Locus does not default to the current working directory. Root order is the tool argument, then launch `--root`, then `LOCUS_ROOT`, then `CODERAG_ROOT`.

### Lexical ranking

`codebase_search` scores chunks with BM25 (`k1` 1.2, `b` 0.75). Tokens are ASCII letters, digits, and underscore, longer than one character. `login` does not match `authenticate`.

### Filters before the limit

`file_extensions`, `path_filter`, and `exclude_paths` choose which chunks compete. `limit` cuts that list. The default limit is 10, and the maximum is 100.

### Symbol chunks

Chunks come from line-start regular expressions, not a syntax tree. If nothing matches, the file is one chunk.

### Related code

`find_related` starts from a repository-relative path and a line you already trust.

## Indexed files

Extensions: `.ts` `.tsx` `.js` `.jsx` `.mjs` `.cjs` `.rs` `.md` `.py` `.go`.

Skipped directory segments: `node_modules`, `dist`, `target`, `.git`. Files larger than 1 MiB are skipped.

A new index is `.locus/rust-index.json` and `.locus/file-hashes.json`. `.coderag/` is read only when `.locus/rust-index.json` is absent.

## Quick start

```bash
npx -y @sylphx/locus --root=/absolute/path/to/project
```

Codex:

```bash
codex mcp add locus -- npx -y @sylphx/locus --root=/absolute/path/to/project
```

```json
{
  "query": "authenticate request",
  "limit": 5,
  "file_extensions": ["ts"],
  "exclude_paths": ["src/legacy"]
}
```

## Links

- GitHub: https://github.com/SylphxAI/locus
- npm: https://www.npmjs.com/package/@sylphx/locus
- Documentation: https://sylphxai.github.io/locus/
