Refine documentation and logic for include_content usage in codebase_search across repositories, clarifying external vs. current repo handling and adding URL comparison guidelines.

Author: rodion-m

src/codealive_mcp_server.py

@@ -53,6 +53,15 @@
     - IMPORTANT: Only use "deep" search mode for very complex conceptual queries as it's resource-intensive
     - Remember that context from previous messages is maintained in the same conversation
 
+    CRITICAL - include_content parameter usage:
+    - For the CURRENT repository (user's working directory): Use include_content=false
+      * You already have file access via Read tool
+      * Get file paths from search, then read them directly for latest content
+    - For EXTERNAL repositories (not in working directory): Use include_content=true
+      * You cannot access these files directly
+      * Content must be included in search results
+    - Compare repository URLs from get_data_sources with current git repo to identify which is which
+
     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

src/tools/datasources.py

@@ -28,6 +28,8 @@ async def get_data_sources(ctx: Context, alive_only: bool = True) -> str:
         - description: Summary of the codebase contents to guide search and chat usage
         - type: The type of data source ("Repository" or "Workspace")
         - url: URL of the repository (for Repository type only)
+          IMPORTANT: Use this URL to identify if a repository matches your current working directory.
+          Compare with your local git remote URL to determine if it's the current or external repo.
         - state: The processing state of the data source (if alive_only=false)
 
     Examples:
@@ -42,8 +44,12 @@ async def get_data_sources(ctx: Context, alive_only: bool = True) -> str:
         Other states include "New" (just added), "Processing" (being indexed),
         "Failed" (indexing failed), etc.
 
-        For repositories, the URL can be used to match with local git repositories
-        to provide enhanced context for code understanding.
+        CRITICAL for optimizing include_content parameter:
+        - Compare repository URLs with your current git remote URL (git config --get remote.origin.url)
+        - If URLs match: This is your CURRENT repository
+          → Use include_content=false in codebase_search, then read files with Read tool
+        - If URLs don't match: This is an EXTERNAL repository
+          → Use include_content=true in codebase_search to get content directly
 
         Use the returned data source names with the codebase_search and codebase_consultant functions.
     """

src/tools/search.py

@@ -66,27 +66,53 @@ async def codebase_search(
                         cross-cutting questions.
 
         include_content: Whether to include full file content in results (default: false).
-                         Agents should proactively request content when needed by setting this to true.
-                         Note: File content may be outdated compared to current local state.
 
-    Returns:
-        Search results as JSON including source info, file paths, line numbers, and code snippets.
-
-    Examples:
-        1. Natural-language question (recommended):
-           codebase_search(query="What is the auth flow?", data_sources=["repo123"])
+                         IMPORTANT - When to include content:
+                         - For EXTERNAL repositories (not in your current working directory):
+                           SET TO TRUE - you don't have file access, so you need the content.
+                         - For CURRENT repository (the one you're working in):
+                           SET TO FALSE - you already have file access via Read tool, so just get
+                           file paths and read them directly for the latest content.
 
-        2. Intent query:
-           codebase_search(query="Where is user registration logic?", data_sources=["repo123"])
+                         How to identify current vs external repositories:
+                         - Compare repository URLs from get_data_sources with your current git repo URL
+                         - Current repo: Use include_content=false, then use Read tool on result paths
+                         - External repos: Use include_content=true to get the content directly
 
-        3. Workspace-wide question:
-           codebase_search(query="How do microservices talk to the billing API?", data_sources=["backend-team"])
+                         Note: Indexed content may be from a different branch than your local state.
 
-        4. Mixed query with a known identifier:
-           codebase_search(query="Where do we validate JWTs (AuthService)?", data_sources=["repo123"])
+    Returns:
+        Search results as JSON including source info, file paths, line numbers, and code snippets.
 
-        5. Concise results without full file contents:
-           codebase_search(query="Where is password reset handled?", data_sources=["repo123"], include_content=false)
+    Examples:
+        1. Search CURRENT repository (you have file access):
+           codebase_search(
+               query="Where is user authentication handled?",
+               data_sources=["my-current-repo"],
+               include_content=false  # Get paths only, then use Read tool
+           )
+           # Then read the files: Read(file_path="/path/from/results")
+
+        2. Search EXTERNAL repository (no file access):
+           codebase_search(
+               query="How does the payment service validate cards?",
+               data_sources=["external-payments-repo"],
+               include_content=true  # Need content, can't read files directly
+           )
+
+        3. Workspace-wide question across external repos:
+           codebase_search(
+               query="How do microservices talk to the billing API?",
+               data_sources=["backend-team"],
+               include_content=true  # External workspace, include content
+           )
+
+        4. Mixed query with known identifier:
+           codebase_search(
+               query="Where do we validate JWTs (AuthService)?",
+               data_sources=["repo123"],
+               include_content=false  # Current repo, read files separately
+           )
 
     Note:
         - At least one data source name must be provided