TimeChimp MCP Server

Um servidor para interagir com a API v2 do TimeChimp para gerenciar controle de horas e projetos.

GitHub
4
Experimente este MCPPatrocinado

Documentação

TimeChimp MCP Server

Um servidor abrangente do Model Context Protocol (MCP) para interagir com a API v2 do TimeChimp. Este servidor fornece ferramentas para recuperar e gerenciar todos os principais recursos do TimeChimp, incluindo projetos, usuários, lançamentos de horas, contatos, clientes, tarefas, faturas, despesas, quilometragem e tags.

Recursos

  • Projetos: Operações CRUD completas (Criar, Ler, Atualizar, Excluir) com gerenciamento abrangente de projetos, incluindo faturamento, orçamento, atribuições de tarefas/usuários e insights
  • Usuários: Operações CRUD completas (Criar, Ler, Atualizar, Excluir) com gerenciamento de usuários, incluindo funções, contratos, tags e informações de funcionários
  • Lançamentos de Horas: Buscar lançamentos de horas com intervalos de datas, filtros por usuário/projeto e ordenação
  • Contatos: Operações CRUD completas (Criar, Ler, Atualizar, Excluir) para gerenciamento de contatos
  • Clientes: Operações CRUD completas (Criar, Ler, Atualizar, Excluir) para gerenciamento de clientes
  • Tarefas: Obter informações de tarefas com filtro por projeto e ordenação
  • Faturas: Recuperar faturas com filtro por cliente e data
  • Despesas: Operações CRUD completas (Criar, Ler, Atualizar, Excluir) para gerenciamento de despesas com acompanhamento de status
  • Quilometragem: Operações CRUD completas (Criar, Ler, Atualizar, Excluir) para gerenciamento de quilometragem com acompanhamento de status e atribuição de veículos
  • Veículos de Quilometragem: Recuperar informações de veículos de quilometragem para atribuição de veículos
  • Tags: Obter informações de tags para organização e categorização
  • Construído como um único arquivo JavaScript para facilitar a implantação
  • Usa a API v2 do TimeChimp com autenticação adequada e convenções OData
  • Tratamento abrangente de erros e validação
  • Suporte para $expand, $count e todos os parâmetros de consulta OData

Pré-requisitos

  • Node.js 18.0.0 ou superior
  • Uma conta TimeChimp com acesso à API
  • Chave de API do TimeChimp

Instalação

  1. Clone ou baixe este repositório:
git clone <repository-url>
cd TimeJS
  1. Instale as dependências:
npm install
  1. Torne o servidor executável:
chmod +x timechimp-mcp-server.js

Configuração

Configuração da Chave de API

Você precisa definir sua chave de API do TimeChimp como uma variável de ambiente:

export TIMECHIMP_API_KEY="your-api-key-here"

Ou crie um arquivo .env:

TIMECHIMP_API_KEY=your-api-key-here

Obtendo Sua Chave de API do TimeChimp

  1. Faça login na sua conta TimeChimp
  2. Vá para as configurações do seu perfil
  3. Navegue até a seção de API
  4. Gere ou copie sua chave de API

Integração com Claude Desktop

Para usar este servidor MCP do TimeChimp com o Claude Desktop, você precisa adicioná-lo à configuração do Claude Desktop.

Passo 1: Clone o Repositório

git clone https://github.com/Sungdaddy/TimeyChimpey.git
cd TimeyChimpey
npm install

Passo 2: Configure Sua Chave de API

Crie um arquivo .env no diretório do projeto:

echo "TIMECHIMP_API_KEY=your-actual-api-key-here" > .env

Passo 3: Configure o Claude Desktop

Adicione a seguinte configuração às configurações do Claude Desktop. A localização do arquivo de configuração depende do seu sistema operacional:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "timechimp": {
      "command": "node",
      "args": ["timechimp-mcp-server.js"],
      "cwd": "/path/to/your/TimeyChimpey",
      "env": {
        "TIMECHIMP_API_KEY": "your-actual-api-key-here"
      }
    }
  }
}

Importante: Substitua /path/to/your/TimeyChimpey pelo caminho real onde você clonou o repositório e substitua your-actual-api-key-here pela sua chave de API real do TimeChimp.

Passo 4: Reinicie o Claude Desktop

Após adicionar a configuração, reinicie o Claude Desktop completamente para que as alterações tenham efeito.

Passo 5: Verifique a Integração

Após o Claude Desktop reiniciar, você deve conseguir usar comandos relacionados ao TimeChimp. Tente pedir ao Claude para:

  • "Obter todos os meus projetos do TimeChimp"
  • "Mostrar lançamentos de horas recentes"
  • "Listar todos os clientes"
  • "Criar um novo lançamento de despesa"

Exemplo de Configuração

Aqui está um exemplo completo de arquivo de configuração:

{
  "mcpServers": {
    "timechimp": {
      "command": "node",
      "args": ["timechimp-mcp-server.js"],
      "cwd": "/Users/yourname/TimeyChimpey",
      "env": {
        "TIMECHIMP_API_KEY": "your-actual-api-key-here"
      }
    }
  }
}

Solução de Problemas da Integração com Claude Desktop

  1. Servidor não conectando: Certifique-se de que o caminho em cwd está correto e aponta para o diretório que contém timechimp-mcp-server.js

  2. Erros de chave de API: Verifique se sua chave de API está correta e possui as permissões adequadas no TimeChimp

  3. Node.js não encontrado: Certifique-se de que o Node.js está instalado e acessível pela linha de comando

  4. Erros de permissão: Certifique-se de que o Claude Desktop tem permissão para executar o Node.js e acessar o diretório do projeto

  5. Configuração não carregando: Verifique novamente a sintaxe JSON no seu arquivo de configuração - deve ser JSON válido

Ferramentas Disponíveis no Claude Desktop

Uma vez configurado, você terá acesso a todas as 46 ferramentas do TimeChimp através do Claude Desktop:

  • Projetos: Criar, ler, atualizar, excluir projetos com insights
  • Usuários: Gerenciar usuários com contratos e funções
  • Lançamentos de Horas: Rastrear e gerenciar lançamentos de horas
  • Contatos: Gerenciamento completo de contatos
  • Clientes: Gerenciamento completo do ciclo de vida do cliente
  • Despesas: Rastreamento de despesas com fluxos de aprovação
  • Quilometragem: Rastreamento de quilometragem com gerenciamento de veículos
  • E muito mais...

Você pode pedir ao Claude para realizar qualquer operação do TimeChimp naturalmente, como "Criar um novo projeto para o cliente ABC" ou "Mostrar todas as despesas pendentes que precisam de aprovação."

Uso

Executando o Servidor

# Start the server
npm start

# Or run directly
node timechimp-mcp-server.js

# For development with debugging
npm run dev

Ferramentas Disponíveis

Projetos

1. get_projects

Recuperar projetos do TimeChimp.

Parâmetros:

  • top (número, opcional): Número máximo de projetos a retornar (1-10000, padrão: 100)
  • skip (número, opcional): Número de projetos a pular para paginação (padrão: 0)
  • count (booleano, opcional): Se deve incluir a contagem total de resultados (padrão: true)
  • expand (string, opcional): Lista separada por vírgulas de propriedades para expandir (ex.: "customer,tasks")
  • active_only (booleano, opcional): Retornar apenas projetos ativos (padrão: false)
  • filter (string, opcional): Expressão de filtro OData
  • orderby (string, opcional): Expressão de ordenação OData

Exemplo:

{
  "name": "get_projects",
  "arguments": {
    "top": 50,
    "active_only": true,
    "expand": "customer,tasks",
    "orderby": "name desc"
  }
}
2. get_project_by_id

Obter um projeto específico por ID.

Parâmetros:

  • id (número, obrigatório): ID do projeto
  • expand (string, opcional): Lista separada por vírgulas de propriedades para expandir

Exemplo:

{
  "name": "get_project_by_id",
  "arguments": {
    "id": 123,
    "expand": "customer,tasks"
  }
}
3. create_project

Criar um novo projeto.

