todo-mcp

Un servidor MCP cuyo almacén es un TODO.md que puedes leer, editar y comparar (diff) a mano. Las escrituras son empalmes por rangos de bytes, así que el archivo sigue siendo tuyo: las tablas escritas a mano, la indentación con tabulaciones y cualquier prosa fuera de una tarea nunca se vuelven a serializar.

Habla stdio para clientes MCP y Streamable HTTP para todo lo demás.

Créditos

Basado en CalamityAdam/mcp-todo, que aportó el andamiaje original: la forma de fábrica createTodoMcpServer, el envoltorio Express de Streamable HTTP y el manejo de sesiones.

Casi nada más sobrevive. Aquella versión guardaba las tareas como registros numerados en un blob JSON en ~/.mcp-todos.json, con tres herramientas sobre { id, title, done }. Esta reemplaza el almacén por un documento markdown, cambia los id numéricos por slugs y amplía la superficie de herramientas a siete, con estados, áreas, migas de referencia, notas de registro fechadas, búsqueda de texto completo y detección de duplicados. Los dos proyectos ya no comparten ninguna implementación.

El proyecto original no incluye un archivo LICENSE; su package.json declara ISC, que es lo que este repositorio mantiene.

Instalación

Ejecútalo directamente desde GitHub, sin clonar:

npx github:adrianhardy/todo-mcp

Tras publicar cualquier cambio, usa npx --ignore-existing github:adrianhardy/todo-mcp para recogerlos.

Para uso normal, instálalo una vez y olvídate:

npm i -g github:adrianhardy/todo-mcp
todo-mcp

Ambas vías compilan el código fuente al instalar mediante el script prepare, así que dist/ nunca se confirma. Se requiere Node 20 o superior.

Uso

todo-mcp arranca el servidor HTTP por defecto, porque eso es lo útil cuando lo ejecuta una persona en un terminal. Define MCP_STDIO=1 para hablar stdio, que es lo que espera un cliente MCP que lo lanza como subproceso.

Con un cliente MCP

{
  "mcpServers": {
    "todo": {
      "command": "npx",
      "args": ["-y", "github:adrianhardy/todo-mcp"],
      "env": { "MCP_STDIO": "1" }
    }
  }
}

Instalado de forma global, eso se convierte en "command": "todo-mcp" con el mismo bloque env.

El directorio de trabajo decide qué archivo usas. TODO_FILE se resuelve contra el directorio de trabajo actual del proceso y por defecto es TODO.md, así que un cliente lanzado en un proyecto edita la lista de tareas de ese proyecto. Define TODO_FILE como una ruta absoluta si quieres una lista compartida da igual dónde se inicie el servidor.

Por HTTP

PORT=8080 TODO_MCP_TOKEN=$(openssl rand -hex 32) todo-mcp

• POST /mcp - peticiones JSON-RPC

• GET /mcp - flujo SSE para notificaciones del servidor

• DELETE /mcp - termina la sesión

Si defines TODO_MCP_TOKEN, se requiere Authorization: Bearer <token> en los tres. Si lo dejas sin definir, la autenticación está desactivada, lo cual está bien solo en localhost y en ningún otro sitio.

Configuración

Se lee un archivo .env si existe. Consulta .env.example.

Almacenamiento

TODO.md es el almacén, no un blob JSON. El archivo es el registro: legible, editable a mano y comparable (diff) con git.

Una tarea es una sección ## . Los campos que el servidor regula viven en un bloque de comentarios justo debajo del encabezado; todo lo que hay debajo es la prosa que el humano es dueño y controla.

## Feature Idea version two: the new widget which tracks things

<!-- todo
id: feature-idea-version-two
area: inventory
status: next
refs: [./src/do_stuff.ts, ClassName.Method, OtherClassName]
created: 2026-08-19
updated: 2026-08-22
-->

**Next step:** close the ledger. ClassName.Method uses 0.25 and it needs 17.2%.

**Already known:** ...

### Log

- 2026-08-22 Slab_Wall_1x3 not started; parade places 24 of those to every 6 of the 3x3.

Los id son slugs, no números, por lo que sobreviven a reordenamientos y borrados. El orden del archivo es el orden de prioridad, por eso no hay campo de prioridad.

Las escrituras son empalmes por rangos de bytes: una mutación reescribe solo el tramo que le pertenece. Las tablas escritas a mano, la indentación con tabulaciones y cualquier prosa fuera de una sección de tarea nunca se vuelven a serializar, por lo que no pueden ser refluidas ni perderse. Los manejadores se serializan a través de un candado, porque dos ciclos entrelazados de leer-modificar-escribir empalmarían contra desplazamientos que ya no describen el archivo.

Diseño

• La lista está abreviada El recurso list_todos devuelve un índice de una línea y nunca los cuerpos de las tareas. get_todo devuelve una sección completa en markdown. El camino previsto es q o ref; listarlo todo es la excepción.

• La captura admite un solo campo. Solo title es obligatorio, y las tareas nuevas pasan a tener estado captured. Una herramienta que exige un área y un siguiente paso en el momento en que se nota algo no se usa, y el archivo solo funciona si las cosas se anotan cuando se encuentran. El triaje pasa captured a open, next, parked o someday más tarde.

Valores de estado

Herramientas

• list_todos - índice abreviado; filtra por area, status, ref, q, limit

• get_todo - markdown completo de una tarea, incluido el cuerpo

• add_todo - captura a tarea; solo se requiere title. Informa de posibles duplicados

• update_todo - cambia cualquier campo; solo se rescribe lo que se pasa

• append_note - añade una viñeta con fecha al registro de la tarea

• set_status - mueve una tarea por el triaje

• remove_todo - borra una tarea y su prosa. Mejor usa set_status done

Recursos

• todos://list - índice de una línea de tareas abiertas

Arquitectura

• src/todo.ts - el almacén markdown: análisis sintáctico, parcheo por rangos de bytes, consulta, deduplicación

• src/server.ts - superficie de herramientas MCP. Fábrica pura, sin efectos secundarios al importar

• src/http.ts - transporte Streamable HTTP, autenticación y mapa de sesiones

• src/cli.ts - binario todo-mcp; elige un transporte y lo arranca