TDC Flow MCP Server

Un servidor MCP stdio sobre la API REST de TDC Flow, para que Claude Code pueda leer tus tareas asignadas, proponer tareas y subtareas, actualizarlas y registrar tiempo con instantes reales de inicio y fin tomados del historial de git.

Configuración

La autenticación es la cookie de sesión del navegador. Abre cualquier solicitud autenticada en tdcflow.tdcapps.com en devtools, copia la cookie __Secure-better-auth.session_token y ponla en .env:

cp .env.example .env
$EDITOR .env

Registra el servidor con Claude Code:

claude mcp add tdcflow --scope user /home/yashasvi/Developer/tdcflow-mcp/run.sh

La cookie caduca después de siete días. Cuando las llamadas empiecen a fallar con Session cookie is invalid or expired, actualízala en .env.

Related MCP server: Povio Worklog MCP Server

Validación

test.mjs inicia el servidor, habla JSON-RPC real sobre stdio y ejercita cada herramienta. Las pruebas de escritura crean sus propios fixtures y los retiran después:

node test.mjs

Herramientas

Lectura:

• tdcflow_whoami: el usuario y la organización con sesión iniciada

• tdcflow_list_tasks: tus tareas abiertas por defecto; filtra por asignado, estado, proyecto o título

• tdcflow_get_task: una tarea con asignados y subtareas

• tdcflow_list_drafts: tareas propuestas pendientes de aprobación, tuyas y de tu equipo

• tdcflow_list_projects, tdcflow_list_phases, tdcflow_list_sprints, tdcflow_list_project_members, tdcflow_list_project_tasks

• tdcflow_list_users, tdcflow_list_tags, tdcflow_list_time_categories

• tdcflow_list_approvers: quién puede aprobar una hoja de tiempos

Escritura:

• tdcflow_create_task: proponer una tarea, o una subtarea con parentTaskId. Te la asigna a menos que pases assignToMe: false.

• tdcflow_update_task: cambiar estado, título, fechas, estimación o ubicación

• tdcflow_assign_task: asignar una tarea a ti mismo

• tdcflow_log_time: una entrada con startedAt y endedAt explícitos

• tdcflow_add_timesheet_entry: una entrada basada en duración en un día de hoja de tiempos

• tdcflow_get_timesheet: la hoja de tiempos semanal con sus entradas y totales

• tdcflow_submit_timesheet: enviar una hoja de tiempos a un aprobador

• tdcflow_delete_time_entry, tdcflow_delete_task, tdcflow_add_tag

Registro de tiempo desde el historial de Git

Pasa instantes reales en lugar del reloj actual. Toma el rango de los propios commits:

git log --since=2026-08-20 --author=Yashasvi --date=iso-strict \
  --pretty='%ad %h %s'

Alimenta las marcas de tiempo del primer y último commit de un bloque de trabajo a tdcflow_log_time como startedAt y endedAt. La herramienta rechaza un endedAt igual o anterior a startedAt.

Límites de permisos

El servidor expone lo que la cuenta puede hacer. En la cuenta de Yashasvi:

• tdcflow_create_task devuelve un borrador con isDraft: true. Un líder lo aprueba antes de que se active.

• No se puede reservar tiempo contra una tarea en borrador. tdcflow_add_timesheet_entry lo comprueba y falla con un motivo claro en lugar del engañoso "does not belong to this project" de la API.

• tdcflow_add_tag necesita projects:write y devuelve 403.

• tdcflow_delete_task necesita tasks:delete y devuelve 403. En su lugar, establece status en cancelled.

• El esfuerzo por asignado es de solo lectura en la interfaz, por lo que ninguna herramienta lo establece. Usa en su lugar estimatedMinutes a nivel de tarea.

• Reasignar a alguien que ya es asignado devuelve 400. tdcflow_assign_task lo reporta como alreadyAssigned en lugar de fallar.

Envío de una hoja de tiempos

El envío notifica a una persona real y bloquea el período, por lo que test.mjs nunca lo dispara. Existen nueve aprobadores, por lo que approverId debe ser explícito; la herramienta los lista en su error cuando lo omites.

tdcflow_submit_timesheet {
  date: '2026-08-26',
  note: 'Week of 24 August',
  approverId: '019ea732-17d2-704a-9e52-c8dc2af0bfec'
}

Períodos de hoja de tiempos

Los períodos van de lunes a domingo y la API los identifica por la fecha del lunes. tdcflow_get_timesheet y tdcflow_add_timesheet_entry lo calculan a partir de cualquier fecha dentro de la semana.