MCP Server for vectorized technical notes repository using SQLite + sqlite-vec
npm install context-whisperMCP Server para repositório de notas técnicas vetorizadas usando SQLite + sqlite-vec.
O context-whisper é um servidor MCP (Model Context Protocol) que fornece um repositório de notas técnicas vetorizadas para projetos de software. Ele utiliza SQLite com a extensão sqlite-vec para realizar buscas por similaridade semântica (KNN) diretamente em SQL, e embeddings locais com @xenova/transformers para gerar vetores de documentos.
- Busca Vetorial Semântica: Busque notas técnicas usando similaridade semântica, não apenas palavras-chave
- Embeddings Locais: Gera embeddings usando modelos locais (MiniLM-L6-v2), sem necessidade de APIs externas
- Rastreabilidade: Links notas técnicas com código-fonte específico (repo, path, símbolos, linhas)
- Workspace/Project Organization: Organize notas por workspace e projeto
- Tags e Status: Categorize notas com tags e controle de revisão (DRAFT/APPROVED)
- Auto-detecção de Contexto: Detecta automaticamente workspace/project do Git, configuração ou estrutura de pastas
- Rastreabilidade de Repositório: Armazena informações do repositório (URL, fingerprint, provider, owner) para melhor organização
``bash`
npm install
npm run build
`bash`
npx context-whisper
`bash`
npm run dev
- --db : Caminho para o arquivo SQLite (padrão: ~/.local/share/context-whisper/meta.sqlite no Linux)--vec-lib
- : Caminho para a extensão sqlite-vec
- CONTEXT_WHISPER_DB_PATH: Caminho do banco de dadosCONTEXT_WHISPER_VEC_LIB
- : Caminho da extensão sqlite-vec
O sqlite-vec é essencial para a funcionalidade RAG (Retrieval-Augmented Generation) e está incluído como dependência. O binário correto para sua plataforma será instalado automaticamente via npm:
`bash`
npm install
O servidor detectará automaticamente o binário (vec0.so no Linux, vec0.dylib no macOS, vec0.dll no Windows) em node_modules/sqlite-vec-.
Detecção automática:
O servidor procura a extensão automaticamente em:
1. node_modules/sqlite-vec- (se instalado via npm)/usr/local/lib/sqlite3/vector0
2. Paths comuns do sistema:
-
-
-
-
-
Especificar caminho manualmente (se necessário):
Use --vec-lib ou CONTEXT_WHISPER_VEC_LIB se a detecção automática falhar.
Cria ou atualiza uma nota técnica vetorizada.
Payload:
`json`
{
"repo_url": "https://github.com/workspace/project",
"topic": "autenticacao",
"subtopic": "jwt",
"tags": ["backend", "seguranca", "auth"],
"body_md": "## Decisão\nImplementado JWT com refresh token...",
"created_by": "John Doe (claude-sonnet)",
"review_status": "DRAFT",
"links": [
{
"repo": "softec-app",
"path": "src/auth/jwt.ts",
"line_start": 5,
"line_end": 120,
"commit_sha": "abc123"
}
]
}
Nota:
- repo_url é obrigatório e deve ser obtido via git config --get remote.origin.url no diretório do projetoworkspace
- e project são derivados automaticamente da URLcreated_by
- deve ser preenchido no formato: "git_user_name (agent_name)" - ex: "John Doe (claude-sonnet)"
Recupera uma nota específica do repositório.
Payload:
`json`
{
"repo_url": "https://github.com/workspace/project",
"topic": "autenticacao",
"subtopic": "jwt"
}
Nota: repo_url é obrigatório.
Busca notas usando similaridade semântica vetorial. Busca global se repo_url não for especificado.
Payload:
`json`
{
"query": "refresh token expiração",
"top_k": 5,
"tags": ["backend"],
"review_status": "APPROVED",
"repo_url": "https://github.com/workspace/project"
}
Nota: repo_url é opcional - se não fornecido, busca em todos os repositórios.
Lista todos os tópicos disponíveis para um repositório.
Payload:
`json`
{
"repo_url": "https://github.com/workspace/project"
}
Nota: repo_url é obrigatório.
Remove uma nota e todos os dados associados.
Payload:
`json`
{
"repo_url": "https://github.com/workspace/project",
"topic": "autenticacao",
"subtopic": "jwt"
}
Nota: repo_url é obrigatório.
Verifica o status do banco de dados e extensão sqlite-vec.
Payload: {}
O banco de dados SQLite contém:
- notes: Tabela principal com notas técnicas
- note_links: Links para código-fonte relacionado
- note_vectors: Tabela virtual com embeddings (384 dimensões)
O sistema inclui uma mensagem de sistema que orienta agentes a:
1. Usar upsert_note para documentação técnica em vez de criar arquivos .md
2. Consultar antes de analisar código para entender decisões técnicasrepo_url
3. Fornecer em todas as operações (obter via git config --get remote.origin.url)
4. Workspace/project são derivados automaticamente da repo_url fornecida
- better-sqlite3: Cliente SQLite para Node.js@xenova/transformers
- : Embeddings locaissqlite-vec
- : Extensão SQLite para busca vetorial (deve ser instalada separadamente)@modelcontextprotocol/sdk
- : SDK do MCPzod
- : Validação de schemascommander
- : CLI parsing
`bashInstalar dependências
npm install
MIT