Puente Taiga MCP

Descripción general

El puente Taiga MCP es una poderosa capa de integración que conecta la plataforma de gestión de proyectos Taiga con el Protocolo de contexto de modelo (MCP), lo que permite que las herramientas y los 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:

Cree y administre proyectos, epopeyas, historias de usuario, tareas y problemas en Taiga
Realizar un seguimiento de sprints y hitos
Asignar y actualizar elementos de trabajo
Consultar información detallada sobre los artefactos del proyecto
Administrar miembros y permisos del proyecto

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

Características

Soporte integral de recursos

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

Proyectos : crear, actualizar y administrar configuraciones y metadatos del proyecto
Épicas : administre funciones grandes que abarcan varios sprints
Historias de usuario : Manejar requisitos detallados y criterios de aceptación
Tareas : Realizar un seguimiento de unidades de trabajo más pequeñas dentro de las historias de usuario
Problemas : gestionar errores, preguntas y solicitudes de mejora
Sprints (hitos) : planifique y realice un seguimiento del trabajo en intervalos de tiempo definidos

Instalación

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

Prerrequisitos

Python 3.10 o superior
administrador de paquetes uv

Instalación básica

# Clone the repository
git clone https://github.com/your-org/pyTaigaMCP.git
cd pyTaigaMCP

# Install dependencies
./install.sh

Instalación de desarrollo

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

./install.sh --dev

Instalación manual

Si prefieres instalarlo manualmente:

# Production dependencies only
uv pip install -e .

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

Configuración

El puente se puede configurar a través de variables de entorno o un archivo .env :

Variable de entorno	Descripción	Por defecto
`TAIGA_API_URL`	URL base para la API de Taiga	http://localhost:9000
`SESSION_EXPIRY`	Tiempo de expiración de la sesión en segundos	28800 (8 horas)
`TAIGA_TRANSPORT`	Modo de transporte (stdio o sse)	estudio
`REQUEST_TIMEOUT`	Tiempo de espera de la solicitud de API en segundos	30
`MAX_CONNECTIONS`	Número máximo de conexiones HTTP	10
`MAX_KEEPALIVE_CONNECTIONS`	Máximo de conexiones keepalive	5
`RATE_LIMIT_REQUESTS`	Máximo de solicitudes por minuto	100
`LOG_LEVEL`	Nivel de registro	INFORMACIÓN
`LOG_FILE`	Ruta al archivo de registro	taiga_mcp.log

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

TAIGA_API_URL=https://api.taiga.io/api/v1/
TAIGA_TRANSPORT=sse
LOG_LEVEL=DEBUG

Uso

Con modo stdio

Pegue el siguiente json en la sección de configuración mcp de su aplicación Claude o Cursor:

{
    "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>"
            }
        }
}

Corriendo el Puente

Inicie 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 al servidor

Puede configurar el modo de transporte de varias maneras:

Usando el indicador --sse con run.sh o server.py (el valor predeterminado es stdio)
Configuración de la variable de entorno TAIGA_TRANSPORT
Agregar TAIGA_TRANSPORT=sse a su archivo .env

Flujo de autenticación

Este puente MCP utiliza un modelo de autenticación basado en sesión:

Iniciar sesión : Los clientes primero deben autenticarse utilizando 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 : Incluya el session_id en cada llamada 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" })
Comprobar el estado de la sesión : Puedes comprobar 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
Cerrar sesión : cuando haya terminado, puede cerrar la sesión para finalizar la sesión:
client.call_tool("logout", {"session_id": session_id})

Ejemplo: Flujo de trabajo completo de creación de proyectos

A continuación se muestra un ejemplo completo de creación de un proyecto con epopeyas 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

pyTaigaMCP/
├── src/
│   ├── server.py          # MCP server implementation with tools
│   ├── taiga_client.py    # Taiga API client with all CRUD operations
│   ├── tools.py           # MCP tools definitions
│   └── config.py          # Configuration settings with Pydantic
├── tests/
│   ├── conftest.py        # Shared pytest fixtures
│   ├── unit/              # Unit tests
│   └── integration/       # Integration tests
├── pyproject.toml         # Project configuration and dependencies
├── install.sh             # Installation script
├── run.sh                 # Server execution script
└── README.md              # Project documentation

Pruebas

Ejecutar pruebas con pytest:

# Run all tests
pytest

# Run only unit tests
pytest tests/unit/

# Run only integration tests
pytest tests/integration/

# Run tests with specific markers
pytest -m "auth"  # Authentication tests
pytest -m "core"  # Core functionality tests

# Run tests with coverage reporting
pytest --cov=src

Depuración e inspección

Utilice 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 API devuelven respuestas de error estandarizadas en el siguiente formato:

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

Consideraciones de rendimiento

El puente implementa varias optimizaciones de rendimiento:

Agrupación de conexiones : reutiliza las conexiones HTTP para un mejor rendimiento
Limitación de velocidad : evita la sobrecarga de la API de Taiga
Mecanismo de reintento : reintenta automáticamente las solicitudes fallidas con retroceso exponencial
Limpieza de sesiones : limpia periódicamente las sesiones caducadas para liberar recursos

Contribuyendo

¡Agradecemos sus contribuciones! No dude en enviar una solicitud de incorporación de cambios.

Bifurcar el repositorio
Crea tu rama de funciones ( git checkout -b feature/amazing-feature )
Instalar dependencias de desarrollo ( ./install.sh --dev )
Realiza tus cambios
Ejecutar pruebas ( pytest )
Confirme sus cambios ( git commit -m 'Add some amazing feature' )
Empujar a la rama ( git push origin feature/amazing-feature )
Abrir una solicitud de extracción

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

Expresiones de gratitud

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

Taiga MCP Bridge

Integrations