Refactor chat_completions to codebase_consultant with simplified API

- Renamed chat_completions to codebase_consultant for clarity
- Simplified API: now accepts 'question' parameter instead of messages array
- Internal transformation: question → [{"role": "user", "content": question}]
- Cleaner contract: agents just pass a string question, not nested objects
- Updated all imports, tests, and documentation
- Tests passing: simplified validation for empty questions
- Maintains backward compatibility with data source format

The new name better reflects the capability (consulting an AI expert about code)
and the simplified API is more intuitive for agents to use.

Author: IvanBiruk

CLAUDE.md

@@ -48,7 +48,7 @@ This is a Model Context Protocol (MCP) server that provides AI clients with acce
 ### Core Components
 
 - **`codealive_mcp_server.py`**: Main server implementation using FastMCP framework
-- **Three main tools**: `chat_completions`, `codebase_search`, `get_data_sources`
+- **Three main tools**: `codebase_consultant`, `codebase_search`, `get_data_sources`
 - **CodeAliveContext**: Manages HTTP client and API credentials
 - **Async lifespan management**: Handles client setup/teardown
 
@@ -63,7 +63,7 @@ This is a Model Context Protocol (MCP) server that provides AI clients with acce
 ### Data Flow
 
 1. AI client connects to MCP server via stdio/SSE transport
-2. Client calls tools (`get_data_sources` → `codebase_search` → `chat_completions`)
+2. Client calls tools (`get_data_sources` → `codebase_search` → `codebase_consultant`)
 3. MCP server translates tool calls to CodeAlive API requests
 4. CodeAlive API returns semantic search results or chat completions
 5. Server formats and returns results to AI client

README.md

@@ -23,15 +23,15 @@ Once connected, you'll have access to these powerful tools:
 
 1. **`get_data_sources`** - List your indexed repositories and workspaces
 2. **`codebase_search`** - Semantic code search across your indexed codebase (main/master branch)  
-3. **`chat_completions`** - AI chat with full project context
+3. **`codebase_consultant`** - AI consultant with full project expertise
 
 ## 🎯 Usage Examples
 
 After setup, try these commands with your AI assistant:
 
 - *"Show me all available repositories"* → Uses `get_data_sources`
 - *"Find authentication code in the user service"* → Uses `codebase_search`
-- *"Explain how the payment flow works in this codebase"* → Uses `chat_completions`
+- *"Explain how the payment flow works in this codebase"* → Uses `codebase_consultant`
 
 ## Table of Contents
 

src/codealive_mcp_server.py

@@ -25,7 +25,7 @@
 
 # Import core components
 from core import codealive_lifespan, setup_debug_logging
