Todos
Protocolo MCP 2024-11-05

API MCP

Referencia de las tools disponibles en el servidor MCP de Todos. Accede a través de /mcp.

Autenticación

El servidor admite dos métodos de autenticación:

Bearer

Envía un token OAuth en la cabecera Authorization: Bearer <token>. El token se valida contra la tabla oauth_tokens.

Query

Pasa ?uid=<uid>&key=<key> en la URL. La key se valida comparando su SHA-1 con el keyhash almacenado.

Si la autenticación falla, el servidor devuelve 401 Unauthorized con una cabecera WWW-Authenticate.

Tipo Todo

Objeto devuelto por todas las tools que crean o modifican tareas.

Campo Tipo Descripción
id string Identificador único de la tarea.
uid string ID del usuario propietario.
name string Título de la tarea.
description string Descripción en formato Markdown.
priority "low" | "medium" | "high" Prioridad de la tarea.
createdAt string (ISO 8601) Fecha y hora de creación.
updatedAt string (ISO 8601) Fecha y hora de última actualización.
completedAt string | null Fecha de completado, o null si está pendiente.
deletedAt string | null Fecha de eliminación, o null si está activa.
deadlineAt string | null Fecha límite opcional.
links string[] IDs de tareas relacionadas (para agrupar sub-tareas).

Tools

tool

get_list_usage

Devuelve el uso actual de la lista: número de tareas creadas, límite del plan y porcentaje de ocupación.

Parámetros de entrada

Sin parámetros.

Respuesta

count Número total de tareas en la lista (activas, completadas y eliminadas).
maxTasks Límite de tareas del plan (plan free: 1 200).
percentage Porcentaje de ocupación redondeado al entero más cercano. 
{
  "content": [
    {
      "type": "text",
      "text": "{\"count\":42,\"maxTasks\":1200,\"percentage\":4}"
    }
  ]
}
tool

get_list_url

Devuelve la URL de la página web donde el usuario puede ver sus tareas en el navegador.

Parámetros de entrada

Sin parámetros.

Respuesta

content[0].type = "text"
content[0].text URL completa con uid y key. 
{
  "content": [
    { "type": "text", "text": "https://todos.jon.soy/list?uid=...&key=..." }
  ]
}
tool

put_todo

Crea o reemplaza una tarea del usuario actual. Si ya existe una tarea con el mismo id, se sobreescribe por completo.

Parámetros de entrada

id requerido string

Identificador único de la tarea (ej: kebab-case).

name requerido string

Título de la tarea.

description requerido string

Descripción en Markdown.

priority opcional "low" | "medium" | "high"

Por defecto: "medium".

completedAt opcional string | null

Fecha ISO 8601 de completado. Por defecto: null.

deadlineAt opcional string | null

Fecha límite ISO 8601. Por defecto: null.

links opcional string[]

IDs de tareas relacionadas. Por defecto: [].

Respuesta

Devuelve el objeto Todo creado o actualizado serializado como JSON.

{
  "content": [
    {
      "type": "text",
      "text": "{ ...Todo }"
    }
  ]
}
tool

list_todos

Lista las tareas del usuario actual. Por defecto solo muestra las tareas pendientes (no completadas ni eliminadas). Usa los parámetros opcionales para ampliar los resultados.

Parámetros de entrada

includeCompleted opcional boolean

Si es true, incluye las tareas completadas. Por defecto: false.

includeDeleted opcional boolean

Si es true, incluye las tareas eliminadas. Por defecto: false.

Respuesta

Array de objetos Todo serializado como JSON.

{
  "content": [
    {
      "type": "text",
      "text": "[{ ...Todo },...]"
    }
  ]
}
tool

search_todos

Busca tareas del usuario usando búsqueda difusa (fuzzy search) sobre el título y la descripción. Los resultados se devuelven ordenados por relevancia. Utiliza Fuse.js como motor de búsqueda.

Parámetros de entrada

query requerido string

Texto a buscar en el título y la descripción de las tareas.

includeCompleted opcional boolean

Si es true, incluye tareas completadas en la búsqueda. Por defecto: false.

Respuesta

Array de objetos Todo que coinciden con la búsqueda, ordenados de mayor a menor relevancia. Devuelve un array vacío si no hay coincidencias. Las tareas eliminadas nunca se incluyen. 

{
  "content": [
    {
      "type": "text",
      "text": "[{ ...Todo },...]"
    }
  ]
}
tool

complete_todo

Marca una tarea del usuario actual como completada. Establece completedAt con la fecha y hora actual.

Parámetros de entrada

id requerido string

Identificador de la tarea a completar.

Respuesta

Devuelve el objeto Todo actualizado. Si el id no existe, devuelve un error. 

// Éxito
{
  "content": [{ "type": "text", "text": "...Todo" }]
}

// Error
{
  "isError": true,
  "content": [{ "type": "text", "text": "Todo not found" }]
}

Prompts

prompt

start_workspace

Inicia un área de trabajo a partir de una premisa. El asistente crea una tarea raíz y guía al usuario para agregar sub-tareas vinculadas mediante el campo links.

Argumentos

premise requerido string

La meta o premisa del área de trabajo. Ej: "vamos a trabajar en la remodelación del sótano".

Comportamiento

  1. El agente crea una tarea raíz con put_todo usando un ID descriptivo en kebab-case.
  2. Muestra el ID de la tarea raíz al usuario.
  3. Pide sub-tareas y las crea con links: [id-raiz] para vincularlas.