Conatus MCP Server

Un servidor Model Context Protocol instalable de forma independiente para el gestor de tareas Conatus autoalojado.

Expone herramientas seguras para agentes para proyectos, secciones, tareas, etiquetas, comentarios y recordatorios. Admite clientes locales stdio y clientes remotos Streamable HTTP. La eliminación permanente no se expone intencionadamente.

Requisitos

• Node.js 20 o superior

• Una instalación de Conatus accesible con la API /api/v1

• Un token de API con alcance creado en Configuración → Tokens de API

Related MCP server: Google Tasks MCP Server

Configuración local stdio

El modo local es el predeterminado recomendado. El host de IA inicia un proceso MCP para la cuenta del gestor de tareas configurada.

Configuración con un solo comando

Ejecute el instalador interactivo para validar su URL de Conatus y el token de API con alcance, luego registre el servidor con Claude Desktop, Claude Code, Cursor u otro archivo de configuración JSON de MCP:

npx -y conatus-mcp setup

El instalador nunca muestra el token, lo verifica antes de cambiar un archivo de configuración y restringe el archivo de configuración escrito a permisos de solo propietario cuando el sistema operativo lo admite. Reinicie el cliente elegido cuando termine. La configuración directa a continuación sigue siendo la alternativa no interactiva.

{
  "mcpServers": {
    "my-tasks": {
      "command": "npx",
      "args": ["-y", "conatus-mcp"],
      "env": {
        "TASKS_BASE_URL": "https://tasks.example.com",
        "TASKS_API_TOKEN": "tdm_replace_me"
      }
    }
  }
}

Para una instalación de desarrollo local, use http://localhost:3000 como TASKS_BASE_URL.

También puede instalar el paquete una vez:

npm install --global conatus-mcp
conatus-mcp

Modo remoto Streamable HTTP con OAuth de navegador

Use OAuth cuando un agente necesite conectarse por URL. El servidor MCP actúa como una puerta de enlace de un solo usuario: su TASKS_API_TOKEN con alcance identifica el espacio de trabajo de tareas, mientras que cada cliente de IA recibe un token OAuth separado de corta duración. El token de tareas nunca sale del servidor.

TASKS_BASE_URL=https://tasks.example.com \
TASKS_API_TOKEN=tdm_replace_me \
MCP_HOST=0.0.0.0 \
MCP_PORT=3001 \
MCP_PUBLIC_URL=https://mcp.example.com/mcp \
MCP_OAUTH_PASSWORD='use-a-long-separate-approval-password' \
MCP_OAUTH_STORE_PATH=/var/lib/task-mcp/oauth-store.json \
MCP_ALLOWED_ORIGINS=https://your-ai-host.example \
conatus-mcp-http

Proporcione al cliente de IA solo https://mcp.example.com/mcp. Un cliente compatible descubre los metadatos del recurso protegido, se registra dinámicamente, abre la página de aprobación y completa un flujo de código de autorización OAuth con S256 PKCE. Introduzca MCP_OAUTH_PASSWORD en esa página para aprobarlo.

El servidor emite tokens de acceso de una hora y tokens de actualización rotativos de 30 días. Los registros de clientes OAuth y los hashes de tokens se almacenan en el archivo en MCP_OAUTH_STORE_PATH con modo 0600; los tokens OAuth sin procesar y la contraseña de aprobación no se almacenan. Ejecute una réplica MCP por archivo de almacenamiento. Para múltiples réplicas, reemplace el almacenamiento JSON con un almacenamiento transaccional compartido primero.

Coloque TLS y un proxy inverso frente al puerto 3001. MCP_PUBLIC_URL debe ser el endpoint externo exacto y terminar en /mcp. Las URL de producción deben usar HTTPS. Las solicitudes que llevan un encabezado Origin se aceptan solo cuando el origen está listado en MCP_ALLOWED_ORIGINS; los clientes nativos comúnmente no envían Origin.

Dominio y proxy inverso

La aplicación de tareas y la puerta de enlace MCP pueden usar direcciones separadas:

• https://tasks.example.com → la aplicación web y /api/v1

