mstodo-mcp

Usa tus tareas de Microsoft To Do desde Claude (o cualquier cliente MCP), en lenguaje natural. Este es un servidor personal y autohospedado que ejecutas en tu propio Cloudflare Worker y que conecta Claude.ai con tu cuenta de Microsoft To Do, de modo que puedes pedirle a Claude que encuentre, cree, actualice, complete, busque y organice tareas en todas tus listas sin salir del chat. Mantiene un espejo local rápido de tus listas y tareas, por lo que buscar y consultar en todas las listas es rápido y no satura a Microsoft en cada solicitud.

Es de un solo usuario por diseño: un despliegue atiende exactamente a una cuenta de Microsoft (cualquier otra persona es rechazada por una compuerta de identidad del propietario), por lo que está pensado para ejecutar tu propia instancia privada, no un servicio compartido o multiinquilino.

Contenido

• Requisitos

• Herramientas

• Cómo funciona

• Configuración

• Restablecimiento

• Borrado automático al cambiar de identidad

• Decisiones de diseño a revisar

• Autor

• Guía de despliegue →

• Registro de cambios →

Requisitos

• Una cuenta de Microsoft 365 (M365) o una cuenta personal de Microsoft que use Microsoft To Do.

• Una cuenta de Cloudflare: el plan gratuito funciona para cuentas pequeñas; se recomienda Workers de pago cuando tengas miles de tareas (consulta la nota sobre el plan en la guía de despliegue).

• Un registro de aplicación en Microsoft Entra, gratuito y creado una sola vez (tutorial en la guía de despliegue).

• Node 18+ y la CLI Wrangler de Cloudflare para desplegar.

• Claude.ai (u otro cliente MCP) para conectarte al servidor desplegado.

➡️ Configuración y despliegue: consulta DEPLOYMENT.md para ver la guía completa paso a paso (incluido el registro de la aplicación en Microsoft Entra), la configuración de un dominio personalizado y la resolución de problemas. La referencia de Configuración está más abajo.

Herramientas

El servidor expone una superficie de herramientas de Microsoft To Do a través de MCP. Lo más destacado:

• Listas y tareas (CRUD) — list_lists, get_list, create_list, update_list, delete_list; list_tasks, get_task, create_task, update_task, delete_task, move_task.

• Subrecursos — elementos de lista de verificación y recursos vinculados (crear/listar/obtener/actualizar/eliminar cada uno); archivos adjuntos (list_attachments, get_attachment, remove_attachment).

• Subida de archivos adjuntos — create_upload_link genera un enlace web de un solo uso y corta duración que el usuario abre en un navegador para adjuntar archivos a una tarea específica. Los bytes van del navegador → al Worker → a Microsoft (≤ 25 MB cada uno, en línea o mediante sesión de subida por fragmentos) y nunca pasan por el modelo. Consulta Subida web más abajo.

• Descarga de archivos adjuntos — mint_download_link genera una URL de un solo uso y corta duración (≤ 5 min) que sirve los bytes de un archivo adjunto para una transferencia de servidor a servidor (p. ej., pasando la URL a la herramienta de ingesta de URL de otro servidor MCP). Los bytes se obtienen en el lado del servidor y nunca pasan por el modelo. Activada por defecto; establece ENABLE_DOWNLOAD_LINKS="false" para desactivarla. Consulta Descarga entre servidores más abajo.

• Consulta y búsqueda entre listas (respondidas desde el espejo local TodoIndex):

  • query_tasks — filtra por listas, estado, rangos de fechas, importancia, tiene-lista-de-verificación, has_open_checklist_item (tareas con un elemento sin marcar, el filtro de «en espera de algo»); types/exclude_types (incluir/excluir por clasificación de lista); un atajo completed (mutuamente excluyente con status); paginado.

  • search_tasks — búsqueda de texto completo sobre títulos/cuerpos de tareas mediante FTS5 (el motor de búsqueda de texto completo integrado de SQLite); los mismos filtros lists/status/types/exclude_types/completed. exclude_types:["excluded"] elimina ruido (p. ej., listas de correos marcados) de los resultados sin borrar nada. Cuando la caché de listas de verificación está activada, también coincide con el texto de los elementos de la lista de verificación (subtarea/paso) por defecto (include_checklist, en un nivel posterior a las coincidencias de título/cuerpo).

  • find_task_list, get_pending_across_lists, get_recently_completed.

• Seguimientos de lista de verificación (opt-in) — controlado por ENABLE_CHECKLIST_CACHE=true. Refleja los elementos de la lista de verificación de las tareas en una tabla consultable para que puedas usar los elementos de la lista de verificación como un sistema ligero de seguimiento (añade un elemento «en espera de respuesta de Acme» y luego encuentra lo que sigue abierto). search_checklist_items hace búsqueda de texto completo (FTS) sobre el texto de las listas de verificación o, sin consulta, lista los elementos pendientes de más antiguo a más reciente (lo que llevas más tiempo esperando), agrupados por tarea. Se combina con el filtro has_open_checklist_item de query_tasks. Desactivada por defecto (añade un relleno inicial único por tarea); la caché se mantiene actualizada con el ciclo delta normal. Cubre solo tareas abiertas: las tareas completadas se excluyen deliberadamente de las consultas de listas de verificación entre tareas (get_task sigue mostrando los elementos de cualquier tarea en vivo), y las listas omitidas (no_sync/Correos marcados) no se almacenan en caché.

• Mi día y orden manual (opt-in, Substrate) — controlado por ENABLE_MY_DAY=true (estas funciones usan el endpoint no documentado de Substrate que usa la aplicación web de To Do, porque Mi día y la posición de reordenamiento manual por arrastre son invisibles para Graph): list_my_day_tasks, add_to_my_day, remove_from_my_day; list_tasks_by_manual_order (una lista en el orden manual de la aplicación) y reorder_task (mover una tarea al principio/final, antes/después de otra, o a una posición basada en 1).

• Configuración — get_list_config/set_list_config (patrones de clasificación, no_sync, sync_flagged_emails), set_list_alias, get_link_rules/set_link_rules, get_attachment_config/set_attachment_config, extract_links.

• Operaciones — whoami, sync_status, resync.

Cómo funciona

Claude.ai se conecta al Worker a través de MCP remoto; el Worker actúa de intermediario de las solicitudes hacia la API de Microsoft Graph (flujo de código de autorización OAuth con PKCE y un secreto de cliente). Un objeto durable TodoIndex singleton (la primitiva de computación con estado y consistencia fuerte de Cloudflare) mantiene un espejo sincronizado por delta de tus listas y tareas en su base de datos SQLite integrada, junto con un índice de texto completo FTS5 (FTS5 es el motor de búsqueda de texto completo integrado de SQLite). Las herramientas de consulta entre listas query_tasks, search_tasks y las herramientas de agregación leen de este espejo local en lugar de volver a recorrer Graph en cada llamada; un cron */15 lo mantiene sincronizado y una compuerta de identidad del propietario lo mantiene privado.

Por defecto, el espejo también se suscribe a las notificaciones de cambio de Graph (una por lista), de modo que una edición en cualquier cliente de To Do llega a la caché en aproximadamente 2 minutos, casi al instante, como en las aplicaciones nativas, en lugar de esperar al siguiente ciclo del temporizador. Esto es un desencadenante de la sincronización delta, no un reemplazo: el ciclo del temporizador se mantiene como respaldo (Graph no garantiza notificaciones no perdidas para tareas). Usa el ámbito existente Tasks.ReadWrite (sin consentimiento adicional), necesita una SERVICE_BASE_URL accesible (Graph publica en ${SERVICE_BASE_URL}/webhook) y se puede activar o desactivar con ENABLE_TASK_SUBSCRIPTIONS ("false" ⇒ solo temporizador, sin webhook público). Una notificación también actualiza solo los campos de Mi día de la tarea cambiada mediante una lectura específica de Substrate: la ruta del webhook nunca escribe de vuelta a Microsoft, por lo que no puede entrar en bucle.

El estado pequeño y que cambia lentamente (tus tokens OAuth, el registro de identidad del propietario y los blobs de configuración siguientes) vive en KV de Cloudflare (un almacén clave-valor). El corpus grande de tareas consultado con frecuencia vive en el SQLite del objeto durable, no en KV.

