fenix-mcp 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

fenix_mcp/__init__.py

@@ -10,8 +10,11 @@ This package follows a Clean Architecture layout inside the MCP ecosystem:
 - application: tools, registries, presenters and use-case orchestrators
 - domain: pure business models and services
 - infrastructure: API clients, config, logging and shared context
+
+Version 0.1.0 - Initial release with basic MCP functionality.
+Updated with improved error handling and better documentation.
 """
 
 __all__ = ["__version__"]
 
-__version__ = "0.1.0"
+__version__ = "0.2.1"

fenix_mcp/application/tool_base.py

@@ -35,7 +35,9 @@ class Tool(ABC):
             "inputSchema": self.request_model.model_json_schema(),
         }
 
-    async def execute(self, raw_arguments: Dict[str, Any], context: AppContext) -> ToolResponse:
+    async def execute(
+        self, raw_arguments: Dict[str, Any], context: AppContext
+    ) -> ToolResponse:
         """Validate raw arguments and run the tool."""
         payload = self.request_model.model_validate(raw_arguments or {})
         return await self.run(payload, context)
@@ -43,4 +45,3 @@ class Tool(ABC):
     @abstractmethod
     async def run(self, payload: ToolRequest, context: AppContext) -> ToolResponse:
         """Execute business logic and return a MCP-formatted response."""
-

fenix_mcp/application/tool_registry.py

@@ -22,7 +22,9 @@ class ToolRegistry:
     def list_definitions(self) -> List[dict]:
         return [tool.schema() for tool in self._tools.values()]
 
-    async def execute(self, name: str, arguments: dict, context: AppContext) -> ToolResponse:
+    async def execute(
+        self, name: str, arguments: dict, context: AppContext
+    ) -> ToolResponse:
         try:
             tool = self._tools[name]
         except KeyError as exc:

fenix_mcp/application/tools/health.py

@@ -3,9 +3,7 @@
 
 from __future__ import annotations
 
-from pydantic import BaseModel
-
-from fenix_mcp.application.presenters import key_value, text
+from fenix_mcp.application.presenters import key_value
 from fenix_mcp.application.tool_base import Tool, ToolRequest
 from fenix_mcp.infrastructure.context import AppContext
 

fenix_mcp/application/tools/initialize.py

@@ -21,26 +21,35 @@ class InitializeAction(str, Enum):
 
 
 class InitializeRequest(ToolRequest):
-    action: InitializeAction = Field(description="Operação de inicialização a executar.")
+    action: InitializeAction = Field(
+        description="Operação de inicialização a executar."
+    )
     include_user_docs: bool = Field(
         default=True,
-        description="Inclui documentos pessoais durante a inicialização (apenas para ação init).",
+        description=(
+            "Inclui documentos pessoais durante a inicialização "
+            "(apenas para ação init)."
+        ),
     )
     limit: int = Field(
         default=50,
         ge=1,
         le=200,
-        description="Quantidade máxima de documentos principais/pessoais carregados.",
+        description=("Quantidade máxima de documentos principais/pessoais carregados."),
     )
     answers: Optional[List[str]] = Field(
         default=None,
-        description="Lista com 9 respostas textuais para processar o setup personalizado.",
+        description=(
+            "Lista com 9 respostas textuais para processar o setup personalizado."
+        ),
     )
 
 
 class InitializeTool(Tool):
     name = "initialize"
-    description = "Inicializa o ambiente do Fênix Cloud ou processa o setup personalizado."
+    description = (
+        "Inicializa o ambiente do Fênix Cloud ou processa o setup personalizado."
+    )
     request_model = InitializeRequest
 
     def __init__(self, context: AppContext):
@@ -62,7 +71,10 @@ class InitializeTool(Tool):
             )
         except Exception as exc:  # pragma: no cover - defensive
             self._context.logger.error("Initialize failed: %s", exc)
-            return text("❌ Falha ao carregar dados de inicialização. Verifique se o token tem acesso à API.")
+            return text(
+                "❌ Falha ao carregar dados de inicialização. "
+                "Verifique se o token tem acesso à API."
+            )
 
         if (
             not data.core_documents

fenix_mcp/application/tools/intelligence.py

@@ -4,7 +4,7 @@
 from __future__ import annotations
 
 from enum import Enum
-from typing import Any, Dict, Iterable, List, Optional
+from typing import Any, Dict, List, Optional
 
 from pydantic import Field
 
@@ -21,10 +21,16 @@ class IntelligenceAction(str, Enum):
         obj.description = description
         return obj
 
-    SMART_CREATE = ("memory_smart_create", "Cria memórias inteligentes com análise de similaridade.")
+    SMART_CREATE = (
+        "memory_smart_create",
+        "Cria memórias inteligentes com análise de similaridade.",
+    )
     QUERY = ("memory_query", "Lista memórias aplicando filtros e busca textual.")
     SIMILARITY = ("memory_similarity", "Busca memórias similares a um conteúdo base.")
-    CONSOLIDATE = ("memory_consolidate", "Consolida múltiplas memórias em uma principal.")
+    CONSOLIDATE = (
+        "memory_consolidate",
+        "Consolida múltiplas memórias em uma principal.",
+    )
     PRIORITY = ("memory_priority", "Retorna memórias ordenadas por prioridade.")
     ANALYTICS = ("memory_analytics", "Calcula métricas e analytics das memórias.")
     UPDATE = ("memory_update", "Atualiza campos de uma memória existente.")
@@ -47,17 +53,24 @@ class IntelligenceAction(str, Enum):
 
 ACTION_FIELD_DESCRIPTION = (
     "Ação de inteligência a executar. Use um dos valores: "
-    + ", ".join(f"`{member.value}` ({member.description.rstrip('.')})." for member in IntelligenceAction)
+    + ", ".join(
+        f"`{member.value}` ({member.description.rstrip('.')})."
+        for member in IntelligenceAction
+    )
 )
 
 
 class IntelligenceRequest(ToolRequest):
     action: IntelligenceAction = Field(description=ACTION_FIELD_DESCRIPTION)
     title: Optional[str] = Field(default=None, description="Título da memória.")
-    content: Optional[str] = Field(default=None, description="Conteúdo/texto da memória.")
+    content: Optional[str] = Field(
+        default=None, description="Conteúdo/texto da memória."
+    )
     context: Optional[str] = Field(default=None, description="Contexto adicional.")
     source: Optional[str] = Field(default=None, description="Fonte da memória.")
-    importance: str = Field(default="medium", description="Nível de importância da memória.")
+    importance: str = Field(
+        default="medium", description="Nível de importância da memória."
+    )
     tags: Optional[List[str]] = Field(default=None, description="Tags da memória.")
     limit: int = Field(default=20, ge=1, le=100, description="Limite de resultados.")
     offset: int = Field(default=0, ge=0, description="Offset para paginação.")
@@ -65,23 +78,39 @@ class IntelligenceRequest(ToolRequest):
     category: Optional[str] = Field(default=None, description="Categoria para filtro.")
     date_from: Optional[str] = Field(default=None, description="Filtro inicial (ISO).")
     date_to: Optional[str] = Field(default=None, description="Filtro final (ISO).")
-    threshold: float = Field(default=0.8, ge=0, le=1, description="Limite mínimo de similaridade.")
-    max_results: int = Field(default=5, ge=1, le=20, description="Máximo de memórias similares.")
-    memory_ids: Optional[List[str]] = Field(default=None, description="IDs para consolidação.")
+    threshold: float = Field(
+        default=0.8, ge=0, le=1, description="Limite mínimo de similaridade."
+    )
+    max_results: int = Field(
+        default=5, ge=1, le=20, description="Máximo de memórias similares."
+    )
+    memory_ids: Optional[List[str]] = Field(
+        default=None, description="IDs para consolidação."
+    )
     strategy: str = Field(default="merge", description="Estratégia de consolidação.")
-    time_range: str = Field(default="month", description="Janela de tempo para analytics.")
+    time_range: str = Field(
+        default="month", description="Janela de tempo para analytics."
+    )
     group_by: str = Field(default="category", description="Agrupamento para analytics.")
     id: Optional[str] = Field(default=None, description="ID da memória para update.")
-    documentation_item_id: Optional[str] = Field(default=None, description="ID de documentação relacionada.")
+    documentation_item_id: Optional[str] = Field(
+        default=None, description="ID de documentação relacionada."
+    )
     mode_id: Optional[str] = Field(default=None, description="ID do modo relacionado.")
     rule_id: Optional[str] = Field(default=None, description="ID da regra relacionada.")
-    work_item_id: Optional[str] = Field(default=None, description="ID do work item relacionado.")
-    sprint_id: Optional[str] = Field(default=None, description="ID do sprint relacionado.")
+    work_item_id: Optional[str] = Field(
+        default=None, description="ID do work item relacionado."
+    )
+    sprint_id: Optional[str] = Field(
+        default=None, description="ID do sprint relacionado."
+    )
 
 
 class IntelligenceTool(Tool):
     name = "intelligence"
-    description = "Operações de inteligência do Fênix Cloud (memórias e smart operations)."
+    description = (
+        "Operações de inteligência do Fênix Cloud (memórias e smart operations)."
+    )
     request_model = IntelligenceRequest
 
     def __init__(self, context: AppContext):
@@ -231,7 +260,10 @@ class IntelligenceTool(Tool):
         )
 
     async def _handle_help(self):
-        return text("📚 **Ações disponíveis para intelligence**\n\n" + IntelligenceAction.formatted_help())
+        return text(
+            "📚 **Ações disponíveis para intelligence**\n\n"
+            + IntelligenceAction.formatted_help()
+        )
 
 
 def _format_memory(memory: Dict[str, Any]) -> str:

fenix_mcp/application/tools/knowledge.py

@@ -10,7 +10,7 @@ from pydantic import Field
 
 from fenix_mcp.application.presenters import text
 from fenix_mcp.application.tool_base import Tool, ToolRequest
-from fenix_mcp.domain.knowledge import KnowledgeService, _format_date, _strip_none
+from fenix_mcp.domain.knowledge import KnowledgeService, _format_date
 from fenix_mcp.infrastructure.context import AppContext
 
 
@@ -22,10 +22,19 @@ class KnowledgeAction(str, Enum):
         return obj
 
     # Work items
-    WORK_CREATE = ("work_create", "Cria um work item com título, status e vínculos opcionais.")
-    WORK_LIST = ("work_list", "Lista work items com filtros de status, prioridade e contexto.")
+    WORK_CREATE = (
+        "work_create",
+        "Cria um work item com título, status e vínculos opcionais.",
+    )
+    WORK_LIST = (
+        "work_list",
+        "Lista work items com filtros de status, prioridade e contexto.",
+    )
     WORK_GET = ("work_get", "Obtém detalhes completos de um work item pelo ID.")
-    WORK_UPDATE = ("work_update", "Atualiza campos específicos de um work item existente.")
+    WORK_UPDATE = (
+        "work_update",
+        "Atualiza campos específicos de um work item existente.",
+    )
     WORK_DELETE = ("work_delete", "Remove um work item definitivamente.")
     WORK_BACKLOG = ("work_backlog", "Lista itens do backlog de um time.")
     WORK_SEARCH = ("work_search", "Busca work items por texto com filtros adicionais.")
@@ -45,7 +54,10 @@ class KnowledgeAction(str, Enum):
     SPRINT_BY_TEAM = ("sprint_by_team", "Lista sprints associados a um time.")
     SPRINT_ACTIVE = ("sprint_active", "Obtém o sprint ativo de um time.")
     SPRINT_GET = ("sprint_get", "Obtém detalhes de um sprint pelo ID.")
-    SPRINT_WORK_ITEMS = ("sprint_work_items", "Lista work items vinculados a um sprint.")
+    SPRINT_WORK_ITEMS = (
+        "sprint_work_items",
+        "Lista work items vinculados a um sprint.",
+    )
 
     # Modes
     MODE_CREATE = ("mode_create", "Cria um modo com conteúdo e metadados opcionais.")
@@ -54,7 +66,10 @@ class KnowledgeAction(str, Enum):
     MODE_UPDATE = ("mode_update", "Atualiza propriedades de um modo existente.")
     MODE_DELETE = ("mode_delete", "Remove um modo.")
     MODE_RULE_ADD = ("mode_rule_add", "Associa uma regra a um modo.")
-    MODE_RULE_REMOVE = ("mode_rule_remove", "Remove a associação de uma regra com um modo.")
+    MODE_RULE_REMOVE = (
+        "mode_rule_remove",
+        "Remove a associação de uma regra com um modo.",
+    )
     MODE_RULES = ("mode_rules", "Lista regras associadas a um modo.")
 
     # Rules
@@ -99,9 +114,9 @@ class KnowledgeAction(str, Enum):
         return "\n".join(lines)
 
 
-ACTION_FIELD_DESCRIPTION = (
-    "Ação de conhecimento. Escolha um dos valores: "
-    + ", ".join(f"`{member.value}` ({member.description.rstrip('.')})." for member in KnowledgeAction)
+ACTION_FIELD_DESCRIPTION = "Ação de conhecimento. Escolha um dos valores: " + ", ".join(
+    f"`{member.value}` ({member.description.rstrip('.')})."
+    for member in KnowledgeAction
 )
 
 
@@ -117,22 +132,38 @@ class KnowledgeRequest(ToolRequest):
     action: KnowledgeAction = Field(description=ACTION_FIELD_DESCRIPTION)
     id: Optional[str] = Field(default=None, description="ID principal do recurso.")
     limit: int = Field(default=20, ge=1, le=100, description="Limite de resultados.")
-    offset: int = Field(default=0, ge=0, description="Offset de paginação (quando suportado).")
-    team_id: Optional[str] = Field(default=None, description="ID do time para filtros (boards/sprints/docs).")
+    offset: int = Field(
+        default=0, ge=0, description="Offset de paginação (quando suportado)."
+    )
+    team_id: Optional[str] = Field(
+        default=None, description="ID do time para filtros (boards/sprints/docs)."
+    )
     board_id: Optional[str] = Field(default=None, description="ID do board associado.")
-    sprint_id: Optional[str] = Field(default=None, description="ID do sprint associado.")
+    sprint_id: Optional[str] = Field(
+        default=None, description="ID do sprint associado."
+    )
     epic_id: Optional[str] = Field(default=None, description="ID do épico associado.")
     query: Optional[str] = Field(default=None, description="Filtro/busca.")
-    return_content: Optional[bool] = Field(default=None, description="Retorna conteúdo completo.")
-    return_description: Optional[bool] = Field(default=None, description="Retorna descrição completa.")
-    return_metadata: Optional[bool] = Field(default=None, description="Retorna metadados completos.")
+    return_content: Optional[bool] = Field(
+        default=None, description="Retorna conteúdo completo."
+    )
+    return_description: Optional[bool] = Field(
+        default=None, description="Retorna descrição completa."
+    )
+    return_metadata: Optional[bool] = Field(
+        default=None, description="Retorna metadados completos."
+    )
 
     # Work item fields
     work_title: Optional[str] = Field(default=None, description="Título do work item.")
-    work_description: Optional[str] = Field(default=None, description="Descrição do work item.")
+    work_description: Optional[str] = Field(
+        default=None, description="Descrição do work item."
+    )
     work_type: Optional[str] = Field(default="task", description="Tipo do work item.")
     work_status: Optional[str] = Field(default=None, description="Status do work item.")
-    work_priority: Optional[str] = Field(default=None, description="Prioridade do work item.")
+    work_priority: Optional[str] = Field(
+        default=None, description="Prioridade do work item."
+    )
     story_points: Optional[int] = Field(default=None, description="Story points.")
     assignee_id: Optional[str] = Field(default=None, description="ID do responsável.")
     parent_id: Optional[str] = Field(default=None, description="ID do item pai.")
@@ -140,34 +171,56 @@ class KnowledgeRequest(ToolRequest):
     # Mode fields
     mode_id: Optional[str] = Field(default=None, description="ID do modo relacionado.")
     mode_name: Optional[str] = Field(default=None, description="Nome do modo.")
-    mode_description: Optional[str] = Field(default=None, description="Descrição do modo.")
+    mode_description: Optional[str] = Field(
+        default=None, description="Descrição do modo."
+    )
     mode_content: Optional[str] = Field(default=None, description="Conteúdo do modo.")
-    mode_is_default: Optional[bool] = Field(default=None, description="Indica se o modo é padrão.")
+    mode_is_default: Optional[bool] = Field(
+        default=None, description="Indica se o modo é padrão."
+    )
 
     # Rule fields
     rule_id: Optional[str] = Field(default=None, description="ID da regra relacionada.")
     rule_name: Optional[str] = Field(default=None, description="Nome da regra.")
-    rule_description: Optional[str] = Field(default=None, description="Descrição da regra.")
+    rule_description: Optional[str] = Field(
+        default=None, description="Descrição da regra."
+    )
     rule_content: Optional[str] = Field(default=None, description="Conteúdo da regra.")
     rule_is_default: Optional[bool] = Field(default=None, description="Regra padrão.")
 
     # Documentation fields
-    doc_title: Optional[str] = Field(default=None, description="Título da documentação.")
+    doc_title: Optional[str] = Field(
+        default=None, description="Título da documentação."
+    )
     doc_description: Optional[str] = Field(default=None, description="Descrição.")
-    doc_content: Optional[str] = Field(default=None, description="Conteúdo da documentação.")
-    doc_status: Optional[str] = Field(default=None, description="Status da documentação.")
+    doc_content: Optional[str] = Field(
+        default=None, description="Conteúdo da documentação."
+    )
+    doc_status: Optional[str] = Field(
+        default=None, description="Status da documentação."
+    )
     doc_type: Optional[str] = Field(default=None, description="Tipo da documentação.")
-    doc_language: Optional[str] = Field(default=None, description="Idioma da documentação.")
+    doc_language: Optional[str] = Field(
+        default=None, description="Idioma da documentação."
+    )
     doc_parent_id: Optional[str] = Field(default=None, description="Documento pai.")
-    doc_team_id: Optional[str] = Field(default=None, description="Time responsável pela documentação.")
+    doc_team_id: Optional[str] = Field(
+        default=None, description="Time responsável pela documentação."
+    )
     doc_owner_id: Optional[str] = Field(default=None, description="ID do dono.")
     doc_reviewer_id: Optional[str] = Field(default=None, description="ID do revisor.")
     doc_version: Optional[str] = Field(default=None, description="Versão.")
     doc_category: Optional[str] = Field(default=None, description="Categoria.")
     doc_tags: Optional[List[str]] = Field(default=None, description="Tags.")
-    doc_position: Optional[int] = Field(default=None, description="Posição desejada ao mover documentos.")
-    doc_emoji: Optional[str] = Field(default=None, description="Emoji exibido junto ao documento.")
-    doc_emote: Optional[str] = Field(default=None, description="Alias para emoji, mantido por compatibilidade.")
+    doc_position: Optional[int] = Field(
+        default=None, description="Posição desejada ao mover documentos."
+    )
+    doc_emoji: Optional[str] = Field(
+        default=None, description="Emoji exibido junto ao documento."
+    )
+    doc_emote: Optional[str] = Field(
+        default=None, description="Alias para emoji, mantido por compatibilidade."
+    )
 
 
 class KnowledgeTool(Tool):
@@ -323,7 +376,11 @@ class KnowledgeTool(Tool):
 
         return text(
             "❌ Ação de work item não suportada.\n\nEscolha um dos valores:\n"
-            + "\n".join(f"- `{value}`" for value in KnowledgeAction.choices() if value.startswith("work_"))
+            + "\n".join(
+                f"- `{value}`"
+                for value in KnowledgeAction.choices()
+                if value.startswith("work_")
+            )
         )
 
     # ------------------------------------------------------------------
@@ -332,7 +389,9 @@ class KnowledgeTool(Tool):
     async def _run_board(self, payload: KnowledgeRequest):
         action = payload.action
         if action is KnowledgeAction.BOARD_LIST:
-            boards = await self._service.board_list(limit=payload.limit, offset=payload.offset)
+            boards = await self._service.board_list(
+                limit=payload.limit, offset=payload.offset
+            )
             if not boards:
                 return text("🗂️ Nenhum board encontrado.")
             body = "\n\n".join(_format_board(board) for board in boards)
@@ -366,12 +425,19 @@ class KnowledgeTool(Tool):
             columns = await self._service.board_columns(payload.board_id)
             if not columns:
                 return text("📊 Board sem colunas cadastradas.")
-            body = "\n".join(f"- {col.get('name', 'Sem nome')} (ID: {col.get('id')})" for col in columns)
+            body = "\n".join(
+                f"- {col.get('name', 'Sem nome')} (ID: {col.get('id')})"
+                for col in columns
+            )
             return text(f"📊 **Colunas do board:**\n{body}")
 
         return text(
             "❌ Ação de board não suportada.\n\nEscolha um dos valores:\n"
-            + "\n".join(f"- `{value}`" for value in KnowledgeAction.choices() if value.startswith("board_"))
+            + "\n".join(
+                f"- `{value}`"
+                for value in KnowledgeAction.choices()
+                if value.startswith("board_")
+            )
         )
 
     # ------------------------------------------------------------------
@@ -380,7 +446,9 @@ class KnowledgeTool(Tool):
     async def _run_sprint(self, payload: KnowledgeRequest):
         action = payload.action
         if action is KnowledgeAction.SPRINT_LIST:
-            sprints = await self._service.sprint_list(limit=payload.limit, offset=payload.offset)
+            sprints = await self._service.sprint_list(
+                limit=payload.limit, offset=payload.offset
+            )
             if not sprints:
                 return text("🏃 Nenhum sprint encontrado.")
             body = "\n\n".join(_format_sprint(sprint) for sprint in sprints)
@@ -420,7 +488,11 @@ class KnowledgeTool(Tool):
 
         return text(
             "❌ Ação de sprint não suportada.\n\nEscolha um dos valores:\n"
-            + "\n".join(f"- `{value}`" for value in KnowledgeAction.choices() if value.startswith("sprint_"))
+            + "\n".join(
+                f"- `{value}`"
+                for value in KnowledgeAction.choices()
+                if value.startswith("sprint_")
+            )
         )
 
     # ------------------------------------------------------------------
@@ -514,13 +586,18 @@ class KnowledgeTool(Tool):
             if not rules:
                 return text("🔗 Nenhuma associação encontrada.")
             body = "\n".join(
-                f"- {item.get('name', 'Sem nome')} (ID: {item.get('id')})" for item in rules
+                f"- {item.get('name', 'Sem nome')} (ID: {item.get('id')})"
+                for item in rules
             )
             return text(f"🔗 **Associações para {context_label}:**\n{body}")
 
         return text(
             "❌ Ação de modo não suportada.\n\nEscolha um dos valores:\n"
-            + "\n".join(f"- `{value}`" for value in KnowledgeAction.choices() if value.startswith("mode_"))
+            + "\n".join(
+                f"- `{value}`"
+                for value in KnowledgeAction.choices()
+                if value.startswith("mode_")
+            )
         )
 
     # ------------------------------------------------------------------
@@ -585,7 +662,11 @@ class KnowledgeTool(Tool):
 
         return text(
             "❌ Ação de regra não suportada.\n\nEscolha um dos valores:\n"
-            + "\n".join(f"- `{value}`" for value in KnowledgeAction.choices() if value.startswith("rule_"))
+            + "\n".join(
+                f"- `{value}`"
+                for value in KnowledgeAction.choices()
+                if value.startswith("rule_")
+            )
         )
 
     # ------------------------------------------------------------------
@@ -685,17 +766,24 @@ class KnowledgeTool(Tool):
                 limit=payload.limit,
             )
             if not docs:
-                return text("🔍 Nenhum documento encontrado para os filtros informados.")
+                return text(
+                    "🔍 Nenhum documento encontrado para os filtros informados."
+                )
             body = "\n\n".join(_format_doc(doc) for doc in docs)
             return text(f"🔍 **Resultados ({len(docs)}):**\n\n{body}")
 
         if action is KnowledgeAction.DOC_ROOTS:
             if not (payload.doc_team_id or payload.team_id):
                 return text("❌ Informe team_id para listar raízes.")
-            docs = await self._service.doc_roots(team_id=payload.doc_team_id or payload.team_id)
+            docs = await self._service.doc_roots(
+                team_id=payload.doc_team_id or payload.team_id
+            )
             if not docs:
                 return text("📚 Nenhuma raiz encontrada.")
-            body = "\n".join(f"- {doc.get('title', 'Sem título')} (ID: {doc.get('id')})" for doc in docs)
+            body = "\n".join(
+                f"- {doc.get('title', 'Sem título')} (ID: {doc.get('id')})"
+                for doc in docs
+            )
             return text(f"📚 **Raízes de documentação:**\n{body}")
 
         if action is KnowledgeAction.DOC_RECENT:
@@ -713,7 +801,9 @@ class KnowledgeTool(Tool):
         if action is KnowledgeAction.DOC_ANALYTICS:
             if not (payload.doc_team_id or payload.team_id):
                 return text("❌ Informe team_id para obter analytics.")
-            analytics = await self._service.doc_analytics(team_id=payload.doc_team_id or payload.team_id)
+            analytics = await self._service.doc_analytics(
+                team_id=payload.doc_team_id or payload.team_id
+            )
             lines = ["📊 **Analytics de Documentação**"]
             for key, value in analytics.items():
                 lines.append(f"- {key}: {value}")
@@ -725,7 +815,10 @@ class KnowledgeTool(Tool):
             docs = await self._service.doc_children(payload.id)
             if not docs:
                 return text("📄 Nenhum filho cadastrado para o documento informado.")
-            body = "\n".join(f"- {doc.get('title', 'Sem título')} (ID: {doc.get('id')})" for doc in docs)
+            body = "\n".join(
+                f"- {doc.get('title', 'Sem título')} (ID: {doc.get('id')})"
+                for doc in docs
+            )
             return text(f"📄 **Filhos:**\n{body}")
 
         if action is KnowledgeAction.DOC_TREE:
@@ -742,7 +835,9 @@ class KnowledgeTool(Tool):
             if not payload.id:
                 return text("❌ Informe o ID da documentação.")
             if payload.doc_parent_id is None and payload.doc_position is None:
-                return text("❌ Informe doc_parent_id, doc_position ou ambos para mover.")
+                return text(
+                    "❌ Informe doc_parent_id, doc_position ou ambos para mover."
+                )
             move_payload = {
                 "new_parent_id": payload.doc_parent_id,
                 "new_position": payload.doc_position,
@@ -760,7 +855,9 @@ class KnowledgeTool(Tool):
             if not payload.id:
                 return text("❌ Informe o ID da documentação.")
             if not payload.doc_version:
-                return text("❌ Informe doc_version com o número/identificador da versão.")
+                return text(
+                    "❌ Informe doc_version com o número/identificador da versão."
+                )
             version_payload = {
                 "title": payload.doc_title or f"Version {payload.doc_version}",
                 "version": payload.doc_version,
@@ -785,11 +882,18 @@ class KnowledgeTool(Tool):
 
         return text(
             "❌ Ação de documentação não suportada.\n\nEscolha um dos valores:\n"
-            + "\n".join(f"- `{value}`" for value in KnowledgeAction.choices() if value.startswith("doc_"))
+            + "\n".join(
+                f"- `{value}`"
+                for value in KnowledgeAction.choices()
+                if value.startswith("doc_")
+            )
         )
 
     async def _handle_help(self):
-        return text("📚 **Ações disponíveis para knowledge**\n\n" + KnowledgeAction.formatted_help())
+        return text(
+            "📚 **Ações disponíveis para knowledge**\n\n"
+            + KnowledgeAction.formatted_help()
+        )
 
 
 def _format_work(item: Dict[str, Any], *, header: Optional[str] = None) -> str:
@@ -810,7 +914,9 @@ def _format_work(item: Dict[str, Any], *, header: Optional[str] = None) -> str:
         ]
     )
     if item.get("due_date") or item.get("dueDate"):
-        lines.append(f"Vencimento: {_format_date(item.get('due_date') or item.get('dueDate'))}")
+        lines.append(
+            f"Vencimento: {_format_date(item.get('due_date') or item.get('dueDate'))}"
+        )
     return "\n".join(lines)
 
 
@@ -844,9 +950,13 @@ def _format_sprint(sprint: Dict[str, Any], header: Optional[str] = None) -> str:
         ]
     )
     if sprint.get("start_date") or sprint.get("startDate"):
-        lines.append(f"Início: {_format_date(sprint.get('start_date') or sprint.get('startDate'))}")
+        lines.append(
+            f"Início: {_format_date(sprint.get('start_date') or sprint.get('startDate'))}"
+        )
     if sprint.get("end_date") or sprint.get("endDate"):
-        lines.append(f"Fim: {_format_date(sprint.get('end_date') or sprint.get('endDate'))}")
+        lines.append(
+            f"Fim: {_format_date(sprint.get('end_date') or sprint.get('endDate'))}"
+        )
     return "\n".join(lines)
 
 
@@ -898,7 +1008,9 @@ def _format_doc(doc: Dict[str, Any], header: Optional[str] = None) -> str:
         ]
     )
     if doc.get("updated_at") or doc.get("updatedAt"):
-        lines.append(f"Atualizado em: {_format_date(doc.get('updated_at') or doc.get('updatedAt'))}")
+        lines.append(
+            f"Atualizado em: {_format_date(doc.get('updated_at') or doc.get('updatedAt'))}"
+        )
     return "\n".join(lines)