code-index-mcp 0.1.0__tar.gz

code_index_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2015 johnhuang316
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

code_index_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,321 @@
+Metadata-Version: 2.4
+Name: code-index-mcp
+Version: 0.1.0
+Summary: Code indexing and analysis tools for LLMs using MCP
+Author: johnhuang316
+License: MIT
+Project-URL: Homepage, https://github.com/johnhuang316/code-index-mcp
+Project-URL: Bug Tracker, https://github.com/johnhuang316/code-index-mcp/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=0.3.0
+Dynamic: license-file
+
+# Code Index MCP
+
+Code Index MCP is a Model Context Protocol server that enables large language models (LLMs) to index, search, and analyze code in project directories.
+
+## Features
+
+- Index and navigate project file structures
+- Search for specific patterns in code
+- Get detailed file summaries
+- Analyze code structure and complexity
+- Support for multiple programming languages
+- Persistent storage of project settings
+
+## Installation
+
+This project uses the following tools:
+
+1. **uv**: A fast Python package manager for dependency installation (recommended but optional)
+2. **code-indexer** or **uvx**: Command-line entry points provided by this package to run the Code Index MCP server
+
+> **Note about `uvx`**: Our `uvx` command is a custom entry point defined in this package, and is not related to the `uvx` command from the uv package manager (which is an alias for `uv tool run`). If you have both installed, you can use the full path to our `uvx` command or use the `code-indexer` command instead to avoid conflicts.
+
+### Installation Steps
+
+1. Ensure you have Python 3.10 or later installed
+
+2. Install uv (recommended but not required):
+   ```bash
+   # Windows
+   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+   # macOS/Linux
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
+
+3. Install the code-index-mcp package to get the command-line tools:
+   ```bash
+   # Using uv (recommended)
+   uv pip install code-index-mcp
+
+   # Or using traditional pip
+   pip install code-index-mcp
+   ```
+
+4. After installation, you can use either the `code-indexer` or `uvx` command (both do the same thing):
+   ```bash
+   # Using code-indexer
+   code-indexer /path/to/your/project
+
+   # Or using uvx
+   uvx /path/to/your/project
+   ```
+
+   Note: Both commands are entry points defined in this package that run the same code. If you have the uv package manager installed, be aware that it also has a command called `uvx` (which is an alias for `uv tool run`). To avoid conflicts, you can:
+
+   - Use the full path to our `uvx` command
+   - Use the `code-indexer` command instead
+   - Create an alias in your shell for our `uvx` command
+
+### Installing from Source
+
+If you want to install from source code:
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/johnhuang316/code-index-mcp.git
+   cd code-index-mcp
+   ```
+
+2. Install the package (this will also install the command-line tools):
+   ```bash
+   # Using uv (recommended)
+   uv pip install -e .
+
+   # Or using traditional pip
+   pip install -e .
+   ```
+
+   This will make both the `code-indexer` and `uvx` commands available in your environment.
+
+## Usage
+
+### Running the Server Directly
+
+There are multiple ways to run the server:
+
+```bash
+# Using the code-indexer command (requires installing the package first)
+code-indexer
+
+# Or using the uvx command (requires installing the package first)
+uvx
+
+# Using uv to run the script directly (doesn't require installing the package)
+uv run run.py
+
+# Using Python directly (doesn't require installing the package)
+python -m code_index_mcp.server
+```
+
+Note: When run without arguments, both `code-indexer` and `uvx` will start the server without setting a project path. You'll need to set the project path using the `set_project_path` tool after connecting.
+
+> **Important**: If you have the uv package manager installed, be aware that it also provides a command called `uvx` (which is an alias for `uv tool run`). To avoid command conflicts, you can use the full path to our `uvx` command, use `code-indexer` instead, or create a shell alias.
+
+UV will automatically handle all dependency installations based on the project's configuration.
+
+### Using Docker
+
+You can also use Code Index MCP as a containerized tool with Docker:
+
+```bash
+# Build the Docker image
+docker build -t code-index-mcp .
+
+# Use the container as a tool to analyze your code
+docker run --rm -i code-index-mcp
+```
+
+This containerized approach works well with Claude Desktop, which treats MCP servers as on-demand processes rather than persistent servers. Claude Desktop will start the container when needed and communicate with it via stdio, keeping it running only for the duration of the session.
+
+When using the containerized version, you'll need to set the project path explicitly using the `set_project_path` tool, just like in the non-containerized version.
+
+### Integrating with Claude Desktop
+
+You can easily integrate Code Index MCP with Claude Desktop:
+
+#### Prerequisites
+
+1. Make sure you have completed the appropriate installation steps above
+2. Verify that the command you plan to use is available:
+   - For Option 1: Verify `uvx` is available by running `uvx --help` in your terminal
+   - For Option 2: Make sure you have the source code repository
+   - For Option 3: Ensure Docker is installed and the image is built
+
+#### Configuration Steps
+
+1. Find or create the Claude Desktop configuration file:
+   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+   - macOS/Linux: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+2. Add the appropriate configuration based on your preferred method:
+
+#### Option 1: Using command-line tools (Recommended, requires package installation)
+
+   **For Windows**:
+
+   ```json
+   {
+     "mcpServers": {
+       "code-indexer": {
+         "command": "code-indexer",
+         "args": [
+            "C:\\Users\\username\\path\\to\\project"
+          ]
+       }
+     }
+   }
+   ```
+
+   **For macOS/Linux**:
+
+   ```json
+   {
+     "mcpServers": {
+       "code-indexer": {
+         "command": "code-indexer",
+         "args": [
+            "/Users/username/path/to/project"
+          ]
+       }
+     }
+   }
+   ```
+
+   **Note**: You can also use `uvx` instead of `code-indexer` as the command - both are entry points defined in this package that do the same thing. These commands are available after installing the package with `pip install code-index-mcp` or `uv pip install code-index-mcp`.
+
+#### Option 2: Using Python directly (No package installation required)
+
+   ```json
+   {
+     "mcpServers": {
+       "code-indexer": {
+         "command": "python",
+         "args": [
+           "-m",
+           "code_index_mcp.server"
+         ],
+         "cwd": "C:\\path\\to\\code-index-mcp"
+       }
+     }
+   }
+   ```
+
+   **Note**: This option requires specifying the full path to the source code repository in the `cwd` parameter.
+
+#### Option 3: Using Docker (Containerized)
+
+1. Build the Docker image as described in the Docker section above
+2. Find or create the Claude Desktop configuration file (same locations as above)
+3. Add the following configuration:
+
+   ```json
+   {
+     "mcpServers": {
+       "code-indexer": {
+         "command": "docker",
+         "args": [
+            "run",
+            "-i",
+            "--rm",
+            "code-index-mcp"
+          ]
+       }
+     }
+   }
+   ```
+
+   **Note**: This configuration allows Claude Desktop to start the containerized MCP tool on demand.
+
+4. Restart Claude Desktop to use Code Indexer for analyzing code projects
+
+Claude Desktop will start the MCP server as an on-demand process when needed, communicate with it via stdio, and keep it running only for the duration of your session.
+
+### Basic Workflow
+
+1. **Set Project Path** (required first step):
+
+   - When using for the first time, you must set the project path to analyze
+   - Through Claude command: "I need to analyze a project, help me set up the project path"
+   - Provide the complete project directory path
+2. **Code Search**:
+
+   - Search for specific keywords or patterns: "Search for 'function name' in the project"
+   - Filter by file type: "Search for 'import' in all .py files"
+3. **File Analysis**:
+
+   - Analyze specific files: "Analyze the file src/main.py"
+   - Get file summaries: "Give me a list of functions in utils/helpers.js"
+3. **Project Navigation**:
+
+   - View project structure: "Show me the structure of this project"
+   - Find files matching specific patterns: "Find all test_*.py files"
+
+## Technical Details
+
+### Persistent Storage
+
+All index and settings data are stored in the system temporary directory, in a subfolder specific to each project:
+
+- Windows: `%TEMP%\code_indexer\[project_hash]\`
+- Linux/macOS: `/tmp/code_indexer/[project_hash]/`
+
+Each project's data includes:
+- `config.json`: Project configuration information
+- `file_index.pickle`: File index data
+- `content_cache.pickle`: File content cache
+
+This approach ensures that:
+1. Different projects' data are kept separate
+2. The data is automatically cleaned up by the OS when no longer needed
+3. In containerized environments, the data is stored in the container's temporary directory
+
+### Dependency Management with UV
+
+Code Index MCP uses UV for dependency management, which provides several advantages:
+
+- Automatic dependency resolution based on project requirements
+- Faster package installation and environment setup
+- Consistent dependency versions via the lock file
+
+### Supported File Types
+
+The following file types are currently supported for indexing and analysis:
+
+- Python (.py)
+- JavaScript/TypeScript (.js, .ts, .jsx, .tsx)
+- Java (.java)
+- C/C++ (.c, .cpp, .h, .hpp)
+- C# (.cs)
+- Go (.go)
+- Ruby (.rb)
+- PHP (.php)
+- Swift (.swift)
+- Kotlin (.kt)
+- Rust (.rs)
+- Scala (.scala)
+- Shell (.sh, .bash)
+- HTML/CSS (.html, .css, .scss)
+- Markdown (.md)
+- JSON (.json)
+- XML (.xml)
+- YAML (.yml, .yaml)
+
+## Security Considerations
+
+- File path validation prevents directory traversal attacks
+- Absolute path access is not allowed
+- Project path must be explicitly set, with no default value
+- Index data is stored in the system temporary directory, not in the project directory
+- Each project's data is stored in a separate directory based on the project path's hash
+
+## Contributing
+
+Contributions via issues or pull requests to add new features or fix bugs are welcome.
+
+---
+
+*For documentation in Chinese, please see [README_zh.md](README_zh.md).*

code_index_mcp-0.1.0/README.md

@@ -0,0 +1,307 @@
+# Code Index MCP
+
+Code Index MCP is a Model Context Protocol server that enables large language models (LLMs) to index, search, and analyze code in project directories.
+
+## Features
+
+- Index and navigate project file structures
+- Search for specific patterns in code
+- Get detailed file summaries
+- Analyze code structure and complexity
+- Support for multiple programming languages
+- Persistent storage of project settings
+
+## Installation
+
+This project uses the following tools:
+
+1. **uv**: A fast Python package manager for dependency installation (recommended but optional)
+2. **code-indexer** or **uvx**: Command-line entry points provided by this package to run the Code Index MCP server
+
+> **Note about `uvx`**: Our `uvx` command is a custom entry point defined in this package, and is not related to the `uvx` command from the uv package manager (which is an alias for `uv tool run`). If you have both installed, you can use the full path to our `uvx` command or use the `code-indexer` command instead to avoid conflicts.
+
+### Installation Steps
+
+1. Ensure you have Python 3.10 or later installed
+
+2. Install uv (recommended but not required):
+   ```bash
+   # Windows
+   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+   # macOS/Linux
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
+
+3. Install the code-index-mcp package to get the command-line tools:
+   ```bash
+   # Using uv (recommended)
+   uv pip install code-index-mcp
+
+   # Or using traditional pip
+   pip install code-index-mcp
+   ```
+
+4. After installation, you can use either the `code-indexer` or `uvx` command (both do the same thing):
+   ```bash
+   # Using code-indexer
+   code-indexer /path/to/your/project
+
+   # Or using uvx
+   uvx /path/to/your/project
+   ```
+
+   Note: Both commands are entry points defined in this package that run the same code. If you have the uv package manager installed, be aware that it also has a command called `uvx` (which is an alias for `uv tool run`). To avoid conflicts, you can:
+
+   - Use the full path to our `uvx` command
+   - Use the `code-indexer` command instead
+   - Create an alias in your shell for our `uvx` command
+
+### Installing from Source
+
+If you want to install from source code:
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/johnhuang316/code-index-mcp.git
+   cd code-index-mcp
+   ```
+
+2. Install the package (this will also install the command-line tools):
+   ```bash
+   # Using uv (recommended)
+   uv pip install -e .
+
+   # Or using traditional pip
+   pip install -e .
+   ```
+
+   This will make both the `code-indexer` and `uvx` commands available in your environment.
+
+## Usage
+
+### Running the Server Directly
+
+There are multiple ways to run the server:
+
+```bash
+# Using the code-indexer command (requires installing the package first)
+code-indexer
+
+# Or using the uvx command (requires installing the package first)
+uvx
+
+# Using uv to run the script directly (doesn't require installing the package)
+uv run run.py
+
+# Using Python directly (doesn't require installing the package)
+python -m code_index_mcp.server
+```
+
+Note: When run without arguments, both `code-indexer` and `uvx` will start the server without setting a project path. You'll need to set the project path using the `set_project_path` tool after connecting.
+
+> **Important**: If you have the uv package manager installed, be aware that it also provides a command called `uvx` (which is an alias for `uv tool run`). To avoid command conflicts, you can use the full path to our `uvx` command, use `code-indexer` instead, or create a shell alias.
+
+UV will automatically handle all dependency installations based on the project's configuration.
+
+### Using Docker
+
+You can also use Code Index MCP as a containerized tool with Docker:
+
+```bash
+# Build the Docker image
+docker build -t code-index-mcp .
+
+# Use the container as a tool to analyze your code
+docker run --rm -i code-index-mcp
+```
+
+This containerized approach works well with Claude Desktop, which treats MCP servers as on-demand processes rather than persistent servers. Claude Desktop will start the container when needed and communicate with it via stdio, keeping it running only for the duration of the session.
+
+When using the containerized version, you'll need to set the project path explicitly using the `set_project_path` tool, just like in the non-containerized version.
+
+### Integrating with Claude Desktop
+
+You can easily integrate Code Index MCP with Claude Desktop:
+
+#### Prerequisites
+
+1. Make sure you have completed the appropriate installation steps above
+2. Verify that the command you plan to use is available:
+   - For Option 1: Verify `uvx` is available by running `uvx --help` in your terminal
+   - For Option 2: Make sure you have the source code repository
+   - For Option 3: Ensure Docker is installed and the image is built
+
+#### Configuration Steps
+
+1. Find or create the Claude Desktop configuration file:
+   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+   - macOS/Linux: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+2. Add the appropriate configuration based on your preferred method:
+
+#### Option 1: Using command-line tools (Recommended, requires package installation)
+
+   **For Windows**:
+
+   ```json
+   {
+     "mcpServers": {
+       "code-indexer": {
+         "command": "code-indexer",
+         "args": [
+            "C:\\Users\\username\\path\\to\\project"
+          ]
+       }
+     }
+   }
+   ```
+
+   **For macOS/Linux**:
+
+   ```json
+   {
+     "mcpServers": {
+       "code-indexer": {
+         "command": "code-indexer",
+         "args": [
+            "/Users/username/path/to/project"
+          ]
+       }
+     }
+   }
+   ```
+
+   **Note**: You can also use `uvx` instead of `code-indexer` as the command - both are entry points defined in this package that do the same thing. These commands are available after installing the package with `pip install code-index-mcp` or `uv pip install code-index-mcp`.
+
+#### Option 2: Using Python directly (No package installation required)
+
+   ```json
+   {
+     "mcpServers": {
+       "code-indexer": {
+         "command": "python",
+         "args": [
+           "-m",
+           "code_index_mcp.server"
+         ],
+         "cwd": "C:\\path\\to\\code-index-mcp"
+       }
+     }
+   }
+   ```
+
+   **Note**: This option requires specifying the full path to the source code repository in the `cwd` parameter.
+
+#### Option 3: Using Docker (Containerized)
+
+1. Build the Docker image as described in the Docker section above
+2. Find or create the Claude Desktop configuration file (same locations as above)
+3. Add the following configuration:
+
+   ```json
+   {
+     "mcpServers": {
+       "code-indexer": {
+         "command": "docker",
+         "args": [
+            "run",
+            "-i",
+            "--rm",
+            "code-index-mcp"
+          ]
+       }
+     }
+   }
+   ```
+
+   **Note**: This configuration allows Claude Desktop to start the containerized MCP tool on demand.
+
+4. Restart Claude Desktop to use Code Indexer for analyzing code projects
+
+Claude Desktop will start the MCP server as an on-demand process when needed, communicate with it via stdio, and keep it running only for the duration of your session.
+
+### Basic Workflow
+
+1. **Set Project Path** (required first step):
+
+   - When using for the first time, you must set the project path to analyze
+   - Through Claude command: "I need to analyze a project, help me set up the project path"
+   - Provide the complete project directory path
+2. **Code Search**:
+
+   - Search for specific keywords or patterns: "Search for 'function name' in the project"
+   - Filter by file type: "Search for 'import' in all .py files"
+3. **File Analysis**:
+
+   - Analyze specific files: "Analyze the file src/main.py"
+   - Get file summaries: "Give me a list of functions in utils/helpers.js"
+3. **Project Navigation**:
+
+   - View project structure: "Show me the structure of this project"
+   - Find files matching specific patterns: "Find all test_*.py files"
+
+## Technical Details
+
+### Persistent Storage
+
+All index and settings data are stored in the system temporary directory, in a subfolder specific to each project:
+
+- Windows: `%TEMP%\code_indexer\[project_hash]\`
+- Linux/macOS: `/tmp/code_indexer/[project_hash]/`
+
+Each project's data includes:
+- `config.json`: Project configuration information
+- `file_index.pickle`: File index data
+- `content_cache.pickle`: File content cache
+
+This approach ensures that:
+1. Different projects' data are kept separate
+2. The data is automatically cleaned up by the OS when no longer needed
+3. In containerized environments, the data is stored in the container's temporary directory
+
+### Dependency Management with UV
+
+Code Index MCP uses UV for dependency management, which provides several advantages:
+
+- Automatic dependency resolution based on project requirements
+- Faster package installation and environment setup
+- Consistent dependency versions via the lock file
+
+### Supported File Types
+
+The following file types are currently supported for indexing and analysis:
+
+- Python (.py)
+- JavaScript/TypeScript (.js, .ts, .jsx, .tsx)
+- Java (.java)
+- C/C++ (.c, .cpp, .h, .hpp)
+- C# (.cs)
+- Go (.go)
+- Ruby (.rb)
+- PHP (.php)
+- Swift (.swift)
+- Kotlin (.kt)
+- Rust (.rs)
+- Scala (.scala)
+- Shell (.sh, .bash)
+- HTML/CSS (.html, .css, .scss)
+- Markdown (.md)
+- JSON (.json)
+- XML (.xml)
+- YAML (.yml, .yaml)
+
+## Security Considerations
+
+- File path validation prevents directory traversal attacks
+- Absolute path access is not allowed
+- Project path must be explicitly set, with no default value
+- Index data is stored in the system temporary directory, not in the project directory
+- Each project's data is stored in a separate directory based on the project path's hash
+
+## Contributing
+
+Contributions via issues or pull requests to add new features or fix bugs are welcome.
+
+---
+
+*For documentation in Chinese, please see [README_zh.md](README_zh.md).*

code_index_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "code-index-mcp"
+version = "0.1.0"
+description = "Code indexing and analysis tools for LLMs using MCP"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "MIT"}
+authors = [
+    {name = "johnhuang316"}
+]
+dependencies = [
+    "mcp>=0.3.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/johnhuang316/code-index-mcp"
+"Bug Tracker" = "https://github.com/johnhuang316/code-index-mcp/issues"
+
+[project.scripts]
+code-indexer = "code_index_mcp.server:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}

code_index_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

code_index_mcp-0.1.0/src/code_index_mcp/__init__.py

@@ -0,0 +1,6 @@
+"""Code Index MCP package.
+
+A Model Context Protocol server for code indexing, searching, and analysis.
+"""
+
+__version__ = "0.1.0"

code_index_mcp-0.1.0/src/code_index_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Main entry point for the code-index-mcp package."""
+
+from code_index_mcp.server import main
+
+if __name__ == "__main__":
+    main()