fix: project structure

Author: qduc

AGENTS.md

@@ -53,11 +53,11 @@ Environment variables control defaults:
 - `CODE_RAG_DATABASE_TYPE`: "chroma" or "qdrant"
 - `CODE_RAG_EMBEDDING_MODEL`: Model name
 - `CODE_RAG_CHUNK_SIZE`: Characters per chunk
-- See `src/config/config.py` for full list
+- See `src/code_rag/config/config.py` for full list
 
 ### 5. Entry Points
-- **CLI** (`code-rag`): Interactive query session
-- **MCP Server** (`code-rag-mcp`): Exposes search to AI assistants (Claude, etc.)
+- **CLI** (`code-rag-cli`): Interactive query session
+- **MCP Server** (`code-rag` or `code-rag-mcp`): Exposes search to AI assistants (Claude, etc.)
 - **Embedding Server** (`code-rag-server`): Shared model server for multiple MCP instances
 
 ### 6. Shared Embedding Server
@@ -73,24 +73,27 @@ Configuration (via environment):
 - `CODE_RAG_SHARED_SERVER_PORT=8199`
 
 Files:
-- `src/embedding_server.py` - FastAPI server
-- `src/embeddings/http_embedding.py` - HTTP client for embedding
-- `src/reranker/http_reranker.py` - HTTP client for reranking
+- `src/code_rag/embedding_server.py` - FastAPI server
+- `src/code_rag/embeddings/http_embedding.py` - HTTP client for embedding
+- `src/code_rag/reranker/http_reranker.py` - HTTP client for reranking
 
 ## Quick Start
 
 ```bash
 # Install
 pip install -e .
 
-# Index current directory and start querying
+# Run MCP server (default)
 code-rag
 
+# Index and start querying via CLI
+code-rag-cli
+
 # Index specific repo with different database
-code-rag --path /path/to/repo --database qdrant
+code-rag-cli --path /path/to/repo --database qdrant
 
 # Force reindexing
-code-rag --reindex
+code-rag-cli --reindex
 ```
 
 ## Common Tasks
@@ -108,12 +111,12 @@ code-rag --reindex
 → Extend `SyntaxChunker.LANGUAGE_PACKAGES` with tree-sitter binding
 
 **Add new MCP tools?**
-→ Update `list_tools()` and `call_tool()` in `src/mcp_server.py`
+→ Update `list_tools()` and `call_tool()` in `src/code_rag/mcp_server.py`
 
 ## Where to Learn More
 
 - **Implementation details**: See `IMPLEMENTATION.md`
-- **Code**: Start with `src/main.py` (CLI orchestration)
+- **Code**: Start with `src/code_rag/main.py` (CLI orchestration)
 - **Tests**: `pytest` to run test suite
 - **Questions?**: Read the code - it's well-structured and follows the plugin pattern
 

PUBLISH.md

