codegraphcontext 0.1.9__tar.gz → 0.1.10__tar.gz

{codegraphcontext-0.1.9/src/codegraphcontext.egg-info → codegraphcontext-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codegraphcontext
-Version: 0.1.9
+Version: 0.1.10
 Summary: An MCP server that indexes local code into a graph database to provide context to AI assistants.
 Author-email: Shashank Shekhar Singh <shashankshekharsingh1205@gmail.com>
 License: MIT License
@@ -60,9 +60,10 @@ Dynamic: license-file
 An MCP server that indexes local code into a graph database to provide context to AI assistants.
 
 ## Project Details
-- **Version:** 0.1.8
+- **Version:** 0.1.10
 - **Authors:** Shashank Shekhar Singh <shashankshekharsingh1205@gmail.com>
 - **License:** MIT License (See [LICENSE](LICENSE) for details)
+- **Website:** [CodeGraphContext](http://code-graph-context.vercel.app/)
 
 ## Features
 
@@ -96,8 +97,15 @@ If you’re using CodeGraphContext in your project, feel free to open a PR and a
 
 1.  **Install:** `pip install codegraphcontext`
 2.  **Setup:** `cgc setup`
+    This interactive command guides you through configuring your Neo4j database connection. It offers several options:
+    *   **Local Setup (Docker Recommended):** Helps you set up a local Neo4j instance using Docker, which is the easiest way to get started.
+    *   **Local Setup (Linux Binary):** For Debian-based Linux systems (like Ubuntu), `cgc setup` can automate the installation of Neo4j directly on your machine.
+    *   **Hosted Setup:** Allows you to connect to an existing remote Neo4j database (e.g., Neo4j AuraDB).
+    Upon successful configuration, `cgc setup` will generate two important files:
+    *   `mcp.json`: Contains the MCP client configuration for CodeGraphContext.
+    *   `~/.codegraphcontext/.env`: Stores your Neo4j connection credentials securely.
 3.  **Start:** `cgc start`
-4.  **Index Code:** `cgc tool add-code-to-graph '{"path": "/path/to/your/project"}'` (Under active development)
+
 
 ## MCP Client Configuration
 
@@ -205,6 +213,7 @@ Once the server is running, you can interact with it through your AI assistant u
 ## Contributing
 
 Contributions are welcome! 🎉  
+Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
 If you have ideas for new features, integrations, or improvements, open an [issue](https://github.com/Shashankss1205/CodeGraphContext/issues) or submit a PR.
 
 Join discussions and help shape the future of CodeGraphContext.

{codegraphcontext-0.1.9 → codegraphcontext-0.1.10}/README.md

@@ -8,9 +8,10 @@
 An MCP server that indexes local code into a graph database to provide context to AI assistants.
 
 ## Project Details
-- **Version:** 0.1.8
+- **Version:** 0.1.10
 - **Authors:** Shashank Shekhar Singh <shashankshekharsingh1205@gmail.com>
 - **License:** MIT License (See [LICENSE](LICENSE) for details)
+- **Website:** [CodeGraphContext](http://code-graph-context.vercel.app/)
 
 ## Features
 
@@ -44,8 +45,15 @@ If you’re using CodeGraphContext in your project, feel free to open a PR and a
 
 1.  **Install:** `pip install codegraphcontext`
 2.  **Setup:** `cgc setup`
+    This interactive command guides you through configuring your Neo4j database connection. It offers several options:
+    *   **Local Setup (Docker Recommended):** Helps you set up a local Neo4j instance using Docker, which is the easiest way to get started.
+    *   **Local Setup (Linux Binary):** For Debian-based Linux systems (like Ubuntu), `cgc setup` can automate the installation of Neo4j directly on your machine.
+    *   **Hosted Setup:** Allows you to connect to an existing remote Neo4j database (e.g., Neo4j AuraDB).
+    Upon successful configuration, `cgc setup` will generate two important files:
+    *   `mcp.json`: Contains the MCP client configuration for CodeGraphContext.
+    *   `~/.codegraphcontext/.env`: Stores your Neo4j connection credentials securely.
 3.  **Start:** `cgc start`
-4.  **Index Code:** `cgc tool add-code-to-graph '{"path": "/path/to/your/project"}'` (Under active development)
+
 
 ## MCP Client Configuration
 
@@ -153,6 +161,7 @@ Once the server is running, you can interact with it through your AI assistant u
 ## Contributing
 
 Contributions are welcome! 🎉  
+Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
 If you have ideas for new features, integrations, or improvements, open an [issue](https://github.com/Shashankss1205/CodeGraphContext/issues) or submit a PR.
 
 Join discussions and help shape the future of CodeGraphContext.

{codegraphcontext-0.1.9 → codegraphcontext-0.1.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "codegraphcontext"
-version = "0.1.9"
+version = "0.1.10"
 description = "An MCP server that indexes local code into a graph database to provide context to AI assistants."
 authors = [{ name = "Shashank Shekhar Singh", email = "shashankshekharsingh1205@gmail.com" }]
 readme = "README.md"

{codegraphcontext-0.1.9 → codegraphcontext-0.1.10}/src/codegraphcontext/cli/main.py

@@ -1,4 +1,15 @@
 # src/codegraphcontext/cli/main.py
+"""
+This module defines the command-line interface (CLI) for the CodeGraphContext application.
+It uses the Typer library to create a user-friendly and well-documented CLI.
+
+Commands:
+- setup: Runs an interactive wizard to configure the Neo4j database connection.
+- start: Launches the main MCP server.
+- tool: A placeholder for directly calling server tools (for debugging).
+- help: Displays help information.
+- version: Show the installed version.
+"""
 import typer
 from rich.console import Console
 import asyncio
@@ -7,12 +18,14 @@ import json
 import os
 from pathlib import Path
 from dotenv import load_dotenv, find_dotenv
+from importlib.metadata import version as pkg_version, PackageNotFoundError
 from codegraphcontext.server import MCPServer
 from .setup_wizard import run_setup_wizard
 
-# Set the log level for the noisy neo4j logger to WARNING
-logging.getLogger("neo4j").setLevel(logging.WARNING) # <-- ADD THIS LINE
+# Set the log level for the noisy neo4j logger to WARNING to keep the output clean.
+logging.getLogger("neo4j").setLevel(logging.WARNING)
 
+# Initialize the Typer app and Rich console for formatted output.
 app = typer.Typer(
     name="cgc",
     help="CodeGraphContext: An MCP server for AI-powered code analysis.",
@@ -20,29 +33,49 @@ app = typer.Typer(
 )
 console = Console()
 
+# Configure basic logging for the application.
 logging.basicConfig(level=logging.INFO, format='%(asctime)s - %(levelname)s - %(name)s - %(message)s')
 
+
+def get_version() -> str:
+    """
+    Try to read version from the installed package metadata.
+    Fallback to a dev version if not installed.
+    """
+    try:
+        return pkg_version("codegraphcontext")  # must match [project].name in pyproject.toml
+    except PackageNotFoundError:
+        return "0.0.0 (dev)"
+
+
 @app.command()
 def setup():
     """
-    Run the interactive setup wizard to configure the server and database.
+    Runs the interactive setup wizard to configure the server and database connection.
+    This helps users set up a local Docker-based Neo4j instance or connect to a remote one.
     """
     run_setup_wizard()
 
 @app.command()
 def start():
     """
-    Start the CodeGraphContext MCP server.
+    Starts the CodeGraphContext MCP server, which listens for JSON-RPC requests from stdin.
+    It first attempts to load Neo4j credentials from various sources before starting.
     """
     console.print("[bold green]Starting CodeGraphContext Server...[/bold green]")
-    
-    # 1. Prefer loading environment variables from mcp.json in the current directory
+
+    # The server needs Neo4j credentials. It attempts to load them in the following order of priority:
+    # 1. From a local `mcp.json` file in the current working directory.
+    # 2. From a global `.env` file at `~/.codegraphcontext/.env`.
+    # 3. From any `.env` file found by searching upwards from the current directory.
+
+    # 1. Prefer loading environment variables from mcp.json in the current directory.
     mcp_file_path = Path.cwd() / "mcp.json"
     if mcp_file_path.exists():
         try:
             with open(mcp_file_path, "r") as f:
                 mcp_config = json.load(f)
-            
+
             server_env = mcp_config.get("mcpServers", {}).get("CodeGraphContext", {}).get("env", {})
             for key, value in server_env.items():
                 os.environ[key] = value
@@ -51,7 +84,7 @@ def start():
             console.print(f"[bold red]Error loading mcp.json:[/bold red] {e}")
             console.print("[yellow]Attempting to start server without mcp.json environment variables.[/yellow]")
     else:
-        # 2. If no local mcp.json, try to load from ~/.codegraphcontext/.env
+        # 2. If no local mcp.json, try to load from the global config directory.
         global_env_path = Path.home() / ".codegraphcontext" / ".env"
         if global_env_path.exists():
             try:
@@ -61,30 +94,34 @@ def start():
                 console.print(f"[bold red]Error loading global .env file from {global_env_path}:[/bold red] {e}")
                 console.print("[yellow]Attempting to start server without .env environment variables.[/yellow]")
         else:
-            # Fallback: try to load from a .env file found by find_dotenv (searches up the tree)
+            # 3. Fallback: try to load from any .env file found by searching up the directory tree.
             try:
                 dotenv_path = find_dotenv(usecwd=True, raise_error_if_not_found=False)
                 if dotenv_path:
                     load_dotenv(dotenv_path)
-                    console.print(f"[green]Loaded Neo4j credentials from global .env file: {dotenv_path}[/green]")
+                    console.print(f"[green]Loaded Neo4j credentials from discovered .env file: {dotenv_path}[/green]")
                 else:
                     console.print("[yellow]No local mcp.json or global .env file found. Attempting to start server without explicit Neo4j credentials.[/yellow]")
             except Exception as e:
-                console.print(f"[bold red]Error loading global .env file:[/bold red] {e}")
+                console.print(f"[bold red]Error loading .env file:[/bold red] {e}")
                 console.print("[yellow]Attempting to start server without .env environment variables.[/yellow]")
 
     server = None
     loop = asyncio.new_event_loop()
     asyncio.set_event_loop(loop)
     try:
+        # Initialize and run the main server.
         server = MCPServer(loop=loop)
         loop.run_until_complete(server.run())
     except ValueError as e:
+        # This typically happens if credentials are still not found after all checks.
         console.print(f"[bold red]Configuration Error:[/bold red] {e}")
         console.print("Please run `cgc setup` to configure the server.")
     except KeyboardInterrupt:
+        # Handle graceful shutdown on Ctrl+C.
         console.print("\n[bold yellow]Server stopped by user.[/bold yellow]")
     finally:
+        # Ensure server and event loop are properly closed.
         if server:
             server.shutdown()
         loop.close()
@@ -96,46 +133,51 @@ def tool(
     args: str = typer.Argument("{}", help="A JSON string of arguments for the tool."),
 ):
     """
-    Directly call a CodeGraphContext tool.
-    Note: This command instantiates a new, independent MCP server instance for each call.
-    Therefore, it does not share state (like job IDs) with a server started via `cgc start`.
-
-    This command can be used for:\n
-    - `add_code_to_graph`: Index a new project or directory. Args: `path` (str), `is_dependency` (bool, optional)\n
-    - `add_package_to_graph`: Add a Python package to the graph. Args: `package_name` (str), `is_dependency` (bool, optional)\n
-    - `find_code`: Search for code snippets. Args: `query` (str)\n
-    - `analyze_code_relationships`: Analyze code relationships (e.g., callers, callees). Args: `query_type` (str), `target` (str), `context` (str, optional)\n
-    - `watch_directory`: Start watching a directory for changes. Args: `path` (str)\n
-    - `execute_cypher_query`: Run direct Cypher queries. Args: `cypher_query` (str)\n
-    - `list_imports`: List imports from files. Args: `path` (str), `language` (str, optional), `recursive` (bool, optional)\n
-    - `find_dead_code`: Find potentially unused functions. Args: None\n
-    - `calculate_cyclomatic_complexity`: Calculate function complexity. Args: `function_name` (str), `file_path` (str, optional)\n
-    - `find_most_complex_functions`: Find the most complex functions. Args: `limit` (int, optional)\n
-    - `list_indexed_repositories`: List indexed repositories. Args: None\n
-    - `delete_repository`: Delete an indexed repository. Args: `repo_path` (str)
-    """
+    Directly call a CodeGraphContext tool from the command line.
 
-    # This is a placeholder for a more advanced tool caller that would
-    # connect to the running server via a different mechanism (e.g., a socket).
-    # For now, it's a conceptual part of the CLI.
+    IMPORTANT: This is a placeholder for debugging and does not connect to a running
+    server. It creates a new, temporary server instance for each call, so it cannot
+    be used to check the status of jobs started by `cgc start`.
+    """
     console.print(f"Calling tool [bold cyan]{name}[/bold cyan] with args: {args}")
     console.print("[yellow]Note: This is a placeholder for direct tool invocation.[/yellow]")
 
 @app.command()
 def help(ctx: typer.Context):
-    """Show this message and exit."""
+    """Show the main help message and exit."""
     root_ctx = ctx.parent or ctx
     typer.echo(root_ctx.get_help())
 
 
+@app.command("version")
+def version_cmd():
+    """Show the application version."""
+    console.print(f"CodeGraphContext [bold cyan]{get_version()}[/bold cyan]")
+
+
 @app.callback(invoke_without_command=True)
-def main(ctx: typer.Context):
+def main(
+    ctx: typer.Context,
+    version_: bool = typer.Option(
+        None,
+        "--version",
+        "-v",
+        help="Show the application version and exit.",
+        is_eager=True,
+    ),
+):
     """
-    CodeGraphContext: An MCP server for AI-powered code analysis.
+    Main entry point for the cgc CLI application.
+    If no subcommand is provided, it displays a welcome message with instructions.
     """
+    if version_:
+        console.print(f"CodeGraphContext [bold cyan]{get_version()}[/bold cyan]")
+        raise typer.Exit()
+
     if ctx.invoked_subcommand is None:
         console.print("[bold green]👋 Welcome to CodeGraphContext (cgc)![/bold green]\n")
         console.print("👉 Run [cyan]cgc setup[/cyan] to configure the server and database.")
         console.print("👉 Run [cyan]cgc start[/cyan] to launch the server.")
         console.print("👉 Run [cyan]cgc help[/cyan] to see all available commands.\n")
+        console.print("👉 Run [cyan]cgc --version[/cyan] to check the version.\n")
         console.print("👉 Running [green]codegraphcontext [white]works the same as using [green]cgc")

{codegraphcontext-0.1.9 → codegraphcontext-0.1.10}/src/codegraphcontext/core/database.py

@@ -1,4 +1,7 @@
 # src/codegraphcontext/core/database.py
+"""
+This module provides a thread-safe singleton manager for the Neo4j database connection.
+"""
 import os
 import logging
 import threading
@@ -10,20 +13,30 @@ logger = logging.getLogger(__name__)
 
 class DatabaseManager:
     """
-    Singleton class to manage Neo4j database connections.
+    Manages the Neo4j database driver as a singleton to ensure only one
+    connection pool is created and shared across the application.
+    
+    This pattern is crucial for performance and resource management in a
+    multi-threaded or asynchronous application.
     """
     _instance = None
     _driver: Optional[Driver] = None
-    _lock = threading.Lock()
+    _lock = threading.Lock() # Lock to ensure thread-safe initialization. 
 
     def __new__(cls):
+        """Standard singleton pattern implementation."""
         if cls._instance is None:
             with cls._lock:
+                # Double-check locking to prevent race conditions.
                 if cls._instance is None:
                     cls._instance = super(DatabaseManager, cls).__new__(cls)
         return cls._instance
 
     def __init__(self):
+        """
+        Initializes the manager by reading credentials from environment variables.
+        The `_initialized` flag prevents re-initialization on subsequent calls.
+        """
         if hasattr(self, '_initialized'):
             return
 
@@ -33,10 +46,20 @@ class DatabaseManager:
         self._initialized = True
 
     def get_driver(self) -> Driver:
-        """Get the Neo4j driver instance"""
+        """
+        Gets the Neo4j driver instance, creating it if it doesn't exist.
+        This method is thread-safe.
+
+        Raises:
+            ValueError: If Neo4j credentials are not set in environment variables.
+
+        Returns:
+            The active Neo4j Driver instance.
+        """
         if self._driver is None:
             with self._lock:
                 if self._driver is None:
+                    # Ensure all necessary credentials are provided.
                     if not all([self.neo4j_uri, self.neo4j_username, self.neo4j_password]):
                         raise ValueError(
                             "Neo4j credentials must be set via environment variables:\n"
@@ -50,7 +73,7 @@ class DatabaseManager:
                         self.neo4j_uri,
                         auth=(self.neo4j_username, self.neo4j_password)
                     )
-                    # Test the connection
+                    # Test the connection immediately to fail fast if credentials are wrong.
                     try:
                         with self._driver.session() as session:
                             session.run("RETURN 1").consume()
@@ -64,7 +87,7 @@ class DatabaseManager:
         return self._driver
 
     def close_driver(self):
-        """Close the Neo4j driver"""
+        """Closes the Neo4j driver connection if it exists."""
         if self._driver is not None:
             with self._lock:
                 if self._driver is not None:
@@ -73,7 +96,7 @@ class DatabaseManager:
                     self._driver = None
 
     def is_connected(self) -> bool:
-        """Check if connected to database"""
+        """Checks if the database connection is currently active."""
         if self._driver is None:
             return False
         try:
@@ -81,4 +104,4 @@ class DatabaseManager:
                 session.run("RETURN 1").consume()
             return True
         except Exception:
-            return False
+            return False

{codegraphcontext-0.1.9 → codegraphcontext-0.1.10}/src/codegraphcontext/core/jobs.py

@@ -1,4 +1,8 @@
 # src/codegraphcontext/core/jobs.py
+"""
+This module defines the data structures and manager for handling long-running,
+background jobs, such as code indexing.
+"""
 import uuid
 import threading
 from datetime import datetime, timedelta
@@ -9,7 +13,7 @@ from pathlib import Path
 
 
 class JobStatus(Enum):
-    """Job status enumeration"""
+    """Enumeration for the possible statuses of a background job."""
     PENDING = "pending"
     RUNNING = "running"
     COMPLETED = "completed"
@@ -18,7 +22,10 @@ class JobStatus(Enum):
 
 @dataclass
 class JobInfo:
-    """Data class for job information"""
+    """
+    A data class to hold all information about a single background job.
+    This makes it easy to track the job's progress, status, and results.
+    """
     job_id: str
     status: JobStatus
     start_time: datetime
@@ -34,19 +41,20 @@ class JobInfo:
     is_dependency: bool = False
 
     def __post_init__(self):
+        """Ensures the errors list is initialized after the object is created."""
         if self.errors is None:
             self.errors = []
 
     @property
     def progress_percentage(self) -> float:
-        """Calculate progress percentage"""
+        """Calculates the completion percentage of the job."""
         if self.total_files == 0:
             return 0.0
         return (self.processed_files / self.total_files) * 100
 
     @property
     def estimated_time_remaining(self) -> Optional[float]:
-        """Calculate estimated time remaining"""
+        """Calculates the estimated time remaining based on the average time per file."""
         if self.status != JobStatus.RUNNING or self.processed_files == 0:
             return None
         elapsed = (datetime.now() - self.start_time).total_seconds()
@@ -55,13 +63,16 @@ class JobInfo:
         return remaining_files * avg_time_per_file
 
 class JobManager:
-    """Manager for background jobs"""
+    """
+    A thread-safe manager for creating, updating, and retrieving information
+    about background jobs. It stores job information in memory.
+    """
     def __init__(self):
         self.jobs: Dict[str, JobInfo] = {}
-        self.lock = threading.Lock()
+        self.lock = threading.Lock() # A lock to ensure thread-safe access to the jobs dictionary.
 
     def create_job(self, path: str, is_dependency: bool = False) -> str:
-        """Create a new job and return job ID"""
+        """Creates a new job, assigns it a unique ID, and stores it."""
         job_id = str(uuid.uuid4())
         with self.lock:
             self.jobs[job_id] = JobInfo(
@@ -74,7 +85,7 @@ class JobManager:
         return job_id
 
     def update_job(self, job_id: str, **kwargs):
-        """Update job information"""
+        """Updates the information for a specific job in a thread-safe manner."""
         with self.lock:
             if job_id in self.jobs:
                 job = self.jobs[job_id]
@@ -83,17 +94,17 @@ class JobManager:
                         setattr(job, key, value)
 
     def get_job(self, job_id: str) -> Optional[JobInfo]:
-        """Get job information"""
+        """Retrieves the information for a single job."""
         with self.lock:
             return self.jobs.get(job_id)
 
     def list_jobs(self) -> List[JobInfo]:
-        """List all jobs"""
+        """Returns a list of all jobs currently in the manager."""
         with self.lock:
             return list(self.jobs.values())
 
     def find_active_job_by_path(self, path: str) -> Optional[JobInfo]:
-        """Finds the most recent, active job for a given path."""
+        """Finds the most recent, currently active (pending or running) job for a given path."""
         with self.lock:
             path_obj = Path(path).resolve()
             
@@ -110,7 +121,7 @@ class JobManager:
             return None
 
     def cleanup_old_jobs(self, max_age_hours: int = 24):
-        """Clean up jobs older than specified hours"""
+        """Removes old, completed jobs from memory to prevent memory leaks."""
         cutoff_time = datetime.now() - timedelta(hours=max_age_hours)
         with self.lock:
             jobs_to_remove = [
@@ -118,4 +129,4 @@ class JobManager:
                 if job.end_time and job.end_time < cutoff_time
             ]
             for job_id in jobs_to_remove:
-                del self.jobs[job_id]
+                del self.jobs[job_id]