Taiga MCP Bridge

Interactúa con la plataforma de gestión de proyectos Taiga a través de un puente MCP, permitiendo que herramientas de IA gestionen recursos del proyecto.

GitHub

Prueba este MCPPatrocinado

Documentación

Taiga MCP Bridge

Fork comunitario de talhaorak/pytaiga-mcp con características adicionales, CI/CD y mantenimiento continuo.

Resumen

Taiga MCP Bridge es una capa de integración potente que conecta la plataforma de gestión de proyectos Taiga con el Protocolo de Contexto de Modelos (MCP), permitiendo que herramientas y flujos de trabajo de IA interactúen sin problemas con los recursos de Taiga.

Este puente proporciona un conjunto completo de herramientas y recursos para que los agentes de IA puedan:

Crear y gestionar proyectos, épicas, historias de usuario, tareas e incidencias en Taiga
Realizar seguimiento de sprints e hitos
Asignar y actualizar elementos de trabajo
Consultar información detallada sobre los artefactos del proyecto
Gestionar miembros del proyecto y permisos

Al utilizar el estándar MCP, este puente permite que los sistemas de IA mantengan conciencia contextual sobre el estado del proyecto y realicen tareas complejas de gestión de proyectos de forma programática.

Características

Soporte Integral de Recursos

El puente admite los siguientes recursos de Taiga con operaciones CRUD completas:

Proyectos: Crear, actualizar y gestionar configuraciones y metadatos del proyecto
Épicas: Gestionar funcionalidades grandes que abarcan múltiples sprints
Historias de Usuario: Manejar requisitos detallados y criterios de aceptación
Tareas: Realizar seguimiento de unidades de trabajo más pequeñas dentro de historias de usuario
Incidencias: Gestionar errores, preguntas y solicitudes de mejora
Sprints (Hitos): Planificar y realizar seguimiento del trabajo en intervalos de tiempo definidos

Seguridad y Configuración

Credenciales Seguras: Autenticación mediante variables de entorno con protección de credenciales: las contraseñas nunca aparecen en registros ni mensajes de error
Auto-Autenticación: Configura las variables de entorno TAIGA_USERNAME y TAIGA_PASSWORD para un inicio sin problemas sin inicio de sesión manual
Validación de Entrada: La validación de parámetros basada en listas permitidas evita que datos inesperados lleguen a la API de Taiga

Filtrado de Respuestas

Todas las herramientas admiten un parámetro verbosity para controlar el tamaño de la respuesta, reduciendo el uso de contexto de IA:

Nivel	Descripción	Caso de Uso
`minimal`	Solo campos principales (id, ref, asunto, estado, proyecto)	Listar muchos elementos
`standard`	Campos comunes incluyendo versión para actualizaciones (predeterminado)	Operaciones normales
`full`	Respuesta completa de la API	Depuración, detalles completos

Ejemplo:

# Get minimal response for efficient context usage
stories = client.call_tool("list_user_stories", {
    "project_id": 123,
    "verbosity": "minimal"
})
# Returns: [{"id": 1, "ref": 42, "subject": "...", "status": 1, "project": 123}, ...]

Instalación

Este proyecto utiliza uv para una gestión de paquetes de Python rápida y confiable.

Requisitos Previos

Python 3.12 o superior
Gestor de paquetes uv

Instalación Básica

# Clone the repository
git clone https://github.com/TETRA-2023/pytaiga-mcp.git
cd pytaiga-mcp

# Install dependencies
./install.sh

Instalación para Desarrollo

Para desarrollo (incluye herramientas de prueba y calidad de código):

./install.sh --dev

Instalación Manual

Si prefieres instalar manualmente:

# Production dependencies only
uv pip install -e .

# With development dependencies
uv pip install -e ".[dev]"

Docker

Extrae la imagen preconstruida desde GHCR:

docker pull ghcr.io/tetra-2023/pytaiga-mcp:latest

O compila localmente:

docker build -t pytaiga-mcp .

Ejecuta con variables de entorno:

docker run -i --rm \
  -e TAIGA_API_URL=https://your-taiga-instance.com \
  -e TAIGA_USERNAME=your_username \
  -e TAIGA_PASSWORD=your_password \
  ghcr.io/tetra-2023/pytaiga-mcp:latest

Para usar transporte SSE en lugar de stdio, añade --sse:

docker run --rm \
  -e TAIGA_API_URL=https://your-taiga-instance.com \
  -e TAIGA_USERNAME=your_username \
  -e TAIGA_PASSWORD=your_password \
  -p 8000:8000 \
  ghcr.io/tetra-2023/pytaiga-mcp:latest --sse

Ejemplo de configuración de cliente MCP (.mcp.json) para transporte stdio:

{
  "mcpServers": {
    "taigaApi": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "TAIGA_API_URL",
        "-e", "TAIGA_USERNAME",
        "-e", "TAIGA_PASSWORD",
        "ghcr.io/tetra-2023/pytaiga-mcp:latest"
      ]
    }
  }
}

Nota: Usa -i (interactivo) sin -t (pseudo-TTY) para transporte stdio. La forma -e VAR (sin =value) reenvía la variable desde el entorno de tu host.

Configuración

El puente se puede configurar mediante variables de entorno o un archivo .env:

Variable de Entorno	Descripción	Predeterminado
`TAIGA_API_URL`	URL base para la API de Taiga	http://localhost:9000
`TAIGA_USERNAME`	Nombre de usuario de Taiga para auto-autenticación	(ninguno)
`TAIGA_PASSWORD`	Contraseña de Taiga para auto-autenticación	(ninguno)
`TAIGA_TRANSPORT`	Modo de transporte (stdio o sse)	stdio
`LOG_LEVEL`	Nivel de registro	INFO

Crea un archivo .env en la raíz del proyecto para establecer estos valores:

TAIGA_API_URL=https://api.taiga.io/api/v1/
TAIGA_USERNAME=your_username
TAIGA_PASSWORD=your_password
TAIGA_TRANSPORT=stdio
LOG_LEVEL=INFO

Nota de Seguridad: Las credenciales están protegidas y nunca aparecerán en registros, mensajes de error o trazas de pila. Cuando TAIGA_USERNAME y TAIGA_PASSWORD están configurados, el servidor se auto-autentica al inicio: no se requiere inicio de sesión manual.

Uso

Con modo stdio

Pega el siguiente json en la sección de configuración mcp de tu aplicación Claude o Cursor.

Recomendado: Configura las credenciales mediante variables de entorno en tu perfil de shell en lugar de en archivos de configuración para evitar exponerlas en texto plano.

