mcp-notes-server

Un servidor MCP que ofrece a un agente de IA un almacén de notas markdown con búsqueda: seis herramientas sobre un directorio plano de archivos .md con frontmatter estilo YAML.

Las notas siguen siendo markdown plano en el disco. Nada queda encerrado en una base de datos, así que los mismos archivos funcionan con tu editor, grep y git.

~/notes/
├── pad-thai.md
├── sourdough-starter.md
└── weekly-review.md

Herramientas

Instalación

npm install
npm run build

Úsalo con un cliente MCP

Añádelo a la configuración de servidor de tu cliente — para Claude Desktop, claude_desktop_config.json:

{
  "mcpServers": {
    "notes": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-notes-server/dist/src/index.js", "--vault", "/absolute/path/to/notes"]
    }
  }
}

El directorio del almacén se resuelve en este orden: --vault <dir>, luego $NOTES_VAULT, luego ~/notes. Se crea al inicio si no existe.

Notas de diseño

Los slugs son la identidad, y están validados. Una nota vive en <vault>/<slug>.md, y cada slug se comprueba contra /^[a-z0-9]+(?:-[a-z0-9]+)*$/ antes de llegar al sistema de archivos. Eso es lo que hace que read_note({slug: "../../.ssh/id_rsa"}) sea imposible y no meramente improbable — una lista de permitidos, no un paso de escape. Los slugs también son estables entre actualizaciones: renombrar el archivo cuando cambia el título invalidaría cualquier slug que el modelo aún tenga de una llamada de herramienta anterior.

Los errores de herramienta son datos, no excepciones. «No hay ninguna nota con el slug X» vuelve como un resultado de herramienta normal con isError: true, de modo que el modelo lo lee y se corrige. Si se lanzara, el cliente vería un error de protocolo, del que el modelo no puede recuperarse. Los bugs genuinos (cualquier cosa que no sea un VaultError) se siguen lanzando, para que sigan siendo ruidosos.

La búsqueda es frecuencia de términos ponderada. Un término en el título cuenta triple y un término en una etiqueta cuenta doble, así que buscar sourdough clasifica una nota sobre sourdough por encima de una que lo menciona de pasada. Es deliberadamente simple — no hay índice que mantener sincronizado, y un almacén de unos pocos miles de notas se escanea en milisegundos.

El almacén no sabe nada de MCP. src/vault.ts es código simple de sistema de archivos, src/server.ts es el enlace de MCP, y src/index.ts es el punto de entrada stdio. Esa división es la razón por la que el almacén se puede probar directamente y el servidor se puede probar a través de un cliente MCP real sobre un transporte en memoria, sin subprocesos ni mocks.

Desarrollo

npm test          # 46 tests, vitest
npm run typecheck # tsc --noEmit
npm run build     # emit to dist/

Los tests cubren el almacén directamente (test/vault.test.ts) y el servidor de extremo a extremo a través de un Client MCP real sobre InMemoryTransport (test/server.test.ts), de modo que se ejercitan los esquemas de herramienta, la validación de argumentos y las formas de los resultados — no solo la lógica que hay detrás.

Licencia

MIT