refactor: optimize embedding query with exact project_name match and simplify path handling by removing redundant fields from schemas

Author: wangjichao

README.md

@@ -513,17 +513,70 @@ The agent will incorporate the guidance from your reference documents when sugge
 
 Code-Graph-RAG can run as an MCP (Model Context Protocol) server, enabling seamless integration with Claude Code and other MCP clients.
 
+### MCP Dual Mode System (v0.0.60+)
+
+The MCP server now supports two distinct modes with different capabilities and security profiles:
+
+#### Query Mode (Production Recommended)
+**Read-only access** for safe codebase exploration and analysis.
+
+**Available Tools:**
+- `list_projects` - List all indexed projects
+- `query_code_graph` - Natural language graph queries
+- `get_code_snippet` - Retrieve source code by qualified name
+- `list_directory` - Browse directory structure
+
+**Use Cases:**
+- Production environments where code modification is not allowed
+- Code review and exploration
+- Documentation generation
+- Architecture analysis
+
+#### Edit Mode (Development)
+**Full access** including file editing and database management.
+
+**Additional Tools (beyond Query mode):**
+- `read_file` / `write_file` - File operations
+- `surgical_replace_code` - Precise code editing
+- `delete_project` - Remove projects from graph
+- `wipe_database` - Complete database reset (dangerous!)
+- `index_repository` - Build/update knowledge graph
+
+**Use Cases:**
+- Local development environments
+- Code refactoring assistance
+- Automated code generation
+- Database maintenance
+
 ### Quick Setup
 
+#### Query Mode (Recommended for Production)
+
+```bash
+claude mcp add --transport stdio code-graph-rag \
+  --env TARGET_REPO_PATH="$(pwd)" \
+  --env MCP_MODE=query \
+  --env CYPHER_PROVIDER=openai \
+  --env CYPHER_MODEL=gpt-4 \
+  --env CYPHER_API_KEY=your-api-key \
+  -- uv run --directory /path/to/code-graph-rag code-graph-rag mcp-server
+```
+
+#### Edit Mode (For Development)
+
 ```bash
 claude mcp add --transport stdio code-graph-rag \
-  --env TARGET_REPO_PATH=/absolute/path/to/your/project \
+  --env TARGET_REPO_PATH="$(pwd)" \
+  --env MCP_MODE=edit \
+  --env ALLOWED_PROJECT_ROOTS="$(pwd)" \
   --env CYPHER_PROVIDER=openai \
   --env CYPHER_MODEL=gpt-4 \
   --env CYPHER_API_KEY=your-api-key \
   -- uv run --directory /path/to/code-graph-rag code-graph-rag mcp-server
 ```
 
+**Important:** Always set `ALLOWED_PROJECT_ROOTS` in Edit mode to restrict file operations to specific directories.
+
 ### Available Tools
 
 <!-- SECTION:mcp_tools -->
@@ -543,13 +596,48 @@ claude mcp add --transport stdio code-graph-rag \
 
 ### Example Usage
 
+#### Query Mode
 ```
-> Index this repository
 > What functions call UserService.create_user?
+> Show me all classes that implement Repository
+> List all modules in the utils package
+> Get the source code for AuthService.login
+```
+
+#### Edit Mode
+```
+> Index this repository
 > Update the login function to add rate limiting
+> Refactor this class to use dependency injection
+> Delete the deprecated project from the graph
 ```
 
-For detailed setup, see [Claude Code Setup Guide](docs/claude-code-setup.md).
+### Security Configuration
+
+For Edit mode, always restrict access with `ALLOWED_PROJECT_ROOTS`:
+
+```bash
+# Single project
+--env ALLOWED_PROJECT_ROOTS="/path/to/project"
+
+# Multiple projects (comma-separated)
+--env ALLOWED_PROJECT_ROOTS="/path/to/project1,/path/to/project2"
+```
+
+This ensures file operations cannot modify files outside the specified directories.
+
+### Mode Selection Guide
+
+| Scenario | Recommended Mode | Reasoning |
+|----------|-----------------|-----------|
+| Production code review | Query | Prevents accidental modifications |
+| Development work | Edit | Allows code generation and editing |
+| CI/CD pipelines | Query | Read-only analysis is sufficient |
+| Local experimentation | Edit | Full control for testing |
+| Multi-project analysis | Query | Safe exploration across projects |
+| Code refactoring | Edit | Requires write access |
+
+For detailed setup and configuration examples, see [Claude Code Setup Guide](docs/claude-code-setup.md) and [Security Best Practices](docs/security-best-practices.md).
 
 ## 📊 Graph Schema
 
@@ -653,6 +741,10 @@ Configuration is managed through environment variables in `.env` file:
 - `TARGET_REPO_PATH`: Default repository path (default: `.`)
 - `LOCAL_MODEL_ENDPOINT`: Fallback endpoint for Ollama (default: `http://localhost:11434/v1`)
 
+### MCP Server Configuration
+- `MCP_MODE`: MCP server operation mode - `query` (read-only) or `edit` (full access). Default: `edit`. **Recommended: Use `query` mode for production environments.**
+- `ALLOWED_PROJECT_ROOTS`: Comma-separated list of allowed project root paths for file operations in Edit mode. This is a critical security setting that restricts file read/write operations to specified directories. Example: `/path/to/project1,/path/to/project2`
+
 ### Custom Ignore Patterns
 
 You can specify additional directories to exclude by creating a `.cgrignore` file in your repository root:

codebase_rag/constants.py

@@ -421,11 +421,10 @@ class RelationshipType(StrEnum):
 
 CYPHER_QUERY_EMBEDDINGS = """
 MATCH (m:Module)-[:DEFINES]->(n)
-WHERE (n:Function OR n:Method)
-  AND m.qualified_name STARTS WITH $project_name
+WHERE n.project_name = $project_name
 RETURN id(n) AS node_id, n.qualified_name AS qualified_name,
        n.start_line AS start_line, n.end_line AS end_line,
-       m.path AS path
+       n.path AS path
 """
 
 

codebase_rag/graph_updater.py

@@ -262,9 +262,7 @@ def _is_dependency_file(self, file_name: str, filepath: Path) -> bool:
         )
 
     def run(self) -> None:
-        import os
-
-        absolute_path = Path(os.path.abspath(self.repo_path)).as_posix()
+        absolute_path = str(self.repo_path.absolute())
 
         self.ingestor.ensure_node_batch(
             cs.NODE_PROJECT,
@@ -378,7 +376,7 @@ def _generate_semantic_embeddings(self) -> None:
             logger.info(ls.PASS_4_EMBEDDINGS)
 
             results = self.ingestor.fetch_all(
-                cs.CYPHER_QUERY_EMBEDDINGS, {"project_name": self.project_name + "."}
+                cs.CYPHER_QUERY_EMBEDDINGS, {"project_name": self.project_name}
             )
 
             if not results:

codebase_rag/schemas.py

@@ -38,7 +38,6 @@ class CodeSnippet(BaseModel):
     qualified_name: str
     source_code: str
     file_path: str
-    relative_path: str | None = None
     project_name: str | None = None
     line_start: int
     line_end: int
@@ -55,8 +54,6 @@ class ShellCommandResult(BaseModel):
 
 class EditResult(BaseModel):
     file_path: str
-    relative_path: str | None = None
-    project_name: str | None = None
     success: bool = True
     error_message: str | None = None
 
@@ -69,8 +66,6 @@ def _set_success_on_error(self) -> EditResult:
 
 class FileReadResult(BaseModel):
     file_path: str
-    relative_path: str | None = None
-    project_name: str | None = None
     content: str | None = None
     error_message: str | None = None
 

codebase_rag/tools/code_retrieval.py

@@ -40,7 +40,6 @@ async def find_code_snippet(self, qualified_name: str) -> CodeSnippet:
 
             res = results[0]
             absolute_path_str = res.get("absolute_path")
-            relative_path_str = res.get("relative_path")
             project_name = res.get("project_name")
 
             if not absolute_path_str:
@@ -59,7 +58,6 @@ async def find_code_snippet(self, qualified_name: str) -> CodeSnippet:
                     qualified_name=qualified_name,
                     source_code="",
                     file_path=file_path_to_read or "",
-                    relative_path=relative_path_str,
                     project_name=project_name,
                     line_start=0,
                     line_end=0,
@@ -78,7 +76,6 @@ async def find_code_snippet(self, qualified_name: str) -> CodeSnippet:
                 qualified_name=qualified_name,
                 source_code=source_code,
                 file_path=file_path_to_read,
-                relative_path=relative_path_str,
                 project_name=project_name,
                 line_start=start_line,
                 line_end=end_line,

codebase_rag/tools/file_editor.py

@@ -268,17 +268,7 @@ async def _edit_validated(self, file_path: Path, new_content: str) -> EditResult
                 f.write(new_content)
 
             logger.success(ls.TOOL_FILE_EDIT_SUCCESS.format(path=file_path))
-
-            try:
-                relative_path_str = str(file_path.relative_to(self.project_root))
-            except ValueError:
-                relative_path_str = None
-
-            return EditResult(
-                file_path=str(file_path),
-                relative_path=relative_path_str,
-                success=True,
-            )
+            return EditResult(file_path=str(file_path), success=True)
 
         except Exception as e:
             error_msg = ls.UNEXPECTED.format(error=e)

codebase_rag/tools/file_reader.py

@@ -38,18 +38,7 @@ async def _read_validated(self, file_path: Path) -> FileReadResult:
             try:
                 content = file_path.read_text(encoding=cs.ENCODING_UTF8)
                 logger.info(ls.TOOL_FILE_READ_SUCCESS.format(path=file_path))
-
-                absolute_path_str = str(file_path)
-                try:
-                    relative_path_str = str(file_path.relative_to(self.project_root))
-                except ValueError:
-                    relative_path_str = None
-
-                return FileReadResult(
-                    file_path=absolute_path_str,
-                    relative_path=relative_path_str,
-                    content=content,
-                )
+                return FileReadResult(file_path=str(file_path), content=content)
             except UnicodeDecodeError:
                 error_msg = te.UNICODE_DECODE.format(path=file_path)
                 logger.warning(ls.TOOL_FILE_BINARY.format(message=error_msg))

tests/test_cross_project_access.py

@@ -86,14 +86,12 @@ def test_path_fields_in_schema(self):
             qualified_name="test.func",
             source_code="def test(): pass",
             file_path="/absolute/path/test.py",
-            relative_path="test.py",
             project_name="test_project",
             line_start=1,
             line_end=2,
         )
 
         assert snippet.file_path == "/absolute/path/test.py"
-        assert snippet.relative_path == "test.py"
         assert snippet.project_name == "test_project"