{
    "mcpServers": {
        "taigaApi": {
            "command": "uv",
            "args": [
                "--directory",
                "<path to local pyTaigaMCP folder>",
                "run",
                "src/server.py"
            ],
            "env": {
                "TAIGA_TRANSPORT": "<stdio|sse>",                
                "TAIGA_API_URL": "<Taiga API Url (ex: http://localhost:9000)",
                "TAIGA_USERNAME": "<taiga username>",
                "TAIGA_PASSWORD": "<taiga password>"
            }
        }
}

Ejecutar el Puente

Inicia el servidor MCP con:

# Default stdio transport
./run.sh

# For SSE transport
./run.sh --sse

O manualmente:

# For stdio transport (default)
uv run python src/server.py

# For SSE transport
uv run python src/server.py --sse

Modos de Transporte

El servidor admite dos modos de transporte:

stdio (Entrada/Salida Estándar) - Modo predeterminado para clientes basados en terminal
SSE (Eventos Enviados por el Servidor) - Transporte basado en web con capacidades de envío desde el servidor

Puedes configurar el modo de transporte de varias formas:

Usando la bandera --sse con run.sh o server.py (el predeterminado es stdio)
Configurando la variable de entorno TAIGA_TRANSPORT
Añadiendo TAIGA_TRANSPORT=sse a tu archivo .env

Flujo de Autenticación

Auto-Autenticación (Recomendado)

Si las variables de entorno TAIGA_USERNAME y TAIGA_PASSWORD están configuradas, el servidor se autentica automáticamente al inicio. Puedes omitir session_id en las llamadas a herramientas para usar la sesión predeterminada:

# No login needed - uses auto-authenticated default session
projects = client.call_tool("list_projects", {})
stories = client.call_tool("list_user_stories", {"project_id": 123})
new_story = client.call_tool("create_user_story", {
    "project_id": 123,
    "subject": "New feature request"
})

Gestión Manual de Sesiones

Para escenarios que requieren múltiples sesiones o control explícito, usa el modelo basado en sesiones:

Inicio de Sesión: Autentícate usando la herramienta login:

session = client.call_tool("login", {
    "username": "your_taiga_username",
    "password": "your_taiga_password",
    "host": "https://api.taiga.io" # Optional
})
# Save the session_id from the response
session_id = session["session_id"]

Uso de Herramientas y Recursos: Incluye session_id en cada llamada a la API:

# For resources, include session_id in the URI
projects = client.get_resource(f"taiga://projects?session_id={session_id}")

# For project-specific resources
epics = client.get_resource(f"taiga://projects/123/epics?session_id={session_id}")

# For tools, include session_id as a parameter
new_project = client.call_tool("create_project", {
    "session_id": session_id,
    "name": "New Project",
    "description": "Description"
})

Verificar Estado de Sesión: Puedes verificar si tu sesión sigue siendo válida:

status = client.call_tool("session_status", {"session_id": session_id})
# Returns information about session validity and remaining time

Cierre de Sesión: Cuando termines, puedes cerrar sesión para finalizar la sesión:
```
client.call_tool("logout", {"session_id": session_id})
```

Ejemplo: Flujo Completo de Creación de Proyecto

Aquí tienes un ejemplo completo de creación de un proyecto con épicas e historias de usuario:

from mcp.client import Client

# Initialize MCP client
client = Client()

# Authenticate and get session ID
auth_result = client.call_tool("login", {
    "username": "admin",
    "password": "password123",
    "host": "https://taiga.mycompany.com"
})
session_id = auth_result["session_id"]

# Create a new project
project = client.call_tool("create_project", {
    "session_id": session_id,
    "name": "My New Project",
    "description": "A test project created via MCP"
})
project_id = project["id"]

# Create an epic
epic = client.call_tool("create_epic", {
    "session_id": session_id,
    "project_id": project_id,
    "subject": "User Authentication",
    "description": "Implement user authentication features"
})
epic_id = epic["id"]

# Create a user story in the epic
story = client.call_tool("create_user_story", {
    "session_id": session_id,
    "project_id": project_id,
    "subject": "User Login",
    "description": "As a user, I want to log in with my credentials",
    "epic_id": epic_id
})

# Logout when done
client.call_tool("logout", {"session_id": session_id})

Desarrollo

Estructura del Proyecto

pytaiga-mcp/
├── src/
│   ├── server.py          # MCP server implementation with tools
│   ├── taiga_client.py    # Taiga API client wrapper
│   └── config.py          # Configuration settings with Pydantic
├── tests/
│   ├── test_server.py     # Unit tests
│   └── test_integration.py # Integration tests
├── .github/workflows/
│   └── ci.yml             # CI pipeline (test, lint, Docker, release)
├── .pre-commit-config.yaml # Pre-commit hooks (ruff, pytest)
├── Dockerfile             # Container image definition
├── pyproject.toml         # Project configuration and dependencies
├── install.sh             # Installation script
├── run.sh                 # Server execution script
└── README.md              # Project documentation

Pruebas

Los hooks de pre-commit se ejecutan automáticamente en cada commit (ruff lint, ruff format, pruebas unitarias). Para ejecutar manualmente:

# Run pre-commit hooks on all files
uv run pre-commit run --all-files

# Run tests directly
uv run pytest tests/test_server.py -v --tb=short

# Run with coverage reporting
uv run pytest --cov=src

Depuración e Inspección

Usa la herramienta de inspección incluida para depurar:

# Default stdio transport
./inspect.sh

# For SSE transport
./inspect.sh --sse

# For development mode
./inspect.sh --dev

Manejo de Errores

Todas las operaciones de la API devuelven respuestas de error estandarizadas en el siguiente formato:

{
  "status": "error",
  "error_type": "ExceptionClassName",
  "message": "Detailed error message"
}

Características Planificadas

Las siguientes características están planificadas para futuras versiones:

Expiración de sesión y limpieza automática
Limitación de velocidad para llamadas a la API
Mecanismo de reintento con retroceso exponencial
Agrupación de conexiones

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en enviar una Solicitud de Extracción (Pull Request).

Haz un fork del repositorio
Crea tu rama de características (git checkout -b feature/amazing-feature)
Instala las dependencias de desarrollo (./install.sh --dev)
Configura los hooks de pre-commit (uv run pre-commit install)
Realiza tus cambios
Confirma tus cambios: los hooks de pre-commit ejecutarán linting y pruebas automáticamente
Sube a la rama (git push origin feature/amazing-feature)
Abre una Solicitud de Extracción

Licencia

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

Agradecimientos

Taiga por su excelente plataforma de gestión de proyectos
Protocolo de Contexto de Modelos (MCP) por el marco estandarizado de comunicación para IA
Todos los contribuyentes que han ayudado a dar forma a este proyecto