Modelo de seguridad

El servidor es estrictamente de un solo usuario por diseño, y algunas invariantes son fundamentales; vale la pena exponerlas en un solo lugar:

• Un solo propietario, a prueba de fallos. Cada inicio de sesión se controla en la devolución de llamada de OAuth: el mail/userPrincipalName del /me de Microsoft debe ser igual al secreto OWNER_EMAIL, y una identidad que no coincide recibe un 403 antes de que se almacene ningún token. Un OWNER_EMAIL ausente o mal escrito hace que la comprobación falle para todos: bloquea al propietario, pero nunca abre el acceso.

• Fijación de host antes de la autorización. Cada URL de Graph y de Substrate se fija a su host esperado antes de adjuntar el token Bearer, de modo que un @odata.nextLink malicioso no pueda redirigir una solicitud autenticada y exfiltrar el token. Los tokens viajan solo en la cabecera Authorization, nunca en una URL ni en una línea de registro.

• Un único actualizador de tokens. El objeto durable TodoIndex singleton es el único que llama al endpoint de tokens de Microsoft; las sesiones concurrentes pasan por una única cadena de actualización, por lo que no hay tormentas de actualización ni lógica de manejo de tokens duplicada entre sesiones.

• La configuración es solo del propietario, no una superficie no confiable. Las reglas de regex en config:lists / config:link_rules solo pueden escribirlas el propietario autenticado (mediante herramientas MCP detrás de la compuerta anterior), por lo que las preocupaciones sobre regex proporcionadas por el usuario, como ReDoS, no están en el modelo de amenazas. El motor de enlaces además limita el trabajo con un tope de cuerpo de 8 KB y un presupuesto de 50 ms por tarea.

• Superficies web sin secretos. /upload y /download autorizan con tokens de capacidad de un solo uso (un id aleatorio imposible de adivinar almacenado en KV con un TTL, limitado a una tarea/archivo adjunto), por lo que no hay ninguna clave de firma ni secreto compartido que configurar o filtrar.

• Los registros no contienen secretos. Las cadenas de consulta (que pueden contener tokens delta) se redactan, los cuerpos de error de Microsoft se registran como campos estructurados en lugar de texto sin formato, y la única información de identificación personal (PII) en los registros es la propia dirección del propietario en la línea de cambio de identidad.

Configuración

Tres blobs de configuración opcionales viven en KV bajo el enlace TODO_CACHE. Ejemplos listos para editar (con los comandos exactos de wrangler kv key put) están en config-examples/.

config:lists — clasificación, alias y control de sincronización

• patterns — reglas de regex ordenadas que se comparan con los nombres para mostrar de las listas (sin emojis, sin distinguir mayúsculas por defecto); la primera coincidencia gana → todo | reference | excluded. Las listas sin coincidencia quedan como unclassified. La clasificación alimenta el filtrado de list_lists y los parámetros types/exclude_types en query_tasks/search_tasks. excluded mantiene una lista fuera de las herramientas filtradas por tipo, pero no detiene su sincronización; usa no_sync para eso.

• aliases — identificador corto → ID de lista de Graph, utilizable en cualquier lugar donde se acepte una lista. Se borran automáticamente al cambiar de identidad de Microsoft (los ID son por cuenta).

• no_sync — listas excluidas de la sincronización delta, identificadas por wellknownListName o por el ID de lista de Graph. Siguen apareciendo y se pueden leer bajo demanda, pero no se indexan. Se pueden establecer de forma conversacional mediante set_list_config; el bucle de sincronización purga automáticamente las filas de una lista si la añades más tarde.

• sync_flagged_emails — la lista conocida flaggedEmails se omite por defecto (a menudo es enorme y no es una lista de tareas real); establece true para indexarla. Esta omisión integrada es independiente de no_sync.

config:link_rules — vincular tareas automáticamente

Reglas de regex → recurso vinculado aplicadas a los títulos/cuerpos de las tareas. Consulta config-examples/link-rules.json.

config:attachments — límite de subida en línea