@@ -47,6 +47,6 @@ twine upload dist/*
 
 ## 7. Versioning
 To publish a new version later:
-1. Update the version in `pyproject.toml` and `src/__init__.py`.
+1. Update the version in `pyproject.toml` and `src/code_rag/__init__.py`.
 2. Delete the old `dist/` folder.
 3. Repeat steps 3, 4, and 6.

README.md

@@ -14,24 +14,25 @@ source .venv/bin/activate
 # Install
 pip install -e .
 
-# Index and search your codebase
+# Start the MCP server (default)
 code-rag
 
-# That's it. Start asking questions about your code.
+# Or use the interactive CLI search
+code-rag-cli
 ```
 
-## Example
+## Example (CLI)
 
 ```
-$ code-rag --path /home/user/myproject
+$ code-rag-cli --path /home/user/myproject
 
 Processing codebase... Found 247 files
 Indexed 1,234 chunks in 12s
 
 Query: authentication logic
 
 Result 1 | Similarity: 0.85
-File: src/auth/authenticator.py (lines 45-78)
+File: src/code_rag/auth/authenticator.py (lines 45-78)
 
 class Authenticator:
     """Handle user authentication and session management."""
@@ -134,7 +135,7 @@ Once configured, Claude can automatically search your codebase:
 You: "Find the database connection logic"
 
 Claude: [Automatically searches and finds the code]
-        "I found the database connection logic in src/db/connection.py..."
+        "I found the database connection logic in src/code_rag/db/connection.py..."
 ```
 
 See [docs/mcp.md](docs/mcp.md) for detailed setup and troubleshooting.
@@ -143,19 +144,19 @@ See [docs/mcp.md](docs/mcp.md) for detailed setup and troubleshooting.
 
 ```bash
 # Different codebase
-code-rag --path /path/to/repo
+code-rag-cli --path /path/to/repo
 
 # Force reindex
-code-rag --reindex
+code-rag-cli --reindex
 
 # More results
-code-rag --results 10
+code-rag-cli --results 10
 
 # Different embedding model (better for code)
-code-rag --model text-embedding-3-small # need to set OPENAI_API_KEY env
+code-rag-cli --model text-embedding-3-small # need to set OPENAI_API_KEY env
 
 # Use Qdrant instead of ChromaDB
-code-rag --database qdrant
+code-rag-cli --database qdrant
 ```
 
 ## Configuration
@@ -225,7 +226,7 @@ Pluggable architecture - swap databases, embedding models, or add new ones.
 Use programmatically:
 
 ```python
-from src.api import CodeRAGAPI
+from code_rag.api import CodeRAGAPI
 
 api = CodeRAGAPI(database_type="chroma", embedding_model="all-MiniLM-L6-v2")
 api.initialize_collection("myproject")

docs/IMPLEMENTATION.md

@@ -41,7 +41,7 @@ This document contains detailed implementation notes, patterns, and design decis
 Each chunk includes:
 ```python
 {
-    "file_path": "src/example.py",
+    "file_path": "src/code_rag/example.py",
     "chunk_index": 0,           # Position in file (0-indexed)
     "total_chunks": 5,          # Total chunks from this file
     "content": "chunk text..."  # The actual code chunk
@@ -227,7 +227,7 @@ Embedding models:
 
 ### Environment Variables
 
-Located in `src/config/config.py`. All have fallback defaults:
+Located in `src/code_rag/config/config.py`. All have fallback defaults:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
@@ -403,7 +403,7 @@ elif args.database == "qdrant":
 pytest
 
 # With coverage
-pytest --cov=src
+pytest --cov=code_rag
 
 # Specific module
 pytest tests/test_file_processor.py
@@ -419,13 +419,13 @@ pytest tests/test_file_processor.py
 
 ```bash
 # Format code
-black src/
+black src/code_rag/
 
 # Lint
-flake8 src/
+flake8 src/code_rag/
 
 # Type checking (if configured)
-mypy src/
+mypy src/code_rag/
 ```
 
 ---

docs/mcp.md

@@ -16,20 +16,21 @@ The **final design** intentionally exposes **one tool only**:
 From the project root:
 
 ```bash
-cd /ub/home/qduc/src/code-rag
+cd /ub/home/qduc/src/code_rag/code-rag
 pip install -e .
 ```
 
 This installs:
 
-- `code-rag` (CLI)
-- `code-rag-mcp` (MCP server entry point)
+- `code-rag` (MCP server - default)
+- `code-rag-cli` (CLI search tool)
+- `code-rag-mcp` (MCP server alias)
 - All required dependencies, including `mcp>=0.9.0`
 
 Verify that the MCP server is on your PATH:
 
 ```bash
-which code-rag-mcp
+which code-rag
 ```
 
 ---
@@ -42,16 +43,16 @@ The MCP server uses stdio transport.
 
 ```bash
 claude mcp add code-rag \
-  --type stdio \
-  -- code-rag-mcp
+  --transport stdio \
+  -- code-rag
 ```
 
 If necessary, you can register it with an explicit path:
 
 ```bash
 claude mcp add code-rag \
   --type stdio \
-  -- /ub/home/qduc/src/code-rag/.venv/bin/code-rag-mcp
+  -- /ub/home/qduc/src/code_rag/code-rag/.venv/bin/code-rag-mcp
 ```
 
 ### Manual configuration (JSON)
@@ -182,8 +183,8 @@ model, regardless of this variable.
 2. Claude calls:
    - `search_codebase(codebase_path="/home/user/myapp", query="user authentication implementation")`
 3. Claude returns locations such as:
-   - `src/auth/authenticator.py` (main authentication logic)
-   - `src/middleware/auth.py` (authentication middleware)
+   - `src/code_rag/auth/authenticator.py` (main authentication logic)
+   - `src/code_rag/middleware/auth.py` (authentication middleware)
 4. If the user wants more context, Claude uses its own file-reading capability to show full files.
 
 ---
@@ -192,8 +193,8 @@ model, regardless of this variable.
 
 ### API and MCP layering
 
-- `CodeRAGAPI` (`src/api.py`) provides a clean, reusable façade over the core Code-RAG pipeline (initialize collection, index, search, get chunks, stats, close).
-- `src/mcp_server.py` hosts the MCP server and exposes that API as tools for Claude over stdio.
+- `CodeRAGAPI` (`src/code_rag/api.py`) provides a clean, reusable façade over the core Code-RAG pipeline (initialize collection, index, search, get chunks, stats, close).
+- `src/code_rag/mcp_server.py` hosts the MCP server and exposes that API as tools for Claude over stdio.
 - The same API can later back other interfaces (e.g., HTTP, gRPC) without changing core logic.
 
 ### Single-tool, auto-indexing design (final)

pyproject.toml

@@ -3,8 +3,8 @@ requires = ["setuptools>=61.0"]
 build-backend = "setuptools.build_meta"
 
 [project]
-name = "code-rag"
-version = "0.1.0"
+name = "code-rag-mcp"
+version = "0.1.2"
 description = "MCP server for efficient code search"
 readme = "README.md"
 requires-python = ">=3.10, <3.14"
@@ -60,7 +60,8 @@ dev = [
 ]
 
 [project.scripts]
-code-rag = "code_rag.main:main"
+code-rag = "code_rag.mcp_server:main"
+code-rag-cli = "code_rag.main:main"
 code-rag-mcp = "code_rag.mcp_server:main"
 code-rag-server = "code_rag.embedding_server:main"
 
@@ -69,10 +70,18 @@ Homepage = "https://github.com/qduc/code-rag"
 Issues = "https://github.com/qduc/code-rag/issues"
 
 [tool.setuptools]
-packages = ["code_rag"]
+packages = [
+    "code_rag",
+    "code_rag.config",
+    "code_rag.database",
+    "code_rag.embeddings",
+    "code_rag.index",
+    "code_rag.processor",
+    "code_rag.reranker",
+]
 
 [tool.setuptools.package-dir]
-code_rag = "src"
+"" = "src"
 
 [tool.black]
 line-length = 88

src/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running the package as a module: python -m code_rag"""
+
+from .mcp_server import main
+
+if __name__ == "__main__":
+    main()

src/__init__.py src/code_rag/__init__.pysrc/__init__.py renamed to src/code_rag/__init__.py

@@ -520,7 +520,7 @@ def search(
             collection_name: Name of the collection to search (uses active collection if None)
             expand_context: If True, fetch adjacent chunks to provide more context
             file_types: Optional list of file extensions to filter by (e.g. ['.py', '.md'])
-            include_paths: Optional list of path substrings to include (e.g. ['src/', 'tests/'])
+            include_paths: Optional list of path substrings to include (e.g. ['src/code_rag/', 'tests/'])
 
         Returns:
             List of search results, each containing: