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

fenix_mcp/__init__.py

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

fenix_mcp/application/tools/initialize.py

@@ -5,7 +5,6 @@ from __future__ import annotations
 
 import json
 from enum import Enum
-from typing import List, Optional
 
 from pydantic import Field
 
@@ -17,26 +16,13 @@ from fenix_mcp.infrastructure.context import AppContext
 
 class InitializeAction(str, Enum):
     INIT = "init"
-    SETUP = "setup"
 
 
 class InitializeRequest(ToolRequest):
     action: InitializeAction = Field(description="Initialization operation to execute.")
     include_user_docs: bool = Field(
         default=True,
-        description=(
-            "Include personal documents during initialization (only for init action)."
-        ),
-    )
-    limit: int = Field(
-        default=50,
-        ge=1,
-        le=200,
-        description=("Maximum number of core/personal documents to load."),
-    )
-    answers: Optional[List[str]] = Field(
-        default=None,
-        description=("List of 9 text answers to process the personalized setup."),
+        description=("Include personal documents during initialization."),
     )
 
 
@@ -54,15 +40,12 @@ class InitializeTool(Tool):
     async def run(self, payload: InitializeRequest, context: AppContext):
         if payload.action is InitializeAction.INIT:
             return await self._handle_init(payload)
-        if payload.action is InitializeAction.SETUP:
-            return await self._handle_setup(payload)
         return text("❌ Unknown initialization action.")
 
     async def _handle_init(self, payload: InitializeRequest):
         try:
             data = await self._service.gather_data(
                 include_user_docs=payload.include_user_docs,
-                limit=payload.limit,
             )
         except Exception as exc:  # pragma: no cover - defensive
             self._context.logger.error("Initialize failed: %s", exc)
@@ -77,16 +60,30 @@ class InitializeTool(Tool):
             and not data.profile
         ):
             return text(
-                "⚠️ Could not load documents or profile. Confirm the token and, if this is your first access, use `initialize action=setup` to answer the initial questionnaire."
+                "⚠️ Could not load documents or profile. Confirm the token has API access."
             )
 
         payload_dict = {
             "profile": data.profile,
             "core_documents": data.core_documents,
             "user_documents": data.user_documents if payload.include_user_docs else [],
+            "my_work_items": [
+                {
+                    "id": item.get("id"),
+                    "key": item.get("key"),
+                    "title": item.get("title"),
+                    "item_type": item.get("item_type"),
+                    "status": (
+                        item.get("status", {}).get("name")
+                        if isinstance(item.get("status"), dict)
+                        else item.get("status")
+                    ),
+                    "priority": item.get("priority"),
+                    "due_date": item.get("due_date"),
+                }
+                for item in data.my_work_items
+            ],
         }
-        if data.recent_memories:
-            payload_dict["recent_memories"] = data.recent_memories
 
         # Extract key IDs for easy reference
         profile = data.profile or {}
@@ -116,14 +113,6 @@ class InitializeTool(Tool):
             "```",
         ]
 
