pack-mcp-gitlab 0.1.0__tar.gz

pack_mcp_gitlab-0.1.0/.kiro/specs/pack-mcp-gitlab/.config.kiro

@@ -0,0 +1 @@
+{"specId": "cc8549c0-6591-415d-8157-47290feae813", "workflowType": "requirements-first", "specType": "feature"}

pack_mcp_gitlab-0.1.0/.kiro/specs/pack-mcp-gitlab/design.md

@@ -0,0 +1,462 @@
+# Documento de Design — pack-mcp-gitlab
+
+## Visão Geral
+
+O `pack-mcp-gitlab` é um servidor MCP (Model Context Protocol) leve e standalone que expõe ferramentas para agentes de IA interagirem com a API do GitLab. O servidor é publicado no PyPI e executado via `uvx`, comunicando-se por protocolo stdio.
+
+A arquitetura segue o padrão de servidores MCP em Python: um módulo principal registra tools no framework `mcp`, cada tool delega operações a um cliente GitLab centralizado que encapsula a biblioteca `python-gitlab`. O servidor lê configuração (`GITLAB_URL`, `GITLAB_TOKEN`) de variáveis de ambiente injetadas pelo Config JSON do MCP.
+
+### Decisões de Design
+
+1. **Módulo único `server.py`**: Como o servidor é simples (8 tools, sem estado complexo), toda a lógica de registro de tools e inicialização fica em um único arquivo. Isso simplifica empacotamento e manutenção.
+2. **Classe `GitLabClient` separada**: Encapsula toda interação com `python-gitlab`, facilitando testes unitários via mock e isolando a camada de transporte.
+3. **Tratamento de erros centralizado**: Um decorator/wrapper converte exceções do `python-gitlab` em respostas MCP padronizadas, evitando repetição de try/except em cada tool.
+4. **Sem estado entre chamadas**: Cada invocação de tool é independente. O `GitLabClient` é instanciado uma vez na inicialização e reutilizado.
+
+## Arquitetura
+
+```mermaid
+graph TB
+    Agent[Agente de IA] -->|stdio / MCP Protocol| Server[MCP Server]
+    
+    subgraph "pack-mcp-gitlab"
+        Server -->|registra tools| Tools[Tool Handlers]
+        Tools -->|delega| Client[GitLabClient]
+        Client -->|python-gitlab| API[GitLab API]
+    end
+    
+    ENV[Variáveis de Ambiente<br/>GITLAB_URL, GITLAB_TOKEN] -->|leitura na inicialização| Server
+```
+
+### Fluxo de Execução
+
+```mermaid
+sequenceDiagram
+    participant A as Agente de IA
+    participant S as MCP Server (stdio)
+    participant T as Tool Handler
+    participant C as GitLabClient
+    participant G as GitLab API
+
+    A->>S: Invoca tool (ex: list_merge_requests)
+    S->>T: Despacha para handler registrado
+    T->>C: Chama método correspondente
+    C->>G: Requisição HTTP via python-gitlab
+    G-->>C: Resposta JSON
+    C-->>T: Dados processados
+    T-->>S: Resultado formatado (TextContent)
+    S-->>A: Resposta MCP
+```
+
+## Componentes e Interfaces
+
+### 1. Módulo `server.py` — Ponto de Entrada e Registro de Tools
+
+Responsável por:
+- Ler variáveis de ambiente (`GITLAB_URL`, `GITLAB_TOKEN`)
+- Validar configuração obrigatória na inicialização
+- Instanciar `GitLabClient`
+- Registrar todas as tools no servidor MCP via decorators `@mcp.tool()`
+- Iniciar o servidor com transporte stdio
+
+```python
+# Assinatura simplificada
+import os
+import logging
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("pack-mcp-gitlab")
+
+def get_gitlab_client() -> GitLabClient:
+    """Inicializa e retorna o cliente GitLab com validação de config."""
+    ...
+
+# Cada tool é uma função decorada:
+@mcp.tool()
+async def list_merge_requests(project_path: str, state: str = "opened") -> str:
+    ...
+
+@mcp.tool()
+async def get_merge_request(project_path: str, mr_iid: int) -> str:
+    ...
+
+# ... demais tools
+
+def main():
+    mcp.run(transport="stdio")
+```
+
+### 2. Classe `GitLabClient` — Camada de Acesso ao GitLab
+
+Encapsula toda interação com a API do GitLab via `python-gitlab`.
+
+```python
+class GitLabClient:
+    def __init__(self, gitlab_url: str, gitlab_token: str):
+        """Inicializa conexão com GitLab. Levanta ValueError se params inválidos."""
+        self.gl = gitlab.Gitlab(gitlab_url, private_token=gitlab_token)
+    
+    def list_merge_requests(self, project_path: str, state: str = "opened") -> list[dict]:
+        """Retorna lista de MRs do projeto filtrados por estado."""
+        ...
+    
+    def get_merge_request(self, project_path: str, mr_iid: int) -> dict:
+        """Retorna detalhes completos de um MR."""
+        ...
+    
+    def get_merge_request_changes(self, project_path: str, mr_iid: int) -> list[dict]:
+        """Retorna diffs/alterações de um MR."""
+        ...
+    
+    def get_file_content(self, project_path: str, file_path: str, ref: str = "HEAD") -> str:
+        """Retorna conteúdo de arquivo decodificado em UTF-8."""
+        ...
+    
+    def create_merge_request_note(self, project_path: str, mr_iid: int, body: str) -> dict:
+        """Cria comentário no MR. Retorna id e confirmação."""
+        ...
+    
+    def list_merge_request_notes(self, project_path: str, mr_iid: int) -> list[dict]:
+        """Retorna lista de comentários do MR."""
+        ...
+    
+    def get_project(self, project_path: str) -> dict:
+        """Retorna informações do projeto."""
+        ...
+    
+    def search_projects(self, search: str) -> list[dict]:
+        """Busca projetos por nome."""
+        ...
+```
+
+### 3. Módulo `errors.py` — Tratamento de Erros Centralizado
+
+Converte exceções do `python-gitlab` em mensagens de erro padronizadas para o MCP.
+
+```python
+from gitlab.exceptions import GitlabAuthenticationError, GitlabGetError, GitlabHttpError
+
+def handle_gitlab_error(func):
+    """Decorator que converte exceções GitLab em respostas de erro MCP."""
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except GitlabAuthenticationError:
+            raise McpError("Falha de autenticação: token inválido ou expirado")
+        except GitlabGetError as e:
+            if e.response_code == 404:
+                raise McpError("Recurso não encontrado")
+            raise McpError(f"Erro GitLab: {e.error_message}")
+        except GitlabHttpError as e:
+            if e.response_code == 403:
+                raise McpError("Permissão negada: token sem acesso à operação")
+            raise McpError(f"Erro HTTP GitLab: {e.error_message}")
+        except Exception as e:
+            raise McpError(f"Erro inesperado: {type(e).__name__}: {str(e)}")
+    return wrapper
+```
+
+## Modelos de Dados
+
+### Estruturas de Retorno das Tools
+
+Cada tool retorna dados serializados como JSON string via `TextContent` do MCP. Abaixo os schemas de cada retorno:
+
+#### MergeRequestSummary (list_merge_requests)
+```python
+{
+    "iid": int,
+    "title": str,
+    "author": str,           # username do autor
+    "source_branch": str,
+    "target_branch": str,
+    "state": str,             # "opened" | "closed" | "merged"
+    "web_url": str,
+    "created_at": str,        # ISO 8601
+    "updated_at": str         # ISO 8601
+}
+```
+
+#### MergeRequestDetail (get_merge_request)
+```python
+{
+    "iid": int,
+    "title": str,
+    "description": str | None,
+    "state": str,
+    "author": {
+        "name": str,
+        "username": str
+    },
+    "source_branch": str,
+    "target_branch": str,
+    "web_url": str,
+    "created_at": str,
+    "updated_at": str
+}
+```
+
+#### MergeRequestChange (get_merge_request_changes)
+```python
+[
+    {
+        "new_path": str,
+        "old_path": str,
+        "new_file": bool,
+        "renamed_file": bool,
+        "deleted_file": bool,
+        "diff": str
+    }
+]
+```
+
+#### FileContent (get_file_content)
+```python
+{
+    "file_path": str,
+    "ref": str,
+    "content": str            # conteúdo UTF-8
+}
+```
+
+#### NoteCreated (create_merge_request_note)
+```python
+{
+    "id": int,
+    "success": True
+}
+```
+
+#### Note (list_merge_request_notes)
+```python
+{
+    "id": int,
+    "body": str,
+    "author": {
+        "name": str,
+        "username": str
+    },
+    "created_at": str,
+    "system": bool
+}
+```
+
+#### ProjectInfo (get_project)
+```python
+{
+    "id": int,
+    "name": str,
+    "path_with_namespace": str,
+    "description": str | None,
+    "default_branch": str,
+    "web_url": str,
+    "visibility": str
+}
+```
+
+#### ProjectSearchResult (search_projects)
+```python
+{
+    "id": int,
+    "name": str,
+    "path_with_namespace": str,
+    "description": str | None,
+    "web_url": str
+}
+```
+
+### Estrutura do Pacote
+
+```
+pack-mcp-gitlab/
+├── pyproject.toml
+├── README.md
+├── LICENSE
+└── src/
+    └── pack_mcp_gitlab/
+        ├── __init__.py
+        ├── server.py          # Ponto de entrada, registro de tools
+        ├── client.py          # GitLabClient
+        └── errors.py          # Tratamento de erros centralizado
+```
+
+### pyproject.toml (Estrutura)
+
+```toml
+[project]
+name = "pack-mcp-gitlab"
+version = "0.1.0"
+description = "MCP server for GitLab API integration"
+requires-python = ">=3.10"
+dependencies = [
+    "python-gitlab>=4.0.0",
+    "mcp>=1.0.0",
+]
+
+[project.scripts]
+pack-mcp-gitlab = "pack_mcp_gitlab.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+```
+
+
+## Propriedades de Corretude
+
+*Uma propriedade é uma característica ou comportamento que deve ser verdadeiro em todas as execuções válidas de um sistema — essencialmente, uma declaração formal sobre o que o sistema deve fazer. Propriedades servem como ponte entre especificações legíveis por humanos e garantias de corretude verificáveis por máquina.*
+
+### Propriedade 1: Validação de parâmetros obrigatórios na inicialização
+
+*Para qualquer* string vazia ou composta apenas de espaços em branco fornecida como `GITLAB_URL` ou `GITLAB_TOKEN`, a inicialização do servidor deve levantar um erro descritivo indicando qual parâmetro está ausente.
+
+**Valida: Requisitos 1.1, 1.3, 1.4**
+
+### Propriedade 2: Formatação de MR preserva todos os campos obrigatórios
+
+*Para qualquer* dado de Merge Request válido retornado pela API do GitLab (contendo iid, title, author, branches, state, urls, timestamps), a saída formatada da tool deve conter todos os campos especificados no modelo de dados correspondente.
+
+**Valida: Requisitos 2.2, 3.2**
+
+### Propriedade 3: Formatação de changes preserva todos os campos obrigatórios
+
+*Para qualquer* lista de alterações de arquivo válida retornada pela API do GitLab, a saída formatada deve conter para cada arquivo: `new_path`, `old_path`, `new_file`, `renamed_file`, `deleted_file` e `diff`.
+
+**Valida: Requisitos 4.2**
+
+### Propriedade 4: Formatação de notes preserva todos os campos obrigatórios
+
+*Para qualquer* lista de comentários válida retornada pela API do GitLab, a saída formatada deve conter para cada note: `id`, `body`, `author` (name e username), `created_at` e `system`.
+
+**Valida: Requisitos 7.2**
+
+### Propriedade 5: Formatação de projeto preserva todos os campos obrigatórios
+
+*Para qualquer* dado de projeto válido retornado pela API do GitLab, a saída formatada deve conter: `id`, `name`, `path_with_namespace`, `description`, `default_branch`, `web_url` e `visibility` (para get_project) ou `id`, `name`, `path_with_namespace`, `description` e `web_url` (para search_projects).
+
+**Valida: Requisitos 8.2, 9.2**
+
+### Propriedade 6: Tratamento de erros por tipo de exceção
+
+*Para qualquer* exceção do `python-gitlab`, o error handler deve produzir uma mensagem de erro descritiva apropriada ao tipo: erros 404 devem mencionar "não encontrado", erros 403 devem mencionar "permissão", erros de autenticação devem mencionar "autenticação", e erros de rede devem incluir o tipo e mensagem original da exceção.
+
+**Valida: Requisitos 2.4, 3.3, 4.3, 5.4, 6.4, 7.3, 8.3, 11.1, 11.2, 11.3**
+
+### Propriedade 7: Parâmetros opcionais são repassados corretamente à API
+
+*Para qualquer* valor válido do parâmetro `state` (opened, closed, merged, all) em `list_merge_requests`, e *para qualquer* valor de `ref` em `get_file_content`, o cliente deve repassar esses parâmetros à chamada da API do GitLab.
+
+**Valida: Requisitos 2.3, 5.3**
+
+### Propriedade 8: Validação de body vazio em create_merge_request_note
+
+*Para qualquer* string vazia ou composta apenas de espaços em branco fornecida como `body`, a tool `create_merge_request_note` deve rejeitar a chamada com erro descritivo, sem realizar chamada à API.
+
+**Valida: Requisitos 6.5**
+
+### Propriedade 9: Logs de erro não expõem dados sensíveis
+
+*Para qualquer* token de acesso configurado e *para qualquer* erro que gere log, a mensagem de log registrada não deve conter o valor do token.
+
+**Valida: Requisitos 11.4**
+
+### Propriedade 10: Resposta de criação de nota contém id e confirmação
+
+*Para qualquer* nota criada com sucesso pela API do GitLab (retornando um id numérico), a saída formatada da tool deve conter o `id` da nota e o campo `success` como `true`.
+
+**Valida: Requisitos 6.3**
+
+## Tratamento de Erros
+
+### Estratégia
+
+O tratamento de erros é centralizado no módulo `errors.py` via decorator `@handle_gitlab_error` aplicado a todos os métodos do `GitLabClient`. Isso garante consistência e evita duplicação.
+
+### Mapeamento de Exceções
+
+| Exceção python-gitlab | HTTP Code | Mensagem MCP |
+|---|---|---|
+| `GitlabAuthenticationError` | 401 | "Falha de autenticação: token inválido ou expirado" |
+| `GitlabGetError` (404) | 404 | "Recurso não encontrado: {contexto}" |
+| `GitlabHttpError` (403) | 403 | "Permissão negada: token sem acesso para esta operação" |
+| `requests.ConnectionError` | — | "Erro de conexão: {mensagem original}" |
+| `requests.Timeout` | — | "Timeout na conexão com GitLab: {mensagem}" |
+| Outras exceções | — | "Erro inesperado: {tipo}: {mensagem}" |
+
+### Validações na Inicialização
+
+- `GITLAB_URL` ausente/vazio → `ValueError("GITLAB_URL é obrigatório. Configure a variável de ambiente.")`
+- `GITLAB_TOKEN` ausente/vazio → `ValueError("GITLAB_TOKEN é obrigatório. Configure a variável de ambiente.")`
+
+### Validações em Tools
+
+- `body` vazio em `create_merge_request_note` → erro descritivo sem chamar API
+- `state` inválido em `list_merge_requests` → repassado ao GitLab que retorna erro (sem validação local extra)
+
+### Logging
+
+- Logs de erro com `logging.error()` incluindo tipo de exceção e mensagem
+- Token NUNCA aparece em logs — usar mascaramento ou omissão
+- Nível de log configurável via variável de ambiente `LOG_LEVEL` (padrão: `WARNING`)
+
+## Estratégia de Testes
+
+### Abordagem Dual
+
+O projeto utiliza duas abordagens complementares de teste:
+
+1. **Testes unitários** (pytest): Verificam exemplos específicos, edge cases e condições de erro
+2. **Testes de propriedade** (Hypothesis): Verificam propriedades universais com inputs gerados aleatoriamente
+
+### Biblioteca de Property-Based Testing
+
+- **Hypothesis** (Python) — biblioteca padrão para PBT em Python
+- Configuração: mínimo de 100 iterações por teste de propriedade
+- Cada teste de propriedade deve referenciar a propriedade do design via tag no formato:
+  `Feature: pack-mcp-gitlab, Property {N}: {título}`
+
+### Testes Unitários
+
+Focam em:
+- Verificação de registro correto das 8 tools (nomes, parâmetros)
+- Exemplos específicos de formatação de dados
+- Edge cases: lista vazia de MRs, projeto sem descrição, MR sem description
+- Integração do error handler com exceções reais do python-gitlab (via mock)
+- Verificação do pyproject.toml (entry point, dependências)
+- Transporte stdio configurado corretamente
+
+### Testes de Propriedade
+
+Cada propriedade do design é implementada como um único teste Hypothesis:
+
+| Propriedade | Estratégia de Geração |
+|---|---|
+| P1: Validação de config | Gerar strings vazias/whitespace para URL e token |
+| P2: Formatação de MR | Gerar dicts com campos de MR aleatórios |
+| P3: Formatação de changes | Gerar listas de dicts com campos de change aleatórios |
+| P4: Formatação de notes | Gerar listas de dicts com campos de note aleatórios |
+| P5: Formatação de projeto | Gerar dicts com campos de projeto aleatórios |
+| P6: Error handler | Gerar exceções de diferentes tipos com mensagens aleatórias |
+| P7: Parâmetros opcionais | Gerar valores de state e ref aleatórios válidos |
+| P8: Body vazio | Gerar strings whitespace-only |
+| P9: Logs sem token | Gerar tokens aleatórios e provocar erros |
+| P10: Resposta de nota | Gerar IDs numéricos aleatórios |
+
+### Mocking
+
+- Todas as chamadas à API do GitLab são mockadas nos testes unitários e de propriedade
+- O `python-gitlab` é mockado no nível do `gitlab.Gitlab` para isolar o `GitLabClient`
+- Nenhum teste faz chamada real à API
+
+### Estrutura de Testes
+
+```
+tests/
+├── conftest.py              # Fixtures compartilhadas (mock GitLab client)
+├── test_server.py           # Testes unitários do registro de tools
+├── test_client.py           # Testes unitários do GitLabClient
+├── test_errors.py           # Testes unitários do error handler
+├── test_properties.py       # Testes de propriedade (Hypothesis)
+└── strategies.py            # Estratégias Hypothesis para geração de dados
+```

pack_mcp_gitlab-0.1.0/.kiro/specs/pack-mcp-gitlab/requirements.md

@@ -0,0 +1,135 @@
+# Documento de Requisitos — pack-mcp-gitlab
+
+## Introdução
+
+O `pack-mcp-gitlab` é um servidor MCP (Model Context Protocol) standalone, publicado no PyPI, que expõe ferramentas para agentes de IA interagirem com a API do GitLab. O servidor recebe URL e token do GitLab como parâmetros de configuração via JSON do MCP e disponibiliza tools para consultar Merge Requests, obter diffs, ler conteúdo de arquivos, postar comentários e listar projetos. Este servidor substitui a camada de interação com o GitLab que hoje existe no projeto KiroReview, isolando-a como pacote reutilizável.
+
+## Glossário
+
+- **MCP_Server**: O servidor MCP `pack-mcp-gitlab` que recebe requisições de agentes de IA e interage com a API do GitLab
+- **GitLab_Client**: Componente interno do MCP_Server responsável por autenticar e executar chamadas à API do GitLab usando a biblioteca `python-gitlab`
+- **MR**: Merge Request no GitLab — solicitação de mesclagem de código entre branches
+- **Tool**: Uma ferramenta exposta pelo MCP_Server que agentes de IA podem invocar via protocolo MCP
+- **Config_JSON**: Arquivo de configuração JSON do MCP que contém URL do GitLab, token de acesso e demais parâmetros
+- **Diff**: Representação textual das diferenças entre versões de um arquivo em um MR
+- **Note**: Comentário postado em um MR no GitLab
+- **Project**: Repositório/projeto no GitLab identificado por path (ex: `grupo/subgrupo/projeto`)
+
+## Requisitos
+
+### Requisito 1: Configuração e Autenticação
+
+**User Story:** Como agente de IA, eu quero configurar o MCP_Server com URL e token do GitLab via Config_JSON, para que o servidor autentique nas chamadas à API do GitLab.
+
+#### Critérios de Aceitação
+
+1. WHEN o MCP_Server é iniciado, THE MCP_Server SHALL ler os parâmetros `GITLAB_URL` e `GITLAB_TOKEN` das variáveis de ambiente fornecidas no Config_JSON
+2. WHEN o MCP_Server é iniciado com `GITLAB_URL` e `GITLAB_TOKEN` válidos, THE GitLab_Client SHALL autenticar com sucesso na API do GitLab
+3. IF o parâmetro `GITLAB_TOKEN` estiver ausente ou vazio, THEN THE MCP_Server SHALL retornar um erro descritivo informando que o token é obrigatório
+4. IF o parâmetro `GITLAB_URL` estiver ausente ou vazio, THEN THE MCP_Server SHALL retornar um erro descritivo informando que a URL é obrigatória
+5. IF o token fornecido for inválido ou expirado, THEN THE GitLab_Client SHALL retornar um erro descritivo informando falha de autenticação
+
+### Requisito 2: Listar Merge Requests
+
+**User Story:** Como agente de IA, eu quero listar Merge Requests de um projeto no GitLab, para que eu possa identificar MRs relevantes para análise.
+
+#### Critérios de Aceitação
+
+1. THE MCP_Server SHALL expor uma Tool chamada `list_merge_requests` que aceita os parâmetros `project_path` (obrigatório) e `state` (opcional, padrão: `opened`)
+2. WHEN a Tool `list_merge_requests` é invocada com um `project_path` válido, THE GitLab_Client SHALL retornar uma lista de MRs contendo para cada MR: `iid`, `title`, `author`, `source_branch`, `target_branch`, `state`, `web_url`, `created_at` e `updated_at`
+3. WHERE o parâmetro `state` é fornecido, THE GitLab_Client SHALL filtrar os MRs pelo estado informado (valores aceitos: `opened`, `closed`, `merged`, `all`)
+4. IF o `project_path` não corresponder a um projeto existente, THEN THE MCP_Server SHALL retornar um erro descritivo informando que o projeto não foi encontrado
+
+### Requisito 3: Obter Detalhes de um Merge Request
+
+**User Story:** Como agente de IA, eu quero obter os detalhes completos de um MR específico, para que eu possa analisar o contexto da mudança.
+
+#### Critérios de Aceitação
+
+1. THE MCP_Server SHALL expor uma Tool chamada `get_merge_request` que aceita os parâmetros `project_path` (obrigatório) e `mr_iid` (obrigatório)
+2. WHEN a Tool `get_merge_request` é invocada com parâmetros válidos, THE GitLab_Client SHALL retornar os dados do MR contendo: `iid`, `title`, `description`, `state`, `author` (nome e username), `source_branch`, `target_branch`, `web_url`, `created_at` e `updated_at`
+3. IF o `mr_iid` não corresponder a um MR existente no projeto, THEN THE MCP_Server SHALL retornar um erro descritivo informando que o MR não foi encontrado
+
+### Requisito 4: Obter Alterações (Diffs) de um Merge Request
+
+**User Story:** Como agente de IA, eu quero obter os diffs de um MR, para que eu possa realizar code review analisando as mudanças linha a linha.
+
+#### Critérios de Aceitação
+
+1. THE MCP_Server SHALL expor uma Tool chamada `get_merge_request_changes` que aceita os parâmetros `project_path` (obrigatório) e `mr_iid` (obrigatório)
+2. WHEN a Tool `get_merge_request_changes` é invocada com parâmetros válidos, THE GitLab_Client SHALL retornar a lista de arquivos alterados contendo para cada arquivo: `new_path`, `old_path`, `new_file` (booleano), `renamed_file` (booleano), `deleted_file` (booleano) e `diff` (texto do diff)
+3. IF o MR não existir no projeto informado, THEN THE MCP_Server SHALL retornar um erro descritivo informando que o MR não foi encontrado
+
+### Requisito 5: Ler Conteúdo de Arquivo do Repositório
+
+**User Story:** Como agente de IA, eu quero ler o conteúdo completo de um arquivo no repositório, para que eu possa analisar o contexto além do diff durante um code review.
+
+#### Critérios de Aceitação
+
+1. THE MCP_Server SHALL expor uma Tool chamada `get_file_content` que aceita os parâmetros `project_path` (obrigatório), `file_path` (obrigatório) e `ref` (opcional, padrão: `HEAD`)
+2. WHEN a Tool `get_file_content` é invocada com parâmetros válidos, THE GitLab_Client SHALL retornar o conteúdo do arquivo decodificado em UTF-8
+3. WHERE o parâmetro `ref` é fornecido, THE GitLab_Client SHALL buscar o conteúdo do arquivo na branch ou commit especificado
+4. IF o arquivo não existir no caminho ou ref informados, THEN THE MCP_Server SHALL retornar um erro descritivo informando que o arquivo não foi encontrado
+
+### Requisito 6: Postar Comentário em um Merge Request
+
+**User Story:** Como agente de IA, eu quero postar comentários em um MR, para que eu possa registrar resultados de code review diretamente no GitLab.
+
+#### Critérios de Aceitação
+
+1. THE MCP_Server SHALL expor uma Tool chamada `create_merge_request_note` que aceita os parâmetros `project_path` (obrigatório), `mr_iid` (obrigatório) e `body` (obrigatório)
+2. WHEN a Tool `create_merge_request_note` é invocada com parâmetros válidos, THE GitLab_Client SHALL criar um comentário (Note) no MR com o conteúdo fornecido em `body`
+3. WHEN o comentário é criado com sucesso, THE MCP_Server SHALL retornar o `id` do comentário criado e a confirmação de sucesso
+4. IF o MR não existir no projeto informado, THEN THE MCP_Server SHALL retornar um erro descritivo informando que o MR não foi encontrado
+5. IF o `body` estiver vazio, THEN THE MCP_Server SHALL retornar um erro descritivo informando que o conteúdo do comentário é obrigatório
+
+### Requisito 7: Listar Comentários de um Merge Request
+
+**User Story:** Como agente de IA, eu quero listar os comentários existentes em um MR, para que eu possa entender o histórico de discussões e evitar duplicar feedback.
+
+#### Critérios de Aceitação
+
+1. THE MCP_Server SHALL expor uma Tool chamada `list_merge_request_notes` que aceita os parâmetros `project_path` (obrigatório) e `mr_iid` (obrigatório)
+2. WHEN a Tool `list_merge_request_notes` é invocada com parâmetros válidos, THE GitLab_Client SHALL retornar a lista de comentários do MR contendo para cada Note: `id`, `body`, `author` (nome e username), `created_at` e `system` (booleano indicando se é nota do sistema)
+3. IF o MR não existir no projeto informado, THEN THE MCP_Server SHALL retornar um erro descritivo informando que o MR não foi encontrado
+
+### Requisito 8: Obter Informações de um Projeto
+
+**User Story:** Como agente de IA, eu quero obter informações de um projeto no GitLab, para que eu possa contextualizar análises com dados do repositório.
+
+#### Critérios de Aceitação
+
+1. THE MCP_Server SHALL expor uma Tool chamada `get_project` que aceita o parâmetro `project_path` (obrigatório)
+2. WHEN a Tool `get_project` é invocada com um `project_path` válido, THE GitLab_Client SHALL retornar os dados do projeto contendo: `id`, `name`, `path_with_namespace`, `description`, `default_branch`, `web_url` e `visibility`
+3. IF o `project_path` não corresponder a um projeto existente, THEN THE MCP_Server SHALL retornar um erro descritivo informando que o projeto não foi encontrado
+
+### Requisito 9: Buscar Projetos
+
+**User Story:** Como agente de IA, eu quero buscar projetos no GitLab por nome, para que eu possa descobrir o path correto de um projeto quando não o conheço.
+
+#### Critérios de Aceitação
+
+1. THE MCP_Server SHALL expor uma Tool chamada `search_projects` que aceita o parâmetro `search` (obrigatório)
+2. WHEN a Tool `search_projects` é invocada com um termo de busca, THE GitLab_Client SHALL retornar uma lista de projetos correspondentes contendo para cada projeto: `id`, `name`, `path_with_namespace`, `description` e `web_url`
+3. WHEN nenhum projeto corresponder ao termo de busca, THE MCP_Server SHALL retornar uma lista vazia
+
+### Requisito 10: Publicação no PyPI
+
+**User Story:** Como desenvolvedor, eu quero que o pacote seja publicável no PyPI como `pack-mcp-gitlab`, para que usuários possam instalá-lo via `uvx pack-mcp-gitlab@latest`.
+
+#### Critérios de Aceitação
+
+1. THE MCP_Server SHALL ser empacotado com `pyproject.toml` contendo o nome `pack-mcp-gitlab`, versão semântica, dependências (`python-gitlab`, `mcp`) e entry point para execução via `uvx`
+2. THE MCP_Server SHALL utilizar o protocolo stdio para comunicação MCP
+3. THE MCP_Server SHALL ser compatível com a configuração MCP no formato: `{"command": "uvx", "args": ["pack-mcp-gitlab@latest"], "env": {"GITLAB_URL": "...", "GITLAB_TOKEN": "..."}}`
+
+### Requisito 11: Tratamento de Erros
+
+**User Story:** Como agente de IA, eu quero receber mensagens de erro claras e estruturadas, para que eu possa entender e comunicar falhas ao usuário.
+
+#### Critérios de Aceitação
+
+1. IF uma chamada à API do GitLab falhar por erro de rede, THEN THE MCP_Server SHALL retornar um erro descritivo contendo o tipo de falha e a mensagem original da exceção
+2. IF uma chamada à API do GitLab retornar erro de permissão (HTTP 403), THEN THE MCP_Server SHALL retornar um erro descritivo informando que o token não possui permissão para a operação solicitada
+3. IF uma chamada à API do GitLab retornar erro de recurso não encontrado (HTTP 404), THEN THE MCP_Server SHALL retornar um erro descritivo informando que o recurso solicitado não existe
+4. THE MCP_Server SHALL registrar logs de erro com detalhes suficientes para diagnóstico sem expor dados sensíveis como tokens