code-index-mcp — Claude MCP 必备工具中文教程

🚀 **Recommended Setup (Most Users)**

The easiest way to get started with any MCP-compatible application:

Prerequisites: Python 3.10+ and uv

1. Add to your MCP configuration (e.g., claude_desktop_config.json or ~/.claude.json):

   {
     "mcpServers": {
       "code-index": {
         "command": "uvx",
         "args": ["code-index-mcp"]
       }
     }
   }
   

1. Restart your application – uvx automatically handles installation and execution

3. Start using (give these prompts to your AI assistant):

   Set the project path to /Users/dev/my-react-app
   Find all TypeScript files in this project  
   Search for "authentication" functions
   Analyze the main App.tsx file
   

🛠️ **Development Setup**

For contributing or local development:

1. Clone and install:

   git clone https://github.com/johnhuang316/code-index-mcp.git
   cd code-index-mcp
   uv sync
   

2. Configure for local development:

   {
     "mcpServers": {
       "code-index": {
         "command": "uv",
         "args": ["run", "code-index-mcp"]
       }
     }
   }
   

3. Debug with MCP Inspector:

   npx @modelcontextprotocol/inspector uv run code-index-mcp
   

<details> <summary><strong>Alternative: Manual pip Installation</strong></summary>

If you prefer traditional pip management:

pip install code-index-mcp

Then configure:

{
  "mcpServers": {
    "code-index": {
      "command": "code-index-mcp",
      "args": []
    }
  }
}

</details>

🔧 **Building from Source**

git clone https://github.com/johnhuang316/code-index-mcp.git
cd code-index-mcp
uv sync
uv run code-index-mcp

Quick Start

Typical Use Cases

Code Review: "Find all places using the old API" Refactoring Help: "Where is this function called?" Learning Projects: "Show me the main components of this React project" Debugging: "Search for all error handling related code"

Usage Examples

🎯 **Quick Start Workflow**

1. Initialize Your Project

Set the project path to /Users/dev/my-react-app

2. Explore Project Structure

Find all TypeScript component files in src/components

3. Analyze Key Files

Give me a summary of src/api/userService.ts

🔍 **Advanced Search Examples**

<details> <summary><strong>Code Pattern Search</strong></summary>

Search for all function calls matching "get.*Data" using `regex=True`

</details>

<details> <summary><strong>Fuzzy Function Search</strong></summary>

Find authentication-related functions with fuzzy search for 'authUser'

</details>

<details> <summary><strong>Language-Specific Search</strong></summary>

Search for "API_ENDPOINT" only in Python files

</details>

<details> <summary><strong>Auto-refresh Configuration</strong></summary>

Configure automatic index updates when files change

</details>

<details> <summary><strong>Project Maintenance</strong></summary>

I added new components, please refresh the project index

</details>

Codex CLI Configuration

If you are using Anthropic's Codex CLI, add the server to ~/.codex/config.toml. On Windows the file lives at C:\Users\<you>\.codex\config.toml:

[mcp_servers.code-index]
type = "stdio"
command = "uvx"
args = ["code-index-mcp"]

On Windows, uvx needs the standard profile directories to be present. Keep the environment override in the same block so the MCP starts reliably:

env = {
  HOME = "C:\\Users\\<you>",
  APPDATA = "C:\\Users\\<you>\\AppData\\Roaming",
  LOCALAPPDATA = "C:\\Users\\<you>\\AppData\\Local",
  SystemRoot = "C:\\Windows"
}

Linux and macOS already expose the required XDG paths and HOME, so you can usually omit the env table there. Add overrides only if you run the CLI inside a restricted container.

**macOS File Watcher Options**

The default FSEvents observer works well for most projects. If you experience issues, you can switch to an alternative observer via configure_file_watcher:

• "auto" (default): Platform default (FSEvents on macOS)
• "kqueue": Kqueue observer (macOS/BSD)
• "fsevents": Force FSEvents (macOS only)
• "polling": Cross-platform polling fallback

Note: Kqueue opens one file descriptor per watched file. For large projects using kqueue, you may need to increase the limit: ulimit -n 10240

Troubleshooting