Rename codebase consultant to chat

Author: rodion-m

CLAUDE.md

@@ -95,7 +95,7 @@ This is a Model Context Protocol (MCP) server that provides AI clients with acce
 ### Core Components
 
 - **`codealive_mcp_server.py`**: Main entry point — bootstraps logging, tracing, registers tools and middleware
-- **Five tools**: `get_data_sources`, `codebase_search`, `fetch_artifacts`, `codebase_consultant`, `get_artifact_relationships`
+- **Eight tools**: `get_data_sources`, `semantic_search`, `grep_search`, `fetch_artifacts`, `get_artifact_relationships`, `chat`, `codebase_search`, `codebase_consultant`
 - **`core/client.py`**: `CodeAliveContext` dataclass + `codealive_lifespan` (httpx.AsyncClient lifecycle, `_server_ready` flag)
 - **`core/logging.py`**: loguru structured JSON logging + PII masking + OTel context injection
 - **`core/observability.py`**: OpenTelemetry TracerProvider setup with OTLP export
@@ -105,7 +105,7 @@ This is a Model Context Protocol (MCP) server that provides AI clients with acce
 
 1. **FastMCP Framework**: Uses FastMCP 3.x with lifespan context, middleware hooks, and built-in `Client` for testing
 2. **HTTP Client Management**: Single persistent `httpx.AsyncClient` with connection pooling, created in lifespan
-3. **Streaming Support**: `codebase_consultant` uses SSE streaming (`response.aiter_lines()`) for chat completions
+3. **Streaming Support**: `chat` and the deprecated `codebase_consultant` alias use SSE streaming (`response.aiter_lines()`) for chat completions
 4. **Environment Configuration**: Supports both .env files and command-line arguments with precedence
 5. **Error Handling**: Centralized in `utils/errors.py` — all tools use `handle_api_error()` with `method=` prefix
 6. **N8N Middleware**: Strips extra parameters (sessionId, action, chatInput, toolCallId) from n8n tool calls before validation
@@ -114,7 +114,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/HTTP transport
-2. Client calls tools (`get_data_sources` → `codebase_search` → `fetch_artifacts` / `codebase_consultant`)
+2. Client calls tools (`get_data_sources` → `semantic_search` / `grep_search` → `fetch_artifacts` / `get_artifact_relationships` → `chat` only if synthesis is still needed)
 3. Middleware chain runs: N8N cleanup → ObservabilityMiddleware (OTel span + log correlation)
 4. Tool translates MCP call to CodeAlive API request (with `X-CodeAlive-*` headers)
 5. Response parsed, formatted as XML or text, returned to AI client
@@ -144,7 +144,7 @@ The server is designed to integrate with:
 - Any MCP-compatible AI client
 
 Key integration considerations:
-- AI clients should use `get_data_sources` first to discover available repositories/workspaces, then use those IDs for targeted search and chat operations
+- AI clients should use `get_data_sources` first to discover available repositories/workspaces, then default to `semantic_search` and `grep_search` for evidence gathering; use `chat` only as a slower synthesis fallback
 - **n8n Integration**: The server includes middleware to automatically strip n8n's extra parameters (sessionId, action, chatInput, toolCallId) from tool calls, so n8n works out of the box without any special configuration
 
 ## Logging Best Practices
@@ -157,7 +157,7 @@ This project uses **loguru** for structured JSON logging. All logs go to **stder
 
 2. **All logs go to stderr.** The stdio MCP transport uses stdout for protocol messages. Any stray `print()` or stdout write will corrupt the MCP protocol and break the client. If you add a new log sink, it must target `sys.stderr`.
 
