Goodday

Um servidor somente leitura para a plataforma de gerenciamento de projetos Goodday.

GitHub

Documentação

Servidor MCP Somente Leitura Goodday

Um servidor de Model Context Protocol (MCP) somente leitura para integração com a plataforma de gerenciamento de projetos Goodday. Este servidor fornece ferramentas somente leitura para consultar projetos, tarefas e usuários por meio da API v2 do Goodday, garantindo que nenhum dado possa ser modificado.

Recursos

Gerenciamento de Projetos (Somente Leitura)

  • get_projects: Recupera lista de projetos (com opções para filtragem por arquivados e somente raiz)
  • get_project: Obtém informações detalhadas sobre um projeto específico
  • get_project_users: Obtém usuários associados a um projeto específico

Gerenciamento de Tarefas (Somente Leitura)

  • get_project_tasks: Recupera tarefas de projetos específicos (com opções para tarefas fechadas e subpastas)
  • get_user_assigned_tasks: Obtém tarefas atribuídas a um usuário específico
  • get_user_action_required_tasks: Obtém tarefas que exigem ação de um usuário
  • get_task: Obtém informações detalhadas sobre uma tarefa específica

Gerenciamento de Usuários (Somente Leitura)

  • get_users: Recupera lista de usuários da organização
  • get_user: Obtém informações detalhadas sobre um usuário específico

Instalação

Via PyPI (Recomendado)

pip install goodday-ro-mcp

Via Código-Fonte

Pré-requisitos

  • Python 3.10 ou superior
  • Gerenciador de pacotes UV (recomendado) ou pip
  • Token da API Goodday

Configuração com UV

  1. Instale o UV (se ainda não estiver instalado):

    curl -LsSf https://astral.sh/uv/install.sh | sh

  2. Clone e configure o projeto:

    git clone https://github.com/your-username/goodday-ro-mcp.git
cd goodday-ro-mcp
uv sync

Configuração com pip

git clone https://github.com/your-username/goodday-ro-mcp.git
cd goodday-ro-mcp
pip install -e .

Configuração

Variáveis de Ambiente

Defina seu token da API Goodday como uma variável de ambiente:

export GOODDAY_API_TOKEN="your_goodday_api_token_here"

Encontrando seu token da API:

  1. Faça login na sua conta Goodday
  2. Vá para Configurações → API e Integrações
  3. Gere ou copie seu token da API

Uso

Como Servidor MCP (Claude Desktop)

Adicione ao arquivo de configuração do Claude Desktop:

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

{
  "mcpServers": {
    "goodday-ro": {
      "command": "goodday-ro-mcp",
      "env": {
        "GOODDAY_API_TOKEN": "your_goodday_api_token_here"
      }
    }
  }
}

Como Servidor HTTP (Docker)

Você também pode executar isso como um servidor HTTP autônomo com documentação OpenAPI e suporte a Server-Sent Events:

# Run directly
goodday-ro-mcp-server

# Or with Docker (see Docker section below)
docker run -e GOODDAY_API_TOKEN=your_token -p 8000:8000 goodday-ro-mcp:latest

O servidor estará disponível em:

Implantação com Docker

Construir Imagem Docker

cd goodday-ro-mcp
docker build -t goodday-ro-mcp:latest .

Executar com Docker

docker run -d \
  --name goodday-ro-mcp \
  -e GOODDAY_API_TOKEN=your_goodday_api_token_here \
  -p 8000:8000 \
  goodday-ro-mcp:latest

Executar com Docker Compose

version: '3.8'
services:
  goodday-ro-mcp:
    build: .
    environment:
      - GOODDAY_API_TOKEN=${GOODDAY_API_TOKEN}
    ports:
      - "8000:8000"
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Endpoints da API

Ao executar como servidor HTTP, os seguintes endpoints estão disponíveis:

Endpoints Principais

  • GET / - Informações do servidor e ferramentas disponíveis
  • GET /health - Endpoint de verificação de saúde
  • GET /tools - Lista de ferramentas disponíveis com descrições
  • POST /tools/call - Executa uma ferramenta com argumentos
  • GET /sse - Server-Sent Events para atualizações em tempo real
  • GET /docs - Documentação OpenAPI (Swagger UI)

Exemplo de Uso da API

# Get all projects
curl -X POST http://localhost:8000/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "get_projects", "arguments": {"archived": false, "root_only": true}}'

# Get specific project
curl -X POST http://localhost:8000/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "get_project", "arguments": {"project_id": "12345"}}'

# Get project tasks
curl -X POST http://localhost:8000/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name": "get_project_tasks", "arguments": {"project_id": "12345", "closed": false}}'

Ferramentas Disponíveis

Todas as ferramentas são somente leitura e não modificarão nenhum dado na sua conta Goodday.

Ferramentas de Projeto

  • get_projects(archived=False, root_only=False) - Lista projetos
  • get_project(project_id) - Obtém detalhes do projeto
  • get_project_users(project_id) - Obtém membros da equipe do projeto

Ferramentas de Tarefa

  • get_project_tasks(project_id, closed=False, subfolders=False) - Lista tarefas do projeto
  • get_task(task_id) - Obtém detalhes da tarefa
  • get_user_assigned_tasks(user_id, closed=False) - Obtém tarefas atribuídas ao usuário
  • get_user_action_required_tasks(user_id) - Obtém tarefas que exigem ação do usuário

Ferramentas de Usuário

  • get_users() - Lista usuários da organização
  • get_user(user_id) - Obtém detalhes do usuário

Tratamento de Erros

O servidor inclui tratamento abrangente de erros:

  • Erros de API: Erros da API Goodday são capturados e retornados com mensagens descritivas
  • Erros de Rede: Timeouts de conexão e problemas de rede são tratados com elegância
  • Erros de Autenticação: Tokens de API ausentes ou inválidos são relatados claramente
  • Validação de Dados: Respostas inválidas da API são tratadas com segurança

Desenvolvimento

Executando Testes

uv run pytest

Formatação de Código

uv run black goodday_ro_mcp/
uv run isort goodday_ro_mcp/

Verificação de Tipos

uv run mypy goodday_ro_mcp/

Segurança

Este é um servidor somente leitura que:

  • Apenas faz requisições GET à API Goodday
  • Não pode criar, atualizar ou excluir nenhum dado
  • Valida todas as entradas para prevenir ataques de injeção
  • Usa cabeçalhos HTTP seguros e políticas de CORS

Limitações

  • Somente Leitura: Não pode criar, atualizar ou excluir projetos, tarefas ou usuários
  • Limite de Taxa: Sujeito aos limites de taxa da API Goodday
  • Autenticação: Requer um token válido da API Goodday
  • Permissões: Limitado aos dados acessíveis pelo usuário associado ao token da API

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

Contribuição

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade
  3. Faça suas alterações
  4. Adicione testes se aplicável
  5. Envie um pull request

Suporte

Para problemas e perguntas: