Initial commit

Author: johnhuang316

.code_indexer/.gitignore

@@ -0,0 +1,4 @@
+# Ignore everything in this directory
+*
+# Except this file
+!.gitignore

.gitignore

@@ -0,0 +1,36 @@
+# Python cache files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+env/
+ENV/
+
+# IDE files
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS specific files
+.DS_Store
+Thumbs.db

.python-version

@@ -0,0 +1 @@
+3.11

README.md

@@ -0,0 +1,135 @@
+# 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 uv for environment management and dependency installation.
+
+1. Ensure you have Python 3.10 or later installed
+2. Install uv (recommended):
+   ```bash
+   # Windows
+   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+   # macOS/Linux
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
+
+3. Set up the environment and install dependencies:
+   ```bash
+   # Create virtual environment and install dependencies
+   uv venv
+   uv pip install -r requirements.txt
+   ```
+
+## Usage
+
+### Running the Server
+
+```bash
+# Using Python from the virtual environment
+.venv/Scripts/python server.py  # Windows
+.venv/bin/python server.py     # macOS/Linux
+
+# Or more conveniently with uv
+uv run server.py
+```
+
+### Integrating with Claude Desktop
+
+You can manually configure Claude Desktop to integrate with Code Index MCP:
+
+1. Ensure you have completed the environment setup as described above
+
+2. Find or create the Claude Desktop configuration file:
+   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+3. Add the following configuration (replace with your actual path):
+   ```json
+   {
+     "mcpServers": {
+       "code-indexer": {
+         "command": "uv",
+         "args": ["run", "C:/path/to/your/code-index-mcp/server.py"]
+       }
+     }
+   }
+   ```
+
+4. Restart Claude Desktop to use Code Indexer for analyzing code projects
+
+### 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"
+
+4. **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 `.code_indexer` folder within the project directory:
+- `config.json`: Project configuration information
+- `file_index.pickle`: File index data
+- `content_cache.pickle`: File content cache
+
+This ensures that the entire project doesn't need to be re-indexed each time it's used.
+
+### 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
+
+## 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).*

README_zh.md

@@ -0,0 +1,131 @@
+# Code Index MCP
+
+Code Index MCP 是一個基於 Model Context Protocol 的服務器，允許大型語言模型 (LLMs) 索引、搜索和分析專案目錄中的程式碼。
+
+## 功能特點
+
+- 索引並導航專案文件結構
+- 搜索特定模式的程式碼
+- 獲取文件的詳細摘要
+- 分析程式碼結構和複雜性
+- 支持多種程式語言
+- 專案設定持久化存儲
+
+## 安裝
+
+本專案使用 uv 進行環境管理和依賴安裝。
+
+1. 確保您已安裝 Python 3.10 或更高版本
+2. 安裝 uv (推薦):
+   ```bash
+   # Windows
+   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+   # macOS/Linux
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
+
+3. 設置環境並安裝依賴:
+   ```bash
+   # 創建虛擬環境和安裝依賴
+   uv venv
+   uv pip install -r requirements.txt
+   ```
+
+## 使用方法
+
+### 運行服務器
+
+```bash
+# 使用虛擬環境中的 Python 執行
+.venv/Scripts/python server.py  # Windows
+.venv/bin/python server.py     # macOS/Linux
+
+# 或使用 uv 更簡便地執行
+uv run server.py
+```
+
+### 與 Claude Desktop 整合
+
+您可以手動配置 Claude Desktop 使其與 Code Index MCP 整合:
+
+1. 確保已按上述步驟完成環境安裝
+
+2. 找到或創建 Claude Desktop 配置文件:
+   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+3. 添加以下配置 (請替換為您的實際路徑):
+   ```json
+   {
+     "mcpServers": {
+       "code-indexer": {
+         "command": "uv",
+         "args": ["run", "C:/path/to/your/code-index-mcp/server.py"]
+       }
+     }
+   }
+   ```
+
+4. 重啟 Claude Desktop，就可以使用 Code Indexer 來分析代碼專案
+
+### 基本使用流程
+
+1. **設定專案路徑** (必要第一步):
+   - 首次使用時，必須先設定要分析的專案路徑
+   - 透過 Claude 指令: "我需要分析一個專案，幫我設定專案路徑"
+   - 提供完整的專案目錄路徑
+
+2. **代碼搜索**:
+   - 搜索特定關鍵字或模式: "在專案中搜索 'function name'"
+   - 支援按文件類型過濾: "搜索所有 .py 文件中的 'import'"
+
+3. **文件分析**:
+   - 分析特定文件: "分析 src/main.py 這個文件"
+   - 獲取文件摘要: "給我 utils/helpers.js 的函數列表"
+
+4. **專案導航**:
+   - 查看專案結構: "顯示這個專案的結構"
+   - 查找特定模式的文件: "找出所有的 test_*.py 文件"
+
+## 技術細節
+
+### 持久化存儲
+
+所有索引和設定數據存儲在專案目錄下的 `.code_indexer` 文件夾中:
+- `config.json`: 專案配置資訊
+- `file_index.pickle`: 檔案索引數據
+- `content_cache.pickle`: 檔案內容緩存
+
+這確保了不需要在每次使用時重新索引整個專案。
+
+### 支持的文件類型
+
+目前支持以下文件類型的索引和分析:
+- 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)
+
+## 安全考量
+
+- 檔案路徑驗證防止目錄遍歷攻擊
+- 不允許透過絕對路徑存取文件
+- 專案路徑必須明確設定，無預設值
+
+## 貢獻
+
+歡迎提交問題或拉取請求，以添加新功能或修復錯誤。

