Add fetch_artifacts tool and replace include_content with description_detail (v0.5.0)

New fetch_artifacts tool retrieves full source code for search results by identifier.
Search now returns descriptions and content sizes instead of inline content.
Bump version to 0.5.0.

Author: IvanBiruk

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codealive-mcp"
-version = "0.4.7"
+version = "0.5.0"
 description = "MCP server for the CodeAlive API"
 readme = "README.md"
 requires-python = ">=3.11"

smoke_test.py

@@ -133,7 +133,7 @@ async def test_list_tools(self) -> bool:
             result = await self.session.list_tools()
             tools = result.tools
 
-            expected_tools = {"codebase_consultant", "get_data_sources", "codebase_search"}
+            expected_tools = {"codebase_consultant", "get_data_sources", "codebase_search", "fetch_artifacts"}
             actual_tools = {tool.name for tool in tools}
 
             if expected_tools == actual_tools:
@@ -187,7 +187,7 @@ async def test_codebase_search(self) -> bool:
                 "query": "test query",
                 "data_sources": ["test-repo"],
                 "mode": "auto",
-                "include_content": False
+                "description_detail": "short"
             })
 
             if result.isError:
@@ -248,7 +248,7 @@ async def test_parameter_validation(self) -> bool:
                 "query": "",  # Empty query should fail
                 "data_sources": ["test"],
                 "mode": "auto",
-                "include_content": False
+                "description_detail": "short"
             })
 
             # Should get an error about empty query

src/codealive_mcp_server.py

@@ -26,7 +26,7 @@
 # Import core components
 from core import codealive_lifespan, setup_debug_logging
 from middleware import N8NRemoveParametersMiddleware