Parâmetros:

  • name (string, obrigatório): O nome do projeto
  • active (booleano, opcional): Se o projeto pode ser usado (padrão: true)
  • code (string, opcional): O código do projeto
  • notes (string, opcional): A descrição do projeto
  • color (string, opcional): A cor do projeto
  • startDate (string, opcional): A data de início do projeto (formato AAAA-MM-DD)
  • endDate (string, opcional): A data de término do projeto (formato AAAA-MM-DD)
  • invoicing (objeto, opcional): As configurações de faturamento do projeto
    • method (string, opcional): O método de faturamento do projeto usado
      • Valores permitidos: NoInvoicing, TaskHourlyRate, UserHourlyRate, ProjectHourlyRate, CustomerHourlyRate, ProjectRate, TaskRate
    • hourlyRate (número, opcional): A taxa horária do projeto (usada apenas quando o método de faturamento = ProjectHourlyRate)
    • fixedRate (número, opcional): A taxa/preço fixo do projeto (usado apenas quando o método de faturamento = ProjectRate)
    • reference (string, opcional): A referência de faturamento do projeto
    • date (string, opcional): A data de faturamento do projeto (formato AAAA-MM-DD, usado apenas quando o método de faturamento = ProjectRate)
  • budget (objeto, opcional): As configurações de orçamento do projeto
    • method (string, opcional): O método de orçamento do projeto usado
      • Valores permitidos: NoBudget, TotalHours, TaskHours, UserHours, TotalRate, TaskRate, TotalCost
    • hours (número, opcional): O orçamento horário do projeto (usado apenas quando o método de orçamento = TotalHours)
    • rate (número, opcional): A taxa de orçamento do projeto (usada apenas quando o método de orçamento = TotalRate ou TotalCost)
    • notificationPercentage (número, opcional): O limite percentual do orçamento no qual uma notificação é enviada
  • customer (objeto, opcional): Cliente a ser vinculado ao projeto
    • id (número, obrigatório): Identificador único do cliente
  • mainProject (objeto, opcional): Projeto principal a ser vinculado ao projeto (se for um subprojeto)
    • id (número, obrigatório): Identificador único do projeto
  • subprojects (array, opcional): Lista de subprojetos a serem vinculados ao projeto (se for um projeto principal)
  • managers (array, opcional): Lista de gerentes a serem vinculados ao projeto
  • tags (array, opcional): Lista de tags a serem vinculadas ao projeto
  • projectTasks (array, obrigatório): Lista de tarefas do projeto a serem vinculadas ao projeto (se nenhuma tarefa for especificada, as tarefas comuns ativas serão pré-preenchidas)
  • projectUsers (array, obrigatório): Lista de usuários do projeto a serem vinculados ao projeto (se nenhum usuário for especificado, os usuários ativos serão pré-preenchidos)

Exemplo:

{
  "name": "create_project",
  "arguments": {
    "name": "Website Redesign",
    "code": "WEB-2024",
    "notes": "Complete redesign of company website",
    "color": "#3498db",
    "startDate": "2024-01-15",
    "endDate": "2024-06-30",
    "invoicing": {
      "method": "ProjectHourlyRate",
      "hourlyRate": 125.00,
      "reference": "WEB-2024-INV"
    },
    "budget": {
      "method": "TotalHours",
      "hours": 400,
      "notificationPercentage": 80
    },
    "customer": {"id": 123},
    "managers": [{"id": 456}],
    "tags": [{"id": 1}, {"id": 2}],
    "projectTasks": [
      {
        "active": true,
        "billable": true,
        "hourlyRate": 125.00,
        "task": {"id": 789}
      }
    ],
    "projectUsers": [
      {
        "active": true,
        "hourlyRate": 125.00,
        "budgetHours": 200,
        "user": {"id": 101}
      }
    ]
  }
}
4. update_project

Atualizar um projeto existente.

Parâmetros:

  • id (número, obrigatório): ID do projeto
  • name (string, obrigatório): O nome do projeto
  • active (booleano, opcional): Se o projeto pode ser usado
  • code (string, opcional): O código do projeto
  • notes (string, opcional): A descrição do projeto
  • color (string, opcional): A cor do projeto
  • startDate (string, opcional): A data de início do projeto (formato AAAA-MM-DD)
  • endDate (string, opcional): A data de término do projeto (formato AAAA-MM-DD)
  • invoicing (objeto, obrigatório): As configurações de faturamento do projeto
    • method (string, opcional): O método de faturamento do projeto usado
      • Valores permitidos: NoInvoicing, TaskHourlyRate, UserHourlyRate, ProjectHourlyRate, CustomerHourlyRate, ProjectRate, TaskRate, Subscription
    • hourlyRate (número, opcional): A taxa horária do projeto (usada apenas quando o método de faturamento = ProjectHourlyRate)
    • fixedRate (número, opcional): A taxa/preço fixo do projeto (usado apenas quando o método de faturamento = ProjectRate)
    • reference (string, opcional): A referência de faturamento do projeto
    • date (string, opcional): A data de faturamento do projeto (formato AAAA-MM-DD, usado apenas quando o método de faturamento = ProjectRate)
  • budget (objeto, obrigatório): As configurações de orçamento do projeto
    • method (string, opcional): O método de orçamento do projeto usado
      • Valores permitidos: NoBudget, TotalHours, TaskHours, UserHours, TotalRate, TaskRate, Invoiced, TotalCost
    • hours (número, opcional): O orçamento horário do projeto (usado apenas quando o método de orçamento = TotalHours)
    • rate (número, opcional): A taxa de orçamento do projeto (usada apenas quando o método de orçamento = TotalRate ou TotalCost)
    • notificationPercentage (número, opcional): O limite percentual do orçamento no qual uma notificação é enviada
  • customer (objeto, opcional): Cliente a ser vinculado ao projeto
    • id (número, obrigatório): Identificador único do cliente
  • mainProject (objeto, opcional): Projeto principal a ser vinculado ao projeto (se for um subprojeto)
    • id (número, obrigatório): Identificador único do projeto
  • subprojects (array, opcional): Lista de subprojetos a serem vinculados ao projeto (se for um projeto principal)
  • managers (array, opcional): Lista de gerentes a serem vinculados ao projeto
  • tags (array, opcional): Lista de tags a serem vinculadas ao projeto
  • projectTasks (array, obrigatório): Lista de tarefas do projeto a serem vinculadas ao projeto
  • projectUsers (array, obrigatório): Lista de usuários do projeto a serem vinculados ao projeto

Exemplo:

{
  "name": "update_project",
  "arguments": {
    "id": 123,
    "name": "Website Redesign - Phase 2",
    "endDate": "2024-08-31",
    "invoicing": {
      "method": "ProjectHourlyRate",
      "hourlyRate": 150.00
    },
    "budget": {
      "method": "TotalHours",
      "hours": 600,
      "notificationPercentage": 85
    },
    "projectTasks": [
      {
        "id": 456,
        "active": true,
        "billable": true,
        "hourlyRate": 150.00,
        "budgetHours": 120,
        "task": {"id": 789}
      }
    ],
    "projectUsers": [
      {
        "id": 789,
        "active": true,
        "hourlyRate": 150.00,
        "budgetHours": 300,
        "costHourlyRate": 90.00,
        "user": {"id": 101}
      }
    ]
  }
}
5. delete_project

Excluir um projeto.

Parâmetros:

  • id (número, obrigatório): ID do projeto

Exemplo:

{
  "name": "delete_project",
  "arguments": {
    "id": 123
  }
}
6. get_project_insights

Obter insights do projeto, incluindo horas, orçamento, custos e dados de receita.

Parâmetros:

  • id (número, obrigatório): ID do projeto

Exemplo:

{
  "name": "get_project_insights",
  "arguments": {
    "id": 123
  }
}

Usuários

7. get_users

Recuperar usuários do TimeChimp.

Parâmetros:

  • top (número, opcional): Número máximo de usuários a retornar (1-10000, padrão: 100)
  • skip (número, opcional): Número de usuários a pular para paginação (padrão: 0)
  • count (booleano, opcional): Se deve incluir a contagem total de resultados (padrão: true)
  • expand (string, opcional): Lista de propriedades separadas por vírgula para expandir
  • active_only (booleano, opcional): Retornar apenas usuários ativos (padrão: false)
  • filter (string, opcional): Expressão de filtro OData
  • orderby (string, opcional): Expressão de ordenação OData

Exemplo:

{
  "name": "get_users",
  "arguments": {
    "top": 100,
    "filter": "firstName eq 'John' and active eq true",
    "orderby": "lastName asc"
  }
}
8. get_user_by_id

Obter um usuário específico pelo ID.

Parâmetros:

  • id (número, obrigatório): ID do usuário
  • expand (string, opcional): Lista de propriedades separadas por vírgula para expandir
9. create_user

Criar um novo usuário (nota: adicionar usuários pode resultar em fatura adicional e custo extra).

