Saltearse al contenido

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]
FlagPor defectoEfecto
--store <URI>memory://mcpNamespace a servir. Cualquier URI de almacenamiento.
--vault <DIR>ningunoCarga un vault de Markdown en el namespace antes de servir (mismo mapeo que namidb load-vault).
--placeholdersdesactivadoCon --vault, crea notas stub para los links a notas inexistentes.
--watchdesactivadoCon --vault, mantiene el grafo sincronizado con la carpeta mientras sirve.

Dos configuraciones comunes:

Ventana de terminal
# 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.

HerramientaArgumentosRetorna
list_notes—El título y la ruta de cada nota (hasta 500).
get_notenoteEl título, la ruta y el cuerpo Markdown completo de una nota.
backlinksnoteLas notas que enlazan o embeben la nota.
neighborsnote, 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.
searchtextLas notas cuyo título o cuerpo contiene el substring (distingue mayúsculas, hasta 100).
list_tags—Todos los tags (hasta 500).
notes_by_tagtagLas notas con el tag o con cualquier tag anidado debajo de él.
subtagstagLos tags hijos inmediatos en el árbol de tags anidados.
tags_ofnoteLos tags de una nota.
vector_searchquery, k, label, property, whereNotas ordenadas por similitud semántica; la consulta se convierte en embedding con el modelo usado al cargar.
hybrid_searchquery, k, label, property, lexical_weight, semantic_weight, whereResultados por palabra clave y semánticos fusionados con Reciprocal Rank Fusion.
graph_algorithmalgorithm, label, edge_types, k, damping, max_iterations, source, targetEjecuta wcc, scc, pagerank, degree, betweenness, triangle_count, label_propagation, louvain o shortest_path sobre el subgrafo de un label.
cypherqueryCualquier 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:

Ventana de terminal
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}}