fenix-mcp 1.14.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

fenix_mcp/application/tools/knowledge.py

@@ -81,7 +81,7 @@ class KnowledgeAction(str, Enum):
     )
     WORK_MINE = (
         "work_mine",
-        "Lists work items assigned to the current user. Automatically excludes items with status 'done' or 'cancelled'. Supports pagination via limit and offset parameters.",
+        "START HERE for 'my tasks' or 'what am I working on'. Lists work items assigned to current user. Excludes done/cancelled. Supports limit and offset.",
     )
     WORK_BULK_CREATE = (
         "work_bulk_create",
@@ -150,7 +150,7 @@ class KnowledgeAction(str, Enum):
     )
     DOC_GET = (
         "doc_get",
-        "Reads document content by ID. Get the ID from doc_full_tree or doc_children first.",
+        "Reads document content by ID. PREREQUISITE: Get the ID from doc_full_tree first. Do NOT guess IDs.",
     )
     DOC_UPDATE = ("doc_update", "Updates a documentation item.")
     DOC_DELETE = ("doc_delete", "Removes a documentation item.")
@@ -167,13 +167,27 @@ class KnowledgeAction(str, Enum):
     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.",
+        "START HERE when looking for documentation. Returns complete folder structure with IDs. You NEED the ID from this to use doc_get. Workflow: 1) doc_full_tree to see all docs with IDs, 2) doc_get(id) to read content.",
     )
     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.")
     DOC_DUPLICATE = ("doc_duplicate", "Duplicates an existing document.")
 
+    # API Catalog
+    API_CATALOG_SEARCH = (
+        "api_catalog_search",
+        "Semantic search to find APIs by natural language query (e.g., 'API de usuários').",
+    )
+    API_CATALOG_LIST = (
+        "api_catalog_list",
+        "Lists API specifications with optional filters (status, tags).",
+    )
+    API_CATALOG_GET = (
+        "api_catalog_get",
+        "Gets full details of an API including all endpoints and environments.",
+    )
+
     HELP = ("knowledge_help", "Shows available actions and their uses.")
 
     @classmethod
@@ -191,10 +205,73 @@ class KnowledgeAction(str, Enum):
         return "\n".join(lines)
 
 
-ACTION_FIELD_DESCRIPTION = "Knowledge action. Choose one of the values: " + ", ".join(
-    f"`{member.value}` ({member.description.rstrip('.')})."
-    for member in KnowledgeAction
-)
+ACTION_FIELD_DESCRIPTION = """Knowledge action grouped by category:
+
+**WORK ITEMS** (tasks, bugs, features):
+- `work_mine`: YOUR assigned tasks (START HERE for "my tasks")
+- `work_list`: List with filters (status, priority, type)
+- `work_get`: Get details by ID or key (use work_key for "FENIX-123")
+- `work_create`: Create new (requires: work_title, work_category)
+- `work_update`: Update fields (title, description, priority, story_points, tags, due_date)
+- `work_search`: Search by text
+- `work_bulk_create`: Create multiple with hierarchy
+- `work_backlog`: Team backlog items
+- `work_children`: Child items of a parent
+- `work_by_sprint`: Items in a sprint
+- `work_by_board`: Items in a board
+- `work_by_epic`: Items in an epic
+- `work_status_update`: Update only status
+- `work_assign_sprint`: Assign items to sprint
+- `work_assign_to_me`: Assign item to yourself
+- `work_analytics`: Work item metrics
+
+**DOCUMENTATION**:
+- `doc_full_tree`: Complete tree (START HERE to find docs and get IDs)
+- `doc_get`: Read content (needs ID from doc_full_tree)
+- `doc_children`: Folder contents
+- `doc_create`: Create new doc (requires: doc_title, doc_emoji for non-folders)
+- `doc_update`: Update doc
+- `doc_delete`: Remove doc
+- `doc_roots`: Root folders
+- `doc_recent`: Recently accessed
+- `doc_tree`: Tree from specific doc
+- `doc_move`: Move to another parent
+- `doc_publish`: Change publication status
+- `doc_version`: Create/get version
+- `doc_duplicate`: Duplicate doc
+- `doc_analytics`: Doc metrics
+
+**SPRINTS**:
+- `sprint_active`: Current sprint (START HERE)
+- `sprint_list`: All sprints
+- `sprint_get`: Sprint details
+- `sprint_by_team`: Team sprints
+- `sprint_work_items`: Items in sprint
+
+**BOARDS**:
+- `board_list`: All boards
+- `board_get`: Board details
+- `board_by_team`: Team boards
+- `board_favorites`: Favorite boards
+- `board_columns`: Board columns
+
+**RULES** (coding standards):
+- `rule_list`: Team rules
+- `rule_get`: Rule content
+- `rule_create`: Create rule (requires: rule_scope, rule_name, rule_content)
+- `rule_update`: Update rule
+- `rule_delete`: Remove rule
+- `rule_export`: Export for IDE (cursor, claude, copilot, windsurf)
+- `rule_marketplace`: Public rules
+- `rule_fork`: Fork a rule
+
+**API CATALOG**:
+- `api_catalog_search`: Semantic search for APIs (natural language)
+- `api_catalog_list`: List all APIs
+- `api_catalog_get`: API details with endpoints
+
+`knowledge_help`: Show all actions with descriptions
+"""
 
 
 _ALLOWED_DOC_TYPES = {
@@ -376,12 +453,44 @@ class KnowledgeRequest(ToolRequest):
         default=None, description="Whether the rule is active."
     )
 
+    # API Catalog fields
+    api_spec_id: Optional[UUIDStr] = Field(
+        default=None,
+        description="API specification ID (UUID). Can also use 'id' field instead.",
+    )
+
 
 class KnowledgeTool(Tool):
     name = "knowledge"
-    description = (
-        "Fenix Cloud knowledge operations (Work Items, Boards, Sprints, Rules, Docs)."
-    )
+    description = """Fenix knowledge base - use this tool when user asks about:
+
+WORK ITEMS (tasks, bugs, features):
+- "what are my tasks?" -> action: work_mine
+- "show task FENIX-123" -> action: work_get, work_key: "FENIX-123"
+- "what's in the backlog?" -> action: work_backlog
+- "create a task" -> action: work_create (requires: work_title, work_category)
+
+DOCUMENTATION:
+- "find docs about X" -> action: doc_full_tree (START HERE to get IDs)
+- "read the architecture doc" -> action: doc_get (needs ID from doc_full_tree)
+
+SPRINTS:
+- "current sprint?" -> action: sprint_active
+- "sprint items?" -> action: sprint_work_items
+
+RULES (coding standards):
+- "team coding standards?" -> action: rule_list
+- "export rules for cursor" -> action: rule_export
+
+API CATALOG:
+- "find user API" -> action: api_catalog_search
+- "list all APIs" -> action: api_catalog_list
+
+IMPORTANT WORKFLOWS:
+1. For MY tasks: Always use work_mine first
+2. For docs: Always use doc_full_tree first to get IDs, then doc_get
+3. For work item by key: Use work_key parameter (e.g., "FENIX-123")
+"""
     request_model = KnowledgeRequest
 
     def __init__(self, context: AppContext):
@@ -402,6 +511,8 @@ class KnowledgeTool(Tool):
             return await self._run_rule(payload)
         if action.value.startswith("doc_"):
             return await self._run_doc(payload)
+        if action.value.startswith("api_catalog_"):
+            return await self._run_api_catalog(payload)
         return text(
             "❌ Invalid action for knowledge.\n\nChoose one of the values:\n"
             + "\n".join(f"- `{value}`" for value in KnowledgeAction.choices())
@@ -1154,6 +1265,63 @@ class KnowledgeTool(Tool):
             )
         )
 