Parâmetros:

  • userName (string, obrigatório): O endereço de e-mail do usuário
  • displayName (string, obrigatório): O nome do usuário
  • language (string, opcional): O idioma do usuário (padrão: en)
    • Valores permitidos: en, nl, de, pl, fr, es
  • role (objeto, opcional): Função a ser atribuída ao usuário (padrão: User)
    • id (número, obrigatório): Identificador único para a função
  • sendInvitation (booleano, opcional): Se um convite deve ser enviado ao usuário (padrão: false)
  • contracts (array, opcional): Lista de contratos de usuário a serem vinculados
    • startDate (string, opcional): A data de início do contrato (formato AAAA-MM-DD, padrão: UTC hoje)
    • endDate (string, opcional): A data de término do contrato (formato AAAA-MM-DD)
    • weekHours (número, opcional): As horas semanais do contrato
    • hourlyRate (número, opcional): A taxa horária de vendas do contrato
    • costHourlyRate (número, opcional): A taxa horária de compra do contrato
    • contractNumber (string, opcional): O número do contrato
    • contractType (objeto, obrigatório): Tipo de contrato a ser vinculado ao contrato
      • id (número, obrigatório): Identificador único para o tipo de contrato

Exemplo:

{
  "name": "create_user",
  "arguments": {
    "userName": "john.doe@company.com",
    "displayName": "John Doe",
    "language": "en",
    "role": {"id": 2},
    "sendInvitation": true,
    "contracts": [
      {
        "startDate": "2024-01-15",
        "endDate": "2024-12-31",
        "weekHours": 40,
        "hourlyRate": 75.00,
        "costHourlyRate": 50.00,
        "contractNumber": "EMP-2024-001",
        "contractType": {"id": 1}
      }
    ]
  }
}
10. update_user

Atualizar um usuário existente.

Parâmetros:

  • id (número, obrigatório): ID do usuário
  • displayName (string, obrigatório): O nome do usuário
  • language (string, opcional): O idioma do usuário (padrão: en)
    • Valores permitidos: en, nl, de, pl, fr, es
  • employeeNumber (string, opcional): O número de funcionário do usuário
  • badgeNumber (string, opcional): O número de crachá do usuário
  • citizenServiceNumber (string, opcional): O número de serviço do cidadão do usuário
  • role (objeto, opcional): Função a ser atribuída ao usuário (padrão: User)
    • id (número, obrigatório): Identificador único para a função
  • tags (array, opcional): Lista de tags a serem vinculadas ao usuário
  • contracts (array, opcional): Lista de contratos de usuário a serem vinculados
    • id (número, opcional): Identificador único para o contrato do usuário (pode ser nulo se um novo contrato de usuário precisar ser adicionado)
    • startDate (string, opcional): A data de início do contrato (formato AAAA-MM-DD, padrão: UTC hoje)
    • endDate (string, opcional): A data de término do contrato (formato AAAA-MM-DD)
    • weekHours (número, opcional): As horas semanais do contrato
    • hourlyRate (número, opcional): A taxa horária de vendas do contrato
    • costHourlyRate (número, opcional): A taxa horária de compra/custo do contrato
    • contractNumber (string, opcional): O número do contrato
    • contractType (objeto, obrigatório): Tipo de contrato a ser vinculado ao contrato
      • id (número, obrigatório): Identificador único para o tipo de contrato

Exemplo:

{
  "name": "update_user",
  "arguments": {
    "id": 123,
    "displayName": "John Doe - Senior Developer",
    "language": "en",
    "employeeNumber": "EMP-001",
    "badgeNumber": "BADGE-001",
    "role": {"id": 3},
    "tags": [{"id": 1}, {"id": 2}],
    "contracts": [
      {
        "id": 456,
        "startDate": "2024-01-15",
        "endDate": "2024-12-31",
        "weekHours": 40,
        "hourlyRate": 85.00,
        "costHourlyRate": 55.00,
        "contractNumber": "EMP-2024-001-UPD",
        "contractType": {"id": 1}
      }
    ]
  }
}

Registros de Tempo

11. get_time_entries

Recuperar registros de tempo do TimeChimp.

Parâmetros:

  • top (número, opcional): Número máximo de registros de tempo a retornar (1-10000, padrão: 100)
  • skip (número, opcional): Número de registros de tempo a pular para paginação (padrão: 0)
  • count (booleano, opcional): Se deve incluir a contagem total de resultados (padrão: true)
  • expand (string, opcional): Lista de propriedades separadas por vírgula para expandir (ex.: "user,project,task")
  • user_id (string, opcional): Filtrar por ID de usuário específico
  • project_id (string, opcional): Filtrar por ID de projeto específico
  • from_date (string, opcional): Data de início para filtragem (formato AAAA-MM-DD)
  • to_date (string, opcional): Data de término para filtragem (formato AAAA-MM-DD)
  • filter (string, opcional): Expressão de filtro OData
  • orderby (string, opcional): Expressão de ordenação OData

Exemplo:

{
  "name": "get_time_entries",
  "arguments": {
    "top": 100,
    "from_date": "2024-01-01",
    "to_date": "2024-01-31",
    "user_id": "123",
    "expand": "user,project,task",
    "orderby": "date desc"
  }
}
12. get_time_entry_by_id

Obter um registro de tempo específico pelo ID.

Parâmetros:

  • id (número, obrigatório): ID do registro de tempo
  • expand (string, opcional): Lista de propriedades separadas por vírgula para expandir

Contatos

13. get_contacts

Recuperar todos os contatos do TimeChimp.

Parâmetros:

  • top (número, opcional): Número máximo de contatos a retornar (1-10000, padrão: 100)
  • skip (número, opcional): Número de contatos a pular para paginação (padrão: 0)
  • count (booleano, opcional): Se deve incluir a contagem total de resultados (padrão: true)
  • expand (string, opcional): Lista de propriedades separadas por vírgula para expandir (ex.: "customers")
  • active_only (booleano, opcional): Retornar apenas contatos ativos (padrão: false)
  • filter (string, opcional): Expressão de filtro OData
  • orderby (string, opcional): Expressão de ordenação OData

Exemplo:

{
  "name": "get_contacts",
  "arguments": {
    "top": 50,
    "expand": "customers",
    "filter": "name eq 'John Doe'",
    "orderby": "name asc"
  }
}
14. get_contact_by_id

Obter um contato específico pelo ID.

Parâmetros:

  • id (número, obrigatório): ID do contato
  • expand (string, opcional): Lista de propriedades separadas por vírgula para expandir
15. create_contact

Criar um novo contato.

Parâmetros:

  • name (string, obrigatório): O nome do contato
  • jobTitle (string, opcional): O cargo do contato
  • email (string, opcional): O endereço de e-mail do contato
  • phone (string, opcional): O número de telefone do contato
  • useForInvoicing (booleano, opcional): Se as informações do contato serão usadas para faturamento (padrão: false)
  • active (booleano, opcional): Se o contato pode ser usado (padrão: true)
  • customers (array, opcional): Lista de IDs de clientes para vincular a este contato

Exemplo:

{
  "name": "create_contact",
  "arguments": {
    "name": "John Doe",
    "jobTitle": "Project Manager",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "useForInvoicing": true,
    "customers": [{"id": 123}, {"id": 456}]
  }
}
16. update_contact

Atualizar um contato existente.

Parâmetros:

  • id (número, obrigatório): ID do contato
  • name (string, obrigatório): O nome do contato
  • jobTitle (string, opcional): O cargo do contato
  • email (string, opcional): O endereço de e-mail do contato
  • phone (string, opcional): O número de telefone do contato
  • useForInvoicing (booleano, opcional): Se as informações do contato serão usadas para faturamento
  • active (booleano, opcional): Se o contato pode ser usado
  • customers (array, opcional): Lista de IDs de clientes para vincular a este contato
17. delete_contact

Excluir um contato.

Parâmetros:

  • id (número, obrigatório): ID do contato

Exemplo:

{
  "name": "delete_contact",
  "arguments": {
    "id": 123
  }
}

Clientes

18. get_customers

Recuperar todos os clientes do TimeChimp.

Parâmetros:

  • top (número, opcional): Número máximo de clientes a retornar (1-10000, padrão: 100)
  • skip (número, opcional): Número de clientes a pular para paginação (padrão: 0)
  • count (booleano, opcional): Se deve incluir a contagem total de resultados (padrão: true)
  • expand (string, opcional): Lista de propriedades separadas por vírgula para expandir (ex.: "contacts,projects")
  • active_only (booleano, opcional): Retornar apenas clientes ativos (padrão: false)
  • filter (string, opcional): Expressão de filtro OData
  • orderby (string, opcional): Expressão de ordenação OData
19. get_customer_by_id

Obter um cliente específico pelo ID.