example_client.py

@@ -0,0 +1,74 @@
+"""
+Example client script for the Code Index MCP Server.
+
+This script shows how to programmatically interact with the Code Index MCP Server.
+"""
+import asyncio
+import json
+from mcp import ClientSession, StdioServerParameters
+from mcp.client.stdio import stdio_client
+
+async def main():
+    # Create server parameters for stdio connection
+    server_params = StdioServerParameters(
+        command="python",
+        args=["server.py"],
+    )
+    
+    async with stdio_client(server_params) as (read, write):
+        async with ClientSession(read, write) as session:
+            # Initialize the connection
+            await session.initialize()
+            
+            print("Connected to Code Index MCP Server\n")
+            
+            # List available tools
+            print("Available Tools:")
+            tools = await session.list_tools()
+            for tool in tools:
+                print(f"  - {tool['name']}: {tool['description']}")
+            print()
+            
+            # Set project path (use a known code directory)
+            print("Setting project path...")
+            result = await session.call_tool(
+                "set_project_path", 
+                arguments={"path": "."}  # Index the current directory
+            )
+            print(f"Result: {result}\n")
+            
+            # Get project structure
+            print("Getting project structure...")
+            content, _ = await session.read_resource("structure://project")
+            structure = json.loads(content)
+            print(f"Project structure: {len(structure)} top-level items\n")
+            
+            # Search for some code
+            print("Searching for 'mcp.tool'...")
+            results = await session.call_tool(
+                "search_code",
+                arguments={
+                    "query": "mcp.tool",
+                    "extensions": [".py"],
+                    "case_sensitive": False
+                }
+            )
+            print(f"Found {len(results)} files with matches:")
+            for file, matches in results.items():
+                print(f"  - {file}: {len(matches)} matches")
+            print()
+            
+            # Get a file summary
+            print("Getting file summary for server.py...")
+            summary = await session.call_tool(
+                "get_file_summary",
+                arguments={"file_path": "server.py"}
+            )
+            print(f"File summary:")
+            print(f"  - Lines: {summary.get('line_count')}")
+            print(f"  - Functions: {summary.get('function_count', 'N/A')}")
+            print(f"  - Classes: {summary.get('class_count', 'N/A')}")
+            print()
+
+if __name__ == "__main__":
+    asyncio.run(main())