allye-mcp 1.0.2__py3-none-any.whl

allye_mcp/__init__.py

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: 2024 Bruno Fernandes
+# SPDX-License-Identifier: MIT
+
+"""
+Fênix Cloud MCP Server (Python edition).
+"""
+
+__all__ = ["__version__"]
+
+
+__version__ = "1.0.2"

allye_mcp/application/formatters/__init__.py

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: MIT
+"""Formatter helpers extracted from legacy monolithic tool."""
+
+from __future__ import annotations
+
+from .api_catalog import _format_api_detail, _format_api_item, _format_api_search_result
+from .board import _format_board
+from .doc import (
+    _extract_name_count,
+    _format_doc,
+    _format_doc_analytics,
+    _format_doc_tree_flat,
+    _format_doc_tree_nested,
+)
+from .skill import (
+    _export_skill_format,
+    _export_skills_merged_format,
+    _format_marketplace_skill,
+    _format_skill,
+)
+from .sprint import _format_sprint
+from .work import _format_work
+
+__all__ = [
+    "_format_work",
+    "_format_board",
+    "_format_sprint",
+    "_format_doc",
+    "_format_doc_tree_flat",
+    "_format_doc_tree_nested",
+    "_extract_name_count",
+    "_format_doc_analytics",
+    "_format_skill",
+    "_format_marketplace_skill",
+    "_export_skill_format",
+    "_export_skills_merged_format",
+    "_format_api_search_result",
+    "_format_api_item",
+    "_format_api_detail",
+]

allye_mcp/application/formatters/api_catalog.py

@@ -0,0 +1,169 @@
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+
+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)

allye_mcp/application/formatters/board.py

@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+
+def _format_board(board: Dict[str, Any], header: Optional[str] = None) -> str:
+    lines: List[str] = []
+    if header:
+        lines.append(header)
+        lines.append("")
+    lines.extend(
+        [
+            f"🗂️ **{board.get('name', 'Unnamed')}**",
+            f"ID: {board.get('id', 'N/A')}",
+            f"Team: {board.get('team_id', 'N/A')}",
+            f"Columns: {len(board.get('columns', []))}",
+        ]
+    )
+    return "\n".join(lines)

allye_mcp/application/formatters/doc.py