Parâmetros:

  • id (número, obrigatório): ID do cliente
  • expand (string, opcional): Lista de propriedades separadas por vírgula para expandir
20. create_customer

Criar um novo cliente.

Parâmetros:

  • name (string, obrigatório): O nome do cliente
  • active (booleano, opcional): Se o cliente pode ser usado (padrão: true)
  • relationId (string, opcional): O número do cliente
  • address (objeto, opcional): As informações de endereço do cliente
    • address (string, opcional): A linha de endereço
    • postalCode (string, opcional): O código postal
    • city (string, opcional): A cidade
    • country (string, opcional): O país
  • phone (string, opcional): O número de telefone do cliente
  • email (string, opcional): O endereço de e-mail do cliente
  • website (string, opcional): O URL do site do cliente
  • paymentPeriod (número, opcional): O prazo de pagamento do cliente em dias
  • hourlyRate (número, opcional): O preço horário padrão do cliente
  • mileageRate (número, opcional): O preço padrão de quilometragem do cliente, por KM
  • iban (string, opcional): O IBAN do cliente
  • bic (string, opcional): O BIC do cliente
  • vatNumber (string, opcional): O número de IVA do cliente
  • kvkNumber (string, opcional): O ID comercial do cliente
  • invoiceAddress (objeto, opcional): As informações de endereço de faturamento do cliente, substituindo as informações de endereço do cliente
    • address (string, opcional): A linha de endereço
    • postalCode (string, opcional): O código postal
    • city (string, opcional): A cidade
    • country (string, opcional): O país
  • notes (string, opcional): As notas do cliente
  • prospect (booleano, opcional): O cliente é um prospecto
  • vatRate (objeto, opcional): Taxa de IVA a ser usada para este cliente
    • id (número, obrigatório): Identificador único para a taxa de IVA
  • tags (array, opcional): Lista de IDs de tags para vincular a este cliente
  • contacts (array, opcional): Lista de IDs de contatos para vincular a este cliente

Exemplo:

{
  "name": "create_customer",
  "arguments": {
    "name": "Acme Corporation",
    "email": "contact@acme.com",
    "phone": "+1234567890",
    "website": "https://acme.com",
    "address": {
      "address": "123 Business St",
      "postalCode": "12345",
      "city": "Business City",
      "country": "USA"
    },
    "paymentPeriod": 30,
    "hourlyRate": 150.00,
    "prospect": false,
    "tags": [{"id": 1}, {"id": 2}],
    "contacts": [{"id": 123}]
  }
}
21. update_customer

Atualizar um cliente existente. Parâmetros:

  • id (number, obrigatório): ID do cliente
  • name (string, obrigatório): O nome do cliente
  • active (boolean, opcional): Se o cliente pode ser usado
  • relationId (string, opcional): O número do cliente
  • address (object, opcional): As informações de endereço do cliente
    • address (string, opcional): A linha de endereço
    • postalCode (string, opcional): O código postal
    • city (string, opcional): A cidade
    • country (string, opcional): O país
  • phone (string, opcional): O número de telefone do cliente
  • email (string, opcional): O endereço de e-mail do cliente
  • website (string, opcional): O URL do site do cliente
  • paymentPeriod (number, opcional): O prazo de pagamento do cliente em dias
  • hourlyRate (number, opcional): O preço horário padrão do cliente
  • mileageRate (number, opcional): O preço padrão de quilometragem do cliente, por KM
  • iban (string, opcional): O IBAN do cliente
  • bic (string, opcional): O BIC do cliente
  • vatNumber (string, opcional): O número de IVA do cliente
  • kvkNumber (string, opcional): O ID comercial do cliente
  • invoiceAddress (object, opcional): As informações de endereço de faturamento do cliente, se diferirem das informações de endereço do cliente
    • address (string, opcional): A linha de endereço
    • postalCode (string, opcional): O código postal
    • city (string, opcional): A cidade
    • country (string, opcional): O país
  • notes (string, opcional): As notas do cliente
  • prospect (boolean, opcional): O cliente é um prospect
  • vatRate (object, opcional): Taxa de IVA a ser vinculada ao cliente
    • id (number, obrigatório): Identificador exclusivo para a taxa de IVA
  • tags (array, opcional): Lista de IDs de tags para vincular a este cliente
  • contacts (array, opcional): Lista de IDs de contatos para vincular a este cliente

Exemplo:

{
  "name": "update_customer",
  "arguments": {
    "id": 456,
    "name": "Acme Corporation Ltd",
    "email": "newcontact@acme.com",
    "paymentPeriod": 45,
    "hourlyRate": 175.00
  }
}
22. delete_customer

Excluir um cliente.

Parâmetros:

  • id (number, obrigatório): ID do cliente

Exemplo:

{
  "name": "delete_customer",
  "arguments": {
    "id": 456
  }
}

Tarefas

23. get_tasks

Recuperar todas as tarefas do TimeChimp.

Parâmetros:

  • top (number, opcional): Número máximo de tarefas a retornar (1-10000, padrão: 100)
  • skip (number, opcional): Número de tarefas a pular para paginação (padrão: 0)
  • count (boolean, opcional): Se deve incluir a contagem total de resultados (padrão: true)
  • expand (string, opcional): Lista separada por vírgulas de propriedades a expandir (ex.: "project")
  • active_only (boolean, opcional): Retornar apenas tarefas ativas (padrão: false)
  • project_id (string, opcional): Filtrar por ID de projeto específico
  • filter (string, opcional): Expressão de filtro OData
  • orderby (string, opcional): Expressão de ordenação OData
24. get_task_by_id

Obter uma tarefa específica pelo ID.

Parâmetros:

  • id (number, obrigatório): ID da tarefa
  • expand (string, opcional): Lista separada por vírgulas de propriedades a expandir

Faturas

25. get_invoices

Recuperar todas as faturas do TimeChimp.

Parâmetros:

  • top (number, opcional): Número máximo de faturas a retornar (1-10000, padrão: 100)
  • skip (number, opcional): Número de faturas a pular para paginação (padrão: 0)
  • count (boolean, opcional): Se deve incluir a contagem total de resultados (padrão: true)
  • expand (string, opcional): Lista separada por vírgulas de propriedades a expandir (ex.: "customer,projects")
  • customer_id (string, opcional): Filtrar por ID de cliente específico
  • from_date (string, opcional): Data de início para filtragem (formato YYYY-MM-DD)
  • to_date (string, opcional): Data de término para filtragem (formato YYYY-MM-DD)
  • filter (string, opcional): Expressão de filtro OData
  • orderby (string, opcional): Expressão de ordenação OData
26. get_invoice_by_id

Obter uma fatura específica pelo ID.

Parâmetros:

  • id (number, obrigatório): ID da fatura
  • expand (string, opcional): Lista separada por vírgulas de propriedades a expandir

Despesas

27. get_expenses

Recuperar todas as despesas do TimeChimp.

Parâmetros:

  • top (number, opcional): Número máximo de despesas a retornar (1-10000, padrão: 100)
  • skip (number, opcional): Número de despesas a pular para paginação (padrão: 0)
  • count (boolean, opcional): Se deve incluir a contagem total de resultados (padrão: true)
  • expand (string, opcional): Lista separada por vírgulas de propriedades a expandir (ex.: "user,project,customer")
  • user_id (string, opcional): Filtrar por ID de usuário específico
  • project_id (string, opcional): Filtrar por ID de projeto específico
  • customer_id (string, opcional): Filtrar por ID de cliente específico
  • from_date (string, opcional): Data de início para filtragem (formato YYYY-MM-DD)
  • to_date (string, opcional): Data de término para filtragem (formato YYYY-MM-DD)
  • filter (string, opcional): Expressão de filtro OData
  • orderby (string, opcional): Expressão de ordenação OData
28. get_expense_by_id

Obter uma despesa específica pelo ID.

Parâmetros:

  • id (number, obrigatório): ID da despesa
  • expand (string, opcional): Lista separada por vírgulas de propriedades a expandir
29. create_expense

Criar uma nova despesa.

Parâmetros:

  • date (string, opcional): A data da despesa (formato YYYY-MM-DD, padrão: hoje em UTC)
  • notes (string, opcional): As notas da despesa
  • quantity (number, opcional): A quantidade da despesa (padrão: 1)
  • rate (number, obrigatório): A taxa/preço da despesa
  • billable (boolean, opcional): Se a despesa pode ser faturada (padrão: true)
  • customer (object, opcional): Cliente a ser vinculado à despesa
    • id (number, obrigatório): Identificador exclusivo para o cliente
  • project (object, opcional): Projeto a ser vinculado à despesa
    • id (number, obrigatório): Identificador exclusivo para o projeto
  • product (object, opcional): Produto a ser vinculado à despesa
    • id (number, obrigatório): Identificador exclusivo para o produto
  • user (object, obrigatório): Usuário a ser vinculado à despesa
    • id (number, obrigatório): Identificador exclusivo para o usuário
  • vatRate (object, opcional): Taxa de IVA a ser vinculada à despesa (padrão: maior porcentagem)
    • id (number, obrigatório): Identificador exclusivo para a taxa de IVA