+    # ------------------------------------------------------------------
+    # API Catalog
+    # ------------------------------------------------------------------
+    async def _run_api_catalog(self, payload: KnowledgeRequest):
+        action = payload.action
+
+        if action is KnowledgeAction.API_CATALOG_SEARCH:
+            query = sanitize_null(payload.query)
+            if not query:
+                return text("❌ Provide query to search APIs.")
+
+            result = await self._service.api_catalog_search(
+                query=query,
+                limit=payload.limit,
+            )
+
+            data = result.get("data", [])
+            if not data:
+                return text(
+                    f"🔍 No APIs found for: **{query}**\n\n"
+                    "Try a different search term or use `api_catalog_list` to see all APIs."
+                )
+
+            body = "\n\n".join(_format_api_search_result(api) for api in data)
+            total = len(data)
+
+            return text(f"🔍 **APIs found for '{query}'** ({total} results)\n\n{body}")
+
+        if action is KnowledgeAction.API_CATALOG_LIST:
+            apis = await self._service.api_catalog_list(
+                limit=payload.limit,
+                offset=payload.offset,
+            )
+
+            if not apis:
+                return text("📚 No APIs found in the catalog.")
+
+            body = "\n\n".join(_format_api_item(api) for api in apis)
+            return text(f"📚 **API Catalog ({len(apis)} APIs)**\n\n{body}")
+
+        if action is KnowledgeAction.API_CATALOG_GET:
+            spec_id = payload.api_spec_id or payload.id
+            if not spec_id:
+                return text("❌ Provide api_spec_id or id to get the API details.")
+
+            api = await self._service.api_catalog_get(spec_id)
+            return text(_format_api_detail(api))
+
+        return text(
+            "❌ Unsupported API Catalog action.\n\nChoose one of the values:\n"
+            + "\n".join(
+                f"- `{value}`"
+                for value in KnowledgeAction.choices()
+                if value.startswith("api_catalog_")
+            )
+        )
+
     async def _handle_help(self):
         workflow_guide = """
 ## 📖 How to find and read a document
@@ -1423,4 +1591,168 @@ def _format_marketplace_rule(rule: Dict[str, Any]) -> str:
     return "\n".join(lines)
 
 
+def _format_api_search_result(api: Dict[str, Any]) -> str:
+    """Format an API search result with similarity and matched endpoint."""
+    lines: List[str] = []
+
+    title = api.get("title", "Untitled API")
+    slug = api.get("slug", "")
+    similarity = api.get("similarity")
+
+    # Title with similarity
+    if similarity is not None:
+        pct = float(similarity) * 100
+        lines.append(f"🔗 **{title}** ({pct:.0f}% match)")
+    else:
+        lines.append(f"🔗 **{title}**")
+
+    lines.append(f"Slug: {slug}")
+
+    # Status
+    status = api.get("lifecycle_status", "unknown")
+    lines.append(f"Status: {status}")
+
+    # Description (truncated)
+    desc = api.get("description")
+    if desc:
+        truncated = desc[:150] + "..." if len(desc) > 150 else desc
+        lines.append(f"Description: {truncated}")
+
+    # Team info
+    team = api.get("team")
+    if isinstance(team, dict):
+        lines.append(f"Team: {team.get('name', 'Unknown')}")
+
+    # Matched endpoint (for semantic search)
+    matched = api.get("matchedEndpoint")
+    if matched:
+        method = matched.get("method", "").upper()
+        path = matched.get("path", "")
+        summary = matched.get("summary", "")
+        lines.append(f"Best match: **{method} {path}**")
+        if summary:
+            lines.append(f"  └─ {summary}")
+
+    # Current version
+    version = api.get("current_version")
+    if isinstance(version, dict):
+        lines.append(f"Version: {version.get('version', 'N/A')}")
+
+    return "\n".join(lines)
+
+
+def _format_api_item(api: Dict[str, Any]) -> str:
+    """Format an API item for listing."""
+    lines: List[str] = []
+
+    title = api.get("title", "Untitled API")
+    slug = api.get("slug", "")
+    status = api.get("lifecycle_status", "unknown")
+
+    lines.append(f"📦 **{title}**")
+    lines.append(f"ID: {api.get('id', 'N/A')}")
+    lines.append(f"Slug: {slug}")
+    lines.append(f"Status: {status}")
+
+    # Tags
+    tags = api.get("tags", [])
+    if tags:
+        lines.append(f"Tags: {', '.join(tags)}")
+
+    # Team
+    team = api.get("team")
+    if isinstance(team, dict):
+        lines.append(f"Team: {team.get('name', 'Unknown')}")
+
+    # Version
+    version = api.get("current_version")
+    if isinstance(version, dict):
+        lines.append(f"Version: {version.get('version', 'N/A')}")
+
+    return "\n".join(lines)
+
+
+def _format_api_detail(api: Dict[str, Any]) -> str:
+    """Format detailed API specification view."""
+    lines: List[str] = []
+
+    title = api.get("title", "Untitled API")
+    slug = api.get("slug", "")
+
+    lines.append(f"📚 **{title}**")
+    lines.append("")
+    lines.append(f"ID: {api.get('id', 'N/A')}")
+    lines.append(f"Slug: {slug}")
+    lines.append(f"Status: {api.get('lifecycle_status', 'unknown')}")
+
+    # Description
+    desc = api.get("description")
+    if desc:
+        lines.append("")
+        lines.append("**Description:**")
+        lines.append(desc)
+
+    # Tags
+    tags = api.get("tags", [])
+    if tags:
+        lines.append("")
+        lines.append(f"Tags: {', '.join(tags)}")
+
+    # Team
+    team = api.get("team")
+    if isinstance(team, dict):
+        lines.append(f"Team: {team.get('name', 'Unknown')}")
+
+    # Current version
+    version = api.get("current_version")
+    if isinstance(version, dict):
+        lines.append("")
+        lines.append("**Current Version:**")
+        lines.append(f"- Version: {version.get('version', 'N/A')}")
+        lines.append(f"- OpenAPI: {version.get('openapi_version', 'N/A')}")
+
+        # Endpoints from current version
+        endpoints = version.get("endpoint_embeddings", [])
+        if endpoints:
+            lines.append(f"- Endpoints: {len(endpoints)}")
+            lines.append("")
+            lines.append("**Endpoints:**")
+            for ep in endpoints[:10]:  # Limit to 10
+                method = ep.get("method", "").upper()
+                path = ep.get("path", "")
+                summary = ep.get("summary", "")
+                if summary:
+                    lines.append(f"- **{method}** {path} - {summary}")
+                else:
+                    lines.append(f"- **{method}** {path}")
+            if len(endpoints) > 10:
+                lines.append(f"  ... and {len(endpoints) - 10} more endpoints")
+
+    # Environments
+    environments = api.get("environments", [])
+    if environments:
+        lines.append("")
+        lines.append("**Environments:**")
+        for env in environments:
+            name = env.get("name", "Unnamed")
+            url = env.get("base_url", "")
+            lines.append(f"- {name}: {url}")
+
+    # Permissions
+    permissions = api.get("permissions", {})
+    if permissions:
+        lines.append("")
+        lines.append("**Your Permissions:**")
+        if permissions.get("canEdit"):
+            lines.append("- ✅ Edit")
+        if permissions.get("canDelete"):
+            lines.append("- ✅ Delete")
+        if permissions.get("canPublish"):
+            lines.append("- ✅ Publish")
+        if permissions.get("canManageVersions"):
+            lines.append("- ✅ Manage Versions")
+
+    return "\n".join(lines)
+
+
 __all__ = ["KnowledgeTool", "KnowledgeAction"]

fenix_mcp/domain/initialization.py

@@ -15,7 +15,7 @@ class InitializationData:
     profile: Optional[Dict[str, Any]]
     core_documents: List[Dict[str, Any]]
     user_documents: List[Dict[str, Any]]
-    recent_memories: List[Dict[str, Any]]
+    my_work_items: List[Dict[str, Any]]
 
 
 class InitializationService:
@@ -25,9 +25,7 @@ class InitializationService:
         self._api = api_client
         self._logger = logger
 
-    async def gather_data(
-        self, *, include_user_docs: bool, limit: int
-    ) -> InitializationData:
+    async def gather_data(self, *, include_user_docs: bool) -> InitializationData:
         profile = await self._safe_call(self._api.get_profile)
         core_docs = await self._safe_call(
             self._api.list_core_documents,
@@ -46,11 +44,19 @@ class InitializationService:
             )
             if self._logger:
                 self._logger.debug("User docs response", extra={"user_docs": user_docs})
+
+        # Fetch user's assigned work items for proactive context
+        work_items_response = await self._safe_call(
+            self._api.get_work_items_mine,
+            limit=10,
+        )
+        my_work_items = self._extract_items(work_items_response, "workItems")
+
         return InitializationData(
             profile=profile,
             core_documents=self._extract_items(core_docs, "coreDocuments"),
             user_documents=self._extract_items(user_docs, "userCoreDocuments"),
-            recent_memories=[],
+            my_work_items=my_work_items,
         )
 
     async def _safe_call(self, func, *args, **kwargs):
@@ -71,110 +77,3 @@ class InitializationService:
             if isinstance(value, list):
                 return [item for item in value if isinstance(item, dict)]
         return []
-
-    @staticmethod
-    def build_existing_user_summary(
-        data: InitializationData, include_user_docs: bool
-    ) -> str:
-        profile = data.profile or {}
-        user_info = profile.get("user") or {}
-        tenant_info = profile.get("tenant") or {}
-        core_count = len(data.core_documents)
-        user_count = len(data.user_documents)
-        memories_count = len(data.recent_memories)
-
-        lines = [
-            "✅ **Fênix Cloud inicializado com sucesso!**",
-        ]
-
-        if user_info:
-            lines.append(
-                f"- Usuário: {user_info.get('name') or 'Desconhecido'} "
-                f"(ID: {user_info.get('id', 'N/A')})"
-            )
-        if tenant_info:
-            lines.append(f"- Organização: {tenant_info.get('name', 'N/A')}")
-
-        lines.append(f"- Documentos principais carregados: {core_count}")
-
-        if include_user_docs:
-            lines.append(f"- Documentos pessoais carregados: {user_count}")
-
-        lines.append(f"- Memórias recentes disponíveis: {memories_count}")
-
-        if core_count:
-            preview = ", ".join(
-                doc.get("name", doc.get("title", "sem título"))
-                for doc in data.core_documents[:5]
-            )
-            lines.append(f"- Exemplos de documentos principais: {preview}")
-
-        if include_user_docs and user_count:
-            preview = ", ".join(
-                doc.get("name", "sem título") for doc in data.user_documents[:5]
-            )
-            lines.append(f"- Exemplos de documentos pessoais: {preview}")
-
-        if memories_count:
-            preview = ", ".join(
-                mem.get("title", "sem título") for mem in data.recent_memories[:3]
-            )
-            lines.append(f"- Memórias recentes: {preview}")
-
-        lines.append("")
-        lines.append(
-            "Agora você pode usar as ferramentas de produtividade, conhecimento e inteligência para continuar."
-        )
-        return "\n".join(lines)
-
-    @staticmethod
-    def build_new_user_prompt(data: InitializationData) -> str:
-        profile = data.profile or {}
-        user_name = (profile.get("user") or {}).get("name") or "Bem-vindo(a)"
-
-        questions = [
-            "Qual é o foco principal do seu trabalho atualmente?",
-            "Quais são seus objetivos para as próximas semanas?",
-            "Existem tarefas ou projetos que gostaria de priorizar?",
-            "Como você prefere organizar suas rotinas ou checklists?",
-            "Quais são os principais blocos de conhecimento que precisa acessar rapidamente?",
-            "Há regras ou procedimentos que precisam ser seguidos com frequência?",
-            "Que tipo de memória ou registro você consulta com frequência?",
-            "Quais ferramentas ou integrações externas são essenciais no seu dia a dia?",
-            "O que significaria sucesso para você utilizando o Fênix?",
-        ]
-
-        body = [
-            f"👋 **{user_name}, bem-vindo(a) ao Fênix Cloud!**",
-            "",
-            "Notamos que você ainda não tem documentos pessoais configurados. "
-            "Vamos criar uma experiência personalizada para você.",
-            "",
-            "Responda às perguntas abaixo para que possamos preparar modos, regras e documentos alinhados às suas necessidades:",
-            "",
-        ]
-
-        body.extend(f"{idx + 1}. {question}" for idx, question in enumerate(questions))
-        body.extend(
-            [
-                "",
-                "Envie as respostas no formato:",
-                "```",
-                'initialize action=setup answers=["resposta 1", "resposta 2", ..., "resposta 9"]',
-                "```",
-                "",
-                "Com base nisso, sugerirei documentos, regras e rotinas para você utilizar.",
-            ]
-        )
-
-        return "\n".join(body)
-
-    @staticmethod
-    def validate_setup_answers(answers: List[str]) -> Optional[str]:
-        if not answers:
-            return "Envie uma lista com 9 respostas para processarmos o setup."
-        if len(answers) != 9:
-            return f"Esperado receber 9 respostas, mas recebi {len(answers)}."
-        if not all(isinstance(answer, str) and answer.strip() for answer in answers):
-            return "Todas as respostas devem ser textos preenchidos."
-        return None