-from tools import chat_completions, get_data_sources, codebase_search
+from tools import codebase_consultant, get_data_sources, codebase_search
 
 # Initialize FastMCP server with lifespan and enhanced system instructions
 mcp = FastMCP(
@@ -88,7 +88,7 @@ async def health_check(request: Request) -> JSONResponse:
 
 
 # Register tools
-mcp.tool()(chat_completions)
+mcp.tool()(codebase_consultant)
 mcp.tool()(get_data_sources)
 mcp.tool()(codebase_search)
 

src/tests/test_chat_tool.py

@@ -1,16 +1,16 @@
-"""Test suite for chat completions tool."""
+"""Test suite for codebase consultant tool."""
 
 import pytest
 from unittest.mock import AsyncMock, MagicMock, patch
 import json
 from fastmcp import Context
-from tools.chat import chat_completions
+from tools.chat import codebase_consultant
 
 
 @pytest.mark.asyncio
 @patch('tools.chat.get_api_key_from_context')
-async def test_chat_with_simple_ids(mock_get_api_key):
-    """Test chat completions with simple string IDs."""
+async def test_consultant_with_simple_ids(mock_get_api_key):
+    """Test codebase consultant with simple string IDs."""
     mock_get_api_key.return_value = "test_key"
 
     ctx = MagicMock(spec=Context)
@@ -40,9 +40,9 @@ async def mock_aiter_lines():
     ctx.request_context.lifespan_context = mock_codealive_context
 
     # Test with simple string IDs
-    result = await chat_completions(
+    result = await codebase_consultant(
         ctx=ctx,
-        messages=[{"role": "user", "content": "Test question"}],
+        question="Test question",
         data_sources=["repo123", "repo456"]
     )
 
@@ -61,8 +61,8 @@ async def mock_aiter_lines():
 
 @pytest.mark.asyncio
 @patch('tools.chat.get_api_key_from_context')
-async def test_chat_with_dict_ids(mock_get_api_key):
-    """Test chat completions with dictionary format IDs."""
+async def test_consultant_preserves_string_ids(mock_get_api_key):
+    """Test codebase consultant preserves string IDs."""
     mock_get_api_key.return_value = "test_key"
 
     ctx = MagicMock(spec=Context)
@@ -88,14 +88,11 @@ async def mock_aiter_lines():
 
     ctx.request_context.lifespan_context = mock_codealive_context
 
-    # Test with dict format (backward compatibility)
-    result = await chat_completions(
+    # Test with string IDs
+    result = await codebase_consultant(
         ctx=ctx,
-        messages=[{"role": "user", "content": "Test"}],
-        data_sources=[
-            {"type": "repository", "id": "repo123"},
-            {"id": "repo456"}
-        ]
+        question="Test",
+        data_sources=["repo123", "repo456"]
     )
 
     call_args = mock_client.post.call_args
@@ -112,8 +109,8 @@ async def mock_aiter_lines():
 
 @pytest.mark.asyncio
 @patch('tools.chat.get_api_key_from_context')
-async def test_chat_with_conversation_id(mock_get_api_key):
-    """Test chat completions with existing conversation ID."""
+async def test_consultant_with_conversation_id(mock_get_api_key):
+    """Test codebase consultant with existing conversation ID."""
     mock_get_api_key.return_value = "test_key"
 
     ctx = MagicMock(spec=Context)
@@ -137,9 +134,9 @@ async def mock_aiter_lines():
 
     ctx.request_context.lifespan_context = mock_codealive_context
 
-    result = await chat_completions(
+    result = await codebase_consultant(
         ctx=ctx,
-        messages=[{"role": "user", "content": "Follow up"}],
+        question="Follow up",
         conversation_id="conv_123"
     )
 
@@ -156,51 +153,29 @@ async def mock_aiter_lines():
 
 @pytest.mark.asyncio
 @patch('tools.chat.get_api_key_from_context')
-async def test_chat_empty_messages_validation(mock_get_api_key):
-    """Test validation of empty messages."""
+async def test_consultant_empty_question_validation(mock_get_api_key):
+    """Test validation of empty question."""
     mock_get_api_key.return_value = "test_key"
 
     ctx = MagicMock(spec=Context)
     ctx.request_context.lifespan_context = MagicMock()
 
-    # Test with no messages
-    result = await chat_completions(ctx=ctx, messages=None)
-    assert "Error: No messages provided" in result
+    # Test with empty question
+    result = await codebase_consultant(ctx=ctx, question="")
+    assert "Error: No question provided" in result
 
-    # Test with empty list
-    result = await chat_completions(ctx=ctx, messages=[])
-    assert "Error: No messages provided" in result
+    # Test with whitespace only
+    result = await codebase_consultant(ctx=ctx, question="   ")
+    assert "Error: No question provided" in result
 
 
-@pytest.mark.asyncio
-@patch('tools.chat.get_api_key_from_context')
-async def test_chat_invalid_message_format(mock_get_api_key):
-    """Test validation of message format."""
-    mock_get_api_key.return_value = "test_key"
-
-    ctx = MagicMock(spec=Context)
-    ctx.request_context.lifespan_context = MagicMock()
-
-    # Test with missing role
-    result = await chat_completions(
-        ctx=ctx,
-        messages=[{"content": "Test"}]
-    )
-    assert "Error: Each message must have 'role' and 'content'" in result
-
-    # Test with missing content
-    result = await chat_completions(
-        ctx=ctx,
-        messages=[{"role": "user"}]
-    )
-    assert "Error: Each message must have 'role' and 'content'" in result
 
 
 @pytest.mark.asyncio
 @patch('tools.chat.get_api_key_from_context')
 @patch('tools.chat.handle_api_error')
-async def test_chat_error_handling(mock_handle_error, mock_get_api_key):
-    """Test error handling in chat completions."""
+async def test_consultant_error_handling(mock_handle_error, mock_get_api_key):
+    """Test error handling in codebase consultant."""
     mock_get_api_key.return_value = "test_key"
     mock_handle_error.return_value = "Error: Authentication failed"
 
@@ -216,9 +191,9 @@ async def test_chat_error_handling(mock_handle_error, mock_get_api_key):
 
     ctx.request_context.lifespan_context = mock_codealive_context
 
-    result = await chat_completions(
+    result = await codebase_consultant(
         ctx=ctx,
-        messages=[{"role": "user", "content": "Test"}],
+        question="Test",
         data_sources=["repo123"]
     )
 

src/tools/__init__.py

@@ -1,7 +1,7 @@
 """Tool implementations for CodeAlive MCP server."""
 
-from .chat import chat_completions
+from .chat import codebase_consultant
 from .datasources import get_data_sources
 from .search import codebase_search
 
-__all__ = ['chat_completions', 'get_data_sources', 'codebase_search']
+__all__ = ['codebase_consultant', 'get_data_sources', 'codebase_search']

src/tools/chat.py

@@ -11,77 +11,72 @@
 from utils import handle_api_error, format_data_source_ids
 
 
-async def chat_completions(
+async def codebase_consultant(
     ctx: Context,
-    messages: Optional[List[Dict[str, str]]] = None,
-    data_sources: Optional[List] = None,  # Accept both strings and dicts for compatibility
+    question: str,
+    data_sources: Optional[List[str]] = None,
     conversation_id: Optional[str] = None
 ) -> str:
     """
-    Streams chat completions from the CodeAlive API for code-aware conversations with knowledge of your codebase.
+    Consult with an AI expert about your codebase for insights, explanations, and architectural guidance.
+
+    This consultant understands your entire codebase and can help with:
+    - Architecture and design decisions
+    - Implementation strategies
+    - Code explanations and walkthroughs
+    - Best practices and optimization advice
+    - Debugging and problem-solving
 
     Args:
-        messages: List of message objects with "role" and "content" fields
-                 Example: [
-                   {"role": "system", "content": "Analyze the authentication flow"},
-                   {"role": "user", "content": "How does the login process work?"}
-                 ]
+        question: What you want to know about the codebase
+                 Example: "How does the authentication system work?"
 
-        data_sources: List of data source IDs (repository or workspace IDs).
+        data_sources: Repository or workspace IDs to analyze
                      Example: ["67f664fd4c2a00698a52bb6f", "5e8f9a2c1d3b7e4a6c9d0f8e"]
-                     Just pass the IDs directly as strings.
-        conversation_id: Optional ID to continue a previous conversation
-                        Example: "conv_6789f123a456b789c123d456"
 
+        conversation_id: Continue a previous consultation session
+                        Example: "conv_6789f123a456b789c123d456"
 
     Returns:
-        The generated completion text with code understanding from specified repositories/workspaces.
-        The response will incorporate knowledge from the specified code repositories.
+        Expert analysis and explanation addressing your question.
 
     Examples:
-        1. Start a new conversation with simple ID format (recommended):
-           chat_completions(
-             messages=[{"role": "user", "content": "Explain the authentication flow in this code"}],
+        1. Ask about architecture:
+           codebase_consultant(
+             question="What's the best way to add caching to our API?",
              data_sources=["67f664fd4c2a00698a52bb6f"]
            )
 
-        2. Start a new conversation using multiple data sources:
-           chat_completions(
-             messages=[{"role": "user", "content": "How do the microservices communicate with each other?"}],
-             data_sources=["67f664fd4c2a00698a52bb6f", "5e8f9a2c1d3b7e4a6c9d0f8e"]
+        2. Understand implementation:
+           codebase_consultant(
+             question="How do the microservices communicate?",
+             data_sources=["workspace_123", "repo_456"]
            )
 
-        3. Continue an existing conversation:
-           chat_completions(
-             messages=[{"role": "user", "content": "How is password hashing implemented?"}],
+        3. Continue a consultation:
+           codebase_consultant(
+             question="What about error handling in that flow?",
              conversation_id="conv_6789f123a456b789c123d456"
            )
 
-
     Note:
         - Either conversation_id OR data_sources is typically provided
-        - When creating a new conversation, data_sources is optional if the API key has exactly one assigned data source
-        - When continuing a conversation, conversation_id is required
-        - The conversation maintains context across multiple messages
-        - Messages should be in chronological order with the newest message last
-        - Choose between workspace-level access (for broader context) or repository-level access
-          (for targeted analysis) based on your query needs
-        - If a user is working in a local git repository that matches one of the indexed repositories
-          in CodeAlive (by URL), you can leverage this integration for enhanced code understanding
+        - When creating a new conversation, data_sources is optional if your API key has exactly one assigned data source
+        - When continuing a conversation, conversation_id is required to maintain context
+        - The consultant maintains full conversation history for follow-up questions
+        - Choose workspace IDs for broad architectural questions or repository IDs for specific implementation details
     """
     context: CodeAliveContext = ctx.request_context.lifespan_context
 
-    if not messages or len(messages) == 0:
-        return "Error: No messages provided. Please include at least one message with 'role' and 'content' fields."
+    if not question or not question.strip():
+        return "Error: No question provided. Please provide a question to ask the consultant."
 
     # Validate that either conversation_id or data_sources is provided
     if not conversation_id and (not data_sources or len(data_sources) == 0):
         await ctx.info("No data sources provided. If the API key has exactly one assigned data source, that will be used as default.")
 
-    # Validate that each message has the required fields
-    for msg in messages:
-        if not msg.get("role") or not msg.get("content"):
-            return "Error: Each message must have 'role' and 'content' fields. Valid roles are 'system', 'user', and 'assistant'."
+    # Transform simple question into message format internally
+    messages = [{"role": "user", "content": question}]
 
     # Prepare the request payload
     request_data = {
@@ -99,8 +94,8 @@ async def chat_completions(
         api_key = get_api_key_from_context(ctx)
 
         # Log the attempt
-        await ctx.info(f"Requesting chat completion with {len(messages)} messages" +
-                       (f" in conversation {conversation_id}" if conversation_id else " in a new conversation"))
+        await ctx.info(f"Consulting about: '{question[:100]}...'" if len(question) > 100 else f"Consulting about: '{question}'" +
+                       (f" (continuing conversation {conversation_id})" if conversation_id else ""))
 
         headers = {"Authorization": f"Bearer {api_key}"}
 

src/tools/datasources.py

@@ -48,7 +48,7 @@ async def get_data_sources(ctx: Context, alive_only: bool = True) -> str:
         For workspaces, the repositoryIds can be used to identify and work with
         individual repositories that make up the workspace.
 
-        Use the returned data source IDs with the codebase_search and chat_completions functions.
+        Use the returned data source IDs with the codebase_search and codebase_consultant functions.
     """
     context: CodeAliveContext = ctx.request_context.lifespan_context
 
@@ -84,7 +84,7 @@ async def get_data_sources(ctx: Context, alive_only: bool = True) -> str:
         result = f"Available data sources:\n{formatted_data}"
 
         # Add usage hint
-        result += "\n\nYou can use these data source IDs with the codebase_search and chat_completions functions."
+        result += "\n\nYou can use these data source IDs with the codebase_search and codebase_consultant functions."
 
         return result