max_inline_bytes (tope máximo de 3072 KiB, el límite confirmado de Graph). Para subidas web, este es el punto de corte: los archivos de ese tamaño o inferiores se adjuntan en línea; los más grandes (hasta 25 MB) se adjuntan mediante una sesión de subida de Graph por fragmentos. Consulta config-examples/attachments.json.

Subida web (/upload)

Los bytes de un archivo no pueden viajar de forma práctica a través de una llamada de herramienta MCP (el presupuesto de argumentos por llamada del modelo es de unos pocos KB). En su lugar, create_upload_link genera un enlace de un solo uso y corta duración (15 min por defecto, máx. 30) limitado a una tarea específica; el usuario lo abre en un navegador y los bytes van directamente del navegador al Worker y de ahí a Microsoft Graph, nunca a través del modelo. Proporciona un filename para un enlace de un solo archivo, u omítelo para un enlace por lotes (hasta max_files, 1–10, por defecto 5). Los archivos idénticos ya adjuntos a la tarea se detectan por hash de contenido y se omiten como duplicados.

El enlace es un token de capacidad: un id aleatorio imposible de adivinar (32 bytes del CSPRNG). El ámbito de destino (ids de listas/tareas, nombre de archivo, número de archivos) se almacena en el servidor en OAUTH_KV bajo ese id con un TTL; el id del enlace no revela nada. Poseer el id autoriza una subida exactamente a la tarea indicada — verificado mediante una consulta a KV, expirado por el TTL, consumido (eliminado) al usarse. No hay ninguna clave de firma ni secreto compartido que configurar: el id es el nonce.

Para activarlo, establece SERVICE_BASE_URL (variable, en wrangler.jsonc) — el origen público de este Worker (tu URL de workers.dev o dominio personalizado), que se usa para construir el enlace. Si no se establece (o se deja el valor de marcador), create_upload_link devuelve upload_disabled.

Descarga entre servidores (/download)

Es la operación inversa de la subida: mint_download_link devuelve una URL de un solo uso y de corta duración (≤ 5 min) junto con los metadatos del adjunto (filename, content_type, size). El consumidor previsto es la herramienta url-ingest de otro servidor MCP: esta obtiene la URL en el lado del servidor, por lo que los bytes viajan de servidor a servidor y nunca entran en el contexto del modelo. La mecánica de capacidad es un espejo de la subida (un id imposible de adivinar en OAUTH_KV bajo el prefijo download:, acotado a un adjunto), y el enlace se quema en el primer GET alcanzable sea cual sea el resultado, de modo que no puede reproducirse si más tarde aparece en el historial de la conversación. (Un solo uso frente a un consumidor honesto; como /upload, no es transaccional: dos GET realmente simultáneos podrían competir). Los metadatos se leen en el momento de la acuñación desde la colección de adjuntos, por lo que /download hace una única llamada a Graph para obtener los bytes y no confía en ninguna cabecera de la solicitud.

El size devuelto es el metadato que notifica Graph y puede sobreestimar los bytes reales: el tamaño autoritativo es el Content-Length de la descarga. Los bytes servidos coinciden byte a byte con el origen (verificado hasta un adjunto de sesión de subida de 4 MiB), por lo que la transferencia es fiel incluso cuando size no coincide. Los adjuntos grandes funcionan (Graph devuelve contentBytes en el GET individual independientemente del límite de creación en línea); el límite práctico es el máximo de adjunto de Graph de ~25 MB, ya que /download almacena el archivo en búfer en la memoria del Worker.

Esta superficie está activada por defecto; establece ENABLE_DOWNLOAD_LINKS="false" (variable) para desactivar tanto mint_download_link como /download y reducir la superficie de ataque si no la necesitas. También requiere SERVICE_BASE_URL (igual que la subida); sin establecer o con marcador ⇒ download_disabled.

Restablecimiento

Tres ámbitos, de menor a mayor. Ejecuta desde la raíz del proyecto; sustituye --remote por --local si quieres operar sobre el almacén KV local de miniflare que usa wrangler dev.

1. Restablecimiento suave entre iteraciones de prueba

El más común: volver a disparar el flujo OAuth de Microsoft sin destruir la infraestructura. El borrado automático por cambio de identidad (integrado en /auth/microsoft/callback) limpiará automáticamente la caché por identidad la próxima vez que autorices con una cuenta diferente de Microsoft 365 (M365), pero también puedes borrarla manualmente.

