Timesheet MCP (PRIS)

Servidor MCP (Model Context Protocol) en Python que mantiene el control horario del profesional en un archivo JSON editable entre sesiones y, al pedirlo, renderiza un .xlsx respetando la plantilla Timesheet Modelo Mayo 2025 PRIS.xlsx (logo, merges, formulas).

Stack

• Python 3.11+

• openpyxl 3.1+

• mcp[cli] 1.0+

• pydantic 2.6+

Related MCP server: timesheet-data

Estructura

timesheet/
  models.py      # pydantic: Professional, Supervisor, DayItem, Day, State
  state.py       # load_state, save_state, mutadores puros
  dates.py       # working_days(year, month) y agregaciones
  renderer.py    # render(state, template, out) + plan B de imagen
template/        # copia inmutable de la plantilla PRIS
data/            # state.json (se crea al primer arranque)
exports/         # salida de export_to_excel
tests/           # smoke test (10 casos del spec + extras de borde)
server.py        # entrypoint MCP stdio, 11 tools

Setup (Windows)

# 1. Instalar Python 3.11+ desde python.org (marca "Add to PATH")
# 2. Desde la raiz del proyecto:
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
# 3. Verificar que la plantilla este copiada en template/
# 4. Smoke test:
python tests/smoke_test.py

Registro en cliente MCP

OpenCode (recomendado — ya configurado en este proyecto)

El MCP timesheet ya esta registrado globalmente en %USERPROFILE%\.config\opencode\opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "timesheet": {
      "type": "local",
      "command": [
        "C:\\proyectos\\timesheet\\.venv\\Scripts\\python.exe",
        "C:\\proyectos\\timesheet\\server.py"
      ],
      "cwd": "C:\\proyectos\\timesheet",
      "enabled": true,
      "timeout": 15000
    }
  }
}

Disponible en cualquier sesion de opencode (en cualquier directorio de trabajo) con solo mencionarlo en el prompt, p.ej.:

use timesheet para cargar las horas de hoy y exportar el excel del mes

Verificacion:

opencode mcp list
# -> ✓ timesheet  connected

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "timesheet": {
      "command": "C:\\proyectos\\timesheet\\.venv\\Scripts\\python.exe",
      "args": ["C:\\proyectos\\timesheet\\server.py"]
    }
  }
}

Tools (11)

Notas

• Recalculo de formulas al abrir: el servidor setea wb.calculation.fullCalcOnLoad = True para que Excel/LibreOffice recalcule automaticamente. Si no se ve el total actualizado al abrir el archivo, presione F9 o Ctrl+Alt+F9.

• Paginas multiples: si el mes tiene mas de 22 laborables (caso conocido: 2027-07 y 2027-12), el archivo exportado puede ocupar 2 paginas impresas. La impresion usa fitToPage=true del template.

• Imagen del logo: openpyxl generalmente la preserva. Como salvaguarda el renderer aplica un Plan B con zipfile tras el save, copiando xl/media/ y xl/drawings/_rels/*.rels desde la plantilla original si hace falta. Si la imagen sigue sin aparecer, verifique la consola para el warning de respuesta.

• Encoding: el JSON se persiste en UTF-8 con ensure_ascii=False, preservando acentos y tildes (ej: "Raúl").

• Persistencia atomica: cada mutacion escribe a state.json.tmp y luego hace os.replace. No hay state.json huerfano a medio escribir.