Cronos

PyPI License: MIT Python 3.10+

MCP server for structured daily work diary management — entries, standup summaries, weekly reports, full-text search, and automatic git commits.

---

English

Features

• Add entries: Add new work entries to the daily diary, creating files and directories automatically
• Read diary: Read entries by single date, date range, or last N days
• Standup summary: Generate a high-level, narrative summary ready for standup meetings
• Blockers management: Set and update the blockers section of any diary file
• End-of-day workflow: Rewrite and restructure the day's entries, generate day summary, technical summary, and standup message
• Consolidate diary: Merge fragmented or duplicate entries into a coherent file
• List projects: List all projects worked on in a given period
• Full-text search: Search diary entries with regex support
• Weekly report: Summarize the week grouped by project
• Append to project: Add a sub-section to an existing project entry without fragmentation
• Write end-of-day file: Persist the structured end-of-day content to disk
• Internationalisation: Built-in Italian and English language packs, configurable via cronos.toml
• Git integration: Automatic commit (and optional push) at end-of-day

Installation

pip install mcp-cronos

Or with uv:

uv add mcp-cronos

Configuration

Claude Code (settings.json)

Add the following to your Claude Code settings file (typically ~/.claude/settings.json):

{
  "mcpServers": {
    "cronos": {
      "command": "uvx",
      "args": ["mcp-cronos"],
      "env": {
        "CRONOS_DIARIO_PATH": "/path/to/your/Diary"
      }
    }
  }
}

If you are running from a local checkout instead of the published package:

{
  "mcpServers": {
    "cronos": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/Cronos",
        "run",
        "mcp-cronos"
      ],
      "env": {
        "CRONOS_DIARIO_PATH": "/path/to/your/Diary"
      }
    }
  }
}

The CRONOS_DIARIO_PATH environment variable is required. It must point to the root directory of your diary.

cronos.toml

Place a cronos.toml file in your diary root directory (i.e. $CRONOS_DIARIO_PATH/cronos.toml), or at ~/.config/cronos/cronos.toml. An explicit path can also be set via the CRONOS_CONFIG_PATH environment variable.

All settings are optional and fall back to language-specific defaults when omitted.

[cronos]
# Language: "it" (default) or "en"
lang = "en"

[cronos.sections]
# Override section heading labels used in diary files.
# These must match the headings already present in existing files if you
# are migrating from the default Italian labels.
entries        = "What I did yesterday"
blockers       = "Blockers"
day_summary    = "Daily summary"
tech_summary   = "Technical summary"
standup_message = "Standup message"

[cronos.diary]
# Format string for the file title. Supports {date} placeholder.
title_format = "For Stand-up - {date}"

[cronos.git]
# Enable automatic git commit at end-of-day (default: true)
enabled = true
# Push after committing (default: true)
auto_push = true
# Commit message template. Supports {date} placeholder.
commit_message = "diary: end of day {date}"

Custom Templates

Template files for generated output (end-of-day file, standup message, etc.) can be placed in a templates/ subdirectory inside your diary root. When present, these override the built-in defaults. The server loads templates from $CRONOS_DIARIO_PATH/templates/ automatically.

Tools

cronos_aggiungi_entry

Add a new entry to the daily diary. Creates the file and year/month directory structure if they do not exist.

Required parameters:

• progetto (string): Project name (e.g. "SmarTicket", "MCP Cronos")
• descrizione (string): Short description of the work done (e.g. "Fix auth bug")
• paragrafo_intro (string): Introductory paragraph summarising what was done

Optional parameters:

• contenuto (string): Additional content — sub-sections, bullet points, code
• richiesto_da (string): Name of the person who requested the work
• repository (string): Repository name
• branch (string): Branch name
• jira_ticket (string): Jira ticket code (e.g. "SMART-123")
• jira_url (string): Jira ticket URL
• gitlab_mr (string): GitLab MR number (e.g. "!456")
• gitlab_mr_url (string): GitLab MR URL
• data (string): Date in YYYY-MM-DD format (default: today)

Returns: Confirmation with file path and entry details.

---

cronos_leggi_diario

Read diary content for a date or date range. All parameters are optional; when none are supplied the tool returns today's diary.

