Goodday MCP Server

Goodday MCP Server

Um servidor Model Context Protocol (MCP) para integração com a plataforma de gerenciamento de projetos Goodday. Este servidor fornece ferramentas para gerenciar projetos, tarefas e usuários através da API v2 do Goodday.

Recursos

Gerenciamento de Projetos

• 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
• create_project: Cria novos projetos com modelos e configurações personalizáveis
• get_project_users: Obtém usuários associados a um projeto específico

Gerenciamento de Tarefas

• 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
• get_task_details: Obtém detalhes abrangentes da tarefa, incluindo subtarefas, campos personalizados e metadados completos
• get_task_messages: Recupera todas as mensagens/comentários de uma tarefa específica
• create_task: Cria novas tarefas com personalização completa (subtarefas, atribuições, datas, prioridades)
• update_task_status: Atualiza o status da tarefa com comentários opcionais
• add_task_comment: Adiciona comentários a tarefas

Gerenciamento de Sprints

• get_goodday_sprint_tasks: Obtém tarefas de sprints específicos por nome do projeto e nome/número do sprint
• get_goodday_sprint_summary: Gera resumos abrangentes de sprints com detalhes de tarefas, distribuição de status e métricas principais

Gerenciamento de Usuários

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

Consulta Inteligente e Busca

• get_goodday_smart_query: Interface em linguagem natural para consultas comuns de gerenciamento de projetos
• search_goodday_tasks: Busca semântica em tarefas usando backend VectorDB
• search_project_documents: Busca documentos dentro de projetos específicos
• get_document_content: Recupera o conteúdo completo de documentos específicos

Integração com OpenWebUI

Este pacote também inclui uma ferramenta OpenWebUI que fornece uma interface completa para o gerenciamento de projetos Goodday diretamente em interfaces de chat. A ferramenta OpenWebUI inclui:

Recursos

• Gerenciamento de Projetos: Obter projetos, tarefas de projetos e detalhes de projetos
• Gerenciamento de Sprints: Obter tarefas de sprints específicos por nome/número, resumos abrangentes de sprints
• Gerenciamento de Usuários: Obter tarefas atribuídas a usuários específicos, detalhes de usuários
• Detalhes de Tarefas: Obter informações abrangentes de tarefas, incluindo subtarefas, campos personalizados e metadados
• Mensagens de Tarefas: Recuperar todas as mensagens e comentários de tarefas
• Consulta Inteligente: Interface em linguagem natural para solicitações comuns de gerenciamento de projetos
• Busca Semântica: Busca em tarefas usando backend VectorDB com embeddings
• Gerenciamento de Documentos: Buscar documentos de projetos e recuperar conteúdo de documentos
• Filtragem Avançada: Suporte para projetos arquivados, tarefas fechadas, subpastas e mais

Configuração

1. Copie openwebui/goodday_openwebui_complete_tool.py para o diretório de ferramentas do seu OpenWebUI
2. Configure as válvulas com suas credenciais de API:
   • api_key: Seu token de API do Goodday
   • search_url: Seu endpoint de busca VectorDB (opcional)
   • bearer_token: Token Bearer para a API de busca (opcional)

Configuração do Banco de Dados Vetorial (Opcional)

Para a funcionalidade de busca semântica, você pode configurar um banco de dados vetorial usando o fluxo de trabalho n8n fornecido (openwebui/n8n-workflow-goodday-vectordb.json). Este fluxo de trabalho:

• Busca todos os projetos e tarefas do Goodday
• Extrai mensagens e conteúdo das tarefas
• Cria embeddings usando Ollama
• Armazena no banco de dados vetorial Qdrant
• Fornece endpoint de API de busca

Consulte openwebui/OPENWEBUI_TOOL_README.md para instruções detalhadas de uso.

Instalação

Do PyPI (Recomendado)

pip install goodday-mcp

Da Fonte

Pré-requisitos

• Python 3.10 ou superior
• Gerenciador de pacotes UV (recomendado) ou pip
• Token de API do 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/cdmx1/goodday-mcp.git
   cd goodday-mcp
   
   # Create virtual environment and install dependencies
   uv venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   uv sync
   

Configuração com pip

git clone https://github.com/cdmx1/goodday-mcp.git
cd goodday-mcp
pip install -e .

Configuração

1. Configure as variáveis de ambiente: Crie um arquivo .env na raiz do seu projeto ou exporte a variável:

   export GOODDAY_API_TOKEN=your_goodday_api_token_here
   

   Para obter seu token de API do Goodday:

   • Vá para sua organização no Goodday
   • Navegue até Configurações → API
   • Clique no botão gerar para criar um novo token

Uso

Executando o Servidor de Forma Independente

Se instalado do PyPI:

goodday-mcp

Se executando da fonte com UV:

uv run goodday-mcp

Usando com Claude Desktop