Exemplo:

{
  "name": "create_expense",
  "arguments": {
    "date": "2024-01-15",
    "notes": "Business lunch with client",
    "quantity": 1,
    "rate": 75.50,
    "billable": true,
    "customer": {"id": 123},
    "project": {"id": 456},
    "user": {"id": 789}
  }
}
30. update_expense

Atualizar uma despesa existente.

Parâmetros:

  • id (number, obrigatório): ID da despesa
  • date (string, opcional): A data da despesa (formato YYYY-MM-DD)
  • notes (string, opcional): As notas da despesa
  • quantity (number, opcional): A quantidade da despesa
  • rate (number, obrigatório): A taxa/preço da despesa
  • billable (boolean, opcional): Se a despesa pode ser faturada
  • customer (object, opcional): Cliente a ser vinculado à despesa
    • id (number, obrigatório): Identificador exclusivo para o cliente
  • project (object, opcional): Projeto a ser vinculado à despesa
    • id (number, obrigatório): Identificador exclusivo para o projeto
  • product (object, opcional): Produto a ser vinculado à despesa
    • id (number, obrigatório): Identificador exclusivo para o produto
  • user (object, obrigatório): Usuário a ser vinculado à despesa
    • id (number, obrigatório): Identificador exclusivo para o usuário
  • vatRate (object, opcional): Taxa de IVA a ser vinculada à despesa
    • id (number, obrigatório): Identificador exclusivo para a taxa de IVA

Exemplo:

{
  "name": "update_expense",
  "arguments": {
    "id": 123,
    "notes": "Updated: Business lunch with client and partner",
    "rate": 85.00,
    "user": {"id": 789}
  }
}
31. delete_expense

Excluir uma despesa.

Parâmetros:

  • id (number, obrigatório): ID da despesa

Exemplo:

{
  "name": "delete_expense",
  "arguments": {
    "id": 123
  }
}
32. update_expense_status

Atualizar o status das despesas (status interno de aprovação/faturamento).

Parâmetros:

  • message (string, opcional): Mensagem de histórico de status
  • expenses (array, obrigatório): Lista de despesas a serem atualizadas (máximo de 100 entradas)
    • id (number, obrigatório): Identificador exclusivo para a despesa
  • status (string, obrigatório): O status interno de aprovação/faturamento
    • Valores permitidos: Open, PendingApproval, Approved, Invoiced, WrittenOff, Rejected

Exemplo:

{
  "name": "update_expense_status",
  "arguments": {
    "message": "Approved by manager",
    "expenses": [{"id": 123}, {"id": 124}],
    "status": "Approved"
  }
}
33. update_expense_client_status

Atualizar o status do cliente das despesas (status externo de aprovação/faturamento).

Parâmetros:

  • clientStatus (string, obrigatório): O status externo de aprovação/faturamento (usado apenas quando o portal do cliente está habilitado)
    • Valores permitidos: Open, PendingApproval, Approved, Invoiced, WrittenOff, Rejected
  • message (string, opcional): Mensagem de histórico de status
  • expenses (array, obrigatório): Lista de despesas a serem atualizadas (máximo de 100 entradas)
    • id (number, obrigatório): Identificador exclusivo para a despesa

Exemplo:

{
  "name": "update_expense_client_status",
  "arguments": {
    "clientStatus": "Approved",
    "message": "Client approved expenses",
    "expenses": [{"id": 123}, {"id": 124}]
  }
}
34. get_expense_status_history

Consultar registros de modificação do histórico de status de uma despesa.

Parâmetros:

  • id (number, obrigatório): ID da despesa
  • top (number, opcional): Número máximo de registros de histórico de status a retornar (1-10000, padrão: 100)
  • skip (number, opcional): Número de registros de histórico de status a pular para paginação (padrão: 0)
  • count (boolean, opcional): Se deve incluir a contagem total de resultados (padrão: true)
  • expand (string, opcional): Lista separada por vírgulas de propriedades a expandir
  • filter (string, opcional): Expressão de filtro OData
  • orderby (string, opcional): Expressão de ordenação OData (ex.: "modifiedOn desc")

Exemplo:

{
  "name": "get_expense_status_history",
  "arguments": {
    "id": 123,
    "orderby": "modifiedOn desc",
    "top": 50
  }
}

Quilometragem

35. get_mileage

Recuperar todas as entradas de quilometragem do TimeChimp.

Parâmetros:

  • top (number, opcional): Número máximo de entradas de quilometragem a retornar (1-10000, padrão: 100)
  • skip (number, opcional): Número de entradas de quilometragem a pular para paginação (padrão: 0)
  • count (boolean, opcional): Se deve incluir a contagem total de resultados (padrão: true)
  • expand (string, opcional): Lista separada por vírgulas de propriedades a expandir (ex.: "user,project,customer")
  • user_id (string, opcional): Filtrar por ID de usuário específico
  • project_id (string, opcional): Filtrar por ID de projeto específico
  • customer_id (string, opcional): Filtrar por ID de cliente específico
  • from_date (string, opcional): Data de início para filtragem (formato YYYY-MM-DD)
  • to_date (string, opcional): Data de término para filtragem (formato YYYY-MM-DD)
  • filter (string, opcional): Expressão de filtro OData
  • orderby (string, opcional): Expressão de ordenação OData
36. get_mileage_by_id

Obter uma entrada de quilometragem específica pelo ID.

Parâmetros:

  • id (number, obrigatório): ID da entrada de quilometragem
  • expand (string, opcional): Lista separada por vírgulas de propriedades a expandir
37. create_mileage

Criar uma nova entrada de quilometragem. Parâmetros:

  • date (string, opcional): A data da quilometragem (formato YYYY-MM-DD, padrão: hoje em UTC)
  • fromAddress (string, opcional): O endereço de origem da quilometragem
  • toAddress (string, opcional): O endereço de destino da quilometragem
  • notes (string, opcional): As observações da quilometragem
  • distance (number, obrigatório): A distância da quilometragem em KM
  • billable (boolean, opcional): Se a quilometragem pode ser faturada (padrão: true)
  • type (string, obrigatório): O tipo de quilometragem
    • Valores permitidos: Private, Business, HomeWork
  • customer (object, opcional): Cliente a ser vinculado à quilometragem
    • id (number, obrigatório): Identificador único do cliente
  • project (object, opcional): Projeto a ser vinculado à quilometragem
    • id (number, obrigatório): Identificador único do projeto
  • vehicle (object, opcional): Veículo a ser vinculado à quilometragem
    • id (number, obrigatório): Identificador único do veículo de quilometragem
  • user (object, obrigatório): Usuário a ser vinculado à quilometragem
    • id (number, obrigatório): Identificador único do usuário

Exemplo:

{
  "name": "create_mileage",
  "arguments": {
    "date": "2024-01-15",
    "fromAddress": "Office - 123 Business St, Business City",
    "toAddress": "Client Site - 456 Client Ave, Client City",
    "notes": "Client meeting and project consultation",
    "distance": 45.5,
    "billable": true,
    "type": "Business",
    "customer": {"id": 123},
    "project": {"id": 456},
    "vehicle": {"id": 789},
    "user": {"id": 101}
  }
}
38. update_mileage

Atualiza um registro de quilometragem existente.

Parâmetros:

  • id (number, obrigatório): ID do registro de quilometragem
  • date (string, opcional): A data da quilometragem (formato YYYY-MM-DD)
  • fromAddress (string, opcional): O endereço de origem da quilometragem
  • toAddress (string, opcional): O endereço de destino da quilometragem
  • notes (string, opcional): As observações da quilometragem
  • distance (number, obrigatório): A distância da quilometragem em KM
  • billable (boolean, opcional): Se a quilometragem pode ser faturada
  • type (string, obrigatório): O tipo de quilometragem
    • Valores permitidos: Private, Business, HomeWork
  • customer (object, opcional): Cliente a ser vinculado à quilometragem
    • id (number, obrigatório): Identificador único do cliente
  • project (object, opcional): Projeto a ser vinculado à quilometragem
    • id (number, obrigatório): Identificador único do projeto
  • vehicle (object, opcional): Veículo a ser vinculado à quilometragem
    • id (number, obrigatório): Identificador único do veículo de quilometragem
  • user (object, obrigatório): Usuário a ser vinculado à quilometragem
    • id (number, obrigatório): Identificador único do usuário