-from tools import codebase_consultant, get_data_sources, codebase_search
+from tools import codebase_consultant, get_data_sources, fetch_artifacts, codebase_search
 
 # Initialize FastMCP server with lifespan and enhanced system instructions
 mcp = FastMCP(
@@ -41,36 +41,23 @@
     - Answer questions about code implementation details
     - Integrate with local git repositories for seamless code exploration
 
-    When working with a codebase:
+    When working with a codebase, follow this workflow:
     1. First use `get_data_sources` to identify available repositories and workspaces
-    2. Then use `codebase_search` to find relevant files and code snippets
-    3. Finally, use `chat_completions` for in-depth analysis of the code
+    2. Use `codebase_search` to find relevant files — returns paths, descriptions, and identifiers
+    3. To get full content:
+       - For repos in your working directory: use `Read()` on the local files
+       - For external repos: use `fetch_artifacts` with identifiers from search results
+    4. Use `codebase_consultant` for in-depth analysis and synthesized answers
 
     For effective code exploration:
     - Start with broad queries to understand the overall structure
     - Use specific function/class names when looking for particular implementations
     - Combine natural language with code patterns in your queries
     - Always use "auto" search mode by default; it intelligently selects the appropriate search depth
     - IMPORTANT: Only use "deep" search mode for very complex conceptual queries as it's resource-intensive
+    - Use `description_detail="full"` in search when you need richer descriptions before fetching content
     - Remember that context from previous messages is maintained in the same conversation
 
-    CRITICAL - include_content parameter usage:
-    You MUST intelligently determine if searching CURRENT or EXTERNAL repositories:
-
-    - CURRENT repository (user's working directory): include_content=false
-      * You have file access → Get paths from search, then use Read tool for latest content
-    - EXTERNAL repositories (not in working directory): include_content=true
-      * No file access → Must include content in search results
-
-    Use these heuristics to identify CURRENT vs EXTERNAL (combine multiple signals):
-    1. Repository/directory name matching (e.g., working in "my-app", repo named "my-app")
-    2. Description matching observed codebase (tech stack, architecture, features)
-    3. User's language ("this repo", "our code" = CURRENT; "the X service" = EXTERNAL)
-    4. URL matching with git remote (when available)
-    5. Working context (files you've been reading/editing match this repo)
-
-    When uncertain, use context: Is user asking about their current work or a different service?
-
     Flexible data source usage:
     - You can use a workspace name as a single data source to search or chat across all its repositories at once
     - Alternatively, you can use specific repository names for more targeted searches
@@ -111,6 +98,7 @@ async def health_check(request: Request) -> JSONResponse:
 mcp.tool()(codebase_consultant)
 mcp.tool()(get_data_sources)
 mcp.tool()(codebase_search)
+mcp.tool()(fetch_artifacts)
 
 
 def main():

src/tests/test_fetch_artifacts.py

@@ -0,0 +1,210 @@
+"""Test suite for fetch_artifacts tool."""
+
+import pytest
+from unittest.mock import AsyncMock, MagicMock, patch
+from fastmcp import Context
+from tools.fetch_artifacts import fetch_artifacts
+
+
+@pytest.mark.asyncio
+@patch('tools.fetch_artifacts.get_api_key_from_context')
+async def test_fetch_artifacts_returns_xml(mock_get_api_key):
+    """Test that fetch_artifacts returns properly formatted XML."""
+    mock_get_api_key.return_value = "test_key"
+
+    ctx = MagicMock(spec=Context)
+    ctx.info = AsyncMock()
+    ctx.warning = AsyncMock()
+    ctx.error = AsyncMock()
+
+    mock_response = MagicMock()
+    mock_response.json.return_value = {
+        "artifacts": [
+            {
+                "identifier": "owner/repo::src/auth.py::login",
+                "content": "def login(user, pwd):\n    return True",
+                "contentByteSize": 38
+            },
+            {
+                "identifier": "owner/repo::src/missing.py::func",
+                "content": None,
+                "contentByteSize": None
+            }
+        ]
+    }
+    mock_response.raise_for_status = MagicMock()
+
+    mock_client = AsyncMock()
+    mock_client.post.return_value = mock_response
+
+    mock_codealive_context = MagicMock()
+    mock_codealive_context.client = mock_client
+    mock_codealive_context.base_url = "https://app.codealive.ai"
+
+    ctx.request_context.lifespan_context = mock_codealive_context
+    ctx.request_context.headers = {"authorization": "Bearer test_key"}
+
+    result = await fetch_artifacts(
+        ctx=ctx,
+        identifiers=["owner/repo::src/auth.py::login", "owner/repo::src/missing.py::func"],
+    )
+
+    assert isinstance(result, str)
+    assert "<artifacts>" in result
+    assert "</artifacts>" in result
+    # Found artifact has content
+    assert "def login(user, pwd):" in result
+    assert 'contentByteSize="38"' in result
+    assert 'identifier="owner/repo::src/auth.py::login"' in result
+    # Not-found artifact is skipped (not in output)
+    assert "missing.py" not in result
+
+
+@pytest.mark.asyncio
+async def test_fetch_artifacts_empty_identifiers():
+    """Test that empty identifiers list returns an error."""
+    ctx = MagicMock(spec=Context)
+
+    result = await fetch_artifacts(ctx=ctx, identifiers=[])
+
+    assert "<error>" in result
+    assert "At least one identifier" in result
+
+
+@pytest.mark.asyncio
+async def test_fetch_artifacts_exceeds_max_identifiers():
+    """Test that more than 20 identifiers returns an error."""
+    ctx = MagicMock(spec=Context)
+
+    identifiers = [f"owner/repo::file{i}.py::func{i}" for i in range(21)]
+
+    result = await fetch_artifacts(ctx=ctx, identifiers=identifiers)
+
+    assert "<error>" in result
+    assert "Maximum 20" in result
+
+
+@pytest.mark.asyncio
+@patch('tools.fetch_artifacts.get_api_key_from_context')
+async def test_fetch_artifacts_posts_correct_body(mock_get_api_key):
+    """Test that fetch_artifacts sends the correct POST body."""
+    mock_get_api_key.return_value = "test_key"
+
+    ctx = MagicMock(spec=Context)
+    ctx.info = AsyncMock()
+    ctx.warning = AsyncMock()
+    ctx.error = AsyncMock()
+
+    mock_response = MagicMock()
+    mock_response.json.return_value = {"artifacts": []}
+    mock_response.raise_for_status = MagicMock()
+
+    mock_client = AsyncMock()
+    mock_client.post.return_value = mock_response
+
+    mock_codealive_context = MagicMock()
+    mock_codealive_context.client = mock_client
+    mock_codealive_context.base_url = "https://app.codealive.ai"
+
+    ctx.request_context.lifespan_context = mock_codealive_context
+    ctx.request_context.headers = {"authorization": "Bearer test_key"}
+
+    await fetch_artifacts(
+        ctx=ctx,
+        identifiers=["id1", "id2"],
+    )
+
+    call_args = mock_client.post.call_args
+    assert call_args.args[0] == "/api/search/artifacts"
+    body = call_args.kwargs["json"]
+    assert body["identifiers"] == ["id1", "id2"]
+    assert "names" not in body
+
+
+@pytest.mark.asyncio
+@patch('tools.fetch_artifacts.get_api_key_from_context')
+async def test_fetch_artifacts_api_error(mock_get_api_key):
+    """Test that API errors are handled gracefully."""
+    import httpx
+
+    mock_get_api_key.return_value = "test_key"
+
+    ctx = MagicMock(spec=Context)
+    ctx.info = AsyncMock()
+    ctx.warning = AsyncMock()
+    ctx.error = AsyncMock()
+
+    mock_response = MagicMock()
+    mock_response.status_code = 500
+    mock_response.text = "Internal server error"
+
+    def raise_500():
+        raise httpx.HTTPStatusError(
+            "Server error",
+            request=MagicMock(),
+            response=mock_response
+        )
+
+    mock_response.raise_for_status = raise_500
+
+    mock_client = AsyncMock()
+    mock_client.post.return_value = mock_response
+
+    mock_codealive_context = MagicMock()
+    mock_codealive_context.client = mock_client
+    mock_codealive_context.base_url = "https://app.codealive.ai"
+
+    ctx.request_context.lifespan_context = mock_codealive_context
+    ctx.request_context.headers = {"authorization": "Bearer test_key"}
+
+    result = await fetch_artifacts(
+        ctx=ctx,
+        identifiers=["some-id"],
+    )
+
+    assert isinstance(result, str)
+    assert "<error>" in result
+
+
+@pytest.mark.asyncio
+@patch('tools.fetch_artifacts.get_api_key_from_context')
+async def test_fetch_artifacts_escapes_xml(mock_get_api_key):
+    """Test that content with XML special characters is properly escaped."""
+    mock_get_api_key.return_value = "test_key"
+
+    ctx = MagicMock(spec=Context)
+    ctx.info = AsyncMock()
+    ctx.warning = AsyncMock()
+    ctx.error = AsyncMock()
+
+    mock_response = MagicMock()
+    mock_response.json.return_value = {
+        "artifacts": [
+            {
+                "identifier": "owner/repo::file.py::func",
+                "content": 'if x < 10 && y > 5:\n    return "<ok>"',
+                "contentByteSize": 40
+            }
+        ]
+    }
+    mock_response.raise_for_status = MagicMock()
+
+    mock_client = AsyncMock()
+    mock_client.post.return_value = mock_response
+
+    mock_codealive_context = MagicMock()
+    mock_codealive_context.client = mock_client
+    mock_codealive_context.base_url = "https://app.codealive.ai"
+
+    ctx.request_context.lifespan_context = mock_codealive_context
+    ctx.request_context.headers = {"authorization": "Bearer test_key"}
+
+    result = await fetch_artifacts(
+        ctx=ctx,
+        identifiers=["owner/repo::file.py::func"],
+    )
+
+    assert "&lt;" in result
+    assert "&amp;" in result
+    assert "<artifacts>" in result
+    assert "</artifacts>" in result