fenix-mcp 1.1.0__tar.gz → 1.3.0__tar.gz

{fenix_mcp-1.1.0 → fenix_mcp-1.3.0}/PKG-INFO

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

{fenix_mcp-1.1.0 → fenix_mcp-1.3.0}/fenix_mcp/__init__.py

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

{fenix_mcp-1.1.0 → fenix_mcp-1.3.0}/fenix_mcp/application/tools/intelligence.py

@@ -35,6 +35,7 @@ class IntelligenceAction(str, Enum):
         "Creates intelligent memories with similarity analysis.",
     )
     QUERY = ("memory_query", "Lists memories applying filters and text search.")
+    GET = ("memory_get", "Gets memory details and content by ID.")
     SIMILARITY = ("memory_similarity", "Finds memories similar to a base content.")
     CONSOLIDATE = (
         "memory_consolidate",
@@ -185,6 +186,8 @@ class IntelligenceTool(Tool):
             return await self._handle_smart_create(payload)
         if action is IntelligenceAction.QUERY:
             return await self._handle_query(payload)
+        if action is IntelligenceAction.GET:
+            return await self._handle_get(payload)
         if action is IntelligenceAction.SIMILARITY:
             return await self._handle_similarity(payload)
         if action is IntelligenceAction.CONSOLIDATE:
@@ -258,6 +261,14 @@ class IntelligenceTool(Tool):
         body = "\n\n".join(_format_memory(mem) for mem in memories)
         return text(f"🧠 **Memories ({len(memories)}):**\n\n{body}")
 
+    async def _handle_get(self, payload: IntelligenceRequest):
+        if not payload.id:
+            return text("❌ Provide the memory ID to get details.")
+        memory = await self._service.get_memory(
+            payload.id, include_content=True, include_metadata=True
+        )
+        return text(_format_memory(memory, show_content=True))
+
     async def _handle_similarity(self, payload: IntelligenceRequest):
         if not payload.content:
             return text("❌ Provide the base content to compare similarity.")
@@ -343,17 +354,20 @@ class IntelligenceTool(Tool):
         )
 
 
-def _format_memory(memory: Dict[str, Any]) -> str:
-    return "\n".join(
-        [
-            f"🧠 **{memory.get('title', 'Untitled')}**",
-            f"ID: {memory.get('id', memory.get('memoryId', 'N/A'))}",
-            f"Category: {memory.get('category', 'N/A')}",
-            f"Tags: {', '.join(memory.get('tags', [])) or 'None'}",
-            f"Importance: {memory.get('importance', 'N/A')}",
-            f"Accesses: {memory.get('access_count', 'N/A')}",
-        ]
-    )
+def _format_memory(memory: Dict[str, Any], *, show_content: bool = False) -> str:
+    lines = [
+        f"🧠 **{memory.get('title', 'Untitled')}**",
+        f"ID: {memory.get('id', memory.get('memoryId', 'N/A'))}",
+        f"Category: {memory.get('category', 'N/A')}",
+        f"Tags: {', '.join(memory.get('tags', [])) or 'None'}",
+        f"Importance: {memory.get('importance', 'N/A')}",
+        f"Accesses: {memory.get('access_count', 'N/A')}",
+    ]
+    if show_content and memory.get("content"):
+        lines.append("")
+        lines.append("**Content:**")
+        lines.append(memory.get("content"))
+    return "\n".join(lines)
 
 
 def format_percentage(value: Optional[float]) -> str:

{fenix_mcp-1.1.0 → fenix_mcp-1.3.0}/fenix_mcp/application/tools/knowledge.py

@@ -107,22 +107,36 @@ class KnowledgeAction(str, Enum):
     RULE_UPDATE = ("rule_update", "Updates an existing rule.")
     RULE_DELETE = ("rule_delete", "Removes a rule.")
 
-    # Documentation
+    # Documentation - Navigation workflow: doc_full_tree -> doc_children -> doc_get
     DOC_CREATE = (
         "doc_create",
         "Creates a documentation item. Requires doc_emoji for page, api_doc, and guide types.",
     )
-    DOC_LIST = ("doc_list", "Lists documentation items with filters.")
-    DOC_GET = ("doc_get", "Gets documentation item details.")
+    DOC_LIST = (
+        "doc_list",
+        "Lists documentation items. Use doc_full_tree for hierarchical view.",
+    )
+    DOC_GET = (
+        "doc_get",
+        "Reads document content by ID. Get the ID from doc_full_tree or doc_children first.",
+    )
     DOC_UPDATE = ("doc_update", "Updates a documentation item.")
     DOC_DELETE = ("doc_delete", "Removes a documentation item.")