Parameters (mutually exclusive, use one):

• data (string): Single date YYYY-MM-DD
• data_inizio + data_fine (strings): Date range YYYY-MM-DD
• ultimi_giorni (integer): Read the last N days

Returns: Diary content including entries, projects, and blockers.

---

cronos_imposta_bloccanti

Set or update the Blockers section of a diary file. The file must already exist (use cronos_aggiungi_entry to create it).

Required parameters:

• bloccanti (string): Blocker text. Use "None" / "Nessuno" when there are no blockers.

Optional parameters:

• data (string): Date YYYY-MM-DD (default: today)

Returns: Confirmation with file path.

---

cronos_riassunto_standup

Generate a narrative, high-level standup summary. The tool returns the raw diary content together with style instructions so that the AI assistant can produce a fluent, professional standup message free of implementation details.

Optional parameters:

• data (string): Single date YYYY-MM-DD (default: last working day)
• data_inizio (string): Range start YYYY-MM-DD
• data_fine (string): Range end YYYY-MM-DD

Returns: Diary content with style instructions for message generation.

---

cronos_fine_giornata

End-of-day workflow trigger. Reads the day's raw entries and returns detailed instructions for generating four structured outputs: rewritten entries, a day summary, a technical summary, and a standup message.

Optional parameters:

• data (string): Date YYYY-MM-DD (default: today)

Returns: Raw diary entries with generation instructions.

---

cronos_consolida_diario

Consolidate the diary by merging fragmented or duplicate entries. The tool reads the current file, identifies structural issues, and returns instructions for rewriting it coherently.

Optional parameters:

• data (string): Date YYYY-MM-DD (default: today)

Returns: File content with analysis and consolidation instructions.

---

cronos_lista_progetti

List all projects mentioned in the diary over a given period.

Optional parameters:

• data_inizio (string): Start date YYYY-MM-DD
• data_fine (string): End date YYYY-MM-DD
• ultimi_giorni (integer): Number of days to analyse (default: 30)

Returns: Project list with occurrence count and dates.

---

cronos_cerca

Full-text search across diary entries. Case-insensitive, with regex support.

Required parameters:

• query (string): Text to search for (supports regular expressions)

Optional parameters:

• data_inizio (string): Search range start YYYY-MM-DD
• data_fine (string): Search range end YYYY-MM-DD
• ultimi_giorni (integer): Days to search (default: 90)

Returns: List of matches with date, project, and surrounding context.

---

cronos_settimana

Weekly summary of the diary grouped by project. Shows how many days each project was worked on during the week, with an activity overview.

Optional parameters:

• data (string): Any date within the week to analyse YYYY-MM-DD (default: current week)

Returns: Per-project summary with day count, dates, and activities.

---

cronos_aggiungi_a_progetto

Append a sub-section (H4) to an existing project entry in today's diary. Avoids fragmentation when logging multiple work sessions on the same project. If no matching project entry is found, a new standard entry is created instead.

Required parameters:

• progetto (string): Exact project name as it appears in the existing H3 heading
• titolo_fase (string): Sub-section title (e.g. "Fix login bug")
• contenuto (string): Sub-section content

Optional parameters:

• richiesto_da (string): Name of the person who requested the work
• repository (string): Repository name
• branch (string): Branch name
• jira_ticket (string): Jira ticket code
• jira_url (string): Jira ticket URL
• gitlab_mr (string): GitLab MR number
• gitlab_mr_url (string): GitLab MR URL
• data (string): Date YYYY-MM-DD (default: today)

Returns: Confirmation with mode (aggiunto_a_esistente or nuova_entry).

---

cronos_scrivi_fine_giornata

Write the end-of-day file with the fully generated content. Use this tool after cronos_fine_giornata: first generate the content following the returned instructions, then call this tool to persist it.

Required parameters:

• contenuto (string): Complete markdown content for the end-of-day file

Optional parameters:

• data (string): Date YYYY-MM-DD (default: today)

Returns: Confirmation with the written file path.

---

Diary Format

File Structure

Diary files are organised in a year/month hierarchy under the diary root:

Diary/
├── cronos.toml          (optional configuration)
├── templates/           (optional custom templates)
└── {year}/
    └── {month}/
        └── {year}-{month}-{day}.md

Example: Diary/2025/04/2025-04-09.md

Markdown Format

# For Stand-up - April 9, 2025

## What I did yesterday

### ProjectName - Short description

Introductory paragraph summarising what was accomplished.

#### Sub-section (optional)

- Detail point 1
- Detail point 2

**References:**
- Repository: repo-name
- Branch: `branch-name`
- Jira: [TICKET-123](https://your.jira/browse/TICKET-123)
- GitLab MR: [MR !456](https://gitlab.example.com/project/-/merge_requests/456)

---

## Blockers

None

Languages

Built-in language packs: Italian (it, default) and English (en). Set via cronos.toml:

[cronos]
lang = "en"

Section headings, month names, weekday names, title format, and default blocker text are all localised automatically when the language is switched.

---

Italiano

Funzionalita'

• Aggiunta entry: Aggiunge nuove entry al diario giornaliero, creando file e cartelle automaticamente
• Lettura diario: Legge le entry per data singola, range di date o ultimi N giorni
• Riassunto standup: Genera un riassunto narrativo ad alto livello pronto per gli standup
• Gestione bloccanti: Imposta e aggiorna la sezione Bloccanti di qualsiasi file del diario
• Workflow fine giornata: Riscrive e ristruttura le entry del giorno, genera riassunto giornata, riassunto tecnico e messaggio standup
• Consolidamento diario: Unisce entry frammentate o duplicate in un file coerente
• Lista progetti: Elenca tutti i progetti su cui si e' lavorato in un periodo
• Ricerca full-text: Cerca nel diario con supporto regex
• Report settimanale: Riassume la settimana raggruppato per progetto
• Aggiungi a progetto: Aggiunge una sotto-sezione a un'entry di progetto esistente senza frammentazione
• Scrivi file fine giornata: Persiste il contenuto strutturato di fine giornata su disco
• Internazionalizzazione: Pacchetti lingua italiano e inglese integrati, configurabili via cronos.toml
• Integrazione Git: Commit automatico (e push opzionale) a fine giornata

Installazione

pip install mcp-cronos

Oppure con uv:

uv add mcp-cronos

Configurazione

Claude Code (settings.json)

Aggiungi al file di configurazione di Claude Code (tipicamente ~/.claude/settings.json):

{
  "mcpServers": {
    "cronos": {
      "command": "uvx",
      "args": ["mcp-cronos"],
      "env": {
        "CRONOS_DIARIO_PATH": "/percorso/al/tuo/Diario"
      }
    }
  }
}

Se stai eseguendo da un checkout locale invece del pacchetto pubblicato:

{
  "mcpServers": {
    "cronos": {
      "command": "uv",
      "args": [
        "--directory",
        "/percorso/a/Cronos",
        "run",
        "mcp-cronos"
      ],
      "env": {
        "CRONOS_DIARIO_PATH": "/percorso/al/tuo/Diario"
      }
    }
  }
}

La variabile d'ambiente CRONOS_DIARIO_PATH e' obbligatoria. Deve puntare alla directory radice del diario.

cronos.toml

Posiziona un file cronos.toml nella directory radice del diario (ovvero $CRONOS_DIARIO_PATH/cronos.toml), oppure in ~/.config/cronos/cronos.toml. Un percorso esplicito puo' essere impostato tramite la variabile d'ambiente CRONOS_CONFIG_PATH.

Tutte le impostazioni sono opzionali e usano i valori predefiniti della lingua quando omesse.

[cronos]
# Lingua: "it" (predefinito) o "en"
lang = "it"

[cronos.sections]
# Sovrascrive le etichette delle sezioni usate nei file del diario.
# Devono corrispondere agli heading presenti nei file esistenti se si sta
# migrando dalle etichette predefinite in italiano.
entries         = "Cosa ho fatto ieri"
blockers        = "Bloccanti"
day_summary     = "Riassunto della giornata"
tech_summary    = "Riassunto tecnico"
standup_message = "Messaggio per lo standup"

[cronos.diary]
# Stringa di formato per il titolo del file. Supporta il placeholder {date}.
title_format = "Per lo Stand-up - {date}"

[cronos.git]
# Abilita commit git automatico a fine giornata (predefinito: true)
enabled = true
# Push dopo il commit (predefinito: true)
auto_push = true
# Template del messaggio di commit. Supporta il placeholder {date}.
commit_message = "diario: fine giornata {date}"

Template Personalizzati

I file template per l'output generato (file di fine giornata, messaggio standup, ecc.) possono essere posizionati in una sottodirectory templates/ all'interno della radice del diario. Quando presenti, questi sovrascrivono i valori predefiniti integrati. Il server carica i template da $CRONOS_DIARIO_PATH/templates/ automaticamente.

Tool

cronos_aggiungi_entry

Aggiunge una nuova entry al diario giornaliero. Crea il file e la struttura di directory anno/mese se non esistono.

Parametri obbligatori:

• progetto (string): Nome del progetto (es. "SmarTicket", "MCP Cronos")
• descrizione (string): Breve descrizione del lavoro svolto (es. "Fix bug autenticazione")
• paragrafo_intro (string): Paragrafo introduttivo che riassume cosa e' stato fatto

Parametri opzionali:

• contenuto (string): Contenuto aggiuntivo — sottosezioni, elenchi puntati, codice
• richiesto_da (string): Nome della persona che ha richiesto il lavoro
• repository (string): Nome del repository
• branch (string): Nome del branch
• jira_ticket (string): Codice ticket Jira (es. "SMART-123")
• jira_url (string): URL del ticket Jira
• gitlab_mr (string): Numero MR GitLab (es. "!456")
• gitlab_mr_url (string): URL della MR GitLab
• data (string): Data nel formato YYYY-MM-DD (predefinito: oggi)

Restituisce: Conferma con path del file e dettagli dell'entry.

---

cronos_leggi_diario

Legge il contenuto del diario per una data o un range di date. Tutti i parametri sono opzionali; se nessuno viene fornito restituisce il diario di oggi.

Parametri (mutualmente esclusivi, usarne uno):

• data (string): Data singola YYYY-MM-DD
• data_inizio + data_fine (string): Range di date YYYY-MM-DD
• ultimi_giorni (integer): Legge gli ultimi N giorni

Restituisce: Contenuto del diario con entry, progetti e bloccanti.

---

cronos_imposta_bloccanti

Imposta o aggiorna la sezione Bloccanti di un file del diario. Il file deve esistere (usare cronos_aggiungi_entry per crearlo).

Parametri obbligatori:

• bloccanti (string): Testo dei bloccanti. Usare "Nessuno" quando non ci sono bloccanti.

Parametri opzionali:

• data (string): Data YYYY-MM-DD (predefinito: oggi)

Restituisce: Conferma con path del file.

---

cronos_riassunto_standup

Genera un riassunto discorsivo ad alto livello per lo standup. Il tool restituisce il contenuto grezzo del diario insieme a istruzioni di stile affinche' l'assistente AI produca un messaggio fluido e professionale privo di dettagli implementativi.

Parametri opzionali:

• data (string): Data singola YYYY-MM-DD (predefinito: ultimo giorno lavorativo)
• data_inizio (string): Inizio range YYYY-MM-DD
• data_fine (string): Fine range YYYY-MM-DD

Restituisce: Contenuto del diario con istruzioni di stile per la generazione del messaggio.

---

cronos_fine_giornata

Avvia il workflow di fine giornata. Legge le entry grezze del giorno e restituisce istruzioni dettagliate per generare quattro output strutturati: entry riscritte, riassunto della giornata, riassunto tecnico e messaggio per lo standup.

Parametri opzionali:

• data (string): Data YYYY-MM-DD (predefinito: oggi)

Restituisce: Entry grezze del diario con istruzioni di generazione.

---

cronos_consolida_diario

Consolida il diario unendo entry frammentate o duplicate. Il tool rilegge il file corrente, identifica i problemi di struttura e restituisce istruzioni per riscriverlo in modo coerente.

Parametri opzionali:

• data (string): Data YYYY-MM-DD (predefinito: oggi)

Restituisce: Contenuto del file con analisi e istruzioni per il consolidamento.

---

cronos_lista_progetti

Elenca tutti i progetti menzionati nel diario in un dato periodo.

Parametri opzionali:

• data_inizio (string): Data inizio YYYY-MM-DD
• data_fine (string): Data fine YYYY-MM-DD
• ultimi_giorni (integer): Numero di giorni da analizzare (predefinito: 30)

Restituisce: Lista progetti con numero di occorrenze e date.

---

cronos_cerca

Ricerca full-text nel diario. Case-insensitive, con supporto regex.

Parametri obbligatori:

• query (string): Testo da cercare (supporta espressioni regolari)

Parametri opzionali:

• data_inizio (string): Inizio range di ricerca YYYY-MM-DD
• data_fine (string): Fine range di ricerca YYYY-MM-DD
• ultimi_giorni (integer): Giorni da cercare (predefinito: 90)

Restituisce: Lista di match con data, progetto e contesto circostante.

---

cronos_settimana

Riassunto settimanale del diario raggruppato per progetto. Mostra su quanti giorni si e' lavorato per ogni progetto durante la settimana, con riepilogo delle attivita'.

Parametri opzionali:

• data (string): Qualsiasi data nella settimana da analizzare YYYY-MM-DD (predefinito: settimana corrente)

Restituisce: Riassunto per progetto con numero di giorni, date e attivita'.

---

cronos_aggiungi_a_progetto

Aggiunge una sotto-sezione (H4) a un'entry di progetto esistente nel diario di oggi. Evita la frammentazione quando si registrano piu' sessioni di lavoro sullo stesso progetto. Se non viene trovata una entry corrispondente, viene creata una nuova entry standard.

Parametri obbligatori:

• progetto (string): Nome esatto del progetto come appare nell'heading H3 esistente
• titolo_fase (string): Titolo della sotto-sezione (es. "Fix bug login")
• contenuto (string): Contenuto della sotto-sezione

Parametri opzionali:

• richiesto_da (string): Nome della persona che ha richiesto il lavoro
• repository (string): Nome del repository
• branch (string): Nome del branch
• jira_ticket (string): Codice ticket Jira
• jira_url (string): URL del ticket Jira
• gitlab_mr (string): Numero MR GitLab
• gitlab_mr_url (string): URL della MR GitLab
• data (string): Data YYYY-MM-DD (predefinito: oggi)

Restituisce: Conferma con modalita' (aggiunto_a_esistente o nuova_entry).

---

cronos_scrivi_fine_giornata

Scrive il file di fine giornata con il contenuto generato. Usare questo tool DOPO cronos_fine_giornata: prima generare il contenuto seguendo le istruzioni ricevute, poi chiamare questo tool per persistere il risultato.

Parametri obbligatori:

• contenuto (string): Contenuto markdown completo del file di fine giornata

Parametri opzionali:

• data (string): Data YYYY-MM-DD (predefinito: oggi)

Restituisce: Conferma con path del file scritto.

---

Formato Diario

Struttura File

I file del diario sono organizzati in una gerarchia anno/mese sotto la directory radice:

Diario/
├── cronos.toml          (configurazione opzionale)
├── templates/           (template personalizzati opzionali)
└── {anno}/
    └── {mese}/
        └── {anno}-{mese}-{giorno}.md

Esempio: Diario/2025/04/2025-04-09.md

Formato Markdown

# Per lo Stand-up - 9 Aprile 2025

## Cosa ho fatto ieri

### NomeProgetto - Breve descrizione

Paragrafo introduttivo che riassume cosa e' stato realizzato.

#### Sottosezione (opzionale)

- Punto di dettaglio 1
- Punto di dettaglio 2

**Riferimenti:**
- Repository: nome-repository
- Branch: `nome-branch`
- Jira: [TICKET-123](https://your.jira/browse/TICKET-123)
- Gitlab Mr: [MR !456](https://gitlab.esempio.it/progetto/-/merge_requests/456)

---

## Bloccanti

Nessuno

Lingue

Pacchetti lingua integrati: Italiano (it, predefinito) e Inglese (en). Si imposta via cronos.toml:

[cronos]
lang = "it"

Intestazioni di sezione, nomi dei mesi, nomi dei giorni della settimana, formato del titolo e testo predefinito dei bloccanti sono tutti localizzati automaticamente al cambio della lingua.

---

License

MIT