Servidor MCP
namidb-mcp es un servidor local de
Model Context Protocol. Habla MCP sobre
stdio, así que un cliente MCP (Claude Desktop, Claude Code y otros) lo lanza
como subproceso y llama a sus herramientas. Todas las herramientas son de
solo lectura; la herramienta cypher rechaza las sentencias de
escritura.
Se distribuye en el archivo del release namidb-v3.3.0-<target> junto a la
CLI, o se compila con cargo install --locked --path crates/namidb-mcp.
Ejecutarlo
namidb-mcp [--store <URI>] [--vault <DIR>] [--placeholders] [--watch]| Flag | Por defecto | Efecto |
|---|---|---|
--store <URI> | memory://mcp | Namespace a servir. Cualquier URI de almacenamiento. |
--vault <DIR> | ninguno | Carga un vault de Markdown en el namespace antes de servir (mismo mapeo que namidb load-vault). |
--placeholders | desactivado | Con --vault, crea notas stub para los links a notas inexistentes. |
--watch | desactivado | Con --vault, mantiene el grafo sincronizado con la carpeta mientras sirve. |
Dos configuraciones comunes:
# Load a vault into memory on startup and keep it live:namidb-mcp --vault ./my-vault --watch
# Serve a namespace you loaded earlier with `namidb load-vault --embed`:namidb-mcp --store "file:///var/lib/namidb?ns=vault"Registrarlo en un cliente
Agrégalo a la configuración de servidores MCP del cliente, por ejemplo:
{ "mcpServers": { "namidb": { "command": "/usr/local/bin/namidb-mcp", "args": ["--store", "file:///var/lib/namidb?ns=vault"] } }}Usa una ruta absoluta al binario; los clientes suelen iniciar los servidores
con un PATH mínimo.
Herramientas
Las herramientas de notas y tags asumen el esquema del vault: nodos
:Note, nodos :Tag y relaciones :LINKS_TO, :EMBEDS, :TAGGED y
:SUBTAG_OF.
| Herramienta | Argumentos | Retorna |
|---|---|---|
list_notes | — | El título y la ruta de cada nota (hasta 500). |
get_note | note | El título, la ruta y el cuerpo Markdown completo de una nota. |
backlinks | note | Las notas que enlazan o embeben la nota. |
neighbors | note, hops (por defecto 1, máx. 5) | Las notas a N saltos o menos, sin dirección, por links o embeds. |
orphans | — | Las notas sin links ni embeds de entrada o salida. |
search | text | Las notas cuyo título o cuerpo contiene el substring (distingue mayúsculas, hasta 100). |
list_tags | — | Todos los tags (hasta 500). |
notes_by_tag | tag | Las notas con el tag o con cualquier tag anidado debajo de él. |
subtags | tag | Los tags hijos inmediatos en el árbol de tags anidados. |
tags_of | note | Los tags de una nota. |
vector_search | query, k, label, property, where | Notas ordenadas por similitud semántica; la consulta se convierte en embedding con el modelo usado al cargar. |
hybrid_search | query, k, label, property, lexical_weight, semantic_weight, where | Resultados por palabra clave y semánticos fusionados con Reciprocal Rank Fusion. |
graph_algorithm | algorithm, label, edge_types, k, damping, max_iterations, source, target | Ejecuta wcc, scc, pagerank, degree, betweenness, triangle_count, label_propagation, louvain o shortest_path sobre el subgrafo de un label. |
cypher | query | Cualquier sentencia Cypher de solo lectura. |
Los nombres de notas se comparan de forma flexible: se ignoran las
diferencias de mayúsculas y de - / _ / espacios, y un título o una ruta
funcionan igual que el nombre del archivo.
vector_search y hybrid_search necesitan embeddings de las notas. Un
vault cargado con --vault los obtiene automáticamente; para un namespace
servido con --store, cárgalo con namidb load-vault --embed (consulta
CLI). La consulta se convierte en
embedding con el mismo embedder, así que usa la misma configuración de
embedder para cargar y para servir.
Probarlo a mano
MCP es JSON-RPC delimitado por saltos de línea sobre stdin/stdout, así que puedes probar el servidor sin un cliente:
printf '%s\n' \ '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \ '{"jsonrpc":"2.0","method":"notifications/initialized"}' \ '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"backlinks","arguments":{"note":"Project X"}}}' \ | RUST_LOG=error namidb-mcp --vault ./my-vault{"id":1,"jsonrpc":"2.0","result":{"capabilities":{"tools":{}},"protocolVersion":"2024-11-05","serverInfo":{"name":"namidb-mcp","version":"3.3.0"}}}{"id":2,"jsonrpc":"2.0","result":{"content":[{"text":"[\n {\n \"path\": \"sub/Idea.md\",\n \"title\": \"Idea\"\n }\n]","type":"text"}],"isError":false}}