Chronos Protocol

Um servidor MCP robusto que elimina a cegueira temporal em

Documentação

Chronos Protocol

Servidor MCP que fornece inteligência temporal, memória persistente e rastreabilidade completa para agentes de codificação de IA.

O Chronos Protocol transforma os fluxos de trabalho de desenvolvimento de IA ao eliminar a cegueira temporal em sistemas automatizados. O servidor MCP fornece rastreabilidade completa e continuidade de sessão, permitindo que agentes de IA mantenham contexto entre sessões, enquanto oferece rastreamento de tempo de nível empresarial, agendamento inteligente e análises abrangentes de desenvolvimento.

Contexto

Capacidades Principais

O Chronos Protocol aborda lacunas críticas nos fluxos de trabalho de desenvolvimento de IA por meio de inteligência temporal sofisticada e sistemas de memória persistente projetados especificamente para ambientes de codificação automatizados.

Abordagem de Tempo do Sistema Primeiro

O Chronos Protocol transforma a forma como sistemas automatizados lidam com o tempo ao priorizar o horário do sistema local do seu computador como o padrão inteligente. Sem mais confusão de fusos horários — basta usar "system" ou "local" e obter consciência temporal instantânea e contextual que se adapta ao seu ambiente.

Inteligência Temporal Principal

get_current_time - Consciência Temporal Simplificada

O Chronos Protocol prioriza o horário do sistema local do seu computador como o padrão inteligente. A maioria dos IDEs de IA já incorpora o horário do sistema em seus prompts, mas o Chronos Protocol fornece contexto temporal explícito e estruturado que funciona em todos os clientes MCP.

Obtenha carimbos de data/hora padronizados com contexto do sistema:

Prioridade do Horário do Sistema: Usa o horário local do sistema como padrão inteligente
Colaboração Entre Fusos: Mostra o horário local junto com o fuso da equipe para projetos globais
Contexto Temporal: Agentes de IA sempre sabem "quando" estão operando para melhor tomada de decisões

convert_time - Tradução Inteligente de Fusos Horários

Elimine erros de cálculo de fusos horários com conversão inteligente:

Agendamento de Reuniões: Converta horários entre fusos horários globais
Planejamento de Lançamentos: Coordene implantações entre regiões
Análise de Diferença de Horário: Calcule offsets de fuso horário com tratamento de horário de verão (DST)

Sistema de Inteligência de Atividades

start_activity_log - Inicialização de Contexto Inteligente

Inicie o monitoramento sofisticado de atividades com IDs de Atividade únicos e metadados ricos para fluxos de trabalho de desenvolvimento agêntico:

Gerenciamento Autônomo de Sessões: Rastreie sessões de codificação, processos de depuração e implementações de funcionalidades com contexto persistente
Análise Inteligente de Tarefas: Monitore e aprenda com padrões de conclusão de tarefas para otimizar o planejamento futuro
Preservação de Contexto: Mantenha registros precisos para continuidade entre sessões e retomada perfeita de tarefas

end_activity_log - Documentação e Análise de Sucesso

Complete atividades com cálculo automático de duração e dados ricos de resultado para inteligência de desempenho:

Auto-Análise de Desempenho: Analise tempos reais vs. estimados de conclusão para melhor precisão no planejamento futuro
Documentação Autônoma: Documente conquistas e lições aprendidas para retenção persistente de conhecimento
Desempenho Adaptativo: Construa inteligência histórica sobre a velocidade de desenvolvimento e padrões de sucesso

get_elapsed_time - Monitoramento de Progresso em Tempo Real

Monitore atividades em andamento sem interromper o fluxo de execução:

Gerenciamento de Tarefas de Longa Duração: Verifique o progresso em depurações extensas ou implementações complexas
Caixa de Tempo Inteligente: Monitore e otimize sessões de trabalho para máxima eficiência
Consciência de Contexto: Rastreie a duração de diferentes fases em processos de resolução de problemas

get_activity_logs - Inteligência Histórica e Análise de Padrões

Consulte e analise padrões de desenvolvimento com filtragem sofisticada:

Reconhecimento Autônomo de Padrões: Gere relatórios de desempenho e identifique oportunidades de otimização
Análise de Auto-Aprendizagem: Identifique quais tipos de tarefas exigem mais recursos e adapte a abordagem conforme necessário
Aprendizado Entre Projetos: Aproveite a experiência de diferentes projetos para melhorar a eficácia geral

update_activity_log - Gerenciamento Inteligente de Atividades

Modifique atividades concluídas com insights atualizados e correções:

Aprendizagem Autônoma: Adicione insights descobertos após a conclusão da tarefa para referência futura
Auto-Correção: Corrija erros de tempo ou atualize descrições de tarefas com base em novas informações
Documentação Contínua: Atualize resultados e aprendizados à medida que os projetos evoluem e novos contextos surgem

Sistema Inteligente de Lembretes

create_time_reminder - Agendamento Contextual de Tarefas

Defina lembretes inteligentes vinculados ao seu fluxo de trabalho de desenvolvimento:

Acompanhamento de Revisão de Código: Nunca esqueça de verificar solicitações de pull pendentes
Atualizações de Dependências: Agende verificações regulares para pacotes desatualizados e patches de segurança
Pontos de Verificação de Lançamento: Defina lembretes para janelas de implantação, teste e rollback

check_time_reminders - Sistema de Consciência Proativa

Fique à frente de tarefas importantes com detecção inteligente de lembretes:

Prazos Próximos: Receba avisos antecipados de marcos de projeto que se aproximam
Janelas de Manutenção: Seja lembrado de manutenção de sistema ou implantações agendadas
Coordenação de Equipe: Nunca perca sessões colaborativas ou check-ins importantes

Declaração do Problema

Resolve Problemas Reais

Elimina a Cegueira Temporal da IA: Seus agentes de IA podem verificar ativamente o horário atual e tomar decisões conscientes do tempo, em vez de depender exclusivamente do horário incorporado no Prompt do Sistema
Reduz a Troca de Contexto: Agentes de IA podem rastrear o tempo sem interromper seu fluxo
Continuidade Entre Projetos: Comece o rastreamento no Projeto A, termine no Projeto B — tudo permanece conectado
Design Centrado no Desenvolvedor: Construído especificamente para fluxos de trabalho de codificação agênticos, não para rastreamento de tempo genérico

Arquitetura

Arquitetura de Armazenamento Flexível

O Chronos Protocol suporta dois modos de armazenamento para se adequar ao seu fluxo de trabalho de desenvolvimento:

Modo Centralizado (Tradicional)

Banco de dados único para todos os projetos
Análises entre projetos e inteligência histórica
Ideal para: Equipes que desejam rastreamento de tempo unificado em todo o trabalho
Integração com Frameworks de IA: Memória persistente funciona em todos os projetos

Modo Por Projeto (Dinâmico)

Detecção automática de projeto com zero configuração
Armazenamento isolado por projeto ({project-root}/chronos-data/time_server_data.json)
Ideal para: Desenvolvedores individuais que preferem rastreamento específico por projeto
Zero Configuração: Basta usar --storage-mode per-project e funciona em qualquer lugar

Integração com a Estrutura de Engenharia de Contexto

O sistema de registro de atividades do Chronos Protocol fornece memória persistente para frameworks de IA como Claude Task Master, Agent OS e Método BMAD, permitindo rastreamento aprimorado de tarefas, registro centralizado de atividades e análise histórica com IDs de Atividade persistentes nas operações do agente.

Guia de Integração: Para agentes de codificação de IA, consulte o modelo de prompt de exemplo em AGENTS.md, que fornece Regras de Cursor que podem ser integradas às suas regras de fluxo de trabalho existentes. Este modelo demonstra o protocolo completo de registro de atividades com padrões de nome de arquivo de lista de tarefas personalizáveis.

Benefícios da Memória Persistente

Continuidade entre Sessões: Tarefas iniciadas em uma sessão podem ser rastreadas e concluídas em outra
Armazenamento Independente de Framework: Banco de dados JSON funciona com qualquer framework de IA que possa anexar IDs de Atividade
Preservação Rica de Contexto: Metadados completos de atividade, incluindo duração, resultados e tags personalizadas
Inteligência Histórica: Frameworks de IA podem consultar atividades passadas para reconhecimento de padrões e otimização

Instalação

Pré-requisitos

Python: 3.10 ou superior
Suporte a MCP: Cliente de IA com suporte ao Model Context Protocol

Etapas de Instalação

# 1. Clone the repository
git clone https://github.com/n0zer0d4y/chronos-protocol.git
cd chronos-protocol

# 2. Install dependencies
pip install -r requirements.txt

# 3. Install in editable mode (required for MCP)
pip install -e .

# 4. Verify installation
python -m chronos_protocol --help

Após a instalação, configure o Chronos Protocol no seu cliente MCP usando o esquema de configuração apropriado na seção Configuração.

Uso

Operações Básicas de Inteligência Temporal

Obter Hora Atual com Contexto