1. Configure o Claude Desktop editando seu arquivo de configuração:

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

2. Adicione a configuração do servidor:

   Opção A: Se instalado do PyPI:

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

   Opção B: Se executando da fonte:

   {
     "mcpServers": {
       "goodday": {
         "command": "uv",
         "args": ["run", "goodday-mcp"],
         "env": {
           "GOODDAY_API_TOKEN": "your_goodday_api_token_here"
         }
       }
     }
   }
   

3. Reinicie o Claude Desktop para carregar o novo servidor.

Usando com Outros Clientes MCP

O servidor se comunica via transporte stdio e pode ser integrado com qualquer cliente compatível com MCP. Consulte a documentação do MCP para instruções de integração específicas do cliente.

Referência da API

Variáveis de Ambiente

Variável	Descrição	Obrigatória
GOODDAY_API_TOKEN	Seu token de API do Goodday	Sim

Exemplos de Ferramentas

Obter Projetos

# Get all active projects
get_projects()

# Get archived projects
get_projects(archived=True)

# Get only root-level projects
get_projects(root_only=True)

Criar uma Tarefa

create_task(
    project_id="project_123",
    title="Implement new feature",
    from_user_id="user_456",
    message="Detailed description of the task",
    to_user_id="user_789",
    deadline="2025-06-30",
    priority=5
)

Atualizar Status da Tarefa

update_task_status(
    task_id="task_123",
    user_id="user_456",
    status_id="status_completed",
    message="Task completed successfully"
)

Formatos de Dados

Formato de Data

Todas as datas devem ser fornecidas no formato YYYY-MM-DD (ex.: 2025-06-16).

Níveis de Prioridade

• 1-10: Níveis de prioridade normais
• 50: Bloqueador
• 100: Emergência

Cores de Projetos

As cores de projetos são especificadas como inteiros de 1 a 24, correspondendo à paleta de cores do Goodday.

Tratamento de Erros

O servidor inclui tratamento abrangente de erros:

• Erros de autenticação: Quando o token de API está ausente ou inválido
• Erros de rede: Quando a API do Goodday está inacessível
• Erros de validação: Quando parâmetros obrigatórios estão ausentes
• Erros de permissão: Quando o usuário não tem permissões para as operações solicitadas

Todos os erros são retornados como strings descritivas para ajudar na solução de problemas.

Desenvolvimento

Estrutura do Projeto

goodday-mcp/
├── goodday_mcp/         # Main package directory
│   ├── __init__.py      # Package initialization
│   └── main.py          # Main MCP server implementation
├── pyproject.toml       # Project configuration and dependencies
├── README.md           # This file
├── LICENSE             # MIT license
├── uv.lock            # Dependency lock file
└── .env               # Environment variables (create this)

Adicionando Novas Ferramentas

Para adicionar novas ferramentas ao servidor:

1. Adicione a função da ferramenta em goodday_mcp/main.py usando o decorador @mcp.tool():

   @mcp.tool()
   async def your_new_tool(param1: str, param2: Optional[int] = None) -> str:
       """Description of what the tool does.
       
       Args:
           param1: Description of parameter 1
           param2: Description of optional parameter 2
       """
       # Implementation here
       return "Result"
   

2. Teste a ferramenta executando o servidor e testando com um cliente MCP.

Testes

Teste o servidor executando-o diretamente:

# If installed from PyPI
goodday-mcp

# If running from source
uv run goodday-mcp

O servidor iniciará e aguardará mensagens do protocolo MCP via stdin/stdout.

Contribuindo

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

Licença

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

Suporte

Para problemas relacionados a:

• MCP Server: Crie um issue neste repositório
• API do Goodday: Consulte a documentação da API do Goodday
• Protocolo MCP: Consulte a documentação do MCP

Changelog

v1.1.0 (Atual)

• Gerenciamento de Tarefas Aprimorado: Adicionados get_task_details e get_task_messages para informações abrangentes de tarefas
• Gerenciamento de Sprints: Adicionados get_goodday_sprint_tasks e get_goodday_sprint_summary para acompanhamento de sprints
• Interface de Consulta Inteligente: Adicionado get_goodday_smart_query para consultas de projetos em linguagem natural
• Busca Semântica: Adicionado search_goodday_tasks com integração VectorDB para busca inteligente de tarefas
• Gerenciamento de Documentos: Adicionados search_project_documents e get_document_content para manipulação de documentos
• Tratamento de Erros Melhorado: Mensagens de erro e relatórios de status aprimorados
• Filtragem Avançada: Suporte para projetos arquivados, tarefas fechadas e inclusão de subpastas

v1.0.0

• Lançamento inicial
• Capacidades completas de gerenciamento de projetos
• Gerenciamento de tarefas com comentários e atualizações de status
• Gerenciamento de usuários
• Tratamento abrangente de erros
• Suporte a UV com empacotamento Python moderno