Goodday

Un servidor de solo lectura para la plataforma de gestión de proyectos Goodday.

GitHub

Documentación

Servidor MCP de Solo Lectura Goodday

Un servidor de Protocolo de Contexto de Modelo (MCP) de solo lectura para integrarse con la plataforma de gestión de proyectos Goodday. Este servidor proporciona herramientas de solo lectura para consultar proyectos, tareas y usuarios a través de la API v2 de Goodday, garantizando que no se puedan modificar datos.

Características

Gestión de Proyectos (Solo Lectura)

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

Gestión de Tareas (Solo Lectura)

  • 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

Gestión de Usuarios (Solo Lectura)

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

Instalación

Desde PyPI (Recomendado)

pip install goodday-ro-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. Instalar UV (si no está instalado):

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

  2. Clonar y configurar el proyecto:

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

Configuración con pip

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

Configuración

Variables de Entorno

Establezca su token de API de Goodday como variable de entorno:

export GOODDAY_API_TOKEN="your_goodday_api_token_here"

Cómo encontrar su token de API:

  1. Inicie sesión en su cuenta de Goodday
  2. Vaya a Configuración → API e Integraciones
  3. Genere o copie su token de API

Uso

Como Servidor MCP (Claude Desktop)

Agregue a su archivo de configuración de 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)

También puede ejecutarlo como un servidor HTTP independiente con documentación OpenAPI y soporte de 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

El servidor estará disponible en:

Implementación con Docker

Construir Imagen Docker

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

Ejecutar con Docker

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

Ejecutar con 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 de API

Cuando se ejecuta como servidor HTTP, están disponibles los siguientes endpoints:

Endpoints Principales

  • GET / - Información del servidor y herramientas disponibles
  • GET /health - Endpoint de verificación de salud
  • GET /tools - Lista de herramientas disponibles con descripciones
  • POST /tools/call - Ejecutar una herramienta con argumentos
  • GET /sse - Server-Sent Events para actualizaciones en tiempo real
  • GET /docs - Documentación OpenAPI (Swagger UI)

Ejemplo de Uso de 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}}'

Herramientas Disponibles

Todas las herramientas son de solo lectura y no modificarán ningún dato en su cuenta de Goodday.

Herramientas de Proyectos

  • get_projects(archived=False, root_only=False) - Listar proyectos
  • get_project(project_id) - Obtener detalles del proyecto
  • get_project_users(project_id) - Obtener miembros del equipo del proyecto

Herramientas de Tareas

  • get_project_tasks(project_id, closed=False, subfolders=False) - Listar tareas del proyecto
  • get_task(task_id) - Obtener detalles de la tarea
  • get_user_assigned_tasks(user_id, closed=False) - Obtener tareas asignadas del usuario
  • get_user_action_required_tasks(user_id) - Obtener tareas que requieren acción del usuario

Herramientas de Usuarios

  • get_users() - Listar usuarios de la organización
  • get_user(user_id) - Obtener detalles del usuario

Manejo de Errores

El servidor incluye manejo integral de errores:

  • Errores de API: Los errores de la API de Goodday se capturan y devuelven con mensajes descriptivos
  • Errores de Red: Los tiempos de espera de conexión y problemas de red se manejan correctamente
  • Errores de Autenticación: Los tokens de API faltantes o inválidos se reportan claramente
  • Validación de Datos: Las respuestas inválidas de la API se manejan de forma segura

Desarrollo

Ejecutar Pruebas

uv run pytest

Formato de Código

uv run black goodday_ro_mcp/
uv run isort goodday_ro_mcp/

Verificación de Tipos

uv run mypy goodday_ro_mcp/

Seguridad

Este es un servidor de solo lectura que:

  • Solo realiza solicitudes GET a la API de Goodday
  • No puede crear, actualizar ni eliminar ningún dato
  • Valida todas las entradas para prevenir ataques de inyección
  • Utiliza encabezados HTTP seguros y políticas CORS

Limitaciones

  • Solo Lectura: No puede crear, actualizar ni eliminar proyectos, tareas o usuarios
  • Límite de Velocidad: Sujeto a los límites de velocidad de la API de Goodday
  • Autenticación: Requiere un token de API válido de Goodday
  • Permisos: Limitado a los datos accesibles por el usuario asociado al token de API

Licencia

Licencia MIT - consulte el archivo LICENSE para más detalles.

Contribuciones

  1. Haga un fork del repositorio
  2. Cree una rama de características
  3. Realice sus cambios
  4. Agregue pruebas si corresponde
  5. Envíe una solicitud de pull

Soporte

Para problemas y preguntas: