Goodday MCP Server

Goodday MCP Server

Un servidor de Model Context Protocol (MCP) para integrarse con la plataforma de gestión de proyectos Goodday. Este servidor proporciona herramientas para gestionar proyectos, tareas y usuarios a través de la API v2 de Goodday.

Características

Gestión de Proyectos

• get_projects: Recuperar lista de proyectos (con opciones para filtrado por archivados y solo raíz)
• get_project: Obtener información detallada sobre un proyecto específico
• create_project: Crear nuevos proyectos con plantillas y ajustes personalizables
• get_project_users: Obtener usuarios asociados a un proyecto específico

Gestión de Tareas

• get_project_tasks: Recuperar tareas de proyectos específicos (con opciones para tareas cerradas y subcarpetas)
• get_user_assigned_tasks: Obtener tareas asignadas a un usuario específico
• get_user_action_required_tasks: Obtener tareas que requieren acción para un usuario
• get_task: Obtener información detallada sobre una tarea específica
• get_task_details: Obtener detalles completos de la tarea, incluyendo subtareas, campos personalizados y metadatos completos
• get_task_messages: Recuperar todos los mensajes/comentarios de una tarea específica
• create_task: Crear nuevas tareas con personalización completa (subtareas, asignaciones, fechas, prioridades)
• update_task_status: Actualizar el estado de la tarea con comentarios opcionales
• add_task_comment: Añadir comentarios a las tareas

Gestión de Sprints

• get_goodday_sprint_tasks: Obtener tareas de sprints específicos por nombre de proyecto y nombre/número de sprint
• get_goodday_sprint_summary: Generar resúmenes completos de sprints con detalles de tareas, distribución de estados y métricas clave

Gestión de Usuarios

• get_users: Recuperar lista de usuarios de la organización
• get_user: Obtener información detallada sobre un usuario específico

Consulta Inteligente y Búsqueda

• get_goodday_smart_query: Interfaz de lenguaje natural para consultas comunes de gestión de proyectos
• search_goodday_tasks: Búsqueda semántica en tareas utilizando backend VectorDB
• search_project_documents: Buscar documentos dentro de proyectos específicos
• get_document_content: Recuperar el contenido completo de documentos específicos

Integración con OpenWebUI

Este paquete también incluye una herramienta OpenWebUI que proporciona una interfaz completa para la gestión de proyectos Goodday directamente en interfaces de chat. La herramienta OpenWebUI incluye:

Características

• Gestión de Proyectos: Obtener proyectos, tareas de proyectos y detalles de proyectos
• Gestión de Sprints: Obtener tareas de sprints específicos por nombre/número, resúmenes completos de sprints
• Gestión de Usuarios: Obtener tareas asignadas a usuarios específicos, detalles de usuarios
• Detalles de Tareas: Obtener información completa de tareas incluyendo subtareas, campos personalizados y metadatos
• Mensajes de Tareas: Recuperar todos los mensajes y comentarios de las tareas
• Consulta Inteligente: Interfaz de lenguaje natural para solicitudes comunes de gestión de proyectos
• Búsqueda Semántica: Buscar en tareas utilizando backend VectorDB con embeddings
• Gestión de Documentos: Buscar documentos de proyectos y recuperar contenido de documentos
• Filtrado Avanzado: Soporte para proyectos archivados, tareas cerradas, subcarpetas y más

Configuración

1. Copie openwebui/goodday_openwebui_complete_tool.py a su directorio de herramientas de OpenWebUI
2. Configure las válvulas con sus credenciales de API:
   • api_key: Su token de API de Goodday
   • search_url: Su endpoint de búsqueda VectorDB (opcional)
   • bearer_token: Token Bearer para la API de búsqueda (opcional)

Configuración de Base de Datos Vectorial (Opcional)

Para la funcionalidad de búsqueda semántica, puede configurar una base de datos vectorial utilizando el flujo de trabajo n8n proporcionado (openwebui/n8n-workflow-goodday-vectordb.json). Este flujo de trabajo:

• Obtiene todos los proyectos y tareas de Goodday
• Extrae mensajes y contenido de las tareas
• Crea embeddings utilizando Ollama
• Almacena en la base de datos vectorial Qdrant
• Proporciona endpoint de API de búsqueda

Consulte openwebui/OPENWEBUI_TOOL_README.md para instrucciones detalladas de uso.

Instalación

Desde PyPI (Recomendado)

pip install goodday-mcp

Desde el Código Fuente

Requisitos Previos

• Python 3.10 o superior
• Gestor de paquetes UV (recomendado) o pip
• Token de API de Goodday

Configuración con UV

1. Instale UV (si no está ya instalado):

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

2. Clone y configure el proyecto:

   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
   

Configuración con pip

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

Configuración

1. Configure las variables de entorno: Cree un archivo .env en la raíz de su proyecto o exporte la variable:

   export GOODDAY_API_TOKEN=your_goodday_api_token_here
   

   Para obtener su token de API de Goodday:

   • Vaya a su organización de Goodday
   • Navegue a Configuración → API
   • Haga clic en el botón de generar para crear un nuevo token

Uso

Ejecutar el Servidor de Forma Independiente

Si está instalado desde PyPI:

goodday-mcp

Si se ejecuta desde el código fuente con UV:

uv run goodday-mcp

Uso con Claude Desktop

1. Configure Claude Desktop editando su archivo de configuración:

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

2. Añada la configuración del servidor:

   Opción A: Si está instalado desde PyPI:

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

   Opción B: Si se ejecuta desde el código fuente:

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

3. Reinicie Claude Desktop para cargar el nuevo servidor.

Uso con Otros Clientes MCP

El servidor se comunica mediante transporte stdio y puede integrarse con cualquier cliente compatible con MCP. Consulte la documentación de MCP para instrucciones de integración específicas del cliente.

Referencia de la API

Variables de Entorno

Variable	Descripción	Requerida
GOODDAY_API_TOKEN	Su token de API de Goodday	Sí

Ejemplos de Herramientas

Obtener Proyectos

# Get all active projects
get_projects()

# Get archived projects
get_projects(archived=True)

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

Crear una Tarea

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
)

Actualizar Estado de Tarea

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

Formatos de Datos

Formato de Fecha

Todas las fechas deben proporcionarse en formato YYYY-MM-DD (por ejemplo, 2025-06-16).

Niveles de Prioridad

• 1-10: Niveles de prioridad normales
• 50: Bloqueante
• 100: Emergencia

Colores de Proyecto

Los colores de proyecto se especifican como enteros del 1 al 24, correspondientes a la paleta de colores de Goodday.

Manejo de Errores

El servidor incluye manejo integral de errores:

• Errores de autenticación: Cuando el token de API falta o no es válido
• Errores de red: Cuando la API de Goodday no es accesible
• Errores de validación: Cuando faltan parámetros requeridos
• Errores de permisos: Cuando el usuario carece de permisos para las operaciones solicitadas

Todos los errores se devuelven como cadenas descriptivas para ayudar en la resolución de problemas.

Desarrollo

Estructura del Proyecto

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)

Añadir Nuevas Herramientas

Para añadir nuevas herramientas al servidor:

1. Añada la función de la herramienta en goodday_mcp/main.py utilizando el 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. Pruebe la herramienta ejecutando el servidor y probando con un cliente MCP.

Pruebas

Pruebe el servidor ejecutándolo directamente:

# If installed from PyPI
goodday-mcp

# If running from source
uv run goodday-mcp

El servidor se iniciará y esperará mensajes de protocolo MCP a través de stdin/stdout.

Contribuciones

1. Haga un fork del repositorio
2. Cree una rama de funcionalidad
3. Realice sus cambios
4. Añada pruebas si corresponde
5. Envíe una solicitud de pull

Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulte el archivo LICENSE para más detalles.

Soporte

Para problemas relacionados con:

• Servidor MCP: Cree un issue en este repositorio
• API de Goodday: Consulte la documentación de la API de Goodday
• Protocolo MCP: Consulte la documentación de MCP

Registro de Cambios

v1.1.0 (Actual)

• Gestión de Tareas Mejorada: Se añadieron get_task_details y get_task_messages para información completa de tareas
• Gestión de Sprints: Se añadieron get_goodday_sprint_tasks y get_goodday_sprint_summary para seguimiento de sprints
• Interfaz de Consulta Inteligente: Se añadió get_goodday_smart_query para consultas de proyectos en lenguaje natural
• Búsqueda Semántica: Se añadió search_goodday_tasks con integración VectorDB para búsqueda inteligente de tareas
• Gestión de Documentos: Se añadieron search_project_documents y get_document_content para manejo de documentos
• Manejo de Errores Mejorado: Mensajes de error y reporte de estados mejorados
• Filtrado Avanzado: Soporte para proyectos archivados, tareas cerradas e inclusión de subcarpetas

v1.0.0

• Lanzamiento inicial
• Capacidades completas de gestión de proyectos
• Gestión de tareas con comentarios y actualizaciones de estado
• Gestión de usuarios
• Manejo integral de errores
• Soporte UV con empaquetado moderno de Python