# Wipe the stored Microsoft refresh token. Forces the next /authorize to
# re-run the full code-exchange flow.
npx wrangler kv key delete --binding=TODO_CACHE --remote tokens:owner

# Also wipe the stored identity record if you want to "forget" which
# account was last seen (this disables the identity-change wipe trigger
# the next time you sign in — useful when you want to test the wipe).
npx wrangler kv key delete --binding=TODO_CACHE --remote identity:owner

# Wipe all Claude.ai-side OAuth grants (DCR sessions) — forces every
# previously-paired Claude.ai client to re-add this MCP from scratch:
npx wrangler kv key list --binding=OAUTH_KV --remote \
  | jq -r '.[].name' \
  | xargs -I {} npx wrangler kv key delete --binding=OAUTH_KV --remote {}

Si además quieres que Microsoft vuelva a pedir consentimiento (en lugar de reemitir tokens silenciosamente porque el consentimiento ya está registrado), revoca la aplicación desde la página de permisos de la cuenta del usuario en el lado de M365, o — cuando expongamos la opción — pasa &prompt=consent a /authorize.

2. Rotar credenciales

Edita .dev.vars con los nuevos valores y luego súbelos todos a Cloudflare de una vez:

bash scripts/push-secrets.sh

El script lee cada nombre de .dev.vars y canaliza el valor por stdin a wrangler secret put, de modo que los valores nunca aparecen en argv, en el entorno, en el historial del terminal ni en transcripciones de IA. Verifícalo con npx wrangler secret list.

Cualquier valor en .dev.vars puede ser, en su lugar, una referencia a secreto de 1Password con la forma op://<vault>/<item>/<field>: el script la resuelve mediante la CLI op en el momento del envío (requiere op signin, u OP_SERVICE_ACCOUNT_TOKEN para uso headless) y canaliza el valor resuelto por stdin como cualquier otro secreto. Los valores literales siguen funcionando sin cambios, por lo que puedes mantener algunos o todos los secretos fuera del archivo:

MS_CLIENT_SECRET=op://Private/MS To-Do MCP/credential

Para enviar un solo secreto manualmente, en su lugar:

npx wrangler secret put MS_CLIENT_SECRET     # prompts for value

El secreto de cliente antiguo sigue siendo válido hasta que también lo elimines en el portal de Azure: wrangler secret put solo actualiza el lado del Worker.

Después de rotar, haz un restablecimiento suave (arriba) para que el próximo /authorize use la nueva identidad.

3. Borrón y cuenta nueva

Para comprobaciones de publicabilidad previas al lanzamiento, o para recuperarse de un estado corrupto:

npx wrangler delete --name=mstodo-mcp                       # nukes Worker + all DO state
npx wrangler kv namespace delete --binding=OAUTH_KV
npx wrangler kv namespace delete --binding=TODO_CACHE
# Then re-create namespaces + update wrangler.jsonc + redeploy (see DEPLOYMENT.md).

Este es el camino de «quiero que esta cuenta parezca un fork recién hecho». Ten en cuenta que wrangler delete es destructivo y no recuperable.

Borrado automático por cambio de identidad (integrado)

Cuando /auth/microsoft/callback se completa con un me.id distinto del identity:owner.id almacenado previamente, el Worker borra automáticamente el estado por identidad antes de guardar los nuevos tokens. Esto evita mezclar silenciosamente tareas de dos cuentas M365.

Lo que borra el borrado automático, en orden (a prueba de fallos: el restablecimiento del Durable Object se ejecuta primero, así que si lanza una excepción no ha ocurrido nada más y /authorize se aborta antes de guardar los nuevos tokens, sin dejar nunca una mezcla a medio borrar):

1. Restablecimiento del DO TodoIndex — elimina todas las tareas indexadas, el registro de listas y todos los cursores sync_state de delta (el corpus de tareas vive en el SQLite del DO, no en KV).

2. tokens:owner y luego identity:owner en TODO_CACHE (el marcador de identidad va al final, de modo que un fallo a mitad del borrado vuelve a disparar el borrado en el próximo /authorize en lugar de omitirlo silenciosamente).