-        if payload.include_user_docs and not data.user_documents and data.profile:
-            message_lines.extend(
-                [
-                    "",
-                    self._service.build_new_user_prompt(data),
-                ]
-            )
-
         # Add memory usage instructions
         message_lines.extend(
             [
@@ -144,30 +133,3 @@ class InitializeTool(Tool):
         )
 
         return text("\n".join(message_lines))
-
-    async def _handle_setup(self, payload: InitializeRequest):
-        answers = payload.answers or []
-        validation_error = self._service.validate_setup_answers(answers)
-        if validation_error:
-            return text(f"❌ {validation_error}")
-
-        summary_lines = [
-            "📝 **Personalized setup received!**",
-            "",
-            "Your answers have been registered. I will suggest documents, rules and routines based on this information.",
-            "",
-            "Answer summary:",
-        ]
-        for idx, answer in enumerate(answers, start=1):
-            summary_lines.append(f"{idx}. {answer.strip()}")
-
-        summary_lines.extend(
-            [
-                "",
-                "You can now request specific content, for example:",
-                "- `productivity action=todo_create ...`",
-                "- `knowledge action=mode_list`",
-            ]
-        )
-
-        return text("\n".join(summary_lines))

fenix_mcp/application/tools/intelligence.py

@@ -1,18 +1,16 @@
 # SPDX-License-Identifier: MIT
-"""Intelligence tool implementation (memories and smart operations)."""
+"""Intelligence tool implementation (memories)."""
 
 from __future__ import annotations
 
 from enum import Enum
-from typing import Any, Dict, List, Optional
+from typing import Any, List, Optional
 
 from pydantic import Field, field_validator
 
 from fenix_mcp.application.presenters import text
 from fenix_mcp.application.tool_base import (
     MERMAID_HINT,
-    CategoryStr,
-    DateTimeStr,
     MarkdownStr,
     TagStr,
     TitleStr,
@@ -20,7 +18,7 @@ from fenix_mcp.application.tool_base import (
     ToolRequest,
     UUIDStr,
 )
-from fenix_mcp.domain.intelligence import IntelligenceService, build_metadata
+from fenix_mcp.domain.intelligence import IntelligenceService
 from fenix_mcp.infrastructure.context import AppContext
 
 
@@ -31,73 +29,73 @@ class IntelligenceAction(str, Enum):
         obj.description = description
         return obj
 
-    SMART_CREATE = (
-        "memory_smart_create",
-        "Creates intelligent memories with similarity analysis.",
+    SAVE = (
+        "memory_save",
+        "INTELLIGENT save with automatic deduplication using AI embeddings. "
+        "If similar memory exists (>80% semantic match): UPDATES existing memory (prevents duplicates). "
+        "If no match found: CREATES new memory. "
+        "REQUIRED: title, content (Markdown), tags (array, min 1). "
+        "OPTIONAL: documentation_item_id, work_item_id, sprint_id (link to entities). "
+        "EXAMPLES of what to save: architecture decisions, solutions found, user preferences, learnings.",
     )
-    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",
-        "Consolidates multiple memories into a primary one.",
+
+    SEARCH = (
+        "memory_search",
+        "Semantic search using AI embeddings - NOT keyword matching. "
+        "CALL THIS AT CONVERSATION START to recover context from previous sessions. "
+        "REQUIRED: query (natural language, e.g., 'authentication decisions', 'database choices'). "
+        "OPTIONAL: limit (1-20, default 5), tags (filter). "
+        "RETURNS: Memories ranked by semantic similarity with scores. "
+        "EXAMPLE: 'what did we decide about the API?' finds related memories even without exact words.",
     )
-    UPDATE = ("memory_update", "Updates fields of an existing memory.")
-    DELETE = ("memory_delete", "Removes a memory by ID.")
-    HELP = ("memory_help", "Shows supported actions and their uses.")
 
     @classmethod
     def choices(cls) -> List[str]:
         return [member.value for member in cls]
 
-    @classmethod
-    def formatted_help(cls) -> str:
-        lines = [
-            "| **Action** | **Description** |",
-            "| --- | --- |",
-        ]
-        for member in cls:
-            lines.append(f"| `{member.value}` | {member.description} |")
-        return "\n".join(lines)
-
-
-ACTION_FIELD_DESCRIPTION = (
-    "Intelligence action to execute. Use one of the values: "
-    + ", ".join(
-        f"`{member.value}` ({member.description.rstrip('.')})."
-        for member in IntelligenceAction
-    )
+
+ACTION_FIELD_DESCRIPTION = "Memory action to execute. " + " | ".join(
+    f"`{member.value}`: {member.description.split('.')[0]}."
+    for member in IntelligenceAction
 )
 
 
 class IntelligenceRequest(ToolRequest):
     action: IntelligenceAction = Field(description=ACTION_FIELD_DESCRIPTION)
-    title: Optional[TitleStr] = Field(default=None, description="Memory title.")
-    content: Optional[MarkdownStr] = Field(
-        default=None, description=f"Memory content/text (Markdown).{MERMAID_HINT}"
+
+    # For memory_save
+    title: Optional[TitleStr] = Field(
+        default=None, description="Memory title. REQUIRED for memory_save."
     )
-    metadata: Optional[MarkdownStr] = Field(
+    content: Optional[MarkdownStr] = Field(
         default=None,
-        description="Structured memory metadata (pipe format, compact toml, etc.).",
+        description=f"Memory content (Markdown supported).{MERMAID_HINT} REQUIRED for memory_save.",
     )
-    context: Optional[str] = Field(default=None, description="Additional context.")
-    source: Optional[str] = Field(default=None, description="Memory source.")
-    importance: Optional[str] = Field(
+    tags: Optional[List[TagStr]] = Field(
         default=None,
-        description="Memory importance level (low, medium, high, critical).",
+        description='Tags for categorization. REQUIRED for memory_save. Format: JSON array, e.g.: ["tag1", "tag2"].',
+        json_schema_extra={"example": ["tag1", "tag2", "tag3"]},
     )
-    include_content: bool = Field(
-        default=False,
-        description="Return full memory content? Set true to include the full text.",
+    documentation_item_id: Optional[UUIDStr] = Field(
+        default=None, description="Link memory to a documentation item (UUID)."
     )
-    include_metadata: bool = Field(
-        default=False,
-        description="Return full memory metadata? Set true to include the raw field.",
+    work_item_id: Optional[UUIDStr] = Field(
+        default=None, description="Link memory to a work item (UUID)."
     )
-    tags: Optional[List[TagStr]] = Field(
+    sprint_id: Optional[UUIDStr] = Field(
+        default=None, description="Link memory to a sprint (UUID)."
+    )
+
+    # For memory_search
+    query: Optional[str] = Field(
         default=None,
-        description='Memory tags. REQUIRED for create. Format: JSON array of strings, e.g.: ["tag1", "tag2"]. Do not use a single string.',
-        json_schema_extra={"example": ["tag1", "tag2", "tag3"]},
+        description="Search query (natural language). REQUIRED for memory_search.",
+    )
+    limit: int = Field(
+        default=5,
+        ge=1,
+        le=20,
+        description="Maximum number of results to return. Default: 5.",
     )
 
     @field_validator("tags", mode="before")
@@ -107,11 +105,9 @@ class IntelligenceRequest(ToolRequest):
         if v is None or v == "":
             return None
 
-        # If it's already a list, return as is
         if isinstance(v, (list, tuple, set)):
             return [str(item).strip() for item in v if str(item).strip()]
 
-        # If it's a string, try to parse as JSON
         if isinstance(v, str):
             try:
                 import json
@@ -121,64 +117,32 @@ class IntelligenceRequest(ToolRequest):
                     return [str(item).strip() for item in parsed if str(item).strip()]
             except (json.JSONDecodeError, TypeError):
                 pass
-
-            # If JSON parsing fails, treat as comma-separated string
             return [item.strip() for item in v.split(",") if item.strip()]
 
-        # For any other type, convert to string and wrap in list
         return [str(v).strip()] if str(v).strip() else None
 
-    limit: int = Field(default=20, ge=1, le=100, description="Result limit.")
-    offset: int = Field(default=0, ge=0, description="Pagination offset.")
-    query: Optional[str] = Field(default=None, description="Search term.")
-    category: Optional[CategoryStr] = Field(
-        default=None, description="Category for filtering."
-    )
-    date_from: Optional[DateTimeStr] = Field(
-        default=None, description="Start date filter (ISO 8601)."
-    )
-    date_to: Optional[DateTimeStr] = Field(
-        default=None, description="End date filter (ISO 8601)."
-    )
-    threshold: float = Field(
-        default=0.8, ge=0, le=1, description="Minimum similarity threshold."
-    )
-    max_results: int = Field(
-        default=5, ge=1, le=20, description="Maximum similar memories."
-    )
-    memory_ids: Optional[List[UUIDStr]] = Field(
-        default=None, description="Memory IDs for consolidation (UUIDs)."
-    )
-    strategy: str = Field(default="merge", description="Consolidation strategy.")
-    time_range: str = Field(default="month", description="Time window for analytics.")
-    group_by: str = Field(default="category", description="Grouping for analytics.")
-    id: Optional[UUIDStr] = Field(default=None, description="Memory ID (UUID).")
-    documentation_item_id: Optional[UUIDStr] = Field(
-        default=None, description="Related documentation ID (UUID)."
-    )
-    mode_id: Optional[UUIDStr] = Field(
-        default=None, description="Related mode ID (UUID)."
-    )
-    rule_id: Optional[UUIDStr] = Field(
-        default=None, description="Related rule ID (UUID)."
-    )
-    work_item_id: Optional[UUIDStr] = Field(
-        default=None, description="Related work item ID (UUID)."
-    )
-    sprint_id: Optional[UUIDStr] = Field(
-        default=None, description="Related sprint ID (UUID)."
-    )
-
 
 class IntelligenceTool(Tool):
     name = "intelligence"
-    description = (
-        "Fenix persistent memory system for cross-session continuity. "
-        "RECOMMENDED USAGE: "
-        "(1) Call memory_query at the START of conversations to retrieve relevant context from previous sessions. "
-        "(2) Call memory_smart_create to save important information, decisions, user preferences, and learnings. "
-        "This enables personalized responses and prevents users from repeating themselves."
-    )
+    description = """Fenix INTELLIGENT memory system with semantic understanding (uses AI embeddings, not keyword matching).
+
+**memory_search** - CALL AT CONVERSATION START
+- Uses AI embeddings for semantic similarity
+- "what did we decide about auth?" finds related memories even without exact keywords
+- Returns ranked results with similarity scores
+- BEST PRACTICE: Always search before asking user to repeat context
+
+**memory_save** - SMART SAVE with auto-deduplication
+- Automatically detects similar existing memories via embeddings
+- If >80% similar memory exists: UPDATES it (prevents duplicates)
+- If no match: Creates new memory
+- Requires: title, content, tags (at least one)
+
+WORKFLOW:
+1. START of conversation -> memory_search for relevant context
+2. User shares decision/learning -> memory_save to persist
+3. Similar topic later -> memory_search finds it automatically
+"""
     request_model = IntelligenceRequest
 
     def __init__(self, context: AppContext):
@@ -187,222 +151,84 @@ class IntelligenceTool(Tool):
 
     async def run(self, payload: IntelligenceRequest, context: AppContext):
         action = payload.action
-        if action is IntelligenceAction.HELP:
-            return await self._handle_help()
-        if action is IntelligenceAction.SMART_CREATE:
-            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:
-            return await self._handle_consolidate(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(
-            "❌ Invalid action for intelligence.\n\nChoose one of the values:\n"
-            + "\n".join(f"- `{value}`" for value in IntelligenceAction.choices())
-        )
 
-    async def _handle_smart_create(self, payload: IntelligenceRequest):
-        if not payload.title or not payload.content:
-            return text("❌ Provide title and content to create a memory.")
+        if action is IntelligenceAction.SAVE:
+            return await self._handle_save(payload)
 
-        if not payload.metadata or not payload.metadata.strip():
-            return text("❌ Provide metadata to create a memory.")
+        if action is IntelligenceAction.SEARCH:
+            return await self._handle_search(payload)
 
-        if not payload.source or not payload.source.strip():
-            return text("❌ Provide source to create a memory.")
+        return text(
+            "Invalid action. Use: "
+            + ", ".join(f"`{v}`" for v in IntelligenceAction.choices())
+        )
 
-        try:
-            normalized_tags = _ensure_tag_sequence(payload.tags)
-        except ValueError as exc:
-            return text(f"❌ {exc}")
+    async def _handle_save(self, payload: IntelligenceRequest):
+        """Save a memory (create or update based on similarity)."""
+        if not payload.title:
+            return text("Provide `title` to save a memory.")
+
+        if not payload.content:
+            return text("Provide `content` to save a memory.")
 
-        if not normalized_tags or len(normalized_tags) == 0:
-            return text("❌ Provide tags to create a memory.")
+        tags = payload.tags
+        if not tags or len(tags) == 0:
+            return text("Provide `tags` to save a memory (at least one required).")
 
-        memory = await self._service.smart_create_memory(
+        result = await self._service.save_memory(
             title=payload.title,
             content=payload.content,
-            metadata=payload.metadata,
-            context=payload.context,
-            source=payload.source,
-            importance=payload.importance,
-            tags=normalized_tags,
+            tags=tags,
+            documentation_item_id=payload.documentation_item_id,
+            work_item_id=payload.work_item_id,
+            sprint_id=payload.sprint_id,
         )
-        lines = [
-            "🧠 **Memory created successfully!**",
-            f"ID: {memory.get('memoryId') or memory.get('id', 'N/A')}",
-            f"Action: {memory.get('action') or 'created'}",
-            f"Similarity: {format_percentage(memory.get('similarity'))}",
-            f"Tags: {', '.join(memory.get('tags', [])) or 'Automatic'}",
-            f"Category: {memory.get('category') or 'Automatic'}",
-        ]
-        return text("\n".join(lines))
 
-    async def _handle_query(self, payload: IntelligenceRequest):
-        memories = await self._service.query_memories(
-            limit=payload.limit,
-            offset=payload.offset,
+        action = result.get("action", "saved")
+        memory_id = result.get("memoryId", "N/A")
+        title = result.get("title", payload.title)
+        version = result.get("version", 1)
+        similarity = result.get("similarity")
+
+        if action == "updated":
+            similarity_str = f"{similarity * 100:.0f}%" if similarity else "N/A"
+            return text(
+                f"Memory updated (similarity: {similarity_str})\n"
+                f"ID: {memory_id}\n"
+                f"Title: {title}\n"
+                f"Version: {version}"
+            )
+        else:
+            return text(f"Memory created\nID: {memory_id}\nTitle: {title}")
+
+    async def _handle_search(self, payload: IntelligenceRequest):
+        """Search memories using semantic similarity."""
+        if not payload.query:
+            return text("Provide `query` to search memories.")
+
+        memories = await self._service.search_memories(
             query=payload.query,
+            limit=payload.limit,
             tags=payload.tags,
-            include_content=payload.include_content,
-            include_metadata=payload.include_metadata,
-            modeId=payload.mode_id,
-            ruleId=payload.rule_id,
-            workItemId=payload.work_item_id,
-            sprintId=payload.sprint_id,
-            documentationItemId=payload.documentation_item_id,
-            category=payload.category,
-            dateFrom=payload.date_from,
-            dateTo=payload.date_to,
-            importance=payload.importance,
-        )
-        if not memories:
-            return text("🧠 No memories found.")
-        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.")
-        memories = await self._service.similar_memories(
-            content=payload.content,
-            threshold=payload.threshold,
-            max_results=payload.max_results,
-        )
         if not memories:
-            return text("🔍 No similar memories found.")
-        body = "\n\n".join(
-            f"🔍 **{mem.get('title', 'Untitled')}**\n   Similarity: {format_percentage(mem.get('finalScore'))}\n   ID: {mem.get('memoryId', 'N/A')}"
-            for mem in memories
-        )
-        return text(f"🔍 **Similar memories ({len(memories)}):**\n\n{body}")
-
-    async def _handle_consolidate(self, payload: IntelligenceRequest):
-        if not payload.memory_ids or len(payload.memory_ids) < 2:
-            return text("❌ Provide at least 2 memory IDs to consolidate.")
-        result = await self._service.consolidate_memories(
-            memory_ids=payload.memory_ids,
-            strategy=payload.strategy,
-        )
-        lines = [
-            "🔄 **Consolidation complete!**",
-            f"Primary memory: {result.get('primary_memory_id', 'N/A')}",
-            f"Consolidated: {result.get('consolidated_count', 'N/A')}",
-            f"Action executed: {result.get('action', 'N/A')}",
-        ]
-        return text("\n".join(lines))
+            return text("No memories found matching your query.")
 
-    async def _handle_update(self, payload: IntelligenceRequest):
-        if not payload.id:
-            return text("❌ Provide the memory ID for update.")
-        existing = await self._service.get_memory(
-            payload.id, include_content=False, include_metadata=True
-        )
-        try:
-            normalized_tags = _ensure_tag_sequence(payload.tags)
-        except ValueError as exc:
-            return text(f"❌ {exc}")
-        metadata = build_metadata(
-            payload.metadata,
-            importance=payload.importance,
-            tags=normalized_tags,
-            source=payload.source,
-            existing=existing.get("metadata") if isinstance(existing, dict) else None,
-        )
-        update_fields: Dict[str, Any] = {
-            "title": payload.title,
-            "content": payload.content,
-            "metadata": metadata,
-            "tags": normalized_tags,
-            "documentation_item_id": payload.documentation_item_id,
-            "mode_id": payload.mode_id,
-            "rule_id": payload.rule_id,
-            "work_item_id": payload.work_item_id,
-            "sprint_id": payload.sprint_id,
-            "importance": payload.importance,
-        }
-        memory = await self._service.update_memory(payload.id, **update_fields)
-        return text(
-            "\n".join(
-                [
-                    "✅ **Memory updated!**",
-                    f"ID: {memory.get('id', payload.id)}",
-                    f"Title: {memory.get('title', 'N/A')}",
-                    f"Priority: {memory.get('priority_score', 'N/A')}",
-                ]
-            )
-        )
+        lines = [f"Found {len(memories)} relevant memories:\n"]
 
-    async def _handle_delete(self, payload: IntelligenceRequest):
-        if not payload.id:
-            return text("❌ Provide the memory ID to remove.")
-        await self._service.delete_memory(payload.id)
-        return text(f"🗑️ Memory {payload.id} removed successfully.")
+        for mem in memories:
+            similarity = mem.get("similarity")
+            similarity_str = f" ({similarity * 100:.0f}% match)" if similarity else ""
 
-    async def _handle_help(self):
-        return text(
-            "📚 **Available actions for intelligence**\n\n"
-            + IntelligenceAction.formatted_help()
-        )
+            lines.append(f"### {mem.get('title', 'Untitled')}{similarity_str}")
+            lines.append(f"ID: {mem.get('id', 'N/A')}")
+            lines.append(f"Tags: {', '.join(mem.get('tags', []))}")
 
+            content = mem.get("content", "")
+            if content:
+                lines.append(f"\n{content}")
 
-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:
-    if value is None:
-        return "N/A"
-    return f"{value * 100:.1f}%"
-
-
-def _ensure_tag_sequence(raw: Optional[Any]) -> Optional[List[str]]:
-    if raw is None or raw == "":
-        return None
-    if isinstance(raw, (list, tuple, set)):
-        result = [str(item).strip() for item in raw if str(item).strip()]
-        return result or None
-    if isinstance(raw, str):
-        # Try to parse as JSON array first
-        try:
-            import json
-
-            parsed = json.loads(raw)
-            if isinstance(parsed, list):
-                result = [str(item).strip() for item in parsed if str(item).strip()]
-                return result or None
-        except (json.JSONDecodeError, TypeError):
-            pass
-
-        raise ValueError(
-            "The `tags` field must be sent as a JSON array, for example: "
-            '["tag1", "tag2"].'
-        )
-    return [str(raw).strip()]
+            lines.append("\n---\n")
+
+        return text("\n".join(lines))