• https://mcp.example.com/mcp → este servicio MCP hijo

Cree registros DNS para ambos nombres, termine TLS en su proxy y reenvíe mcp.example.com al puerto 3001. Solo el proxy debe exponer ese puerto. Los endpoints de metadatos OAuth, registro, autorización, token, revocación, aprobación y MCP comparten el origen MCP.

Respaldo de portador estático

Para clientes que no pueden realizar OAuth, omita MCP_PUBLIC_URL y MCP_OAUTH_PASSWORD, luego establezca MCP_BEARER_TOKEN a un valor aleatorio largo. Conéctese a /mcp y envíe ese valor como token de portador. Esto es menos conveniente de rotar por cliente y no debe pegarse en prompts.

El enlace a una dirección no loopback sin configuración OAuth completa o MCP_BEARER_TOKEN se rechaza.

Docker

Las imágenes publicadas se publican en ghcr.io/nojusmorkunas/conatus-mcp. Compile localmente solo cuando trabaje en el servidor mismo:

docker build -t conatus-mcp .
docker run --rm -p 127.0.0.1:3001:3001 \
  -v task-mcp-oauth:/data \
  -e TASKS_BASE_URL=https://tasks.example.com \
  -e TASKS_API_TOKEN=tdm_replace_me \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PUBLIC_URL=https://mcp.example.com/mcp \
  -e MCP_OAUTH_PASSWORD='use-a-long-separate-approval-password' \
  -e MCP_OAUTH_STORE_PATH=/data/oauth-store.json \
  conatus-mcp

Variables de entorno

No ponga tokens en prompts, argumentos de herramientas, control de versiones o argumentos de línea de comandos. Las variables de entorno los mantienen fuera de los mensajes MCP y de la mayoría de las listas de procesos.

Para revocar un cliente OAuth, deje que ese cliente llame al endpoint de revocación anunciado. Para revocar todos los clientes conectados, detenga el servicio y elimine su archivo de almacenamiento OAuth, luego reinicie; todos los clientes deben volver a conectarse. Revocar o rotar TASKS_API_TOKEN en la Configuración del gestor de tareas si la puerta de enlace misma está comprometida.

Herramientas

• Workspace: get_workspace_context

• Projects: list_projects, get_project, create_project, update_project

• Sections: create_section, update_section

• Tasks: list_tasks, get_task, create_task, quick_add_task, update_task, move_task, complete_task, reopen_task, set_task_labels

• Labels: list_labels, create_label

• Collaboration: add_comment

• Scheduling: set_reminder

Recursos

• taskapp://workspace

• taskapp://views/today

• taskapp://views/upcoming

• taskapp://projects/{id}

• taskapp://tasks/{id}

Desarrollo

npm install
npm test
npm run build
npm run dev

Pruebe el servidor stdio compilado con MCP Inspector:

TASKS_BASE_URL=http://localhost:3000 \
TASKS_API_TOKEN=tdm_replace_me \
npx @modelcontextprotocol/inspector node dist/cli.js

Publicación

Publicar un release de GitHub compila ghcr.io/nojusmorkunas/conatus-mcp para linux/amd64 y linux/arm64, luego publica el paquete npm. Ambos provienen del commit publicado, por lo que un release produce ambos artefactos o ninguno.

Etiquete el release vX.Y.Z que coincida con package.json; el trabajo npm se niega a publicar una discrepancia. Marque los prereleases como tales en GitHub y van al dist-tag beta, dejando latest en el release estable más reciente.

La publicación npm usa trusted publishing, por lo que este repositorio no almacena token npm. Requiere una configuración única en la página de configuración de npmjs.com del paquete que lo vincule a este repositorio y al flujo de trabajo Publish release.

Para publicar manualmente en su lugar:

npm publish --tag latest   # or --tag beta for a prerelease

Nombre el dist-tag explícitamente. npm rechaza un npm publish simple para cualquier versión con un sufijo de prerelease semver, que cada 0.x.y-beta.z tiene.

prepublishOnly vuelve a ejecutar las comprobaciones de prueba, lint y compilación. publishConfig.access ya está configurado, por lo que no se necesita la bandera --access.