-3. **Never call `response.text` without a debug guard.** `log_api_response()` is protected by `_is_debug_enabled()` because reading `response.text` consumes the response body. The `codebase_consultant` tool streams SSE via `response.aiter_lines()` — calling `.text` first would silently consume the stream and produce empty results. If you add new response logging, always check `_is_debug_enabled()` first:
+3. **Never call `response.text` without a debug guard.** `log_api_response()` is protected by `_is_debug_enabled()` because reading `response.text` consumes the response body. The `chat` tool and deprecated `codebase_consultant` alias stream SSE via `response.aiter_lines()` — calling `.text` first would silently consume the stream and produce empty results. If you add new response logging, always check `_is_debug_enabled()` first:
    ```python
    if not _is_debug_enabled():
        return  # Do NOT touch response body at INFO level
@@ -269,7 +269,7 @@ Key points:
 - Custom lifespan yields a real `CodeAliveContext` with a mock-backed httpx client
 - `monkeypatch.setenv("CODEALIVE_API_KEY", ...)` for `get_api_key_from_context` fallback
 - Use `raise_on_error=False` when testing error paths, then assert on `result.content[0].text`
-- For SSE streaming (codebase_consultant), return `httpx.Response(200, text=sse_body)` — `aiter_lines()` works on buffered responses
+- For SSE streaming (`chat` / `codebase_consultant`), return `httpx.Response(200, text=sse_body)` — `aiter_lines()` works on buffered responses
 
 ### Unit Test Patterns
 

README.md

@@ -30,8 +30,9 @@ Once connected, you'll have access to these powerful tools:
 3. **`grep_search`** - Exact text or regex search with line-level matches
 4. **`fetch_artifacts`** - Load the full source for relevant search hits
 5. **`get_artifact_relationships`** - Expand call graph, inheritance, and reference relationships for one artifact
-6. **`codebase_consultant`** - AI consultant with full project expertise
+6. **`chat`** - Slower synthesized codebase Q&A, typically only after search
 7. **`codebase_search`** - Deprecated legacy semantic search alias kept for backward compatibility
+8. **`codebase_consultant`** - Deprecated alias for `chat`
 
 ## 🎯 Usage Examples
 
@@ -40,7 +41,9 @@ 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 `semantic_search`
 - *"Find the exact regex that matches JWT tokens"* → Uses `grep_search`
-- *"Explain how the payment flow works in this codebase"* → Uses `codebase_consultant`
+- *"Explain how the payment flow works in this codebase"* → Usually starts with `semantic_search`/`grep_search`, then optionally uses `chat`
+
+`semantic_search` and `grep_search` should be the default tools for most agents. `chat` is a slower synthesis fallback, can take up to 30 seconds, and is usually unnecessary when an agent can run a multi-step workflow with search, fetch, relationships, and local file reads. If your agent supports subagents, the highest-confidence path is to delegate a focused subagent that orchestrates `semantic_search` and `grep_search` first.
 
 ## 📚 Agent Skill
 
@@ -808,8 +811,9 @@ See [JetBrains MCP Documentation](https://www.jetbrains.com/help/ai-assistant/mc
    - `semantic_search` - Search code semantically
    - `grep_search` - Search by exact text or regex
    - `get_artifact_relationships` - Expand relationships for one artifact
+   - `chat` - Slower synthesized codebase Q&A, usually after search
    - `codebase_search` - Legacy semantic search alias
-   - `codebase_consultant` - Ask questions about code
+   - `codebase_consultant` - Deprecated alias for `chat`
 
 **Example Workflow:**
 ```

manifest.json

@@ -65,13 +65,17 @@
       "name": "grep_search",
       "description": "Search indexed artifacts by exact text or regex and return line-level matches."
     },
+    {
+      "name": "chat",
+      "description": "Synthesized codebase Q&A. Slower and usually not the default choice; prefer semantic_search and grep_search first. Can take up to 30 seconds."
+    },
     {
       "name": "fetch_artifacts",
       "description": "Fetch full source for specific search results when you need the underlying code."
     },
     {
       "name": "codebase_consultant",
-      "description": "Ask architecture and implementation questions with full codebase context."
+      "description": "Deprecated alias for chat kept for backward compatibility."
     },
     {
       "name": "get_artifact_relationships",

server.json

@@ -66,9 +66,13 @@
         "name": "grep_search",
         "description": "Search indexed artifacts using exact text or regex patterns and return line-level matches."
       },
+      {
+        "name": "chat",
+        "description": "Synthesized codebase Q&A. Use only after semantic_search and grep_search when you need a slower, up-to-30-second answer."
+      },
       {
         "name": "codebase_consultant",
-        "description": "Get comprehensive AI-powered analysis, explanations, and insights about your codebase. Ask complex questions about architecture, patterns, dependencies, and implementation details."
+        "description": "Deprecated alias for chat retained for backward compatibility."
       },
       {
         "name": "fetch_artifacts",

src/codealive_mcp_server.py

@@ -29,6 +29,7 @@
 import core.client as _client_module  # for /ready flag access
 from middleware import N8NRemoveParametersMiddleware, ObservabilityMiddleware
 from tools import (
+    chat,
     codebase_consultant,
     codebase_search,
     fetch_artifacts,
@@ -58,13 +59,20 @@
     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
+    4. Use `get_artifact_relationships` or `fetch_artifacts` to drill into the most relevant hits
+    5. If your environment supports subagents and you need the highest reliability or depth,
+       prefer an agentic workflow where a subagent combines `semantic_search`, `grep_search`,
+       artifact fetches, relationship inspection, and local file reads
+    6. Use `chat` only when you specifically need a synthesized answer after search;
+       it is usually not the default choice and can take up to 30 seconds
 
     For effective code exploration:
     - Start with broad natural-language queries in `semantic_search` to understand the overall structure
     - Use `grep_search(regex=false)` for exact strings and `grep_search(regex=true)` for regex patterns
     - Use specific function/class names or file path scopes when looking for particular implementations
+    - Treat `semantic_search` and `grep_search` as the default discovery tools
     - Prefer `semantic_search` over the deprecated `codebase_search` legacy alias
+    - Reserve `chat` for synthesis after search, not for first-pass evidence gathering
     - Remember that context from previous messages is maintained in the same conversation
 
     Flexible data source usage:
@@ -122,10 +130,6 @@ async def readiness_check(request: Request) -> JSONResponse:
 # Register tools with metadata suitable for Claude Desktop and MCP directories.
 _READ_ONLY_TOOL = {"readOnlyHint": True}
 
-mcp.tool(
-    title="Consult Codebase",
-    annotations=_READ_ONLY_TOOL,
-)(codebase_consultant)
 mcp.tool(
     title="List Data Sources",
     annotations=_READ_ONLY_TOOL,
@@ -142,6 +146,10 @@ async def readiness_check(request: Request) -> JSONResponse:
     title="Grep Search",
     annotations=_READ_ONLY_TOOL,
 )(grep_search)
+mcp.tool(
+    title="Chat About Codebase",
+    annotations=_READ_ONLY_TOOL,
+)(chat)
 mcp.tool(
     title="Fetch Artifacts",
     annotations=_READ_ONLY_TOOL,
@@ -150,6 +158,10 @@ async def readiness_check(request: Request) -> JSONResponse:
     title="Inspect Artifact Relationships",
     annotations=_READ_ONLY_TOOL,
 )(get_artifact_relationships)
+mcp.tool(
+    title="Consult Codebase (Deprecated)",
+    annotations=_READ_ONLY_TOOL,
+)(codebase_consultant)
 
 
 def main():

src/tests/test_chat_tool.py

@@ -1,16 +1,16 @@
-"""Test suite for codebase consultant tool."""
+"""Test suite for chat tool and legacy consultant alias."""
 
 import pytest
 from unittest.mock import AsyncMock, MagicMock, patch
 import json
 from fastmcp import Context
-from tools.chat import codebase_consultant
+from tools.chat import chat, codebase_consultant
 
 
 @pytest.mark.asyncio
 @patch('tools.chat.get_api_key_from_context')
-async def test_consultant_with_simple_names(mock_get_api_key):
-    """Test codebase consultant with simple string names."""
+async def test_chat_with_simple_names(mock_get_api_key):
+    """Test chat with simple string names."""
     mock_get_api_key.return_value = "test_key"
 
     ctx = MagicMock(spec=Context)
@@ -40,7 +40,7 @@ async def mock_aiter_lines():
     ctx.request_context.lifespan_context = mock_codealive_context
 
     # Test with simple string names
-    result = await codebase_consultant(
+    result = await chat(
         ctx=ctx,
         question="Test question",
         data_sources=["repo123", "repo456"]
@@ -57,12 +57,13 @@ async def mock_aiter_lines():
     ]
 
     assert result == "Hello world"
+    assert call_args.kwargs["headers"]["X-CodeAlive-Tool"] == "chat"
 
 
 @pytest.mark.asyncio
 @patch('tools.chat.get_api_key_from_context')
-async def test_consultant_preserves_string_names(mock_get_api_key):
-    """Test codebase consultant preserves string names."""
+async def test_consultant_alias_preserves_string_names(mock_get_api_key):
+    """Test deprecated consultant alias preserves behavior."""
     mock_get_api_key.return_value = "test_key"
 
     ctx = MagicMock(spec=Context)
@@ -109,8 +110,8 @@ async def mock_aiter_lines():
 
 @pytest.mark.asyncio
 @patch('tools.chat.get_api_key_from_context')
-async def test_consultant_with_conversation_id(mock_get_api_key):
-    """Test codebase consultant with existing conversation ID."""
+async def test_chat_with_conversation_id(mock_get_api_key):
+    """Test chat with existing conversation ID."""
     mock_get_api_key.return_value = "test_key"
 
     ctx = MagicMock(spec=Context)
@@ -134,7 +135,7 @@ async def mock_aiter_lines():
 
     ctx.request_context.lifespan_context = mock_codealive_context
 
-    result = await codebase_consultant(
+    result = await chat(
         ctx=ctx,
         question="Follow up",
         conversation_id="conv_123"
@@ -153,19 +154,19 @@ async def mock_aiter_lines():
 
 @pytest.mark.asyncio
 @patch('tools.chat.get_api_key_from_context')
-async def test_consultant_empty_question_validation(mock_get_api_key):
+async def test_chat_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 empty question
-    result = await codebase_consultant(ctx=ctx, question="")
+    result = await chat(ctx=ctx, question="")
     assert "Error: No question provided" in result
 
     # Test with whitespace only
-    result = await codebase_consultant(ctx=ctx, question="   ")
+    result = await chat(ctx=ctx, question="   ")
     assert "Error: No question provided" in result
 
 
@@ -174,8 +175,8 @@ async def test_consultant_empty_question_validation(mock_get_api_key):
 @pytest.mark.asyncio
 @patch('tools.chat.get_api_key_from_context')
 @patch('tools.chat.handle_api_error')
-async def test_consultant_error_handling(mock_handle_error, mock_get_api_key):
-    """Test error handling in codebase consultant."""
+async def test_chat_error_handling(mock_handle_error, mock_get_api_key):
+    """Test error handling in chat."""
     mock_get_api_key.return_value = "test_key"
     mock_handle_error.return_value = "Error: Authentication failed"
 
@@ -191,11 +192,11 @@ async def test_consultant_error_handling(mock_handle_error, mock_get_api_key):
 
     ctx.request_context.lifespan_context = mock_codealive_context
 
-    result = await codebase_consultant(
+    result = await chat(
         ctx=ctx,
         question="Test",
         data_sources=["repo123"]
     )
 
     assert result == "Error: Authentication failed"
-    mock_handle_error.assert_called_once()
+    mock_handle_error.assert_called_once()

src/tests/test_e2e_tools.py

@@ -20,6 +20,7 @@
 
 from core import CodeAliveContext
 from tools import (
+    chat,
     codebase_consultant,
     codebase_search,
     fetch_artifacts,
@@ -69,6 +70,7 @@ async def lifespan(server: FastMCP) -> AsyncIterator[CodeAliveContext]:
     mcp.tool()(semantic_search)
     mcp.tool()(grep_search)
     mcp.tool()(fetch_artifacts)
+    mcp.tool()(chat)
     mcp.tool()(codebase_consultant)
     mcp.tool()(get_artifact_relationships)
     return mcp
@@ -464,10 +466,10 @@ async def test_artifact_with_relationships(self):
 
 
 # ---------------------------------------------------------------------------
-# codebase_consultant (streaming SSE)
+# chat / codebase_consultant (streaming SSE)
 # ---------------------------------------------------------------------------
 
-class TestCodebaseConsultantE2E:
+class TestChatE2E:
     @staticmethod
     def _sse_body(chunks: list[str], conv_id: str = "conv-42", msg_id: str = "msg-1") -> str:
         """Build an SSE response body with metadata + content chunks + DONE."""
@@ -497,7 +499,7 @@ def handler(req):
         mcp = _server({"/api/chat/completions": handler})
         async with Client(mcp) as client:
             result = await client.call_tool(
-                "codebase_consultant",
+                "chat",
                 {"question": "How does auth work?", "data_sources": ["backend"]},
             )
 
@@ -518,7 +520,7 @@ def handler(req):
         mcp = _server({"/api/chat/completions": handler})
         async with Client(mcp) as client:
             result = await client.call_tool(
-                "codebase_consultant",
+                "chat",
                 {"question": "And the error handling?", "conversation_id": "conv-existing"},
             )
 
@@ -530,7 +532,7 @@ async def test_empty_question_returns_error(self):
         mcp = _server({})
         async with Client(mcp) as client:
             result = await client.call_tool(
-                "codebase_consultant", {"question": ""},
+                "chat", {"question": ""},
                 raise_on_error=False,
             )
 
@@ -544,14 +546,31 @@ async def test_backend_error_handled(self):
         })
         async with Client(mcp) as client:
             result = await client.call_tool(
-                "codebase_consultant",
+                "chat",
                 {"question": "hello"},
                 raise_on_error=False,
             )
 
         text = _text(result)
         assert "401" in text or "auth" in text.lower()
 
+    @pytest.mark.asyncio
+    async def test_legacy_alias_still_works(self):
+        body = self._sse_body(["Legacy alias"])
+
+        def handler(req):
+            assert req.headers["X-CodeAlive-Tool"] == "codebase_consultant"
+            return httpx.Response(200, text=body, headers={"content-type": "text/event-stream"})
+
+        mcp = _server({"/api/chat/completions": handler})
+        async with Client(mcp) as client:
+            result = await client.call_tool(
+                "codebase_consultant",
+                {"question": "How does auth work?", "data_sources": ["backend"]},
+            )
+
+        assert "Legacy alias" in _text(result)
+
 
 # ---------------------------------------------------------------------------
 # get_artifact_relationships