-    DOC_SEARCH = ("doc_search", "Searches documentation items by text.")
-    DOC_ROOTS = ("doc_roots", "Lists available root documents.")
+    DOC_ROOTS = (
+        "doc_roots",
+        "Lists root folders. Use doc_children to navigate inside.",
+    )
     DOC_RECENT = ("doc_recent", "Lists recently accessed documents.")
     DOC_ANALYTICS = ("doc_analytics", "Returns document analytics.")
-    DOC_CHILDREN = ("doc_children", "Lists child documents of an item.")
-    DOC_TREE = ("doc_tree", "Retrieves the direct tree of a document.")
-    DOC_FULL_TREE = ("doc_full_tree", "Retrieves the full documentation tree.")
+    DOC_CHILDREN = (
+        "doc_children",
+        "Lists child documents of a folder by ID. Use this to navigate into folders.",
+    )
+    DOC_TREE = ("doc_tree", "Retrieves tree starting from a specific document.")
+    DOC_FULL_TREE = (
+        "doc_full_tree",
+        "Retrieves complete documentation tree. Start here to find documents.",
+    )
     DOC_MOVE = ("doc_move", "Moves a document to another parent.")
     DOC_PUBLISH = ("doc_publish", "Changes publication status of a document.")
     DOC_VERSION = ("doc_version", "Generates or retrieves a document version.")
@@ -387,7 +401,9 @@ class KnowledgeTool(Tool):
             if not payload.id:
                 return text("❌ Provide the work item ID.")
             work = await self._service.work_get(payload.id)
-            return text(_format_work(work, header="🎯 Work item details"))
+            return text(
+                _format_work(work, header="🎯 Work item details", show_description=True)
+            )
 
         if action is KnowledgeAction.WORK_UPDATE:
             if not payload.id:
@@ -431,6 +447,11 @@ class KnowledgeTool(Tool):
             items = await self._service.work_search(
                 query=query,
                 limit=payload.limit,
+                item_type=payload.work_type,
+                status=payload.work_status,
+                priority=payload.work_priority,
+                assignee_id=payload.assignee_id,
+                tags=payload.work_tags,
             )
             if not items:
                 return text("🔍 No work items found.")
@@ -658,7 +679,7 @@ class KnowledgeTool(Tool):
                 return_description=payload.return_description,
                 return_metadata=payload.return_metadata,
             )
-            return text(_format_mode(mode, header="🎭 Mode details"))
+            return text(_format_mode(mode, header="🎭 Mode details", show_content=True))
 
         if action is KnowledgeAction.MODE_UPDATE:
             if not payload.mode_id:
@@ -766,7 +787,7 @@ class KnowledgeTool(Tool):
                 return_metadata=payload.return_metadata,
                 return_modes=payload.return_metadata,
             )
-            return text(_format_rule(rule, header="📋 Rule details"))
+            return text(_format_rule(rule, header="📋 Rule details", show_content=True))
 
         if action is KnowledgeAction.RULE_UPDATE:
             if not payload.rule_id:
@@ -854,11 +875,10 @@ class KnowledgeTool(Tool):
         if action is KnowledgeAction.DOC_GET:
             if not payload.id:
                 return text("❌ Provide the documentation ID.")
-            doc = await self._service.doc_get(
-                payload.id,
-                returnContent=payload.return_content,
+            doc = await self._service.doc_get(payload.id)
+            return text(
+                _format_doc(doc, header="📄 Documentation details", show_content=True)
             )
-            return text(_format_doc(doc, header="📄 Documentation details"))
 
         if action is KnowledgeAction.DOC_UPDATE:
             if not payload.id:
@@ -896,19 +916,6 @@ class KnowledgeTool(Tool):
             await self._service.doc_delete(payload.id)
             return text(f"🗑️ Documentation {payload.id} removed.")
 
-        if action is KnowledgeAction.DOC_SEARCH:
-            query = sanitize_null(payload.query)
-            if not query:
-                return text("❌ Provide query to search documentation.")
-            docs = await self._service.doc_search(
-                query=query,
-                limit=payload.limit,
-            )
-            if not docs:
-                return text("🔍 No documents found for the specified filters.")
-            body = "\n\n".join(_format_doc(doc) for doc in docs)
-            return text(f"🔍 **Results ({len(docs)}):**\n\n{body}")
-
         if action is KnowledgeAction.DOC_ROOTS:
             docs = await self._service.doc_roots()
             if not docs:
@@ -1013,13 +1020,34 @@ class KnowledgeTool(Tool):
         )
 
     async def _handle_help(self):
+        workflow_guide = """
+## 📖 How to find and read a document
+
+1. **doc_full_tree** → See complete folder structure with IDs
+2. **doc_children(id)** → List contents of a specific folder
+3. **doc_get(id)** → Read the document content
+
+Example: To find "Overview" inside "Architecture" folder:
+1. Call `doc_full_tree` to see all folders and documents
+2. Find the folder "Architecture" and note its ID
+3. Call `doc_children` with that ID to list its contents
+4. Find "Overview" document and note its ID
+5. Call `doc_get` with that ID to read the content
+
+"""
         return text(
             "📚 **Available actions for knowledge**\n\n"
+            + workflow_guide
             + KnowledgeAction.formatted_help()
         )
 
 
-def _format_work(item: Dict[str, Any], *, header: Optional[str] = None) -> str:
+def _format_work(
+    item: Dict[str, Any],
+    *,
+    header: Optional[str] = None,
+    show_description: bool = False,
+) -> str:
     lines: List[str] = []
     if header:
         lines.append(header)
@@ -1028,6 +1056,9 @@ def _format_work(item: Dict[str, Any], *, header: Optional[str] = None) -> str:
     # Extract title
     title = item.get("title") or item.get("name") or "Untitled"
 
+    # Extract type
+    item_type = item.get("item_type") or item.get("type") or "unknown"
+
     # Extract status
     status = item.get("status") or item.get("state") or "unknown"
 
@@ -1050,6 +1081,7 @@ def _format_work(item: Dict[str, Any], *, header: Optional[str] = None) -> str:
         [
             f"🎯 **{title}**",
             f"ID: {item_id}",
+            f"Type: {item_type}",
             f"Status: {status}",
             f"Priority: {priority}",
             f"Assignee: {assignee}",
@@ -1063,6 +1095,13 @@ def _format_work(item: Dict[str, Any], *, header: Optional[str] = None) -> str:
         tags = item.get("tags", [])
         if tags:
             lines.append(f"Tags: {', '.join(tags)}")
+
+    # Show description only when explicitly requested (e.g., work_get)
+    if show_description and item.get("description"):
+        lines.append("")
+        lines.append("**Description:**")
+        lines.append(item.get("description"))
+
     return "\n".join(lines)
 
 
@@ -1106,7 +1145,12 @@ def _format_sprint(sprint: Dict[str, Any], header: Optional[str] = None) -> str:
     return "\n".join(lines)
 
 
-def _format_mode(mode: Dict[str, Any], header: Optional[str] = None) -> str:
+def _format_mode(
+    mode: Dict[str, Any],
+    *,
+    header: Optional[str] = None,
+    show_content: bool = False,
+) -> str:
     lines: List[str] = []
     if header:
         lines.append(header)
@@ -1120,10 +1164,19 @@ def _format_mode(mode: Dict[str, Any], header: Optional[str] = None) -> str:
     )
     if mode.get("description"):
         lines.append(f"Description: {mode['description']}")
+    if show_content and mode.get("content"):
+        lines.append("")
+        lines.append("**Content:**")
+        lines.append(mode.get("content"))
     return "\n".join(lines)
 
 
-def _format_rule(rule: Dict[str, Any], header: Optional[str] = None) -> str:
+def _format_rule(
+    rule: Dict[str, Any],
+    *,
+    header: Optional[str] = None,
+    show_content: bool = False,
+) -> str:
     lines: List[str] = []
     if header:
         lines.append(header)
@@ -1137,10 +1190,19 @@ def _format_rule(rule: Dict[str, Any], header: Optional[str] = None) -> str:
     )
     if rule.get("description"):
         lines.append(f"Description: {rule['description']}")
+    if show_content and rule.get("content"):
+        lines.append("")
+        lines.append("**Content:**")
+        lines.append(rule.get("content"))
     return "\n".join(lines)
 
 
-def _format_doc(doc: Dict[str, Any], header: Optional[str] = None) -> str:
+def _format_doc(
+    doc: Dict[str, Any],
+    *,
+    header: Optional[str] = None,
+    show_content: bool = False,
+) -> str:
     lines: List[str] = []
     if header:
         lines.append(header)
@@ -1157,6 +1219,13 @@ def _format_doc(doc: Dict[str, Any], header: Optional[str] = None) -> str:
         lines.append(
             f"Updated at: {_format_date(doc.get('updated_at') or doc.get('updatedAt'))}"
         )
+
+    # Show content only when explicitly requested (e.g., doc_get)
+    if show_content and doc.get("content"):
+        lines.append("")
+        lines.append("**Content:**")
+        lines.append(doc.get("content"))
+
     return "\n".join(lines)
 
 

{fenix_mcp-1.1.0 → fenix_mcp-1.3.0}/fenix_mcp/application/tools/productivity.py

@@ -31,8 +31,12 @@ class TodoAction(str, Enum):
         return obj
 
     CREATE = ("todo_create", "Creates a new TODO.")
-    LIST = ("todo_list", "Lists TODOs with optional filters.")
-    GET = ("todo_get", "Gets TODO details by ID.")
+    LIST = (
+        "todo_list",
+        "Lists TODOs. By default returns only pending and in_progress. "
+        "To filter by status, use status parameter with values: pending (backlog), in_progress, completed, cancelled.",
+    )
+    GET = ("todo_get", "Gets TODO details and content by ID.")
     UPDATE = ("todo_update", "Updates fields of an existing TODO.")
     DELETE = ("todo_delete", "Removes a TODO by ID.")
     STATS = ("todo_stats", "Returns aggregated TODO statistics.")
@@ -77,7 +81,7 @@ class ProductivityRequest(ToolRequest):
     )
     status: Optional[str] = Field(
         default=None,
-        description="TODO status (pending, in_progress, completed, cancelled).",
+        description="TODO status. Values: pending (shown as 'backlog' in UI), in_progress, completed, cancelled.",
     )
     priority: Optional[str] = Field(
         default=None, description="TODO priority (low, medium, high, urgent)."
@@ -154,13 +158,32 @@ class ProductivityTool(Tool):
         return text(self._format_single(todo, header="✅ TODO created successfully!"))
 
     async def _handle_list(self, payload: ProductivityRequest):
-        todos = await self._service.list_todos(
-            limit=payload.limit,
-            offset=payload.offset,
-            status=payload.status,
-            priority=payload.priority,
-            category=payload.category,
-        )
+        # If no status filter provided, fetch pending and in_progress only
+        if payload.status:
+            todos = await self._service.list_todos(
+                limit=payload.limit,
+                offset=payload.offset,
+                status=payload.status,
+                priority=payload.priority,
+                category=payload.category,
+            )
+        else:
+            # Fetch pending and in_progress separately and merge
+            pending = await self._service.list_todos(
+                limit=payload.limit,
+                offset=payload.offset,
+                status="pending",
+                priority=payload.priority,
+                category=payload.category,
+            )
+            in_progress = await self._service.list_todos(
+                limit=payload.limit,
+                offset=payload.offset,
+                status="in_progress",
+                priority=payload.priority,
+                category=payload.category,
+            )
+            todos = pending + in_progress
         if not todos:
             return text("📋 No TODOs found.")
         body = "\n\n".join(ProductivityService.format_todo(todo) for todo in todos)
@@ -170,7 +193,9 @@ class ProductivityTool(Tool):
         if not payload.id:
             return text("❌ Provide the ID to get a TODO.")
         todo = await self._service.get_todo(payload.id)
-        return text(self._format_single(todo, header="📋 TODO found"))
+        return text(
+            self._format_single(todo, header="📋 TODO found", show_content=True)
+        )
 
     async def _handle_update(self, payload: ProductivityRequest):
         if not payload.id:
@@ -249,5 +274,13 @@ class ProductivityTool(Tool):
         )
 
     @staticmethod
-    def _format_single(todo: Dict[str, Any], *, header: str) -> str:
-        return "\n".join([header, "", ProductivityService.format_todo(todo)])
+    def _format_single(
+        todo: Dict[str, Any], *, header: str, show_content: bool = False
+    ) -> str:
+        return "\n".join(
+            [
+                header,
+                "",
+                ProductivityService.format_todo(todo, show_content=show_content),
+            ]
+        )

{fenix_mcp-1.1.0 → fenix_mcp-1.3.0}/fenix_mcp/domain/knowledge.py

@@ -85,11 +85,26 @@ class KnowledgeService:
     async def work_backlog(self) -> List[Dict[str, Any]]:
         return await self._call_list(self.api.list_work_items_backlog)
 
-    async def work_search(self, *, query: str, limit: int) -> List[Dict[str, Any]]:
+    async def work_search(
+        self,
+        *,
+        query: str,
+        limit: int,
+        item_type: Optional[str] = None,
+        status: Optional[str] = None,
+        priority: Optional[str] = None,
+        assignee_id: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+    ) -> List[Dict[str, Any]]:
         return await self._call_list(
             self.api.search_work_items,
             query=query,
             limit=limit,
+            item_type=item_type,
+            status=status,
+            priority=priority,
+            assignee_id=assignee_id,
+            tags=tags,
         )
 
     async def work_analytics(self) -> Dict[str, Any]:
@@ -472,14 +487,6 @@ class KnowledgeService:
     async def doc_delete(self, doc_id: str) -> None:
         await self._call(self.api.delete_documentation_item, doc_id)
 
-    async def doc_search(self, *, query: str, limit: int) -> List[Dict[str, Any]]:
-        result = await self._call(
-            self.api.search_documentation_items,
-            query=query,
-            limit=limit,
-        )
-        return _ensure_list(result)
-
     async def doc_roots(self) -> List[Dict[str, Any]]:
         result = await self._call(self.api.list_documentation_roots)
         return _ensure_list(result)
@@ -496,7 +503,7 @@ class KnowledgeService:
         return _ensure_dict(result)
 
     async def doc_children(self, doc_id: str) -> List[Dict[str, Any]]:
-        return await self._call(self.api.get_documentation_children, doc_id) or []
+        return await self._call_list(self.api.get_documentation_children, doc_id)
 
     async def doc_tree(self, doc_id: str) -> Dict[str, Any]:
         return await self._call(self.api.get_documentation_tree, doc_id) or {}

{fenix_mcp-1.1.0 → fenix_mcp-1.3.0}/fenix_mcp/domain/productivity.py

@@ -148,17 +148,20 @@ class ProductivityService:
         return []
 
     @staticmethod
-    def format_todo(item: Dict[str, Any]) -> str:
-        return "\n".join(
-            [
-                f"📋 **{item.get('title', 'Sem título')}**",
-                f"ID: {item.get('id', 'N/A')}",
-                f"Status: {item.get('status', 'desconhecido')}",
-                f"Prioridade: {item.get('priority', 'desconhecida')}",
-                f"Categoria: {item.get('category') or 'não definida'}",
-                f"Vencimento: {format_date(item.get('dueDate') or item.get('due_date'))}",
-            ]
-        )
+    def format_todo(item: Dict[str, Any], *, show_content: bool = False) -> str:
+        lines = [
+            f"📋 **{item.get('title', 'No title')}**",
+            f"ID: {item.get('id', 'N/A')}",
+            f"Status: {item.get('status', 'unknown')}",
+            f"Priority: {item.get('priority', 'unknown')}",
+            f"Category: {item.get('category') or 'not set'}",
+            f"Due date: {format_date(item.get('dueDate') or item.get('due_date'))}",
+        ]
+        if show_content and item.get("content"):
+            lines.append("")
+            lines.append("**Content:**")
+            lines.append(item.get("content"))
+        return "\n".join(lines)
 
 
 def _strip_none(data: Dict[str, Any]) -> Dict[str, Any]:
@@ -177,9 +180,9 @@ def _coerce_str_list(value: Any, *, fallback_key: str) -> List[str]:
 
 def format_date(value: Optional[str]) -> str:
     if not value:
-        return "não definido"
+        return "not set"
     try:
         dt = datetime.fromisoformat(value.replace("Z", "+00:00"))
-        return dt.strftime("%d/%m/%Y")
+        return dt.strftime("%Y-%m-%d")
     except ValueError:
         return value

{fenix_mcp-1.1.0 → fenix_mcp-1.3.0}/fenix_mcp/infrastructure/fenix_api/client.py

@@ -4,7 +4,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass, field
-from typing import Any, Dict, Mapping, Optional
+from typing import Any, Dict, List, Mapping, Optional
 
 from fenix_mcp.infrastructure.http_client import HttpClient
 
@@ -501,8 +501,27 @@ class FenixApiClient:
     def list_work_items_backlog(self) -> Any:
         return self._request("GET", "/api/work-items/backlog")
 
-    def search_work_items(self, *, query: str, limit: int) -> Any:
-        params = self._build_params(required={"q": query, "limit": limit})
+    def search_work_items(
+        self,
+        *,
+        query: str,
+        limit: int,
+        item_type: Optional[str] = None,
+        status: Optional[str] = None,
+        priority: Optional[str] = None,
+        assignee_id: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+    ) -> Any:
+        params = self._build_params(
+            required={"q": query, "limit": limit},
+            optional={
+                "item_type": item_type,
+                "status": status,
+                "priority": priority,
+                "assignee_id": assignee_id,
+                "tags": ",".join(tags) if tags else None,
+            },
+        )
         return self._request("GET", "/api/work-items/search", params=params)
 
     def get_work_items_analytics(self) -> Any:

{fenix_mcp-1.1.0 → fenix_mcp-1.3.0}/fenix_mcp.egg-info/PKG-INFO

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