Exemplo:

{
  "name": "update_mileage",
  "arguments": {
    "id": 123,
    "notes": "Updated: Client meeting, project consultation, and site inspection",
    "distance": 52.3,
    "fromAddress": "Office - 123 Business St, Business City",
    "toAddress": "Client Site - 456 Client Ave, Client City (with site inspection)",
    "type": "Business",
    "user": {"id": 101}
  }
}
39. delete_mileage

Exclui um registro de quilometragem.

Parâmetros:

  • id (number, obrigatório): ID do registro de quilometragem

Exemplo:

{
  "name": "delete_mileage",
  "arguments": {
    "id": 123
  }
}
40. update_mileage_status

Atualiza o status de registros de quilometragem (status interno de aprovação/faturamento).

Parâmetros:

  • message (string, opcional): Mensagem do histórico de status
  • mileages (array, obrigatório): Lista de registros de quilometragem a serem atualizados (máximo de 100 registros)
    • id (number, obrigatório): Identificador único da quilometragem
  • status (string, obrigatório): O status interno de aprovação/faturamento
    • Valores permitidos: Open, PendingApproval, Approved, Invoiced, WrittenOff, Rejected

Exemplo:

{
  "name": "update_mileage_status",
  "arguments": {
    "message": "Approved by manager after review",
    "mileages": [{"id": 123}, {"id": 124}],
    "status": "Approved"
  }
}
41. update_mileage_client_status

Atualiza o status do cliente de registros de quilometragem (status externo de aprovação/faturamento).

Parâmetros:

  • clientStatus (string, obrigatório): O status externo de aprovação/faturamento (usado apenas quando o portal do cliente está habilitado)
    • Valores permitidos: Open, PendingApproval, Approved, Invoiced, WrittenOff, Rejected
  • message (string, opcional): Mensagem do histórico de status
  • mileages (array, obrigatório): Lista de registros de quilometragem a serem atualizados (máximo de 100 registros)
    • id (number, obrigatório): Identificador único da quilometragem

Exemplo:

{
  "name": "update_mileage_client_status",
  "arguments": {
    "clientStatus": "Approved",
    "message": "Client approved mileage claims",
    "mileages": [{"id": 123}, {"id": 124}]
  }
}
42. get_mileage_status_history

Consulta registros de modificação do histórico de status de um registro de quilometragem.

Parâmetros:

  • id (number, obrigatório): ID do registro de quilometragem
  • top (number, opcional): Número máximo de registros de histórico de status a retornar (1-10000, padrão: 100)
  • skip (number, opcional): Número de registros de histórico de status a pular para paginação (padrão: 0)
  • count (boolean, opcional): Se deve incluir a contagem total de resultados (padrão: true)
  • expand (string, opcional): Lista de propriedades separadas por vírgula para expandir
  • filter (string, opcional): Expressão de filtro OData
  • orderby (string, opcional): Expressão orderby OData (ex.: "modifiedOn desc")

Exemplo:

{
  "name": "get_mileage_status_history",
  "arguments": {
    "id": 123,
    "orderby": "modifiedOn desc",
    "top": 50
  }
}
43. get_mileage_vehicles

Recupera todos os veículos de quilometragem do TimeChimp.

Parâmetros:

  • top (number, opcional): Número máximo de veículos de quilometragem a retornar (1-10000, padrão: 100)
  • skip (number, opcional): Número de veículos de quilometragem a pular para paginação (padrão: 0)
  • count (boolean, opcional): Se deve incluir a contagem total de resultados (padrão: true)
  • expand (string, opcional): Lista de propriedades separadas por vírgula para expandir (ex.: "users")
  • active_only (boolean, opcional): Retornar apenas veículos de quilometragem ativos (padrão: false)
  • filter (string, opcional): Expressão de filtro OData
  • orderby (string, opcional): Expressão orderby OData

Exemplo:

{
  "name": "get_mileage_vehicles",
  "arguments": {
    "active_only": true,
    "expand": "users",
    "orderby": "brand asc"
  }
}
44. get_mileage_vehicle_by_id

Obtém um veículo de quilometragem específico pelo ID.

Parâmetros:

  • id (number, obrigatório): ID do veículo de quilometragem
  • expand (string, opcional): Lista de propriedades separadas por vírgula para expandir

Exemplo:

{
  "name": "get_mileage_vehicle_by_id",
  "arguments": {
    "id": 789,
    "expand": "users"
  }
}

Tags

45. get_tags

Recupera todas as tags do TimeChimp.

Parâmetros:

  • top (number, opcional): Número máximo de tags a retornar (1-10000, padrão: 100)
  • skip (number, opcional): Número de tags a pular para paginação (padrão: 0)
  • count (boolean, opcional): Se deve incluir a contagem total de resultados (padrão: true)
  • expand (string, opcional): Lista de propriedades separadas por vírgula para expandir
  • active_only (boolean, opcional): Retornar apenas tags ativas (padrão: false)
  • filter (string, opcional): Expressão de filtro OData
  • orderby (string, opcional): Expressão orderby OData
46. get_tag_by_id

Obtém uma tag específica pelo ID.

Parâmetros:

  • id (number, obrigatório): ID da tag
  • expand (string, opcional): Lista de propriedades separadas por vírgula para expandir

Recursos da API v2 do TimeChimp

Paginação

O servidor usa os parâmetros padrão de paginação do TimeChimp:

  • $top: Número máximo de registros a retornar (1-10000, padrão: 100)
  • $skip: Número de registros a pular para paginação

Filtragem (OData)

O servidor suporta as convenções de filtragem OData do TimeChimp:

  • Filtros básicos: name eq 'Project Name'
  • Filtros booleanos: active eq true
  • Filtros de data: date eq 2023-12-31
  • Filtros de data e hora: start gt 2023-12-31T23:59:59Z
  • Filtros combinados: active eq true and name eq 'Project Name'
  • Filtros de coleção: projects/any(project:project/id eq 123)

Ordenação (OData)

O servidor suporta ordenação OData:

  • Campo único: name desc
  • Múltiplos campos: name desc, createdAt asc
  • Propriedades aninhadas: address/city asc

Expansão (OData)

O servidor suporta expansão de entidades relacionadas:

  • Expansão única: customer
  • Múltiplas expansões: customer,projects,tasks
  • Expansões aninhadas: customer/contacts

Contagem

O servidor suporta contagem de resultados totais:

  • $count=true: Incluir contagem total na resposta
  • $count=false: Excluir contagem total (padrão por desempenho)

Endpoints da API

O servidor interage com os seguintes endpoints da API v2 do TimeChimp:

  • GET /projects - Recuperar projetos
  • GET /projects/{id} - Obter projeto específico pelo ID
  • POST /projects - Criar novo projeto
  • PUT /projects/{id} - Atualizar projeto existente
  • DELETE /projects/{id} - Excluir projeto
  • GET /projects/{id}/insights - Obter insights do projeto
  • GET /users - Recuperar usuários
  • GET /users/{id} - Obter usuário específico pelo ID
  • POST /users - Criar novo usuário
  • PUT /users/{id} - Atualizar usuário existente
  • GET /times - Recuperar registros de tempo
  • GET /times/{id} - Obter registro de tempo específico pelo ID
  • GET /contacts - Recuperar contatos
  • GET /contacts/{id} - Obter contato específico pelo ID
  • POST /contacts - Criar novo contato
  • PUT /contacts/{id} - Atualizar contato existente
  • DELETE /contacts/{id} - Excluir contato
  • GET /customers - Recuperar clientes
  • GET /customers/{id} - Obter cliente específico pelo ID
  • POST /customers - Criar novo cliente
  • PUT /customers/{id} - Atualizar cliente existente
  • DELETE /customers/{id} - Excluir cliente
  • GET /tasks - Recuperar tarefas
  • GET /tasks/{id} - Obter tarefa específica pelo ID
  • GET /invoices - Recuperar faturas
  • GET /invoices/{id} - Obter fatura específica pelo ID
  • GET /expenses - Recuperar despesas
  • GET /expenses/{id} - Obter despesa específica pelo ID
  • POST /expenses - Criar nova despesa
  • PUT /expenses/{id} - Atualizar despesa existente
  • DELETE /expenses/{id} - Excluir despesa
  • PUT /expenses/status - Atualizar status da despesa (interno)
  • PUT /expenses/clientStatus - Atualizar status do cliente da despesa (externo)
  • GET /expenses/{id}/statusHistory - Obter histórico de status da despesa
  • GET /mileage - Recuperar registros de quilometragem
  • GET /mileage/{id} - Obter registro de quilometragem específico pelo ID
  • POST /mileage - Criar novo registro de quilometragem
  • PUT /mileage/{id} - Atualizar registro de quilometragem existente
  • DELETE /mileage/{id} - Excluir registro de quilometragem
  • PUT /mileage/status - Atualizar status da quilometragem (interno)
  • PUT /mileage/clientStatus - Atualizar status do cliente da quilometragem (externo)
  • GET /mileage/{id}/statusHistory - Obter histórico de status da quilometragem
  • GET /mileageVehicles - Recuperar veículos de quilometragem
  • GET /mileageVehicles/{id} - Obter veículo de quilometragem específico pelo ID
  • GET /tags - Recuperar tags
  • GET /tags/{id} - Obter tag específica pelo ID

Todas as solicitações são autenticadas usando o cabeçalho api-key e suportam parâmetros de consulta OData.

Exemplos Avançados

Filtragem Complexa

{
  "name": "get_time_entries",
  "arguments": {
    "filter": "date ge 2024-01-01 and date le 2024-01-31 and user/id eq 123 and project/active eq true",
    "expand": "user,project,task",
    "orderby": "date desc, start desc",
    "top": 50
  }
}

Exemplo de Paginação

{
  "name": "get_projects",
  "arguments": {
    "top": 25,
    "skip": 50,
    "count": true,
    "orderby": "name asc"
  }
}

Criando e Gerenciando Contatos

// Create a contact
{
  "name": "create_contact",
  "arguments": {
    "name": "Jane Smith",
    "jobTitle": "CEO",
    "email": "jane@company.com",
    "useForInvoicing": true,
    "customers": [{"id": 123}]
  }
}

// Update the contact
{
  "name": "update_contact",
  "arguments": {
    "id": 456,
    "name": "Jane Smith-Johnson",
    "phone": "+1987654321"
  }
}

// Get contact with expanded customers
{
  "name": "get_contact_by_id",
  "arguments": {
    "id": 456,
    "expand": "customers"
  }
}

Criando e Gerenciando Clientes

// Create a customer
{
  "name": "create_customer",
  "arguments": {
    "name": "Acme Corporation",
    "email": "contact@acme.com",
    "phone": "+1234567890",
    "website": "https://acme.com",
    "address": {
      "address": "123 Business St",
      "postalCode": "12345",
      "city": "Business City",
      "country": "USA"
    },
    "paymentPeriod": 30,
    "hourlyRate": 150.00,
    "prospect": false,
    "tags": [{"id": 1}, {"id": 2}],
    "contacts": [{"id": 123}]
  }
}

// Update the customer
{
  "name": "update_customer",
  "arguments": {
    "id": 456,
    "name": "Acme Corporation Ltd",
    "email": "newcontact@acme.com",
    "paymentPeriod": 45,
    "hourlyRate": 175.00
  }
}

// Get customer with expanded contacts and tags
{
  "name": "get_customer_by_id",
  "arguments": {
    "id": 456,
    "expand": "contacts,tags"
  }
}

Criando e Gerenciando Despesas

// Create an expense
{
  "name": "create_expense",
  "arguments": {
    "date": "2024-01-15",
    "notes": "Business lunch with client",
    "quantity": 1,
    "rate": 75.50,
    "billable": true,
    "customer": {"id": 123},
    "project": {"id": 456},
    "user": {"id": 789}
  }
}

// Update the expense
{
  "name": "update_expense",
  "arguments": {
    "id": 123,
    "notes": "Updated: Business lunch with client and partner",
    "rate": 85.00,
    "user": {"id": 789}
  }
}

// Update expense status (approve multiple expenses)
{
  "name": "update_expense_status",
  "arguments": {
    "message": "Approved by manager",
    "expenses": [{"id": 123}, {"id": 124}],
    "status": "Approved"
  }
}

// Get expense status history
{
  "name": "get_expense_status_history",
  "arguments": {
    "id": 123,
    "orderby": "modifiedOn desc"
  }
}

Criando e Gerenciando Projetos

// Create a project with comprehensive settings
{
  "name": "create_project",
  "arguments": {
    "name": "Website Redesign Project",
    "code": "WEB-2024-001",
    "notes": "Complete redesign of company website with modern UI/UX",
    "color": "#3498db",
    "startDate": "2024-01-15",
    "endDate": "2024-06-30",
    "invoicing": {
      "method": "ProjectHourlyRate",
      "hourlyRate": 125.00,
      "reference": "WEB-2024-INV"
    },
    "budget": {
      "method": "TotalHours",
      "hours": 400,
      "notificationPercentage": 80
    },
    "customer": {"id": 123},
    "managers": [{"id": 456}],
    "tags": [{"id": 1}, {"id": 2}],
    "projectTasks": [
      {
        "active": true,
        "billable": true,
        "hourlyRate": 125.00,
        "budgetHours": 100,
        "task": {"id": 789}
      },
      {
        "active": true,
        "billable": true,
        "hourlyRate": 150.00,
        "budgetHours": 80,
        "task": {"id": 790}
      }
    ],
    "projectUsers": [
      {
        "active": true,
        "hourlyRate": 125.00,
        "budgetHours": 200,
        "costHourlyRate": 80.00,
        "user": {"id": 101}
      },
      {
        "active": true,
        "hourlyRate": 150.00,
        "budgetHours": 200,
        "costHourlyRate": 100.00,
        "user": {"id": 102}
      }
    ]
  }
}

// Update the project with new requirements
{
  "name": "update_project",
  "arguments": {
    "id": 123,
    "name": "Website Redesign Project - Phase 2",
    "endDate": "2024-08-31",
    "invoicing": {
      "method": "ProjectHourlyRate",
      "hourlyRate": 150.00
    },
    "budget": {
      "method": "TotalHours",
      "hours": 600,
      "notificationPercentage": 85
    },
    "projectTasks": [
      {
        "id": 456,
        "active": true,
        "billable": true,
        "hourlyRate": 150.00,
        "budgetHours": 120,
        "task": {"id": 789}
      }
    ],
    "projectUsers": [
      {
        "id": 789,
        "active": true,
        "hourlyRate": 150.00,
        "budgetHours": 300,
        "costHourlyRate": 90.00,
        "user": {"id": 101}
      }
    ]
  }
}

// Get project insights for performance analysis
{
  "name": "get_project_insights",
  "arguments": {
    "id": 123
  }
}

// Get project with expanded relationships
{
  "name": "get_project_by_id",
  "arguments": {
    "id": 123,
    "expand": "customer,managers,tags,projectTasks,projectUsers"
  }
}

Criando e Gerenciando Usuários

// Create a user with contract and role assignment
{
  "name": "create_user",
  "arguments": {
    "userName": "john.doe@company.com",
    "displayName": "John Doe",
    "language": "en",
    "role": {"id": 2},
    "sendInvitation": true,
    "contracts": [
      {
        "startDate": "2024-01-15",
        "endDate": "2024-12-31",
        "weekHours": 40,
        "hourlyRate": 75.00,
        "costHourlyRate": 50.00,
        "contractNumber": "EMP-2024-001",
        "contractType": {"id": 1}
      }
    ]
  }
}

// Update the user with new role and contract terms
{
  "name": "update_user",
  "arguments": {
    "id": 123,
    "displayName": "John Doe - Senior Developer",
    "language": "en",
    "employeeNumber": "EMP-001",
    "badgeNumber": "BADGE-001",
    "citizenServiceNumber": "123456789",
    "role": {"id": 3},
    "tags": [{"id": 1}, {"id": 2}],
    "contracts": [
      {
        "id": 456,
        "startDate": "2024-01-15",
        "endDate": "2024-12-31",
        "weekHours": 40,
        "hourlyRate": 85.00,
        "costHourlyRate": 55.00,
        "contractNumber": "EMP-2024-001-UPD",
        "contractType": {"id": 1}
      }
    ]
  }
}

// Get user with expanded relationships
{
  "name": "get_user_by_id",
  "arguments": {
    "id": 123,
    "expand": "role,team,tags,contracts,selfBilling,customSchedule"
  }
}

// Get users with filtering and expansion
{
  "name": "get_users",
  "arguments": {
    "filter": "active eq true and role/name eq 'Developer'",
    "expand": "role,contracts",
    "orderby": "displayName asc",
    "top": 50
  }
}

Criando e Gerenciando Quilometragem

