Wrap get_data_sources in {dataSources, hint} envelope; bump to 2.0.4

get_data_sources used to switch wire shapes between empty and non-empty
responses — a bare list when sources existed, a dict carrying a recovery
message when none did. Always returning {"dataSources": [...], "hint":
"..."} matches the convention search tools settled on, gives the model
guidance even when results are present, and removes the dual-shape edge
case for clients.

Drop the naive "no `, ` in text" compact-JSON assertion in the
get_data_sources e2e test — the new hint is plain English and trips it.
The round-trip equality against `json.dumps(..., ensure_ascii=False)`
already verifies both compactness and UTF-8.

Cover the two remaining serialization paths so future regressions get
caught: an XML-content Cyrillic test for fetch_artifacts and an
SSE-stream Cyrillic test for chat. Bump version triplet (pyproject /
manifest / server) to 2.0.4 — wire-format change for get_data_sources
plus the Unicode fixes from 2.0.3+1.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: rodion-m

manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.4",
   "name": "codealive-mcp",
   "display_name": "CodeAlive",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Semantic code search and codebase Q&A for Claude Desktop using your CodeAlive account or self-hosted deployment.",
   "long_description": "CodeAlive gives Claude Desktop access to semantic code search, artifact fetch, repository discovery, and architecture-aware codebase Q&A. This extension runs locally via MCP and supports both CodeAlive Cloud and self-hosted deployments.",
   "author": {

pyproject.toml

@@ -37,7 +37,7 @@ packages = ["src"]
 package-dir = {"" = "."}
 
 [tool.setuptools_scm]
-fallback_version = "2.0.3"
+fallback_version = "2.0.4"
 
 [tool.uv]
 # Relative dates in exclude-newer (e.g. "7 days") require uv ≥ 0.11.

server.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.CodeAlive-AI/codealive-mcp",
-  "version": "2.0.3",
+  "version": "2.0.4",
   "description": "Semantic code search and analysis from CodeAlive for AI assistants and agents.",
   "keywords": [
     "context-engineering",

src/tests/test_datasources.py

@@ -49,8 +49,10 @@ async def test_get_data_sources_removes_repository_ids_from_workspaces(mock_get_
 
     mock_ctx.request_context.lifespan_context = mock_lifespan_context
 
-    # Tool returns the parsed list directly; FastMCP serializes it.
-    data_sources = await get_data_sources(mock_ctx, alive_only=True)
+    # Tool returns a dict {"dataSources":[...], "hint":"..."}.
+    result = await get_data_sources(mock_ctx, alive_only=True)
+    data_sources = result["dataSources"]
+    assert "hint" in result
 
     # Verify repository still has all fields
     repo = next(ds for ds in data_sources if ds["type"] == "Repository")
@@ -112,7 +114,8 @@ async def test_get_data_sources_preserves_other_workspace_fields(mock_get_api_ke
 
     mock_ctx.request_context.lifespan_context = mock_lifespan_context
 
-    data_sources = await get_data_sources(mock_ctx, alive_only=True)
+    result = await get_data_sources(mock_ctx, alive_only=True)
+    data_sources = result["dataSources"]
 
     workspace = data_sources[0]
 
@@ -160,7 +163,8 @@ async def test_get_data_sources_handles_missing_repository_ids(mock_get_api_key)
     mock_ctx.request_context.lifespan_context = mock_lifespan_context
 
     # Should not raise an error
-    data_sources = await get_data_sources(mock_ctx, alive_only=True)
+    result = await get_data_sources(mock_ctx, alive_only=True)
+    data_sources = result["dataSources"]
 
     # Verify workspace is intact
     workspace = data_sources[0]

src/tests/test_e2e_tools.py

@@ -112,26 +112,28 @@ def handler(req):
             result = await client.call_tool("get_data_sources", {})
 
         text = _text(result)
-        # Compact JSON: no spaces after separators
-        assert ", " not in text and ": " not in text
         data = json.loads(text)
-        names = [ds["name"] for ds in data]
+        # Compact JSON, UTF-8 preserved (FastMCP uses pydantic_core.to_json).
+        assert text == json.dumps(data, separators=(",", ":"), ensure_ascii=False)
+        names = [ds["name"] for ds in data["dataSources"]]
         assert "backend" in names
         assert "platform" in names
         # repositoryIds must be stripped from workspaces
-        for ds in data:
+        for ds in data["dataSources"]:
             assert "repositoryIds" not in ds
+        # Always emit a follow-up hint pointing at search/chat tools.
+        assert "semantic_search" in data["hint"]
 
     @pytest.mark.asyncio
-    async def test_empty_list_returns_message(self):
+    async def test_empty_list_returns_recovery_hint(self):
         mcp = _server({"/api/datasources/ready": lambda r: httpx.Response(200, json=[])})
         async with Client(mcp) as client:
             result = await client.call_tool("get_data_sources", {})
 
         text = _text(result)
         data = json.loads(text)
         assert data["dataSources"] == []
-        assert "No data sources found" in data["message"]
+        assert "No data sources found" in data["hint"]
 
     @pytest.mark.asyncio
     async def test_unicode_preserved_in_response(self):
@@ -148,8 +150,9 @@ async def test_unicode_preserved_in_response(self):
         text = _text(result)
         # Round-trip via ensure_ascii=False — ASCII-escaped output would mismatch.
         assert text == json.dumps(json.loads(text), separators=(",", ":"), ensure_ascii=False)
-        assert "кирилл-репо" in text
-        assert "Описание про принтеры HPRT" in text
+        data = json.loads(text)
+        assert data["dataSources"][0]["name"] == "кирилл-репо"
+        assert data["dataSources"][0]["description"] == "Описание про принтеры HPRT"
         assert "\\u04" not in text
 
     @pytest.mark.asyncio
@@ -904,6 +907,31 @@ def handler(req):
         xml = _text(result)
         assert "<artifacts>" in xml
 
+    @pytest.mark.asyncio
+    async def test_unicode_preserved_in_xml(self):
+        """Cyrillic in identifier and content must survive into the XML output."""
+        payload = {
+            "artifacts": [
+                {
+                    "identifier": "org/repo::файл.cs::Класс.Метод",
+                    "content": "класс Привет {\n    метод() => 42\n}\n",
+                    "contentByteSize": 100,
+                    "startLine": 1,
+                }
+            ]
+        }
+        mcp = _server({"/api/search/artifacts": lambda r: httpx.Response(200, json=payload)})
+        async with Client(mcp) as client:
+            result = await client.call_tool(
+                "fetch_artifacts",
+                {"identifiers": ["org/repo::файл.cs::Класс.Метод"]},
+            )
+
+        xml = _text(result)
+        assert "Класс.Метод" in xml
+        assert "класс Привет" in xml
+        assert "\\u04" not in xml
+
 
 # ---------------------------------------------------------------------------
 # Stringified parameter coercion for search tools
@@ -1041,6 +1069,26 @@ async def test_backend_error_handled(self):
         text = _text(result)
         assert "401" in text or "auth" in text.lower()
 
+    @pytest.mark.asyncio
+    async def test_unicode_preserved_in_streamed_response(self):
+        """Cyrillic chunks streamed via SSE must survive as UTF-8 in the final text."""
+        body = self._sse_body(["Привет, ", "мир!"])
+
+        mcp = _server({
+            "/api/chat/completions": lambda r: httpx.Response(
+                200, text=body, headers={"content-type": "text/event-stream"},
+            ),
+        })
+        async with Client(mcp) as client:
+            result = await client.call_tool(
+                "chat",
+                {"question": "Как работает аутентификация?", "data_sources": ["backend"]},
+            )
+
+        text = _text(result)
+        assert "Привет, мир!" in text
+        assert "\\u04" not in text
+
     @pytest.mark.asyncio
     async def test_legacy_alias_still_works(self):
         body = self._sse_body(["Legacy alias"])

src/tools/datasources.py

@@ -1,6 +1,6 @@
 """Data sources tool implementation."""
 
-from typing import Any
+from typing import Any, Dict
 from urllib.parse import urljoin
 
 import httpx
@@ -12,8 +12,28 @@
 # MCP tool/method name surfaced in every error/log message from this module.
 _TOOL_NAME = "get_data_sources"
 
+# Hint embedded in every successful response. Mirrors the convention used by
+# the search tools (see _SEARCH_HINT in utils/response_transformer.py): the
+# response is always in front of the model when it picks the next step, so we
+# repeat the most load-bearing usage rule here instead of relying on the
+# tool's docstring being re-read mid-conversation.
+_DATASOURCES_HINT = (
+    "Use the `name` field as the `data_sources` parameter for `semantic_search`, "
+    "`grep_search`, or `chat`. To identify the CURRENT repository (vs external), "
+    "compare `name`/`description`/`url` against your working directory and the "
+    "code you've already observed."
+)
+
+_DATASOURCES_EMPTY_HINT = (
+    "No data sources found. Add a repository or workspace to CodeAlive at "
+    "https://app.codealive.ai before calling search or chat tools. If you "
+    "expected sources here, retry with alive_only=false to surface ones still "
+    "being indexed."
+)
+
+
 # alive_only refers to ready_only. leaved as is for backward compatibility.
-async def get_data_sources(ctx: Context, alive_only: bool = True) -> Any:
+async def get_data_sources(ctx: Context, alive_only: bool = True) -> Dict[str, Any]:
     """
     **CALL THIS FIRST**: Gets all available data sources (repositories and workspaces) for the user's account.
 
@@ -29,7 +49,9 @@ async def get_data_sources(ctx: Context, alive_only: bool = True) -> Any:
                     If False, returns all data sources regardless of processing state.
 
     Returns:
-        A compact JSON array of available data sources with the following fields for each:
+        {"dataSources": [...], "hint": "..."}
+
+        Each entry in `dataSources` carries:
         - id: Unique identifier for the data source
         - name: Human-readable name - CRITICAL for matching with current working directory name
         - description: Summary of codebase contents - CRITICAL for identifying if this matches your
@@ -38,6 +60,9 @@ async def get_data_sources(ctx: Context, alive_only: bool = True) -> Any:
         - url: Repository URL (for Repository type only) - useful for matching with git remote
         - state: The processing state of the data source (if alive_only=false)
 
+        The `hint` field reminds you how to use the result and how to distinguish
+        the CURRENT repository from EXTERNAL ones.
+
         Use name + description + url together to determine if a repository is the CURRENT one
         you're working in versus an EXTERNAL repository.
 
@@ -107,21 +132,16 @@ async def get_data_sources(ctx: Context, alive_only: bool = True) -> Any:
         # Parse and format the response
         data_sources = response.json()
 
-        # Empty result: return a dict carrying a recovery message instead of a bare
-        # list, so the LLM has guidance when nothing is indexed yet.
         if not data_sources or len(data_sources) == 0:
-            return {
-                "dataSources": [],
-                "message": "No data sources found. Please add a repository or workspace to CodeAlive before using this API.",
-            }
+            return {"dataSources": [], "hint": _DATASOURCES_EMPTY_HINT}
 
         # Remove repositoryIds from workspace data sources
         for data_source in data_sources:
             if data_source.get("type") == "Workspace" and "repositoryIds" in data_source:
                 del data_source["repositoryIds"]
 
         # FastMCP serializes via pydantic_core.to_json, which preserves UTF-8.
-        return data_sources
+        return {"dataSources": data_sources, "hint": _DATASOURCES_HINT}
 
     except (httpx.HTTPStatusError, Exception) as e:
         await handle_api_error(