3. config:lists.aliases — con el mejor esfuerzo, ya que los alias son IDs de Graph por cuenta que resolverían a listas muertas tras un cambio. La clasificación patterns, no_sync, sync_flagged_emails, config:link_rules y config:attachments se conservan (intención independiente de la cuenta).

Las concesiones de OAUTH_KV no se ven afectadas por el borrado automático: tu emparejamiento con Claude.ai sigue funcionando aunque cambies de cuenta de Microsoft. Si quieres que el cliente de Claude.ai vuelva a autenticarse desde cero también, ejecuta el borrado de OAUTH_KV en el bloque de restablecimiento suave de arriba.

Cuando se activa el borrado automático, se emite una línea de registro estructurado:

{"level":"warn","event":"identity_change_wipe","prev_id":"…","prev_mail":"…","new_id":"…","new_mail":"…","hint":"…"}

Puedes usar wrangler tail para observarlo durante las pruebas.

Decisiones de diseño a revisar

Registradas aquí para que futuros mantenedores puedan reconsiderarlas cuando los patrones de uso sugieran una compensación distinta.

Paginación de list_tasks — obtención en vivo por página, sin caché de instantánea

La herramienta list_tasks de la Fase 2 pagina directamente contra Graph ($top + @odata.nextLink). El next_cursor devuelto a los llamantes es la URL opaca de nextLink de Graph; las llamadas posteriores hacen GET de esa URL a través de la ruta estándar de token/refresco de GraphClient. tasks:{listId} NO lo escribe esta herramienta — la sincronización delta de la Fase 5 es la única escritora de esa clave de caché.

Esta es una desviación documentada de la instrucción del plan de la Fase 2: «Guardar instantánea en tasks:{listId} con ETag». Opción A (elegida) frente a Opción B (obtener todas las páginas en la primera llamada, guardar instantánea y luego servir páginas desde la caché):

Reconsidera la Opción B si wrangler tail muestra más tarde que el LLM pagina repetidamente en profundidad listas grandes en ventanas cortas: la obtención inicial + lecturas de caché ahorrarían cuota de Graph de extremo a extremo a costa de la latencia de la primera página. A partir de la Fase 2, el uso típico de To Do es ráfagas y poco profundo; la paginación en vivo es más barata en conjunto y nos permite aplazar el compromiso con la forma de la caché hasta la Fase 5, donde es fundamental.

Subida de adjuntos — /upload web, no una llamada a herramienta MCP

Los bytes de archivo no pueden viajar prácticamente a través de una llamada a herramienta MCP: el presupuesto de salida/tokens de Claude por llamada limita los argumentos de herramienta a unos pocos KB, por lo que todas las subidas excepto las triviales fallan antes siquiera de llegar a Graph (confirmado al construir el proyecto hermano obsidian-mcp-cloudflare). El límite en línea de 3072 KiB de Graph nunca fue la restricción vinculante: lo era el transporte MCP.

La herramienta original create_attachment (base64 en línea en la llamada a la herramienta) se eliminó por tanto y se sustituyó por el flujo de subida web: create_upload_link + el endpoint público /upload (ver Subida web). Los bytes van del navegador al Worker y de ahí a Graph, adjuntos en línea para ≤ 3072 KiB y mediante una sesión de subida por fragmentos para archivos más grandes de hasta 25 MB. Los enlaces son tokens de capacidad: un id aleatorio imposible de adivinar cuyo ámbito de tarea vive en OAUTH_KV bajo un TTL, con ámbito de tarea, de un solo uso y nunca genéricos (cada enlace apunta a una tarea específica). No interviene ninguna clave de firma ni secreto compartido. El Worker reenvía los bytes de forma síncrona durante el POST, por lo que no se necesita un bucket R2 ni almacenamiento temporal de blobs. Adaptado de obsidian-mcp-cloudflare (su src/upload/*), ajustado a las APIs de adjuntos de To Do y simplificado a un token de capacidad sin secreto.

Autor

Creado por David Szpunar. Licenciado bajo la Licencia MIT. Historial de versiones en el changelog.