// Create a mileage entry
{
  "name": "create_mileage",
  "arguments": {
    "date": "2024-01-15",
    "fromAddress": "Office - 123 Business St, Business City",
    "toAddress": "Client Site - 456 Client Ave, Client City",
    "notes": "Client meeting and project consultation",
    "distance": 45.5,
    "billable": true,
    "type": "Business",
    "customer": {"id": 123},
    "project": {"id": 456},
    "vehicle": {"id": 789},
    "user": {"id": 101}
  }
}

// Update the mileage entry
{
  "name": "update_mileage",
  "arguments": {
    "id": 123,
    "notes": "Updated: Client meeting, project consultation, and site inspection",
    "distance": 52.3,
    "fromAddress": "Office - 123 Business St, Business City",
    "toAddress": "Client Site - 456 Client Ave, Client City (with site inspection)",
    "type": "Business",
    "user": {"id": 101}
  }
}

// Update mileage status (approve multiple mileage entries)
{
  "name": "update_mileage_status",
  "arguments": {
    "message": "Approved by manager after review",
    "mileages": [{"id": 123}, {"id": 124}],
    "status": "Approved"
  }
}

// Update mileage client status
{
  "name": "update_mileage_client_status",
  "arguments": {
    "clientStatus": "Approved",
    "message": "Client approved mileage claims",
    "mileages": [{"id": 123}, {"id": 124}]
  }
}

// Get mileage status history
{
  "name": "get_mileage_status_history",
  "arguments": {
    "id": 123,
    "orderby": "modifiedOn desc"
  }
}

// Get mileage entries with filtering
{
  "name": "get_mileage",
  "arguments": {
    "user_id": "101",
    "from_date": "2024-01-01",
    "to_date": "2024-01-31",
    "filter": "type eq 'Business' and billable eq true",
    "expand": "user,project,customer,vehicle",
    "orderby": "date desc"
  }
}

// Get mileage vehicles
{
  "name": "get_mileage_vehicles",
  "arguments": {
    "active_only": true,
    "expand": "users",
    "orderby": "brand asc"
  }
}

// Get specific mileage vehicle with users
{
  "name": "get_mileage_vehicle_by_id",
  "arguments": {
    "id": 789,
    "expand": "users"
  }
}

Tratamento de Erros

O servidor inclui tratamento abrangente de erros:

  • Erros de autenticação: Quando a chave de API está ausente ou é inválida
  • Erros de API: Quando a API do TimeChimp retorna respostas de erro (incluindo limite de taxa 429)
  • Erros de rede: Quando as solicitações falham devido a problemas de conectividade
  • Erros de validação: Quando parâmetros inválidos são fornecidos
  • Erros OData: Quando expressões de filtro ou orderby inválidas são usadas

As respostas de erro incluem mensagens de erro detalhadas para auxiliar na depuração.

Desenvolvimento

Estrutura do Projeto

TimeJS/
├── timechimp-mcp-server.js    # Main server file
├── package.json               # Node.js dependencies and scripts
└── README.md                  # This file

Adicionando Novas Ferramentas

Para adicionar novas ferramentas:

  1. Adicione a definição da ferramenta ao handler ListToolsRequestSchema
  2. Adicione um caso para a ferramenta no handler CallToolRequestSchema
  3. Implemente o método da ferramenta na classe TimechimpMCPServer
  4. Use os métodos genéricos handleGetRequest ou handleGetByIdRequest para consistência

Testes

Você pode testar o servidor usando qualquer cliente MCP ou executando-o diretamente e enviando mensagens JSON-RPC via stdin.

Solução de Problemas

Problemas Comuns

  1. "TIMECHIMP_API_KEY environment variable is required"

    • Certifique-se de que você definiu a variável de ambiente TIMECHIMP_API_KEY
    • Verifique se a chave de API está correta e possui as permissões adequadas

  2. "TimeChimp API error: 401 Unauthorized"

    • Verifique se sua chave de API é válida e não expirou
    • Certifique-se de que sua conta TimeChimp tenha o acesso à API habilitado

  3. "TimeChimp API error: 404 Not Found"

    • O endpoint da API pode não existir ou a URL pode estar incorreta
    • Verifique se você está usando a URL base correta da API v2 do TimeChimp

  4. "TimeChimp API error: 429 Too Many Requests"

    • Você excedeu o limite de requisições (100 requisições por minuto por empresa)
    • Aguarde a redefinição do limite ou implemente a limitação de requisições

  5. Erros de filtro OData

    • Verifique se a sintaxe do filtro segue as convenções do OData
    • Verifique se os nomes dos campos estão corretos e devidamente escapados
    • Use aspas simples para valores de string: name eq 'Project Name'

  6. Erros de conexão de rede

    • Verifique sua conexão com a internet
    • Verifique se há restrições de firewall

Modo de Depuração

Execute o servidor em modo de depuração para obter logs mais detalhados:

npm run dev

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Faça suas alterações
  4. Teste minuciosamente
  5. Envie um pull request

Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.

Suporte

Para problemas relacionados a:

  • Este servidor MCP: Abra uma issue neste repositório
  • TimeChimp API: Entre em contato com o suporte da TimeChimp em ict@timechimp.com
  • Protocolo MCP: Consulte a documentação do Model Context Protocol

Changelog

v0.7.0

  • Adicionadas operações CRUD completas para quilometragem (Criar, Ler, Atualizar, Excluir)
  • Adicionado gerenciamento de status de quilometragem com atualizações de status internas e externas
  • Adicionada funcionalidade de rastreamento de histórico de status de quilometragem
  • Adicionado gerenciamento de veículos de quilometragem (operações de leitura)
  • Melhorado o gerenciamento de quilometragem com vinculação abrangente a clientes, projetos, veículos e usuários
  • Adicionadas capacidades de atualização em massa de status para quilometragem (até 100 entradas de uma vez)
  • Atualizada a contagem de ferramentas para 46 ferramentas no total
  • Adicionados exemplos de CRUD de quilometragem à documentação

v0.6.0

  • Adicionadas operações CRUD completas para usuários (Criar, Ler, Atualizar, Excluir)
  • Adicionado gerenciamento de contratos de usuário e atribuição de funções
  • Atualizada a contagem de ferramentas para 38 ferramentas no total
  • Adicionados exemplos de CRUD de usuários à documentação

v0.5.0

  • Adicionadas operações CRUD completas para projetos (Criar, Ler, Atualizar, Excluir)
  • Adicionada funcionalidade de insights de projetos
  • Atualizada a contagem de ferramentas para 36 ferramentas no total
  • Adicionados exemplos de CRUD de projetos à documentação

v0.4.0

  • Adicionadas operações CRUD completas para despesas (Criar, Ler, Atualizar, Excluir)
  • Adicionado gerenciamento de status de despesas com atualizações de status internas e externas
  • Adicionada funcionalidade de rastreamento de histórico de status de despesas
  • Melhorado o gerenciamento de despesas com vinculação abrangente a clientes, projetos, produtos, usuários e taxas de IVA
  • Adicionadas capacidades de atualização em massa de status (até 100 despesas de uma vez)
  • Atualizada a contagem de ferramentas para 32 ferramentas no total
  • Adicionados exemplos de CRUD de despesas à documentação

v0.3.0

  • Adicionadas operações CRUD completas para clientes (Criar, Ler, Atualizar, Excluir)
  • Adicionado gerenciamento abrangente de clientes com endereço, condições de pagamento, taxas e relacionamentos
  • Melhoradas as ferramentas de clientes com suporte a taxas de IVA, tags e vinculação de contatos
  • Atualizada a contagem de ferramentas para 26 ferramentas no total
  • Adicionados exemplos de CRUD de clientes à documentação

v0.2.0

  • Adicionado suporte abrangente para todos os principais endpoints da API v2 do TimeChimp
  • Adicionadas operações CRUD completas para contatos (Criar, Ler, Atualizar, Excluir)
  • Adicionado suporte para clientes, tarefas, faturas, despesas, quilometragem e tags
  • Adicionados manipuladores de requisição genéricos para consistência e manutenibilidade
  • Melhorado o suporte OData com $expand, $count e filtragem aprimorada
  • Adicionadas ferramentas individuais de "get by ID" para todos os tipos de recursos
  • Melhorado o tratamento de erros e validação
  • Atualizado o cabeçalho de versão da API para 2.0

v0.1.0

  • Lançamento inicial
  • Suporte para as ferramentas GetProjects, Users e TimeEntries
  • Integração com a API v2 do TimeChimp com suporte OData
  • Tratamento de erros e validação abrangentes
  • Ordenação padrão para projetos (mais recentes primeiro)