fenix-mcp 0.5.12__tar.gz → 0.7.0__tar.gz

{fenix_mcp-0.5.12 → fenix_mcp-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fenix-mcp
-Version: 0.5.12
+Version: 0.7.0
 Summary: Fênix Cloud MCP server implemented in Python
 Author: Fenix Inc
 Requires-Python: >=3.10

{fenix_mcp-0.5.12 → fenix_mcp-0.7.0}/fenix_mcp/__init__.py

@@ -8,4 +8,4 @@ Fênix Cloud MCP Server (Python edition).
 __all__ = ["__version__"]
 
 
-__version__ = "0.5.12"
+__version__ = "0.7.0"

fenix_mcp-0.7.0/fenix_mcp/application/tool_base.py

@@ -0,0 +1,159 @@
+# SPDX-License-Identifier: MIT
+"""Base abstractions for MCP tools."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Annotated, Any, Dict, List, Optional, Type, TypeVar
+
+from pydantic import BaseModel, ConfigDict, Field, StringConstraints
+
+from fenix_mcp.infrastructure.context import AppContext
+
+T = TypeVar("T")
+
+
+def sanitize_null(value: Optional[T]) -> Optional[T]:
+    """Convert string 'null' to None. Handles AI agents passing 'null' as string."""
+    if value == "null" or value == "None" or value == "":
+        return None
+    return value
+
+
+def sanitize_null_list(value: Optional[List[T]]) -> Optional[List[T]]:
+    """Sanitize list values, converting 'null' string to None."""
+    if value == "null" or value == "None" or value == "":  # type: ignore
+        return None
+    if isinstance(value, list):
+        return [v for v in value if v != "null" and v != "None" and v != ""]
+    return value
+
+
+# =============================================================================
+# Type aliases for common field types - generates proper JSON schema
+# =============================================================================
+
+# UUID string - format: uuid, with regex pattern validation
+UUIDStr = Annotated[
+    str,
+    Field(
+        pattern=r"^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$",
+        json_schema_extra={"format": "uuid"},
+    ),
+]
+
+# ISO 8601 date string (YYYY-MM-DD)
+DateStr = Annotated[
+    str,
+    Field(
+        pattern=r"^\d{4}-\d{2}-\d{2}$",
+        json_schema_extra={"format": "date"},
+        examples=["2025-01-15"],
+    ),
+]
+
+# ISO 8601 datetime string (YYYY-MM-DDTHH:MM:SSZ or YYYY-MM-DD)
+DateTimeStr = Annotated[
+    str,
+    Field(
+        pattern=r"^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})?)?$",
+        json_schema_extra={"format": "date-time"},
+        examples=["2025-01-15T10:30:00Z", "2025-01-15"],
+    ),
+]
+
+# Markdown content - indicates rich text
+MarkdownStr = Annotated[
+    str,
+    Field(
+        json_schema_extra={"format": "markdown", "contentMediaType": "text/markdown"},
+    ),
+]
+
+# Short title/name strings (1-300 chars)
+TitleStr = Annotated[
+    str,
+    StringConstraints(min_length=1, max_length=300),
+]
+
+# Description strings (up to 1000 chars)
+DescriptionStr = Annotated[
+    str,
+    StringConstraints(max_length=1000),
+]
+
+# Tag string (lowercase, alphanumeric with hyphens/underscores)
+TagStr = Annotated[
+    str,
+    Field(
+        pattern=r"^[a-zA-Z0-9_-]+$",
+        examples=["bug", "feature", "high-priority"],
+    ),
+]
+
+# Category strings
+CategoryStr = Annotated[
+    str,
+    StringConstraints(max_length=100),
+]
+
+# Language code (ISO 639-1)
+LanguageStr = Annotated[
+    str,
+    Field(
+        pattern=r"^[a-z]{2}(-[A-Z]{2})?$",
+        examples=["pt", "en", "pt-BR", "en-US"],
+    ),
+]
+
+# Version string (semver-like)
+VersionStr = Annotated[
+    str,
+    Field(
+        pattern=r"^[0-9]+(\.[0-9]+)*(-[a-zA-Z0-9]+)?$",
+        max_length=20,
+        examples=["1.0", "2.1.3", "1.0.0-beta"],
+    ),
+]
+
+# Emoji string (single emoji or short code)
+EmojiStr = Annotated[
+    str,
+    StringConstraints(max_length=10),
+]
+
+
+class ToolRequest(BaseModel):
+    """Base request payload."""
+
+    model_config = ConfigDict(extra="forbid")
+
+
+ToolResponse = Dict[str, Any]
+
+
+class Tool(ABC):
+    """Interface implemented by all tools."""
+
+    name: str
+    description: str
+    request_model: Type[ToolRequest] = ToolRequest
+
+    def schema(self) -> Dict[str, Any]:
+        """Return JSON schema describing the tool arguments."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "inputSchema": self.request_model.model_json_schema(),
+        }
+
+    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)
+
+    @abstractmethod
+    async def run(self, payload: ToolRequest, context: AppContext) -> ToolResponse:
+        """Execute business logic and return a MCP-formatted response."""

{fenix_mcp-0.5.12 → fenix_mcp-0.7.0}/fenix_mcp/application/tools/initialize.py

@@ -3,8 +3,8 @@
 
 from __future__ import annotations
 
-from enum import Enum
 import json
+from enum import Enum
 from typing import List, Optional
 
 from pydantic import Field
@@ -93,7 +93,28 @@ class InitializeTool(Tool):
         if data.recent_memories:
             payload_dict["recent_memories"] = data.recent_memories
 
-        message_lines = [
+        # Extract key IDs for easy reference
+        profile = data.profile or {}
+        user_info = profile.get("user") or {}
+        tenant_info = profile.get("tenant") or {}
+        team_info = profile.get("team") or {}
+
+        context_lines = ["📋 **Contexto do Usuário**"]
+        if user_info.get("id"):
+            context_lines.append(f"- **user_id**: `{user_info['id']}`")
+        if user_info.get("name"):
+            context_lines.append(f"- **user_name**: {user_info['name']}")
+        if tenant_info.get("id"):
+            context_lines.append(f"- **tenant_id**: `{tenant_info['id']}`")
+        if tenant_info.get("name"):
+            context_lines.append(f"- **tenant_name**: {tenant_info['name']}")
+        if team_info.get("id"):
+            context_lines.append(f"- **team_id**: `{team_info['id']}`")
+        if team_info.get("name"):
+            context_lines.append(f"- **team_name**: {team_info['name']}")
+
+        message_lines = context_lines + [
+            "",
             "📦 **Dados de inicialização completos**",
             "```json",
             json.dumps(payload_dict, ensure_ascii=False, indent=2),

{fenix_mcp-0.5.12 → fenix_mcp-0.7.0}/fenix_mcp/application/tools/intelligence.py

@@ -9,7 +9,16 @@ from typing import Any, Dict, List, Optional
 from pydantic import Field, field_validator
 
 from fenix_mcp.application.presenters import text
-from fenix_mcp.application.tool_base import Tool, ToolRequest
+from fenix_mcp.application.tool_base import (
+    CategoryStr,
+    DateTimeStr,
+    MarkdownStr,
+    TagStr,
+    TitleStr,
+    Tool,
+    ToolRequest,
+    UUIDStr,
+)
 from fenix_mcp.domain.intelligence import IntelligenceService, build_metadata
 from fenix_mcp.infrastructure.context import AppContext
 
@@ -31,9 +40,8 @@ class IntelligenceAction(str, Enum):
         "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.")
+    DELETE = ("memory_delete", "Remove uma memória pelo ID.")
     HELP = ("memory_help", "Mostra as ações suportadas e seus usos.")
 
     @classmethod
@@ -62,18 +70,19 @@ ACTION_FIELD_DESCRIPTION = (
 
 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."
+    title: Optional[TitleStr] = Field(default=None, description="Título da memória.")
+    content: Optional[MarkdownStr] = Field(
+        default=None, description="Conteúdo/texto da memória (Markdown)."
     )
-    metadata: Optional[str] = Field(
+    metadata: Optional[MarkdownStr] = Field(
         default=None,
         description="Metadata estruturada da memória (formato pipe, toml compacto, etc.).",
     )
     context: Optional[str] = Field(default=None, description="Contexto adicional.")
     source: Optional[str] = Field(default=None, description="Fonte da memória.")
     importance: Optional[str] = Field(
-        default=None, description="Nível de importância da memória."
+        default=None,
+        description="Nível de importância da memória (low, medium, high, critical).",
     )
     include_content: bool = Field(
         default=False,
@@ -83,7 +92,7 @@ class IntelligenceRequest(ToolRequest):
         default=False,
         description="Retornar metadata completa das memórias? Defina true para incluir o campo bruto.",
     )
-    tags: Optional[List[str]] = Field(
+    tags: Optional[List[TagStr]] = Field(
         default=None,
         description="Tags da memória como array JSON de strings.",
         json_schema_extra={"example": ["tag1", "tag2", "tag3"]},
@@ -120,34 +129,44 @@ class IntelligenceRequest(ToolRequest):
     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.")
     query: Optional[str] = Field(default=None, description="Termo de busca.")
-    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).")
+    category: Optional[CategoryStr] = Field(
+        default=None, description="Categoria para filtro."
+    )
+    date_from: Optional[DateTimeStr] = Field(
+        default=None, description="Filtro inicial (ISO 8601)."
+    )
+    date_to: Optional[DateTimeStr] = Field(
+        default=None, description="Filtro final (ISO 8601)."
+    )
     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."
+    memory_ids: Optional[List[UUIDStr]] = Field(
+        default=None, description="IDs das memórias para consolidação (UUIDs)."
     )
     strategy: str = Field(default="merge", description="Estratégia de consolidação.")
     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."
+    id: Optional[UUIDStr] = Field(default=None, description="ID da memória (UUID).")
+    documentation_item_id: Optional[UUIDStr] = Field(
+        default=None, description="ID de documentação relacionada (UUID)."
     )
-    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."
+    mode_id: Optional[UUIDStr] = Field(
+        default=None, description="ID do modo relacionado (UUID)."
     )
-    sprint_id: Optional[str] = Field(
-        default=None, description="ID do sprint relacionado."
+    rule_id: Optional[UUIDStr] = Field(
+        default=None, description="ID da regra relacionada (UUID)."
+    )
+    work_item_id: Optional[UUIDStr] = Field(
+        default=None, description="ID do work item relacionado (UUID)."
+    )
+    sprint_id: Optional[UUIDStr] = Field(
+        default=None, description="ID do sprint relacionado (UUID)."
     )
 
 
@@ -174,12 +193,10 @@ class IntelligenceTool(Tool):
             return await self._handle_similarity(payload)
         if action is IntelligenceAction.CONSOLIDATE:
             return await self._handle_consolidate(payload)
-        if action is IntelligenceAction.PRIORITY:
-            return await self._handle_priority(payload)
-        if action is IntelligenceAction.ANALYTICS:
-            return await self._handle_analytics(payload)
         if action is IntelligenceAction.UPDATE:
             return await self._handle_update(payload)
+        if action is IntelligenceAction.DELETE:
+            return await self._handle_delete(payload)
         return text(
             "❌ Ação inválida para intelligence.\n\nEscolha um dos valores:\n"
             + "\n".join(f"- `{value}`" for value in IntelligenceAction.choices())
@@ -276,31 +293,6 @@ class IntelligenceTool(Tool):
         ]
         return text("\n".join(lines))
 
-    async def _handle_priority(self, payload: IntelligenceRequest):
-        memories = await self._service.priority_memories(limit=payload.limit)
-        if not memories:
-            return text("✅ Nenhuma memória prioritária no momento.")
-        body = "\n\n".join(_format_memory(mem) for mem in memories)
-        return text(f"🧠 **Memórias prioritárias ({len(memories)}):**\n\n{body}")
-
-    async def _handle_analytics(self, payload: IntelligenceRequest):
-        analytics = await self._service.analytics(
-            time_range=payload.time_range,
-            group_by=payload.group_by,
-        )
-        lines = [
-            "📊 **Memória - Analytics**",
-            f"Total: {analytics.get('total_memories', 0)}",
-            f"Novas: {analytics.get('new_memories', 0)}",
-            f"Mais acessada: {analytics.get('most_accessed', 'N/A')}",
-            f"Acesso médio: {analytics.get('avg_access_count', 'N/A')}",
-        ]
-        by_group = analytics.get("by_group")
-        if isinstance(by_group, dict):
-            lines.append("\nPor grupo:")
-            lines.extend(f"- {key}: {value}" for key, value in by_group.items())
-        return text("\n".join(lines))
-
     async def _handle_update(self, payload: IntelligenceRequest):
         if not payload.id:
             return text("❌ Informe o ID da memória para atualização.")
@@ -342,6 +334,12 @@ class IntelligenceTool(Tool):
             )
         )
 
+    async def _handle_delete(self, payload: IntelligenceRequest):
+        if not payload.id:
+            return text("❌ Informe o ID da memória para remover.")
+        await self._service.delete_memory(payload.id)
+        return text(f"🗑️ Memória {payload.id} removida com sucesso.")
+
     async def _handle_help(self):
         return text(
             "📚 **Ações disponíveis para intelligence**\n\n"

{fenix_mcp-0.5.12 → fenix_mcp-0.7.0}/fenix_mcp/application/tools/knowledge.py

@@ -9,7 +9,22 @@ from typing import Any, Dict, List, Optional
 from pydantic import Field
 
 from fenix_mcp.application.presenters import text
-from fenix_mcp.application.tool_base import Tool, ToolRequest
+from fenix_mcp.application.tool_base import (
+    CategoryStr,
+    DateTimeStr,
+    DescriptionStr,
+    EmojiStr,
+    LanguageStr,
+    MarkdownStr,
+    TagStr,
+    TitleStr,
+    Tool,
+    ToolRequest,
+    UUIDStr,
+    VersionStr,
+    sanitize_null,
+    sanitize_null_list,
+)
 from fenix_mcp.domain.knowledge import KnowledgeService, _format_date
 from fenix_mcp.infrastructure.context import AppContext
 
@@ -41,6 +56,16 @@ class KnowledgeAction(str, Enum):
     WORK_ANALYTICS = ("work_analytics", "Retorna métricas consolidadas de work items.")
     WORK_BY_BOARD = ("work_by_board", "Lista work items associados a um board.")
     WORK_BY_SPRINT = ("work_by_sprint", "Lista work items associados a um sprint.")
+    WORK_BY_EPIC = ("work_by_epic", "Lista work items associados a um épico.")
+    WORK_CHILDREN = ("work_children", "Lista work items filhos de um item pai.")
+    WORK_STATUS_UPDATE = (
+        "work_status_update",
+        "Atualiza apenas o status de um work item.",
+    )
+    WORK_ASSIGN_SPRINT = (
+        "work_assign_sprint",
+        "Atribui work items a um sprint.",
+    )
 
     # Boards
     BOARD_LIST = ("board_list", "Lista boards disponíveis com filtros opcionais.")
@@ -130,19 +155,25 @@ _ALLOWED_DOC_TYPES = {
 
 class KnowledgeRequest(ToolRequest):
     action: KnowledgeAction = Field(description=ACTION_FIELD_DESCRIPTION)
-    id: Optional[str] = Field(default=None, description="ID principal do recurso.")
+    id: Optional[UUIDStr] = Field(
+        default=None, description="ID principal do recurso (UUID)."
+    )
     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)."
+    team_id: Optional[UUIDStr] = Field(
+        default=None, description="ID do time para filtros (UUID)."
     )
-    board_id: Optional[str] = Field(default=None, description="ID do board associado.")
-    sprint_id: Optional[str] = Field(
-        default=None, description="ID do sprint associado."
+    board_id: Optional[UUIDStr] = Field(
+        default=None, description="ID do board associado (UUID)."
+    )
+    sprint_id: Optional[UUIDStr] = Field(
+        default=None, description="ID do sprint associado (UUID)."
+    )
+    epic_id: Optional[UUIDStr] = Field(
+        default=None, description="ID do épico associado (UUID)."
     )
-    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."
@@ -155,71 +186,130 @@ class KnowledgeRequest(ToolRequest):
     )
 
     # 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_title: Optional[TitleStr] = Field(
+        default=None, description="Título do work item."
+    )
+    work_description: Optional[MarkdownStr] = Field(
+        default=None, description="Descrição do work item (Markdown)."
+    )
+    work_type: Optional[str] = Field(
+        default="task",
+        description="Tipo do work item (epic, feature, story, task, subtask, bug).",
+    )
+    work_status: Optional[str] = Field(
+        default=None,
+        description="Status do work item (backlog, todo, in_progress, review, testing, done, cancelled).",
     )
-    work_type: Optional[str] = Field(default="task", description="Tipo do work item.")
     work_priority: Optional[str] = Field(
-        default=None, description="Prioridade do work item."
+        default=None,
+        description="Prioridade do work item (critical, high, medium, low).",
+    )
+    story_points: Optional[int] = Field(
+        default=None, ge=0, le=100, description="Story points (0-100)."
+    )
+    assignee_id: Optional[UUIDStr] = Field(
+        default=None, description="ID do responsável (UUID)."
+    )
+    parent_id: Optional[UUIDStr] = Field(
+        default=None, description="ID do item pai (UUID)."
+    )
+    work_due_date: Optional[DateTimeStr] = Field(
+        default=None, description="Data de vencimento do work item (ISO 8601)."
+    )
+    work_tags: Optional[List[TagStr]] = Field(
+        default=None, description="Tags do work item."
+    )
+    work_item_ids: Optional[List[UUIDStr]] = Field(
+        default=None,
+        description="Lista de IDs de work items para operações em lote (UUIDs).",
     )
-    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.")
 
     # 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(
+    mode_id: Optional[UUIDStr] = Field(
+        default=None, description="ID do modo relacionado (UUID)."
+    )
+    mode_name: Optional[TitleStr] = Field(default=None, description="Nome do modo.")
+    mode_description: Optional[DescriptionStr] = Field(
         default=None, description="Descrição do modo."
     )
-    mode_content: Optional[str] = Field(default=None, description="Conteúdo do modo.")
+    mode_content: Optional[MarkdownStr] = Field(
+        default=None, description="Conteúdo do modo (Markdown)."
+    )
     mode_is_default: Optional[bool] = Field(
         default=None, description="Indica se o modo é padrão."
     )
+    mode_metadata: Optional[MarkdownStr] = Field(
+        default=None, description="Metadata do modo para processamento de IA."
+    )
 
     # 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(
+    rule_id: Optional[UUIDStr] = Field(
+        default=None, description="ID da regra relacionada (UUID)."
+    )
+    rule_name: Optional[TitleStr] = Field(default=None, description="Nome da regra.")
+    rule_description: Optional[DescriptionStr] = Field(
         default=None, description="Descrição da regra."
     )
-    rule_content: Optional[str] = Field(default=None, description="Conteúdo da regra.")
+    rule_content: Optional[MarkdownStr] = Field(
+        default=None, description="Conteúdo da regra (Markdown)."
+    )
     rule_is_default: Optional[bool] = Field(default=None, description="Regra padrão.")
+    rule_metadata: Optional[MarkdownStr] = Field(
+        default=None, description="Metadata da regra para processamento de IA."
+    )
 
     # Documentation fields
-    doc_title: Optional[str] = Field(
+    doc_title: Optional[TitleStr] = 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_description: Optional[DescriptionStr] = Field(
+        default=None, description="Descrição da documentação."
+    )
+    doc_content: Optional[MarkdownStr] = Field(
+        default=None, description="Conteúdo da documentação (Markdown)."
     )
     doc_status: Optional[str] = Field(
-        default=None, description="Status da documentação."
+        default=None,
+        description="Status da documentação (draft, review, published, archived).",
+    )
+    doc_type: Optional[str] = Field(
+        default=None, description="Tipo da documentação (folder, page, api_doc, guide)."
+    )
+    doc_language: Optional[LanguageStr] = Field(
+        default=None, description="Idioma da documentação (ex: pt, en, pt-BR)."
+    )
+    doc_parent_id: Optional[UUIDStr] = Field(
+        default=None, description="ID do documento pai (UUID)."
     )
-    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_team_id: Optional[UUIDStr] = Field(
+        default=None, description="ID do time responsável pela documentação (UUID)."
     )
-    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_owner_id: Optional[UUIDStr] = Field(
+        default=None, description="ID do dono (UUID)."
     )
-    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_reviewer_id: Optional[UUIDStr] = Field(
+        default=None, description="ID do revisor (UUID)."
+    )
+    doc_version: Optional[VersionStr] = Field(
+        default=None, description="Versão do documento (ex: 1.0, 2.1.3)."
+    )
+    doc_category: Optional[CategoryStr] = Field(default=None, description="Categoria.")
+    doc_tags: Optional[List[TagStr]] = Field(default=None, description="Tags.")
     doc_position: Optional[int] = Field(
-        default=None, description="Posição desejada ao mover documentos."
+        default=None, ge=0, description="Posição desejada ao mover documentos."
     )
-    doc_emoji: Optional[str] = Field(
+    doc_emoji: Optional[EmojiStr] = Field(
         default=None, description="Emoji exibido junto ao documento."
     )
-    doc_emote: Optional[str] = Field(
+    doc_emote: Optional[EmojiStr] = Field(
         default=None, description="Alias para emoji, mantido por compatibilidade."
     )
+    doc_keywords: Optional[List[TagStr]] = Field(
+        default=None, description="Palavras-chave para busca."
+    )
+    doc_is_public: Optional[bool] = Field(
+        default=None, description="Se o documento é público."
+    )
 
 
 class KnowledgeTool(Tool):
@@ -260,17 +350,23 @@ class KnowledgeTool(Tool):
         if action is KnowledgeAction.WORK_CREATE:
             if not payload.work_title:
                 return text("❌ Informe work_title para criar o item.")
+            if not payload.team_id:
+                return text("❌ Informe team_id para criar o item.")
             work = await self._service.work_create(
                 {
                     "title": payload.work_title,
                     "description": payload.work_description,
                     "item_type": payload.work_type,
+                    "status": payload.work_status,
                     "priority": payload.work_priority,
                     "story_points": payload.story_points,
                     "assignee_id": payload.assignee_id,
                     "sprint_id": payload.sprint_id,
                     "board_id": payload.board_id,
                     "parent_id": payload.parent_id,
+                    "team_id": payload.team_id,
+                    "due_date": payload.work_due_date,
+                    "tags": payload.work_tags,
                 }
             )
             return text(_format_work(work, header="✅ Work item criado"))
@@ -305,12 +401,16 @@ class KnowledgeTool(Tool):
                     "title": payload.work_title,
                     "description": payload.work_description,
                     "item_type": payload.work_type,
+                    "status": payload.work_status,
                     "priority": payload.work_priority,
                     "story_points": payload.story_points,
                     "assignee_id": payload.assignee_id,
                     "sprint_id": payload.sprint_id,
                     "board_id": payload.board_id,
                     "parent_id": payload.parent_id,
+                    "team_id": payload.team_id,
+                    "due_date": payload.work_due_date,
+                    "tags": payload.work_tags,
                 },
             )
             return text(_format_work(work, header="✅ Work item atualizado"))
@@ -322,20 +422,23 @@ class KnowledgeTool(Tool):
             return text(f"🗑️ Work item {payload.id} removido.")
 
         if action is KnowledgeAction.WORK_BACKLOG:
-            if not payload.team_id:
+            team_id = sanitize_null(payload.team_id)
+            if not team_id:
                 return text("❌ Informe team_id para consultar o backlog.")
-            items = await self._service.work_backlog(team_id=payload.team_id)
+            items = await self._service.work_backlog(team_id=team_id)
             if not items:
                 return text("📋 Backlog vazio para o time informado.")
             body = "\n\n".join(_format_work(item) for item in items)
             return text(f"📋 **Backlog ({len(items)}):**\n\n{body}")
 
         if action is KnowledgeAction.WORK_SEARCH:
-            if not payload.query or not payload.team_id:
+            query = sanitize_null(payload.query)
+            team_id = sanitize_null(payload.team_id)
+            if not query or not team_id:
                 return text("❌ Informe query e team_id para buscar work items.")
             items = await self._service.work_search(
-                query=payload.query,
-                team_id=payload.team_id,
+                query=query,
+                team_id=team_id,
                 limit=payload.limit,
             )
             if not items:
@@ -344,9 +447,10 @@ class KnowledgeTool(Tool):
             return text(f"🔍 **Resultados ({len(items)}):**\n\n{body}")
 
         if action is KnowledgeAction.WORK_ANALYTICS:
-            if not payload.team_id:
+            team_id = sanitize_null(payload.team_id)
+            if not team_id:
                 return text("❌ Informe team_id para obter analytics.")
-            analytics = await self._service.work_analytics(team_id=payload.team_id)
+            analytics = await self._service.work_analytics(team_id=team_id)
             lines = ["📊 **Analytics de Work Items**"]
             for key, value in analytics.items():
                 lines.append(f"- {key}: {value}")
@@ -370,6 +474,49 @@ class KnowledgeTool(Tool):
             body = "\n\n".join(_format_work(item) for item in items)
             return text(f"🏃 **Work items do sprint ({len(items)}):**\n\n{body}")
 
+        if action is KnowledgeAction.WORK_BY_EPIC:
+            if not payload.epic_id:
+                return text("❌ Informe epic_id para listar os itens.")
+            items = await self._service.work_by_epic(epic_id=payload.epic_id)
+            if not items:
+                return text("📦 Nenhum item vinculado ao épico informado.")
+            body = "\n\n".join(_format_work(item) for item in items)
+            return text(f"📦 **Work items do épico ({len(items)}):**\n\n{body}")
+
+        if action is KnowledgeAction.WORK_CHILDREN:
+            if not payload.id:
+                return text("❌ Informe o ID do work item pai.")
+            items = await self._service.work_children(payload.id)
+            if not items:
+                return text("👶 Nenhum item filho encontrado.")
+            body = "\n\n".join(_format_work(item) for item in items)
+            return text(f"👶 **Work items filhos ({len(items)}):**\n\n{body}")
+
+        if action is KnowledgeAction.WORK_STATUS_UPDATE:
+            if not payload.id:
+                return text("❌ Informe o ID do work item.")
+            if not payload.work_status:
+                return text("❌ Informe work_status para atualizar.")
+            work = await self._service.work_update_status(
+                payload.id,
+                {"status": payload.work_status},
+            )
+            return text(_format_work(work, header="✅ Status atualizado"))
+
+        if action is KnowledgeAction.WORK_ASSIGN_SPRINT:
+            if not payload.sprint_id:
+                return text("❌ Informe sprint_id para atribuir os itens.")
+            if not payload.work_item_ids:
+                return text("❌ Informe work_item_ids com a lista de IDs.")
+            await self._service.work_assign_to_sprint(
+                {
+                    "sprint_id": payload.sprint_id,
+                    "work_item_ids": payload.work_item_ids,
+                }
+            )
+            count = len(payload.work_item_ids)
+            return text(f"✅ {count} work item(s) atribuído(s) ao sprint.")
+
         return text(
             "❌ Ação de work item não suportada.\n\nEscolha um dos valores:\n"
             + "\n".join(
@@ -505,6 +652,7 @@ class KnowledgeTool(Tool):
                     "description": payload.mode_description,
                     "content": payload.mode_content,
                     "is_default": payload.mode_is_default,
+                    "metadata": payload.mode_metadata,
                 }
             )
             return text(_format_mode(mode, header="✅ Modo criado"))
@@ -540,6 +688,7 @@ class KnowledgeTool(Tool):
                     "description": payload.mode_description,
                     "content": payload.mode_content,
                     "is_default": payload.mode_is_default,
+                    "metadata": payload.mode_metadata,
                 },
             )
             return text(_format_mode(mode, header="✅ Modo atualizado"))
@@ -610,6 +759,7 @@ class KnowledgeTool(Tool):
                     "description": payload.rule_description,
                     "content": payload.rule_content,
                     "is_default": payload.rule_is_default,
+                    "metadata": payload.rule_metadata,
                 }
             )
             return text(_format_rule(rule, header="✅ Regra criada"))
@@ -646,6 +796,7 @@ class KnowledgeTool(Tool):
                     "description": payload.rule_description,
                     "content": payload.rule_content,
                     "is_default": payload.rule_is_default,
+                    "metadata": payload.rule_metadata,
                 },
             )
             return text(_format_rule(rule, header="✅ Regra atualizada"))
@@ -681,19 +832,21 @@ class KnowledgeTool(Tool):
             doc = await self._service.doc_create(
                 {
                     "title": payload.doc_title,
-                    "description": payload.doc_description,
-                    "content": payload.doc_content,
-                    "status": payload.doc_status,
-                    "doc_type": payload.doc_type,
-                    "language": payload.doc_language,
-                    "parent_id": payload.doc_parent_id,
-                    "team_id": payload.doc_team_id or payload.team_id,
-                    "owner_id": payload.doc_owner_id,
-                    "reviewer_id": payload.doc_reviewer_id,
-                    "version": payload.doc_version,
-                    "category": payload.doc_category,
-                    "tags": payload.doc_tags,
-                    "emoji": payload.doc_emoji or payload.doc_emote,
+                    "description": sanitize_null(payload.doc_description),
+                    "content": sanitize_null(payload.doc_content),
+                    "status": sanitize_null(payload.doc_status),
+                    "doc_type": sanitize_null(payload.doc_type),
+                    "language": sanitize_null(payload.doc_language),
+                    "parent_id": sanitize_null(payload.doc_parent_id),
+                    "team_id": sanitize_null(payload.doc_team_id or payload.team_id),
+                    "owner_user_id": sanitize_null(payload.doc_owner_id),
+                    "reviewer_user_id": sanitize_null(payload.doc_reviewer_id),
+                    "version": sanitize_null(payload.doc_version),
+                    "category": sanitize_null(payload.doc_category),
+                    "tags": sanitize_null_list(payload.doc_tags),
+                    "emoji": sanitize_null(payload.doc_emoji or payload.doc_emote),
+                    "keywords": sanitize_null_list(payload.doc_keywords),
+                    "is_public": payload.doc_is_public,
                 }
             )
             return text(_format_doc(doc, header="✅ Documentação criada"))
@@ -729,20 +882,22 @@ class KnowledgeTool(Tool):
             doc = await self._service.doc_update(
                 payload.id,
                 {
-                    "title": payload.doc_title,
-                    "description": payload.doc_description,
-                    "content": payload.doc_content,
-                    "status": payload.doc_status,
-                    "doc_type": payload.doc_type,
-                    "language": payload.doc_language,
-                    "parent_id": payload.doc_parent_id,
-                    "team_id": payload.doc_team_id or payload.team_id,
-                    "owner_id": payload.doc_owner_id,
-                    "reviewer_id": payload.doc_reviewer_id,
-                    "version": payload.doc_version,
-                    "category": payload.doc_category,
-                    "tags": payload.doc_tags,
-                    "emoji": payload.doc_emoji or payload.doc_emote,
+                    "title": sanitize_null(payload.doc_title),
+                    "description": sanitize_null(payload.doc_description),
+                    "content": sanitize_null(payload.doc_content),
+                    "status": sanitize_null(payload.doc_status),
+                    "doc_type": sanitize_null(payload.doc_type),
+                    "language": sanitize_null(payload.doc_language),
+                    "parent_id": sanitize_null(payload.doc_parent_id),
+                    "team_id": sanitize_null(payload.doc_team_id or payload.team_id),
+                    "owner_user_id": sanitize_null(payload.doc_owner_id),
+                    "reviewer_user_id": sanitize_null(payload.doc_reviewer_id),
+                    "version": sanitize_null(payload.doc_version),
+                    "category": sanitize_null(payload.doc_category),
+                    "tags": sanitize_null_list(payload.doc_tags),
+                    "emoji": sanitize_null(payload.doc_emoji or payload.doc_emote),
+                    "keywords": sanitize_null_list(payload.doc_keywords),
+                    "is_public": payload.doc_is_public,
                 },
             )
             return text(_format_doc(doc, header="✅ Documentação atualizada"))
@@ -754,11 +909,13 @@ class KnowledgeTool(Tool):
             return text(f"🗑️ Documentação {payload.id} removida.")
 
         if action is KnowledgeAction.DOC_SEARCH:
-            if not payload.query or not (payload.doc_team_id or payload.team_id):
+            query = sanitize_null(payload.query)
+            team_id = sanitize_null(payload.doc_team_id or payload.team_id)
+            if not query or not team_id:
                 return text("❌ Informe query e team_id para buscar documentação.")
             docs = await self._service.doc_search(
-                query=payload.query,
-                team_id=payload.doc_team_id or payload.team_id,
+                query=query,
+                team_id=team_id,
                 limit=payload.limit,
             )
             if not docs:
@@ -769,11 +926,10 @@ class KnowledgeTool(Tool):
             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):
+            team_id = sanitize_null(payload.doc_team_id or payload.team_id)
+            if not 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=team_id)
             if not docs:
                 return text("📚 Nenhuma raiz encontrada.")
             body = "\n".join(
@@ -783,10 +939,11 @@ class KnowledgeTool(Tool):
             return text(f"📚 **Raízes de documentação:**\n{body}")
 
         if action is KnowledgeAction.DOC_RECENT:
-            if not (payload.doc_team_id or payload.team_id):
+            team_id = sanitize_null(payload.doc_team_id or payload.team_id)
+            if not team_id:
                 return text("❌ Informe team_id para listar documentos recentes.")
             docs = await self._service.doc_recent(
-                team_id=payload.doc_team_id or payload.team_id,
+                team_id=team_id,
                 limit=payload.limit,
             )
             if not docs:
@@ -795,11 +952,10 @@ class KnowledgeTool(Tool):
             return text(f"🕒 **Documentos recentes ({len(docs)}):**\n\n{body}")
 
         if action is KnowledgeAction.DOC_ANALYTICS:
-            if not (payload.doc_team_id or payload.team_id):
+            team_id = sanitize_null(payload.doc_team_id or payload.team_id)
+            if not 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=team_id)
             lines = ["📊 **Analytics de Documentação**"]
             for key, value in analytics.items():
                 lines.append(f"- {key}: {value}")
@@ -932,6 +1088,10 @@ def _format_work(item: Dict[str, Any], *, header: Optional[str] = None) -> str:
         lines.append(
             f"Vencimento: {_format_date(item.get('due_date') or item.get('dueDate'))}"
         )
+    if item.get("tags"):
+        tags = item.get("tags", [])
+        if tags:
+            lines.append(f"Tags: {', '.join(tags)}")
     return "\n".join(lines)
 
 

{fenix_mcp-0.5.12 → fenix_mcp-0.7.0}/fenix_mcp/application/tools/productivity.py

@@ -9,7 +9,16 @@ from typing import Any, Dict, List, Optional
 from pydantic import Field
 
 from fenix_mcp.application.presenters import text
-from fenix_mcp.application.tool_base import Tool, ToolRequest
+from fenix_mcp.application.tool_base import (
+    CategoryStr,
+    DateTimeStr,
+    MarkdownStr,
+    TagStr,
+    TitleStr,
+    Tool,
+    ToolRequest,
+    UUIDStr,
+)
 from fenix_mcp.domain.productivity import ProductivityService
 from fenix_mcp.infrastructure.context import AppContext
 
@@ -59,19 +68,26 @@ ACTION_FIELD_DESCRIPTION = (
 
 class ProductivityRequest(ToolRequest):
     action: TodoAction = Field(description=ACTION_FIELD_DESCRIPTION)
-    id: Optional[str] = Field(default=None, description="Identificador do item TODO.")
-    title: Optional[str] = Field(
+    id: Optional[UUIDStr] = Field(default=None, description="ID do item TODO (UUID).")
+    title: Optional[TitleStr] = Field(
         default=None, description="Título do TODO (obrigatório em create)."
     )
-    content: Optional[str] = Field(
+    content: Optional[MarkdownStr] = Field(
         default=None, description="Conteúdo em Markdown (obrigatório em create)."
     )
-    status: Optional[str] = Field(default=None, description="Status do TODO.")
-    priority: Optional[str] = Field(default=None, description="Prioridade do TODO.")
-    category: Optional[str] = Field(default=None, description="Categoria opcional.")
-    tags: Optional[List[str]] = Field(default=None, description="Lista de tags.")
-    due_date: Optional[str] = Field(
-        default=None, description="Data de vencimento do TODO (ISO)."
+    status: Optional[str] = Field(
+        default=None,
+        description="Status do TODO (pending, in_progress, completed, cancelled).",
+    )
+    priority: Optional[str] = Field(
+        default=None, description="Prioridade do TODO (low, medium, high, urgent)."
+    )
+    category: Optional[CategoryStr] = Field(
+        default=None, description="Categoria opcional."
+    )
+    tags: Optional[List[TagStr]] = Field(default=None, description="Lista de tags.")
+    due_date: Optional[DateTimeStr] = Field(
+        default=None, description="Data de vencimento do TODO (ISO 8601)."
     )
     limit: int = Field(
         default=20, ge=1, le=100, description="Limite de resultados em list/search."

{fenix_mcp-0.5.12 → fenix_mcp-0.7.0}/fenix_mcp/application/tools/user_config.py

@@ -9,7 +9,13 @@ from typing import Any, Dict, List, Optional
 from pydantic import Field
 
 from fenix_mcp.application.presenters import text
-from fenix_mcp.application.tool_base import Tool, ToolRequest
+from fenix_mcp.application.tool_base import (
+    MarkdownStr,
+    TitleStr,
+    Tool,
+    ToolRequest,
+    UUIDStr,
+)
 from fenix_mcp.domain.user_config import UserConfigService, _strip_none
 from fenix_mcp.infrastructure.context import AppContext
 
@@ -51,15 +57,20 @@ ACTION_FIELD_DESCRIPTION = "Ação a executar. Escolha um dos valores: " + ", ".
 
 class UserConfigRequest(ToolRequest):
     action: UserConfigAction = Field(description=ACTION_FIELD_DESCRIPTION)
-    id: Optional[str] = Field(default=None, description="ID do documento.")
-    name: Optional[str] = Field(default=None, description="Nome do documento.")
-    content: Optional[str] = Field(
+    id: Optional[UUIDStr] = Field(default=None, description="ID do documento (UUID).")
+    name: Optional[TitleStr] = Field(default=None, description="Nome do documento.")
+    content: Optional[MarkdownStr] = Field(
         default=None, description="Conteúdo em Markdown/JSON."
     )
-    mode_id: Optional[str] = Field(default=None, description="ID do modo associado.")
+    mode_id: Optional[UUIDStr] = Field(
+        default=None, description="ID do modo associado (UUID)."
+    )
     is_default: Optional[bool] = Field(
         default=None, description="Marca o documento como padrão."
     )
+    metadata: Optional[MarkdownStr] = Field(
+        default=None, description="Metadata estruturada do documento (Markdown)."
+    )
     limit: int = Field(default=20, ge=1, le=100, description="Limite para listagem.")
     offset: int = Field(default=0, ge=0, description="Offset para listagem.")
     return_content: Optional[bool] = Field(
@@ -90,6 +101,7 @@ class UserConfigTool(Tool):
                         "content": payload.content,
                         "mode_id": payload.mode_id,
                         "is_default": payload.is_default,
+                        "metadata": payload.metadata,
                     }
                 )
             )
@@ -124,6 +136,7 @@ class UserConfigTool(Tool):
                     "content": payload.content,
                     "mode_id": payload.mode_id,
                     "is_default": payload.is_default,
+                    "metadata": payload.metadata,
                 }
             )
             doc = await self._service.update(payload.id, data)

{fenix_mcp-0.5.12 → fenix_mcp-0.7.0}/fenix_mcp/domain/intelligence.py

@@ -114,36 +114,6 @@ class IntelligenceService:
         }
         return await self._call(self.api.consolidate_memories, payload)
 
-    async def priority_memories(self, *, limit: int) -> List[Dict[str, Any]]:
-        params = {
-            "limit": limit,
-            "sortBy": "priority_score",
-            "sortOrder": "desc",
-        }
-        return (
-            await self._call(
-                self.api.list_memories,
-                include_content=False,
-                include_metadata=False,
-                **params,
-            )
-            or []
-        )
-
-    async def analytics(self, *, time_range: str, group_by: str) -> Dict[str, Any]:
-        memories = await self.query_memories(
-            limit=200, timeRange=time_range, groupBy=group_by
-        )
-        summary: Dict[str, Any] = {
-            "total_memories": len(memories),
-            "by_group": {},
-        }
-        group_key = group_by
-        for memory in memories:
-            key = memory.get(group_key) or memory.get("metadata") or "N/A"
-            summary["by_group"][key] = summary["by_group"].get(key, 0) + 1
-        return summary
-
     async def update_memory(self, memory_id: str, **fields: Any) -> Dict[str, Any]:
         payload = _strip_none(fields)
         if "importance" in payload:
@@ -162,6 +132,9 @@ class IntelligenceService:
                 payload[new_key] = payload.pop(old_key)
         return await self._call(self.api.update_memory, memory_id, payload)
 
+    async def delete_memory(self, memory_id: str) -> None:
+        await self._call(self.api.delete_memory, memory_id)
+
     async def _call(self, func, *args, **kwargs):
         return await asyncio.to_thread(func, *args, **kwargs)
 

{fenix_mcp-0.5.12 → fenix_mcp-0.7.0}/fenix_mcp.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fenix-mcp
-Version: 0.5.12
+Version: 0.7.0
 Summary: Fênix Cloud MCP server implemented in Python
 Author: Fenix Inc
 Requires-Python: >=3.10

fenix_mcp-0.5.12/fenix_mcp/application/tool_base.py

@@ -1,47 +0,0 @@
-# SPDX-License-Identifier: MIT
-"""Base abstractions for MCP tools."""
-
-from __future__ import annotations
-
-from abc import ABC, abstractmethod
-from typing import Any, Dict, Type
-
-from pydantic import BaseModel, ConfigDict
-
-from fenix_mcp.infrastructure.context import AppContext
-
-
-class ToolRequest(BaseModel):
-    """Base request payload."""
-
-    model_config = ConfigDict(extra="forbid")
-
-
-ToolResponse = Dict[str, Any]
-
-
-class Tool(ABC):
-    """Interface implemented by all tools."""
-
-    name: str
-    description: str
-    request_model: Type[ToolRequest] = ToolRequest
-
-    def schema(self) -> Dict[str, Any]:
-        """Return JSON schema describing the tool arguments."""
-        return {
-            "name": self.name,
-            "description": self.description,
-            "inputSchema": self.request_model.model_json_schema(),
-        }
-
-    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)
-
-    @abstractmethod
-    async def run(self, payload: ToolRequest, context: AppContext) -> ToolResponse:
-        """Execute business logic and return a MCP-formatted response."""