Taiga MCP Bridge

Interaja com a plataforma de gerenciamento de projetos Taiga por meio de uma ponte MCP, permitindo que ferramentas de IA gerenciem recursos do projeto.

GitHub

Experimente este MCPPatrocinado

Documentação

Taiga MCP Bridge

Fork da comunidade de talhaorak/pytaiga-mcp com recursos adicionais, CI/CD e manutenção contínua.

Visão Geral

O Taiga MCP Bridge é uma camada de integração poderosa que conecta a plataforma de gerenciamento de projetos Taiga ao Model Context Protocol (MCP), permitindo que ferramentas de IA e fluxos de trabalho interajam perfeitamente com os recursos do Taiga.

Este bridge fornece um conjunto abrangente de ferramentas e recursos para agentes de IA:

Criar e gerenciar projetos, épicos, histórias de usuário, tarefas e problemas no Taiga
Acompanhar sprints e marcos
Atribuir e atualizar itens de trabalho
Consultar informações detalhadas sobre artefatos do projeto
Gerenciar membros do projeto e permissões

Ao usar o padrão MCP, este bridge permite que sistemas de IA mantenham consciência contextual sobre o estado do projeto e executem tarefas complexas de gerenciamento de projetos programaticamente.

Recursos

Suporte Abrangente a Recursos

O bridge suporta os seguintes recursos do Taiga com operações CRUD completas:

Projetos: Criar, atualizar e gerenciar configurações e metadados do projeto
Épicos: Gerenciar grandes funcionalidades que abrangem múltiplos sprints
Histórias de Usuário: Lidar com requisitos detalhados e critérios de aceitação
Tarefas: Acompanhar unidades menores de trabalho dentro das histórias de usuário
Problemas: Gerenciar bugs, perguntas e solicitações de melhorias
Sprints (Marcos): Planejar e acompanhar o trabalho em intervalos de tempo definidos

Segurança e Configuração

Credenciais Seguras: Autenticação por variáveis de ambiente com proteção de credenciais — senhas nunca aparecem em logs ou mensagens de erro
Autenticação Automática: Configure as variáveis de ambiente TAIGA_USERNAME e TAIGA_PASSWORD para inicialização sem interrupções, sem necessidade de login manual
Validação de Entrada: Validação de parâmetros baseada em lista de permissões evita que dados inesperados cheguem à API do Taiga

Filtragem de Respostas

Todas as ferramentas suportam o parâmetro verbosity para controlar o tamanho da resposta, reduzindo o uso de contexto da IA:

Nível	Descrição	Caso de Uso
`minimal`	Apenas campos principais (id, ref, subject, status, project)	Listar muitos itens
`standard`	Campos comuns, incluindo versão para atualizações (padrão)	Operações normais
`full`	Resposta completa da API	Depuração, detalhes completos

Exemplo:

# 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}, ...]

Instalação

Este projeto usa uv para gerenciamento de pacotes Python rápido e confiável.

Pré-requisitos

Python 3.12 ou superior
Gerenciador de pacotes uv

Instalação Básica

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

# Install dependencies
./install.sh

Instalação para Desenvolvimento

Para desenvolvimento (inclui ferramentas de teste e qualidade de código):

./install.sh --dev

Instalação Manual

Se preferir instalar manualmente:

# Production dependencies only
uv pip install -e .

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

Docker

Baixe a imagem pré-construída do GHCR:

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

Ou construa localmente:

docker build -t pytaiga-mcp .

Execute com variáveis de ambiente:

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 em vez de stdio, acrescente --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

Exemplo de configuração 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: Use -i (interativo) sem -t (pseudo-TTY) para transporte stdio. A forma -e VAR (sem =value) encaminha a variável do ambiente do seu host.

Configuração

O bridge pode ser configurado por meio de variáveis de ambiente ou de um arquivo .env:

Variável de Ambiente	Descrição	Padrão
`TAIGA_API_URL`	URL base para a API do Taiga	http://localhost:9000
`TAIGA_USERNAME`	Nome de usuário do Taiga para autenticação automática	(nenhum)
`TAIGA_PASSWORD`	Senha do Taiga para autenticação automática	(nenhum)
`TAIGA_TRANSPORT`	Modo de transporte (stdio ou sse)	stdio
`LOG_LEVEL`	Nível de registro (logging)	INFO

Crie um arquivo .env na raiz do projeto para definir esses 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 Segurança: As credenciais são protegidas e nunca aparecerão em logs, mensagens de erro ou rastreamentos de pilha. Quando TAIGA_USERNAME e TAIGA_PASSWORD estiverem configurados, o servidor autentica automaticamente na inicialização — nenhum login manual é necessário.

Uso

Com modo stdio

Cole o seguinte JSON nas configurações de mcp do seu aplicativo Claude ou Cursor.

Recomendado: Defina as credenciais por meio de variáveis de ambiente no seu perfil de shell, em vez de arquivos de configuração, para evitar expô-las em texto simples.

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

Executando o Bridge

Inicie o servidor MCP com:

# Default stdio transport
./run.sh

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

Ou manualmente:

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

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

Modos de Transporte

O servidor suporta dois modos de transporte:

stdio (Entrada/Saída Padrão) — Modo padrão para clientes baseados em terminal
SSE (Server-Sent Events) — Transporte baseado na web com recursos de push do servidor

Você pode definir o modo de transporte de várias maneiras:

Usando a flag --sse com run.sh ou server.py (o padrão é stdio)
Definindo a variável de ambiente TAIGA_TRANSPORT
Adicionando TAIGA_TRANSPORT=sse ao seu arquivo .env

Fluxo de Autenticação

Autenticação Automática (Recomendada)

Se as variáveis de ambiente TAIGA_USERNAME e TAIGA_PASSWORD estiverem definidas, o servidor autentica automaticamente na inicialização. Você pode omitir session_id das chamadas de ferramenta para usar a sessão padrão:

# 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"
})

Gerenciamento Manual de Sessão

Para cenários que exigem múltiplas sessões ou controle explícito, use o modelo baseado em sessão:

Login: Autentique usando a ferramenta 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"]

Usando Ferramentas e Recursos: Inclua o session_id em cada chamada de 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"
})

Verifique o Status da Sessão: Você pode verificar se sua sessão ainda é válida:

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

Logout: Quando terminar, você pode fazer logout para encerrar a sessão:
```
client.call_tool("logout", {"session_id": session_id})
```

Exemplo: Fluxo Completo de Criação de Projeto

Aqui está um exemplo completo de criação de um projeto com épicos e histórias de usuário:

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})

Desenvolvimento

Estrutura do Projeto

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

Testes

Os hooks de pré-commit são executados automaticamente a cada commit (ruff lint, ruff format, testes unitários). Para executar 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

Depuração e Inspeção

Use a ferramenta de inspeção incluída para depuração:

# Default stdio transport
./inspect.sh

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

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

Tratamento de Erros

Todas as operações de API retornam respostas de erro padronizadas no seguinte formato:

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

Recursos Planejados

Os seguintes recursos estão planejados para versões futuras:

Expiração de sessão e limpeza automática
Limitação de taxa para chamadas de API
Mecanismo de nova tentativa com backoff exponencial
Pooling de conexões

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request.

Faça um fork do repositório
Crie sua branch de funcionalidade (git checkout -b feature/amazing-feature)
Instale as dependências de desenvolvimento (./install.sh --dev)
Configure os hooks de pré-commit (uv run pre-commit install)
Faça suas alterações
Faça commit das suas alterações — os hooks de pré-commit executarão lint e testes automaticamente
Envie para a branch (git push origin feature/amazing-feature)
Abra um Pull Request

Licença

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

Agradecimentos

Taiga pela excelente plataforma de gerenciamento de projetos
Model Context Protocol (MCP) pelo framework padronizado de comunicação para IA
Todos os contribuidores que ajudaram a moldar este projeto