@@ -0,0 +1,301 @@
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from allye_mcp.domain._service_base import _format_date
+
+
+def _format_doc_tree_flat(data: Any) -> str:
+    """Format a flat list of docs (with parent_id) into a visual tree."""
+    items: List[Dict[str, Any]] = []
+    if isinstance(data, list):
+        items = data
+    elif isinstance(data, dict):
+        nested = data.get("data") or data.get("children") or data.get("items")
+        if isinstance(nested, list):
+            items = nested
+        else:
+            # Single root dict — treat as nested tree
+            return _format_doc_tree_nested(data)
+
+    if not items:
+        return "(empty)"
+
+    # Build parent→children map
+    by_id: Dict[str, Dict[str, Any]] = {}
+    children_map: Dict[Optional[str], List[str]] = {}
+    for item in items:
+        item_id = item.get("id", "")
+        by_id[item_id] = item
+        parent = item.get("parent_id")
+        children_map.setdefault(parent, []).append(item_id)
+
+    # Find roots (parent_id is None or not present in by_id)
+    root_ids = [
+        item_id
+        for item_id, item in by_id.items()
+        if item.get("parent_id") is None or item.get("parent_id") not in by_id
+    ]
+
+    lines: List[str] = []
+
+    def _render_node(
+        item_id: str, prefix: str, connector: str, child_prefix: str
+    ) -> None:
+        item = by_id.get(item_id, {})
+        emoji = item.get("emoji") or item.get("emote") or ""
+        title = item.get("title") or item.get("name") or "Untitled"
+        doc_type = item.get("doc_type") or item.get("type") or ""
+        iid = item.get("id", "")
+
+        label = f"{emoji} {title}".strip()
+        if doc_type:
+            label += f" ({doc_type})"
+        label += f" — ID: {iid}"
+        lines.append(f"{prefix}{connector}{label}")
+
+        child_ids = children_map.get(item_id, [])
+        for i, cid in enumerate(child_ids):
+            is_last_child = i == len(child_ids) - 1
+            c = "└── " if is_last_child else "├── "
+            cp = child_prefix + ("    " if is_last_child else "│   ")
+            _render_node(cid, child_prefix, c, cp)
+
+    for i, rid in enumerate(root_ids):
+        _render_node(rid, "", "", "")
+        if i < len(root_ids) - 1:
+            lines.append("")
+
+    return "\n".join(lines)
+
+
+def _format_doc_tree_nested(data: Any) -> str:
+    """Format a nested dict with 'children' arrays into a visual tree."""
+    if not data:
+        return "(empty)"
+
+    # If data is a list, delegate to flat formatter
+    if isinstance(data, list):
+        return _format_doc_tree_flat(data)
+
+    if not isinstance(data, dict):
+        return "(empty)"
+
+    # Unwrap if the tree is inside a 'data', 'children', or 'items' key
+    # and the root dict itself has no 'title'/'id' (i.e., it's just a wrapper)
+    if not data.get("id") and not data.get("title"):
+        nested = data.get("data") or data.get("children") or data.get("items")
+        if isinstance(nested, list):
+            return _format_doc_tree_flat(nested)
+        if isinstance(nested, dict):
+            data = nested
+
+    if not data.get("id") and not data.get("title"):
+        return "(empty)"
+
+    lines: List[str] = []
+
+    def _render(
+        node: Dict[str, Any], prefix: str, connector: str, child_prefix: str
+    ) -> None:
+        emoji = node.get("emoji") or node.get("emote") or ""
+        title = node.get("title") or node.get("name") or "Untitled"
+        doc_type = node.get("doc_type") or node.get("type") or ""
+        iid = node.get("id", "")
+
+        label = f"{emoji} {title}".strip()
+        if doc_type:
+            label += f" ({doc_type})"
+        label += f" — ID: {iid}"
+        lines.append(f"{prefix}{connector}{label}")
+
+        children = node.get("children", [])
+        if isinstance(children, list):
+            valid = [c for c in children if isinstance(c, dict)]
+            for i, child in enumerate(valid):
+                is_last_child = i == len(valid) - 1
+                c = "└── " if is_last_child else "├── "
+                cp = child_prefix + ("    " if is_last_child else "│   ")
+                _render(child, child_prefix, c, cp)
+
+    _render(data, "", "", "")
+    return "\n".join(lines)
+
+
+def _extract_name_count(item: Dict[str, Any]) -> tuple[str, Any]:
+    """Extract a (name, count) pair from a Prisma groupBy-style dict.
+
+    Prisma groupBy returns fields like {doc_type: "page", _count: 5}
+    or {author_user_id: "uuid", _count: 3}.
+    """
+    # Try known count keys (Prisma uses _count)
+    count = None
+    for key in ("_count", "count", "total", "value"):
+        val = item.get(key)
+        if val is not None and isinstance(val, (int, float)):
+            count = val
+            break
+    # _count can also be a dict like {author_user_id: 3}
+    raw_count = item.get("_count")
+    if count is None and isinstance(raw_count, dict):
+        for v in raw_count.values():
+            if isinstance(v, (int, float)):
+                count = v
+                break
+
+    # Try known name keys
+    name = None
+    for key in (
+        "doc_type",
+        "type",
+        "name",
+        "author",
+        "author_user_id",
+        "label",
+        "title",
+    ):
+        val = item.get(key)
+        if val is not None and isinstance(val, str) and val:
+            name = val
+            break
+
+    # Fallback: first string value
+    if name is None:
+        for key, val in item.items():
+            if key.startswith("_"):
+                continue
+            if isinstance(val, str) and val:
+                name = val
+                break
+
+    return (name or "?", count if count is not None else "?")
+
+
+def _format_doc_analytics(analytics: Dict[str, Any]) -> str:
+    """Format doc analytics into a readable summary."""
+    lines = ["📊 **Documentation Analytics**", ""]
+
+    # Simple scalar fields
+    simple_keys = {
+        "total",
+        "published",
+        "drafts",
+        "inReview",
+        "in_review",
+        "archived",
+        "folders",
+        "pages",
+        "guides",
+    }
+    for key, value in analytics.items():
+        if key in simple_keys and not isinstance(value, (dict, list)):
+            lines.append(f"- **{key}**: {value}")
+
+    # byType
+    by_type = analytics.get("byType")
+    if by_type is None:
+        by_type = analytics.get("by_type")
+    if isinstance(by_type, dict):
+        parts = [f"{k}: {v}" for k, v in by_type.items()]
+        if parts:
+            lines.append(f"- **By type**: {', '.join(parts)}")
+    elif isinstance(by_type, list):
+        parts = []
+        for item in by_type:
+            if isinstance(item, dict):
+                name, count = _extract_name_count(item)
+                parts.append(f"{name}: {count}")
+        if parts:
+            lines.append(f"- **By type**: {', '.join(parts)}")
+
+    # byAuthor
+    by_author = analytics.get("byAuthor")
+    if by_author is None:
+        by_author = analytics.get("by_author")
+    if isinstance(by_author, list):
+        author_parts = []
+        for item in by_author:
+            if isinstance(item, dict):
+                # Prisma groupBy returns {author_user_id, _count}
+                # Try nested author object first, then fall back to ID
+                author_obj = item.get("author")
+                if isinstance(author_obj, dict):
+                    name = author_obj.get("name") or author_obj.get("email") or "?"
+                else:
+                    uid = item.get("author_user_id") or ""
+                    name = uid[:8] + "…" if len(uid) > 8 else uid or "?"
+                _, count = _extract_name_count(item)
+                author_parts.append(f"{name} ({count})")
+        if author_parts:
+            lines.append("")
+            lines.append("**By author:**")
+            for part in author_parts[:10]:
+                lines.append(f"- {part}")
+            if len(author_parts) > 10:
+                lines.append(f"  ... and {len(author_parts) - 10} more")
+
+    # recentlyUpdated
+    recent = analytics.get("recentlyUpdated")
+    if recent is None:
+        recent = analytics.get("recently_updated")
+    if isinstance(recent, list) and recent:
+        lines.append("")
+        lines.append("**Recently updated:**")
+        for item in recent[:10]:
+            if isinstance(item, dict):
+                emoji = item.get("emoji") or item.get("emote") or ""
+                title = item.get("title") or item.get("name") or "Untitled"
+                updated = _format_date(item.get("updated_at") or item.get("updatedAt"))
+                label = f"{emoji} {title}".strip()
+                lines.append(f"- {label} ({updated})")
+        if len(recent) > 10:
+            lines.append(f"  ... and {len(recent) - 10} more")
+
+    # Catch any remaining keys not yet handled
+    handled = simple_keys | {
+        "byType",
+        "by_type",
+        "byAuthor",
+        "by_author",
+        "recentlyUpdated",
+        "recently_updated",
+    }
+    for key, value in analytics.items():
+        if key not in handled and not isinstance(value, (dict, list)):
+            lines.append(f"- **{key}**: {value}")
+
+    return "\n".join(lines)
+
+
+def _format_doc(
+    doc: Dict[str, Any],
+    *,
+    header: Optional[str] = None,
+    show_content: bool = False,
+) -> str:
+    lines: List[str] = []
+    if header:
+        lines.append(header)
+        lines.append("")
+    lines.extend(
+        [
+            f"📄 **{doc.get('title') or doc.get('name', 'Untitled')}**",
+            f"ID: {doc.get('id', 'N/A')}",
+            f"Status: {doc.get('status', 'N/A')}",
+            f"Team: {doc.get('team_id', 'N/A')}",
+        ]
+    )
+    if doc.get("updated_at") or doc.get("updatedAt"):
+        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(str(doc.get("content") or ""))
+
+    return "\n".join(lines)