kxCAUTION
Local-first MCP server and CLI for AI coding agents. Hybrid semantic + BM25 search across code, docs and notes, with SQLite and offline embeddings.
Overview
From the repository's own README, as read at the audited commit. Badges and raw HTML are left out.
Local hybrid search for AI coding agents: turn your code, documentation, and notes into searchable project context.
[](https://github.com/distu/kx/actions/workflows/ci.yml) [](LICENSE) [](#connect-your-ai-agent)
kx is a local-first Model Context Protocol (MCP) server and CLI for semantic and keyword search across software projects. It combines embedding-based retrieval with BM25 full-text search, so AI agents can find both architectural concepts and exact identifiers before writing code.
Use it with Claude Code, Codex, Cursor, or another stdio MCP client, or search directly from your terminal. Retrieval runs on your machine using SQLite, sqlite-vec, FTS5, and Transformers.js. No hosted vector database, cloud inference API, or API key is required. The embedding model downloads on first use; indexing and search can then run offline with the model cached.
If you are building an AI coding workflow, a local retrieval-augmented generation (RAG) pipeline, or a searchable developer knowledge base, kx provides the retrieval layer. Your agent chooses when to call it and how to use the returned context.
Quick start · MCP setup · CLI · Contributing
Why kx?
- Hybrid retrieval: semantic search finds related ideas; BM25 finds class names, configuration keys, and error messages. Reciprocal Rank Fusion (RRF) merges the rankings.
- Local project context: search Markdown docs, source code, configuration files, and personal notes without uploading the indexed corpus to a search service.
- Separate project indexes: each project defines its own sources and SQLite database in
.kx.json. Optional per-call MCP identity checks help prevent accidental cross-proj
3fbbaef16496OBSERVED · 2026-10-10Connect
Built from this server's own package name, version and transport as found in its source — not copied from anyone's documentation, so it cannot drift against a page we do not control. Replace the environment placeholders with a token scoped to the least it needs.
claude mcp add kx --env KX_COCKPIT_TOKEN=${KX_COCKPIT_TOKEN} -- npx -y [email protected]{
"mcpServers": {
"kx": {
"command": "npx",
"args": [
"-y",
"[email protected]"
],
"env": {
"KX_COCKPIT_TOKEN": "${KX_COCKPIT_TOKEN}"
}
}
}
}Exposed tools (9)
7 read · 2 write · 0 destructive.
| Tool | Risk | Description |
|---|---|---|
ingest | read | Indexa um arquivo específico no banco vetorial |
megabrain_add | write | KX activity manager: cria uma atividade NOVA em .vault/megabrain/ e sincroniza o MOC-Atividades.md. Use quando o usuário pedir para registrar/adicionar/catalogar uma atividade ou task nova. Escopo do projeto atual (isolado por .kx.json; nunca cruza projeto). |
megabrain_artifact_link | read | KX artifact registry: vincula um artefato ja registrado a uma atividade — usado quando o artefato caiu em |
megabrain_artifacts | read | KX artifact registry: lista os artefatos web publicados no projeto (link, versao atual, do que trata e a atividade de origem), mais recentes primeiro. Use quando o usuario perguntar |
megabrain_get | read | KX activity manager: retorna o conteúdo completo (.md) de uma atividade pelo slug ou pelo ID numerico exibido em megabrain_status. Escopo do projeto atual. |
megabrain_status | read | KX activity manager: painel de status das atividades do projeto — últimas N (padrão 20), status de cada uma e |
megabrain_update | write | KX activity manager: atualiza uma atividade existente — avanço (entra no Log de Progresso), bloqueio (Erros e Bloqueios + status=bloqueado), ou conclusão (status=concluida + move no MOC). Use quando o usuário relatar avanço/erro/conclusão de uma atividade. Escopo do projeto atual. |
reindex | read | Reindexação completa ou incremental de todo o projeto |
status | read | Estatísticas do índice: total de documentos, chunks e distribuição por tipo |
Trust audit
CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.
| Layer | What it checks | Result |
|---|---|---|
| L0 | Provenance & inventory | PASS |
| L1 | Static analysis of the code | WARN |
| L2 | Instruction surface (what it tells the agent) | PASS |
| L3 | Class-specific surface | PASS |
| L4 | Behavioural (sandbox) | SKIPPED |
What the source does
- Filesystem
- none-observed
- Network
- declared (2 observation(s))
- Shell
- declared (1 observation(s))
- Dependencies
- not all pinned
- Secrets in source
- none-found
Findings (7)
var base = "http://127.0.0.1:7717"
if ! "$NODE" -e "require('http').get('http://127.0.0.1:7717/health',r=>process.exit(r.statusCode===200?0:1)).on('error',()=>process.exit(1))" 2>/dev/null; thenreturn createHash('sha1').update(content).digest('hex');| | http://127.0.0.1:7717 |
- Base URL: `http://127.0.0.1:7717`
Health: curl -s http://127.0.0.1:7717/health
@huggingface/transformers, @modelcontextprotocol/sdk, better-sqlite3, chokidar, commander, glob, minimatch, sqlite-vec
Gates applied: no_behavioural_pass.
3fbbaef16496full audit observations/trust-audit/mcp-server/distu__kx.json · Report an issue / request a re-scanAudit history
Every audit this server has had. A grade with a past is a grade somebody is still checking.
| Date | Source | Verdict | Grade | Score | Change |
|---|---|---|---|---|---|
| 2026-10-10 | 3fbbaef16496 | CAUTION | B | 89 | first audit |
Questions
What is the kx MCP server?
Local-first MCP server and CLI for AI coding agents. Hybrid semantic + BM25 search across code, docs and notes, with SQLite and offline embeddings.
What tools does kx expose?
9 in total: 7 read-only, 2 that write, and 0 that can delete or overwrite. Every one is listed on this page with its risk.
Is kx safe to connect to an agent?
With care. The audit graded it B (89/100) and found 7 things worth knowing before you trust this server, listed below with the exact line each was found on.
What credentials does kx need?
It reads KX_COCKPIT_TOKEN from the environment. Give it a token scoped to the least it needs — an agent that can be talked into calling a tool can be talked into calling it with your credentials.
How does kx run?
It speaks stdio, so it runs as a local process your client starts. It is published on npm as kx at 1.2.0.
How current is this page?
The grade is for one exact copy of the source (3fbbaef16496), read on 2026-10-10. The repository is watched and re-audited when it changes.