# Get current time in your system's timezone
get_current_time(timezone="system")
# Returns: Current time with full timezone context

Conversão Inteligente de Fuso Horário

# Convert meeting time across timezones
convert_time(
  source_timezone="America/New_York",
  time="15:00",
  target_timezone="Europe/London"
)
# Returns: Converted time with timezone difference

Fluxo de Inteligência de Atividades

Rastreamento Completo de Sessão de Desenvolvimento

# 1. Start activity logging
activity_id = start_activity_log(
    activityType="debugging",
    task_scope="feature-implementation",
    description="Fix authentication module login flow"
)

# 2. AI agent works on the task...
# Monitor progress with get_elapsed_time(activity_id)

# 3. Complete with results
end_activity_log(
    activity_id,
    result="Authentication module completed successfully"
)

Análise Inteligente de Tarefas

# Get activity history for pattern analysis
activities = get_activity_logs(
    activityType="debugging",
    task_scope="feature-implementation"
)

# AI learns from patterns and timing
for activity in activities:
    analyze_completion_time(activity)
    identify_successful_patterns(activity)

Continuidade entre Sessões

# Check for ongoing activities
ongoing = get_activity_logs(status="ongoing")
if ongoing:
    # Resume where you left off
    continue_activity(ongoing[0]["activityId"])

# Learning from history
debug_sessions = get_activity_logs(
    activityType="debugging",
    start_date="2024-01-01"
)

Exemplo de Integração com Framework de IA

# Example: AI Framework Integration
activity_id = start_activity_log(
    activityType="framework_task",
    task_scope="feature-implementation",
    description="AI agent implementing authentication module",
    tags=["ai-agent", "claude-task-master"]
)

# Your framework stores the activity_id with task data
# Later: end_activity_log(activity_id, result="Authentication module completed")

Isso cria um ciclo de feedback inteligente onde frameworks de IA aprendem com o desempenho histórico de tarefas e padrões de tempo!

API

Funções de Inteligência Temporal

`get_current_time(timezone)`

Obtenha carimbos de data/hora padronizados com contexto do sistema.

Parâmetros:

timezone (string): Fuso horário de destino. Use "system" ou "local" para o horário local do usuário, ou nomes IANA como "America/New_York", "Europe/London", "UTC"

Retorna: Hora atual com contexto completo de fuso horário e metadados

`convert_time(source_timezone, time, target_timezone)`

Converta a hora entre fusos horários com tratamento inteligente de DST.

Parâmetros:

source_timezone (string): Fuso horário de origem
time (string): Hora no formato 24 horas (HH:MM)
target_timezone (string): Fuso horário de destino

Retorna: Hora convertida com informações de diferença de fuso horário

Funções de Inteligência de Atividades

`start_activity_log(activityType, task_scope, description, tags?)`

Inicialize o monitoramento de atividade com ID de Atividade único e metadados ricos.

Parâmetros:

activityType (string): Tipo de atividade (ex.: 'debugging', 'feature-implementation')
task_scope (string): Escopo da tarefa a partir de opções predefinidas
description (string): Descrição detalhada da atividade
tags (array, opcional): Matriz de strings para categorizar a atividade

Retorna: ID de Atividade único para rastreamento

`end_activity_log(activityId, result?, notes?)`

Complete a atividade com cálculo automático de duração e dados ricos de resultado.

Parâmetros:

activityId (string): Identificador único da atividade a encerrar
result (string, opcional): Resultado ou desfecho da atividade
notes (string, opcional): Notas adicionais sobre a atividade

Retorna: Atividade concluída com duração e carimbos de data/hora

`get_elapsed_time(activityId)`

Monitore atividades em andamento sem interromper o fluxo de execução.

Parâmetros:

activityId (string): Identificador único da atividade

Retorna: Informações de tempo decorrido para a atividade especificada

`get_activity_logs(filters?)`

Consulte e analise padrões de desenvolvimento com filtragem sofisticada.

Parâmetros:

filters (objeto, opcional): Opções de filtragem incluindo:
- activityType (string): Filtrar por tipo de atividade
- task_scope (string): Filtrar por escopo da tarefa
- startDate (string): Filtrar por data de início (formato ISO 8601)
- endDate (string): Filtrar por data de término (formato ISO 8601)
- limit (inteiro): Número máximo de logs a retornar

Retorna: Matriz de logs de atividade que correspondem aos critérios

`update_activity_log(activityId, updates)`

Modifique atividades concluídas com insights atualizados e correções.

Parâmetros:

activityId (string): Identificador único da atividade a atualizar
updates (objeto): Objeto contendo os campos a atualizar

Retorna: Log de atividade atualizado

Funções do Sistema de Lembretes

`create_time_reminder(reminderTime, message, relatedTaskId?)`

Crie lembrete baseado em hora usando o horário do sistema para agendamento.

Parâmetros:

reminderTime (string): Hora do lembrete (formato ISO 8601 com fuso horário)
message (string): Mensagem do lembrete
relatedTaskId (string, opcional): ID da tarefa ou atividade relacionada Retorna: Lembrete criado com identificador único

`check_time_reminders(upcomingMinutes?)`

Verifique lembretes com vencimento ou futuros.

Parâmetros:

upcomingMinutes (inteiro, opcional): Verifique lembretes com vencimento dentro deste número de minutos (padrão: 60)

Retorna: Matriz de lembretes vencidos e futuros

Configuração

Chronos Protocol suporta dois modos de armazenamento:

Modo	Caso de Uso	Localização dos Dados
Por Projeto	Isolamento de projeto individual	`{project-root}/chronos-data/time_server_data.json`
Centralizado	Análise entre projetos	Diretório personalizado via `--data-dir`

Opções de Formato de ID

Formato	Exemplo	Comprimento	Caso de Uso
`custom`	`28RCD6M8A64P`	12 caracteres	Ultracompacto para listas de tarefas
`short`	`vytxeTZskVKR7C7WgdSP3d`	22 caracteres	Legibilidade equilibrada
`uuid`	`bb401d9e-1c3e-41d4-a201-733baa48c13d`	36 caracteres	Compatibilidade legada

Importante: Aviso sobre Parâmetro de Tipo

NÃO adicione "type": "stdio" à sua configuração MCP.

Por que isso causa falhas:

Chronos Protocol é codificado para usar transporte stdio
Quando clientes adicionam "type": "stdio", isso pode interferir na resolução de variáveis
A substituição de variáveis ocorre antes da validação de tipo
Resulta em caminhos inválidos como C:\Program Files\VSCode\${workspaceFolder}

Abordagem correta:

Deixe o Chronos Protocol lidar com a seleção de transporte automaticamente
Especifique "type" somente se seu cliente MCP exigir E você não estiver usando variáveis
A maioria dos clientes MCP funciona perfeitamente sem declaração explícita de tipo

Extensões do VS Code e forks

Extensão Roo Code

{
  "mcpServers": {
    "chronos-protocol": {
      "command": "python",
      "args": [
        "-m",
        "chronos_protocol",
        "--storage-mode",
        "per-project",
        "--project-root",
        "${workspaceFolder}",
        "--id-format",
        "custom"
      ]
    }
  }
}

Forks do VS Code

Cursor & Trae

{
  "mcpServers": {
    "chronos-protocol": {
      "command": "python",
      "args": [
        "-m",
        "chronos_protocol",
        "--storage-mode",
        "per-project",
        "--project-root",
        "${workspaceFolder}",
        "--id-format",
        "custom"
      ]
    }
  }
}

Clientes CLI

Claude Code & Gemini CLI

{
  "chronos-protocol": {
    "command": "python",
    "args": [
      "-m",
      "chronos_protocol",
      "--storage-mode",
      "per-project",
      "--id-format",
      "custom"
    ]
  }
}

Clientes com Suporte Limitado

Cline & Qoder

Limitações conhecidas:

Não suporta substituição de variáveis ${workspaceFolder}
Não é possível usar o modo de armazenamento por projeto
Falhará se o argumento --project-root for incluído
Limitado apenas ao armazenamento centralizado

Configuração funcional:

{
  "chronos-protocol": {
    "disabled": false,
    "timeout": 60,
    "command": "python",
    "args": [
      "-m",
      "chronos_protocol",
      "--storage-mode",
      "centralized",
      "--data-dir",
      "/path/to/centralized/chronos-data",
      "--id-format",
      "custom"
    ]
  }
}

NÃO adicione:

--project-root "${workspaceFolder}" (causa falhas)
Parâmetro "type": "stdio" (veja a seção Importante acima)

Importante: Aviso sobre Parâmetro de Tipo

NÃO adicione "type": "stdio" à sua configuração MCP

Por que isso causa falhas:

Chronos Protocol é codificado para usar transporte stdio
Quando clientes adicionam "type": "stdio", isso pode interferir na resolução de variáveis
A substituição de variáveis ocorre antes da validação de tipo
Resulta em caminhos inválidos como C:\Program Files\VSCode\${workspaceFolder}

Abordagem correta:

Deixe o Chronos Protocol lidar com a seleção de transporte automaticamente
Especifique "type" somente se seu cliente MCP exigir E você não estiver usando variáveis
A maioria dos clientes MCP funciona perfeitamente sem declaração explícita de tipo

Solução de Problemas

Problemas Comuns

Erro "Nenhuma ferramenta ou prompt"

Sintomas:

O servidor MCP parece conectado
As ferramentas não estão disponíveis no cliente
Nenhuma mensagem de erro visível

Soluções por Cliente:

Cursor:

Certifique-se de que --project-root "${workspaceFolder}" está incluído
Verifique se o workspace está abertamente corretamente

Claude Code:

Remova o argumento --project-root (use detecção padrão)
Não adicione o parâmetro "type": "stdio"

Cline/Qoder:

Use o modo de armazenamento centralizado
Remova todas as variáveis do workspace
Defina o caminho --data-dir explicitamente

Problemas de Substituição de Variáveis

Problema: ${workspaceFolder} não está sendo resolvido Clientes Afetados: Cline, Qoder, algumas configurações do Claude Code

Solução:

{
  "chronos-protocol": {
    "command": "python",
    "args": [
      "-m",
      "chronos_protocol",
      "--storage-mode",
      "centralized",
      "--data-dir",
      "/explicit/path/to/chronos-data"
    ]
  }
}

Erros de Permissão de Armazenamento

Erro: Não é possível criar o diretório chronos-data Solução:

Garanta permissões de escrita no diretório do projeto
Para o modo por projeto, verifique as permissões do workspace
Para o modo centralizado, verifique a acessibilidade de --data-dir

Módulo Python Não Encontrado

Erro: ModuleNotFoundError: No module named 'chronos_protocol' Solução:

# Ensure editable installation
pip install -e .
   # Verify installation
python -m chronos_protocol --help

Problemas Específicos do Cliente

Extensões do VS Code

Certifique-se de que a extensão MCP está habilitada
Verifique a compatibilidade da versão do VS Code
Verifique se o workspace está abertamente corretamente

Forks do VS Code

Alguns forks podem ter implementações MCP personalizadas
Consulte a documentação específica do fork
Relate problemas aos mantenedores do fork

Clientes CLI

Garanta a formatação JSON adequada
Verifique as permissões dos arquivos de configuração
Verifique a configuração do ambiente Python

Otimização de Desempenho

Logs de Atividades Grandes

Use o formato de ID apropriado para seu caso de uso
Considere o armazenamento centralizado para análises entre projetos
Arquive atividades antigas periodicamente

Uso de Memória

O modo por projeto isola o uso de memória
O modo centralizado pode acumular dados ao longo do tempo
Monitore os tamanhos dos diretórios de armazenamento

Obtendo Ajuda

Suporte da Comunidade

Verifique os problemas do GitHub para problemas semelhantes
Forneça logs de erro detalhados e configuração
Inclua a versão do cliente e informações da plataforma

Informações de Depuração

# Get detailed server logs
python -m chronos_protocol --verbose

# Check MCP client logs
# (varies by client - check client documentation)

Contribuindo

Configuração de Desenvolvimento

# Fork and clone
git clone https://github.com/n0zer0d4y/chronos-protocol.git
cd chronos-protocol

# Set up development environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt
pip install -e .

# Run tests
pytest tests/

# Run with debug logging
python -m chronos_protocol --debug

Padrões de Código

Python: Siga as diretrizes de estilo PEP 8
Documentação: Use docstrings no estilo Google
Testes: Mantenha cobertura de testes >90%
Commits: Use formato de commit convencional

Testando Clientes MCP

Ao adicionar suporte para novos clientes MCP:

Teste com ambos os modos de armazenamento
Verifique se todas as ferramentas funcionam corretamente
Verifique os cenários de tratamento de erros
Atualize a documentação de configuração
Adicione à matriz de compatibilidade

Reportando Bugs

Modelo de Relatório de Bug:

Nome e versão do cliente MCP
Configuração usada
Comportamento esperado vs. real
Logs de erro (se disponíveis)
Passos para reproduzir

Licença

Este projeto é licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

Agradecimentos

Anthropic pela especificação do Model Context Protocol
Comunidade MCP pelas implementações de clientes e testes
Contribuidores pelos valiosos feedbacks e relatórios de bugs

Pronto para transformar seu fluxo de trabalho de desenvolvimento de IA? Configure o Chronos Protocol no seu cliente MCP e comece a construir com rastreabilidade completa e continuidade de sessão.