[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-johnhuang316--code-index-mcp":3,"tool-johnhuang316--code-index-mcp":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",143909,2,"2026-04-07T11:33:18",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",107888,"2026-04-06T11:32:50",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":10,"last_commit_at":59,"category_tags":60,"status":17},4487,"LLMs-from-scratch","rasbt\u002FLLMs-from-scratch","LLMs-from-scratch 是一个基于 PyTorch 的开源教育项目，旨在引导用户从零开始一步步构建一个类似 ChatGPT 的大型语言模型（LLM）。它不仅是同名技术著作的官方代码库，更提供了一套完整的实践方案，涵盖模型开发、预训练及微调的全过程。\n\n该项目主要解决了大模型领域“黑盒化”的学习痛点。许多开发者虽能调用现成模型，却难以深入理解其内部架构与训练机制。通过亲手编写每一行核心代码，用户能够透彻掌握 Transformer 架构、注意力机制等关键原理，从而真正理解大模型是如何“思考”的。此外，项目还包含了加载大型预训练权重进行微调的代码，帮助用户将理论知识延伸至实际应用。\n\nLLMs-from-scratch 特别适合希望深入底层原理的 AI 开发者、研究人员以及计算机专业的学生。对于不满足于仅使用 API，而是渴望探究模型构建细节的技术人员而言，这是极佳的学习资源。其独特的技术亮点在于“循序渐进”的教学设计：将复杂的系统工程拆解为清晰的步骤，配合详细的图表与示例，让构建一个虽小但功能完备的大模型变得触手可及。无论你是想夯实理论基础，还是为未来研发更大规模的模型做准备",90106,"2026-04-06T11:19:32",[35,15,13,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":66,"readme_en":67,"readme_zh":68,"quickstart_zh":69,"use_case_zh":70,"hero_image_url":71,"owner_login":72,"owner_name":73,"owner_avatar_url":74,"owner_bio":73,"owner_company":73,"owner_location":73,"owner_email":73,"owner_twitter":73,"owner_website":73,"owner_url":75,"languages":76,"stars":116,"forks":117,"last_commit_at":118,"license":119,"difficulty_score":32,"env_os":120,"env_gpu":121,"env_ram":122,"env_deps":123,"category_tags":130,"github_topics":73,"view_count":32,"oss_zip_url":73,"oss_zip_packed_at":73,"status":17,"created_at":131,"updated_at":132,"faqs":133,"releases":162},5028,"johnhuang316\u002Fcode-index-mcp","code-index-mcp","A Model Context Protocol (MCP) server that helps large language models index, search, and analyze code repositories with minimal setup","code-index-mcp 是一款基于模型上下文协议（MCP）的智能服务工具，旨在帮助大语言模型轻松理解、索引和分析复杂的代码仓库。它解决了 AI 在面对大型项目时难以全面掌握代码结构、定位特定功能或进行深度分析的痛点，让 AI 助手能像资深开发者一样快速导航和解读你的代码库。\n\n这款工具特别适合软件开发者、技术团队以及需要处理代码审查、重构、文档生成或架构分析的研究人员使用。只需极简的配置，即可让 AI 获得强大的代码搜索与分析能力。\n\n其核心亮点在于“开箱即用”的便捷性与深度的代码理解力。用户无需编写复杂脚本，通过简单的命令行参数或配置文件，即可将本地项目路径映射给 AI。code-index-mcp 支持智能索引和高级搜索，能精准查找特定类型的文件（如所有 TypeScript 文件）或函数逻辑（如认证相关功能），并能对具体文件进行详细剖析。无论是日常调试、辅助编程还是系统架构梳理，它都能显著提升人机协作的效率，让大模型真正成为懂你代码的得力助手。","# Code Index MCP\n\n\u003Cdiv align=\"center\">\n\n[![MCP Server](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMCP-Server-blue)](https:\u002F\u002Fmodelcontextprotocol.io)\n[![Python](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPython-3.10%2B-green)](https:\u002F\u002Fwww.python.org\u002F)\n[![License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow)](LICENSE)\n\n**Intelligent code indexing and analysis for Large Language Models**\n\nTransform how AI understands your codebase with advanced search, analysis, and navigation capabilities.\n\n\u003C\u002Fdiv>\n\n\u003Ca href=\"https:\u002F\u002Fglama.ai\u002Fmcp\u002Fservers\u002F@johnhuang316\u002Fcode-index-mcp\">\n  \u003Cimg width=\"380\" height=\"200\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fjohnhuang316_code-index-mcp_readme_aa4564d365ab.png\" alt=\"code-index-mcp MCP server\" \u002F>\n\u003C\u002Fa>\n\n## Overview\n\nCode Index MCP is a [Model Context Protocol](https:\u002F\u002Fmodelcontextprotocol.io) server that bridges the gap between AI models and complex codebases. It provides intelligent indexing, advanced search capabilities, and detailed code analysis to help AI assistants understand and navigate your projects effectively.\n\n**Perfect for:** Code review, refactoring, documentation generation, debugging assistance, and architectural analysis.\n\n## Quick Start\n\n### 🚀 **Recommended Setup (Most Users)**\n\nThe easiest way to get started with any MCP-compatible application:\n\n**Prerequisites:** Python 3.10+ and [uv](https:\u002F\u002Fgithub.com\u002Fastral-sh\u002Fuv)\n\n1. **Add to your MCP configuration** (e.g., `claude_desktop_config.json` or `~\u002F.claude.json`):\n   ```json\n   {\n     \"mcpServers\": {\n       \"code-index\": {\n         \"command\": \"uvx\",\n         \"args\": [\"code-index-mcp\"]\n       }\n     }\n   }\n   ```\n   > Optional: append `--project-path \u002Fabsolute\u002Fpath\u002Fto\u002Frepo` to the `args` array so the server\n   > initializes with that repository automatically (equivalent to calling `set_project_path`\n   > after startup).\n\n2. **Restart your application** – `uvx` automatically handles installation and execution\n\n3. **Start using** (give these prompts to your AI assistant):\n   ```\n   Set the project path to \u002FUsers\u002Fdev\u002Fmy-react-app\n   Find all TypeScript files in this project  \n   Search for \"authentication\" functions\n   Analyze the main App.tsx file\n   ```\n   *If you launch with `--project-path`, you can skip the first command above - the server already\n   knows the project location.*\n\n### Codex CLI Configuration\n\nIf you are using Anthropic's Codex CLI, add the server to `~\u002F.codex\u002Fconfig.toml`.\nOn Windows the file lives at `C:\\Users\\\u003Cyou>\\.codex\\config.toml`:\n\n```toml\n[mcp_servers.code-index]\ntype = \"stdio\"\ncommand = \"uvx\"\nargs = [\"code-index-mcp\"]\n```\n> You can append `--project-path C:\u002Fabsolute\u002Fpath\u002Fto\u002Frepo` to the `args` list to set the project\n> automatically on startup (same effect as running the `set_project_path` tool).\n\nOn Windows, `uvx` needs the standard profile directories to be present.\nKeep the environment override in the same block so the MCP starts reliably:\n\n```toml\nenv = {\n  HOME = \"C:\\\\Users\\\\\u003Cyou>\",\n  APPDATA = \"C:\\\\Users\\\\\u003Cyou>\\\\AppData\\\\Roaming\",\n  LOCALAPPDATA = \"C:\\\\Users\\\\\u003Cyou>\\\\AppData\\\\Local\",\n  SystemRoot = \"C:\\\\Windows\"\n}\n```\n\nLinux and macOS already expose the required XDG paths and `HOME`, so you can usually omit the `env`\ntable there.\nAdd overrides only if you run the CLI inside a restricted container.\n\n### FastMCP & Discovery Manifests\n\n- Run `fastmcp run fastmcp.json` to launch the server via [FastMCP](https:\u002F\u002Ffastmcp.wiki\u002F) with\n  the correct source entrypoint and dependency metadata. Pass `--project-path` (or call the\n  `set_project_path` tool after startup) so the index boots against the right repository.\n- Serve or copy `.well-known\u002Fmcp.json` to share a standards-compliant MCP manifest. Clients that\n  support the `.well-known` convention (e.g., Claude Desktop, Codex CLI) can import this file\n  directly instead of crafting configs manually.\n- Publish `.well-known\u002Fmcp.llmfeed.json` when you want to expose the richer LLM Feed metadata.\n  It references the same `code-index` server definition plus documentation\u002Fsource links, which\n  helps registries present descriptions, tags, and capabilities automatically.\n\nWhen sharing the manifests, remind consumers to supply `--project-path` (or to call\n`set_project_path`) so the server indexes the intended repository.\n\n## Typical Use Cases\n\n**Code Review**: \"Find all places using the old API\"  \n**Refactoring Help**: \"Where is this function called?\"  \n**Learning Projects**: \"Show me the main components of this React project\"  \n**Debugging**: \"Search for all error handling related code\"\n\n## Key Features\n\n### 🔍 **Intelligent Search & Analysis**\n- **Dual-Strategy Architecture**: Specialized tree-sitter parsing for 10 core languages, fallback strategy for 50+ file types\n- **Direct Tree-sitter Integration**: No regex fallbacks for specialized languages - fail fast with clear errors\n- **Advanced Search**: Auto-detects and uses the best available tool (ugrep, ripgrep, ag, or grep)\n- **Universal File Support**: Comprehensive coverage from advanced AST parsing to basic file indexing\n- **File Analysis**: Deep insights into structure, imports, classes, methods, and complexity metrics after running `build_deep_index`\n\n### 🗂️ **Multi-Language Support**  \n- **10 Languages with Tree-sitter AST Parsing**: Python, JavaScript, TypeScript, Java, Kotlin, C#, Go, Objective-C, Zig, Rust\n- **50+ File Types with Fallback Strategy**: C\u002FC++, Ruby, PHP, and all other programming languages\n- **Document & Config Files**: Markdown, JSON, YAML, XML with appropriate handling\n- **Web Frontend**: Vue, React, Svelte, HTML, CSS, SCSS\n- **Java Web & Build**: JSP\u002FTag files (`.jsp`, `.jspx`, `.jspf`, `.tag`, `.tagx`), Grails\u002FGSP (`.gsp`), Gradle & Groovy builds (`.gradle`, `.groovy`), `.properties`, and Protocol Buffers (`.proto`)\n- **Database**: SQL variants, NoSQL, stored procedures, migrations\n- **Configuration**: JSON, YAML, XML, Markdown\n- **[View complete list](#supported-file-types)**\n\n### ⚡ **Real-time Monitoring & Auto-refresh**\n- **File Watcher**: Automatic index updates when files change\n- **Cross-platform**: Native OS file system monitoring\n- **Smart Processing**: Batches rapid changes to prevent excessive rebuilds\n- **Shallow Index Refresh**: Watches file changes and keeps the file list current; run a deep rebuild when you need symbol metadata\n\n### ⚡ **Performance & Efficiency**\n- **Tree-sitter AST Parsing**: Native syntax parsing for accurate symbol extraction\n- **Persistent Caching**: Stores indexes for lightning-fast subsequent access\n- **Smart Filtering**: Intelligent exclusion of build directories and temporary files\n- **Memory Efficient**: Optimized for large codebases\n- **Direct Dependencies**: No fallback mechanisms - fail fast with clear error messages\n\n## Supported File Types\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>📁 Programming Languages (Click to expand)\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n**Languages with Specialized Tree-sitter Strategies:**\n- **Python** (`.py`, `.pyw`) - Full AST analysis with class\u002Fmethod extraction and call tracking\n- **JavaScript** (`.js`, `.jsx`, `.mjs`, `.cjs`) - ES6+ class and function parsing with tree-sitter\n- **TypeScript** (`.ts`, `.tsx`) - Complete type-aware symbol extraction with interfaces\n- **Java** (`.java`) - Full class hierarchy, method signatures, and call relationships\n- **Kotlin** (`.kt`, `.kts`) - Package-aware symbol extraction with methods and call relationships\n- **C#** (`.cs`) - Namespace-aware type\u002Fmember extraction with call relationships\n- **Go** (`.go`) - Struct methods, receiver types, and function analysis\n- **Rust** (`.rs`) - Functions, module-aware names, impl methods, structs\u002Fenums\u002Ftraits, and basic call relationships\n- **Objective-C** (`.m`, `.mm`) - Class\u002Finstance method distinction with +\u002F- notation\n- **Zig** (`.zig`, `.zon`) - Function and struct parsing with tree-sitter AST\n\n**All Other Programming Languages:**\nAll other programming languages use the **FallbackParsingStrategy** which provides basic file indexing and metadata extraction. This includes:\n- **System & Low-Level:** C\u002FC++ (`.c`, `.cpp`, `.h`, `.hpp`)\n- **Object-Oriented:** Scala (`.scala`), Swift (`.swift`)\n- **Scripting & Dynamic:** Ruby (`.rb`), PHP (`.php`), Shell (`.sh`, `.bash`)\n- **And 40+ more file types** - All handled through the fallback strategy for basic indexing\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🌐 Web & Frontend (Click to expand)\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n**Frameworks & Libraries:**\n- Vue (`.vue`)\n- Svelte (`.svelte`)\n- Astro (`.astro`)\n\n**Styling:**\n- CSS (`.css`, `.scss`, `.less`, `.sass`, `.stylus`, `.styl`)\n- HTML (`.html`)\n\n**Templates:**\n- Handlebars (`.hbs`, `.handlebars`)\n- EJS (`.ejs`)\n- Pug (`.pug`)\n- FreeMarker (`.ftl`)\n- Mustache (`.mustache`)\n- Liquid (`.liquid`)\n- ERB (`.erb`)\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🗄️ Database & SQL (Click to expand)\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n**SQL Variants:**\n- Standard SQL (`.sql`, `.ddl`, `.dml`)\n- Database-specific (`.mysql`, `.postgresql`, `.psql`, `.sqlite`, `.mssql`, `.oracle`, `.ora`, `.db2`)\n\n**Database Objects:**\n- Procedures & Functions (`.proc`, `.procedure`, `.func`, `.function`)\n- Views & Triggers (`.view`, `.trigger`, `.index`)\n\n**Migration & Tools:**\n- Migration files (`.migration`, `.seed`, `.fixture`, `.schema`)\n- Tool-specific (`.liquibase`, `.flyway`)\n\n**NoSQL & Modern:**\n- Graph & Query (`.cql`, `.cypher`, `.sparql`, `.gql`)\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>📄 Documentation & Config (Click to expand)\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n- Markdown (`.md`, `.mdx`)\n- Configuration (`.json`, `.xml`, `.yml`, `.yaml`, `.properties`)\n\n\u003C\u002Fdetails>\n\n### 🛠️ **Development Setup**\n\nFor contributing or local development:\n\n1. **Clone and install:**\n   ```bash\n   git clone https:\u002F\u002Fgithub.com\u002Fjohnhuang316\u002Fcode-index-mcp.git\n   cd code-index-mcp\n   uv sync\n   ```\n\n2. **Configure for local development:**\n   ```json\n   {\n     \"mcpServers\": {\n       \"code-index\": {\n         \"command\": \"uv\",\n         \"args\": [\"run\", \"code-index-mcp\"]\n       }\n     }\n   }\n   ```\n\n3. **Debug with MCP Inspector:**\n   ```bash\n   npx @modelcontextprotocol\u002Finspector uv run code-index-mcp\n   ```\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Alternative: Manual pip Installation\u003C\u002Fstrong>\u003C\u002Fsummary>\n\nIf you prefer traditional pip management:\n\n```bash\npip install code-index-mcp\n```\n\nThen configure:\n```json\n{\n  \"mcpServers\": {\n    \"code-index\": {\n      \"command\": \"code-index-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\n\n## Available Tools\n\n### 🏗️ **Project Management**\n| Tool | Description |\n|------|-------------|\n| **`set_project_path`** | Initialize indexing for a project directory |\n| **`refresh_index`** | Rebuild the shallow file index after file changes |\n| **`build_deep_index`** | Generate the full symbol index used by deep analysis |\n| **`get_settings_info`** | View current project configuration and status |\n\n*Run `build_deep_index` when you need symbol-level data; the default shallow index powers quick file discovery.*\n\n### 🔍 **Search & Discovery**\n| Tool | Description |\n|------|-------------|\n| **`search_code_advanced`** | Smart search with literal-by-default matching, optional `regex=True`, fuzzy matching, file filtering, and paginated results (10 per page by default); regex mode requires a native search tool because the basic fallback is literal-only |\n| **`find_files`** | Locate files using glob patterns (e.g., `**\u002F*.py`) |\n| **`get_file_summary`** | Analyze file structure, functions, imports, and complexity (requires deep index) |\n\n### 🔄 **Monitoring & Auto-refresh**\n| Tool | Description |\n|------|-------------|\n| **`get_file_watcher_status`** | Check file watcher status and configuration |\n| **`configure_file_watcher`** | Enable\u002Fdisable auto-refresh and configure settings |\n\n### 🛠️ **System & Maintenance**\n| Tool | Description |\n|------|-------------|\n| **`create_temp_directory`** | Set up storage directory for index data |\n| **`check_temp_directory`** | Verify index storage location and permissions |\n| **`clear_settings`** | Reset all cached data and configurations |\n| **`refresh_search_tools`** | Re-detect available search tools (ugrep, ripgrep, etc.) |\n\n## Usage Examples\n\n### 🎯 **Quick Start Workflow**\n\n**1. Initialize Your Project**\n```\nSet the project path to \u002FUsers\u002Fdev\u002Fmy-react-app\n```\n*Automatically indexes your codebase and creates searchable cache*\n\n**2. Explore Project Structure**\n```\nFind all TypeScript component files in src\u002Fcomponents\n```\n*Uses: `find_files` with pattern `src\u002Fcomponents\u002F**\u002F*.tsx`*\n\n**3. Analyze Key Files**\n```\nGive me a summary of src\u002Fapi\u002FuserService.ts\n```\n*Uses: `get_file_summary` to show functions, imports, and complexity*\n*Tip: run `build_deep_index` first if you get a `needs_deep_index` response.*\n\n### 🔍 **Advanced Search Examples**\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Code Pattern Search\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\nSearch for all function calls matching \"get.*Data\" using `regex=True`\n```\n*Finds: `getData()`, `getUserData()`, `getFormData()`, etc. Regex search is opt-in; install a native search tool and use `regex=True` because the basic fallback stays literal-only.*\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Fuzzy Function Search\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\nFind authentication-related functions with fuzzy search for 'authUser'\n```\n*Matches: `authenticateUser`, `authUserToken`, `userAuthCheck`, etc.*\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Language-Specific Search\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\nSearch for \"API_ENDPOINT\" only in Python files\n```\n*Uses: `search_code_advanced` with literal matching and `file_pattern: \"*.py\"` (defaults to 10 matches; use `max_results` to expand or `start_index` to page)*\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Auto-refresh Configuration\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\nConfigure automatic index updates when files change\n```\n*Uses: `configure_file_watcher` to enable\u002Fdisable monitoring and set debounce timing*\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>Project Maintenance\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\nI added new components, please refresh the project index\n```\n*Uses: `refresh_index` to update the searchable cache*\n\n\u003C\u002Fdetails>\n\n## Troubleshooting\n\n### 🔄 **Auto-refresh Not Working**\n\nIf automatic index updates aren't working when files change, try:\n- `pip install watchdog` (may resolve environment isolation issues)\n- Use manual refresh: Call the `refresh_index` tool after making file changes\n- Check file watcher status: Use `get_file_watcher_status` to verify monitoring is active\n\n### **macOS File Watcher Options**\n\nThe default FSEvents observer works well for most projects. If you experience issues, you can switch to an alternative observer via `configure_file_watcher`:\n\n- `\"auto\"` (default): Platform default (FSEvents on macOS)\n- `\"kqueue\"`: Kqueue observer (macOS\u002FBSD)\n- `\"fsevents\"`: Force FSEvents (macOS only)\n- `\"polling\"`: Cross-platform polling fallback\n\nNote: Kqueue opens one file descriptor per watched file. For large projects using kqueue, you may need to increase the limit: `ulimit -n 10240`\n\n## Development & Contributing\n\n### 🔧 **Building from Source**\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fjohnhuang316\u002Fcode-index-mcp.git\ncd code-index-mcp\nuv sync\nuv run code-index-mcp\n```\n\n### 🐛 **Debugging**\n```bash\nnpx @modelcontextprotocol\u002Finspector uvx code-index-mcp\n```\n\n### 🤝 **Contributing**\nContributions are welcome! Please feel free to submit a Pull Request.\n\n---\n\n### 📜 **License**\n[MIT License](LICENSE)\n\n### 🌐 **Translations**\n- [繁體中文](README_zh.md)\n- [日本語](README_ja.md)\n","# 代码索引 MCP\n\n\u003Cdiv align=\"center\">\n\n[![MCP 服务器](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMCP-Server-blue)](https:\u002F\u002Fmodelcontextprotocol.io)\n[![Python](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FPython-3.10%2B-green)](https:\u002F\u002Fwww.python.org\u002F)\n[![许可证](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow)](LICENSE)\n\n**面向大型语言模型的智能代码索引与分析**\n\n通过先进的搜索、分析和导航功能，改变AI理解代码库的方式。\n\n\u003C\u002Fdiv>\n\n\u003Ca href=\"https:\u002F\u002Fglama.ai\u002Fmcp\u002Fservers\u002F@johnhuang316\u002Fcode-index-mcp\">\n  \u003Cimg width=\"380\" height=\"200\" src=\"https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fjohnhuang316_code-index-mcp_readme_aa4564d365ab.png\" alt=\"code-index-mcp MCP 服务器\" \u002F>\n\u003C\u002Fa>\n\n## 概述\n\n代码索引 MCP 是一个 [Model Context Protocol](https:\u002F\u002Fmodelcontextprotocol.io) 服务器，它弥合了 AI 模型与复杂代码库之间的鸿沟。它提供智能索引、高级搜索功能以及详细的代码分析，以帮助 AI 助手有效地理解和导航您的项目。\n\n**非常适合：** 代码审查、重构、文档生成、调试辅助以及架构分析。\n\n## 快速入门\n\n### 🚀 **推荐设置（大多数用户）**\n\n开始使用任何兼容 MCP 的应用程序最简单的方法：\n\n**先决条件：** Python 3.10+ 和 [uv](https:\u002F\u002Fgithub.com\u002Fastral-sh\u002Fuv)\n\n1. **添加到您的 MCP 配置**（例如 `claude_desktop_config.json` 或 `~\u002F.claude.json`）：\n   ```json\n   {\n     \"mcpServers\": {\n       \"code-index\": {\n         \"command\": \"uvx\",\n         \"args\": [\"code-index-mcp\"]\n       }\n     }\n   }\n   ```\n   > 可选：在 `args` 数组中追加 `--project-path \u002Fabsolute\u002Fpath\u002Fto\u002Frepo`，使服务器自动初始化该仓库（等同于启动后调用 `set_project_path`）。\n\n2. **重启您的应用程序** – `uvx` 会自动处理安装和执行\n\n3. **开始使用**（向您的 AI 助手提供以下提示）：\n   ```\n   将项目路径设置为 \u002FUsers\u002Fdev\u002Fmy-react-app\n   查找该项目中的所有 TypeScript 文件  \n   搜索“authentication”函数\n   分析主 App.tsx 文件\n   ```\n   *如果您使用 `--project-path` 启动，则可以跳过上述第一条命令——服务器已经知道项目位置。*\n\n### Codex CLI 配置\n\n如果您使用 Anthropic 的 Codex CLI，请将服务器添加到 `~\u002F.codex\u002Fconfig.toml`。在 Windows 上，该文件位于 `C:\\Users\\\u003Cyou>\\.codex\\config.toml`：\n\n```toml\n[mcp_servers.code-index]\ntype = \"stdio\"\ncommand = \"uvx\"\nargs = [\"code-index-mcp\"]\n```\n> 您可以在 `args` 列表中追加 `--project-path C:\u002Fabsolute\u002Fpath\u002Fto\u002Frepo`，以便在启动时自动设置项目（效果与运行 `set_project_path` 工具相同）。\n\n在 Windows 上，`uvx` 需要标准的配置文件目录存在。请在同一块中保留环境变量覆盖，以确保 MCP 能够可靠启动：\n\n```toml\nenv = {\n  HOME = \"C:\\\\Users\\\\\u003Cyou>\",\n  APPDATA = \"C:\\\\Users\\\\\u003Cyou>\\\\AppData\\\\Roaming\",\n  LOCALAPPDATA = \"C:\\\\Users\\\\\u003Cyou>\\\\AppData\\\\Local\",\n  SystemRoot = \"C:\\\\Windows\"\n}\n```\n\nLinux 和 macOS 已经暴露了所需的 XDG 路径和 `HOME`，因此通常可以省略这里的 `env` 表格。仅当您在受限容器内运行 CLI 时才需要添加覆盖。\n\n### FastMCP & 发现清单\n\n- 运行 `fastmcp run fastmcp.json`，通过 [FastMCP](https:\u002F\u002Ffastmcp.wiki\u002F) 启动服务器，使用正确的源入口点和依赖项元数据。传递 `--project-path`（或在启动后调用 `set_project_path` 工具），以便索引针对正确的仓库进行构建。\n- 提供或复制 `.well-known\u002Fmcp.json`，以共享符合标准的 MCP 清单。支持 `.well-known` 约定的客户端（例如 Claude Desktop、Codex CLI）可以直接导入此文件，而无需手动创建配置。\n- 当您希望公开更丰富的 LLM Feed 元数据时，发布 `.well-known\u002Fmcp.llmfeed.json`。它引用相同的 `code-index` 服务器定义以及文档\u002F源链接，这有助于注册表自动呈现描述、标签和功能。\n\n在分享这些清单时，请提醒使用者提供 `--project-path`（或调用 `set_project_path`），以便服务器索引到预期的仓库。\n\n## 典型用例\n\n**代码审查**：“找出所有使用旧 API 的地方”  \n**重构帮助**：“这个函数在哪里被调用？”  \n**学习项目**：“给我看看这个 React 项目的主组件”  \n**调试**：“搜索所有与错误处理相关的代码”\n\n## 核心功能\n\n### 🔍 **智能搜索与分析**\n- **双策略架构**：针对 10 种核心语言的专业 tree-sitter 解析，对 50 多种文件类型采用回退策略\n- **直接 tree-sitter 集成**：对于专业语言不使用正则表达式回退——快速失败并显示清晰错误\n- **高级搜索**：自动检测并使用最佳可用工具（ugrep、ripgrep、ag 或 grep）\n- **通用文件支持**：从高级 AST 解析到基本文件索引，覆盖全面\n- **文件分析**：运行 `build_deep_index` 后，可深入了解结构、导入、类、方法以及复杂度指标\n\n### 🗂️ **多语言支持**  \n- **10 种使用 tree-sitter AST 解析的语言**：Python、JavaScript、TypeScript、Java、Kotlin、C#、Go、Objective-C、Zig、Rust\n- **50 多种使用回退策略的文件类型**：C\u002FC++、Ruby、PHP，以及其他所有编程语言\n- **文档与配置文件**：Markdown、JSON、YAML、XML，并进行适当处理\n- **Web 前端**：Vue、React、Svelte、HTML、CSS、SCSS\n- **Java Web 与构建**：JSP\u002FTag 文件（`.jsp`、`.jspx`、`.jspf`、`.tag`、`.tagx`）、Grails\u002FGSP（`.gsp`）、Gradle & Groovy 构建（`.gradle`、`.groovy`）、`.properties` 以及 Protocol Buffers（`.proto`）\n- **数据库**：SQL 变体、NoSQL、存储过程、迁移\n- **配置**：JSON、YAML、XML、Markdown\n- **[查看完整列表](#supported-file-types)**\n\n### ⚡ **实时监控与自动刷新**\n- **文件监视器**：文件更改时自动更新索引\n- **跨平台**：原生操作系统文件系统监控\n- **智能处理**：批量处理快速变化，防止过度重建\n- **浅层索引刷新**：监视文件变化并保持文件列表最新；当需要符号元数据时再进行深度重建\n\n### ⚡ **性能与效率**\n- **Tree-sitter AST 解析**：原生语法解析，用于准确提取符号\n- **持久化缓存**：存储索引，以便后续访问速度极快\n- **智能过滤**：智能排除构建目录和临时文件\n- **内存高效**：针对大型代码库优化\n- **直接依赖**：无回退机制——快速失败并显示清晰错误信息\n\n## 支持的文件类型\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>📁 编程语言（点击展开）\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n**具有专用 Tree-sitter 策略的语言：**\n- **Python**（`.py`、`.pyw`） - 全面的 AST 分析，支持类\u002F方法提取和调用跟踪\n- **JavaScript**（`.js`、`.jsx`、`.mjs`、`.cjs`） - 使用 Tree-sitter 解析 ES6+ 的类和函数\n- **TypeScript**（`.ts`、`.tsx`） - 完整的类型感知符号提取，包括接口\n- **Java**（`.java`） - 完整的类层次结构、方法签名及调用关系\n- **Kotlin**（`.kt`、`.kts`） - 包感知的符号提取，包含方法和调用关系\n- **C#**（`.cs`） - 命名空间感知的类型\u002F成员提取，支持调用关系\n- **Go**（`.go`） - 结构体方法、接收者类型及函数分析\n- **Rust**（`.rs`） - 函数、模块感知的命名、impl 方法、结构体\u002F枚举\u002F特质，以及基础的调用关系\n- **Objective-C**（`.m`、`.mm`） - 区分类方法与实例方法，使用 `+\u002F-` 符号表示\n- **Zig**（`.zig`、`.zon`） - 使用 Tree-sitter AST 解析函数和结构体\n\n**其他所有编程语言：**\n所有其他编程语言均使用 **FallbackParsingStrategy**，提供基础的文件索引和元数据提取。其中包括：\n- **系统与底层：** C\u002FC++（`.c`、`.cpp`、`.h`、`.hpp`）\n- **面向对象：** Scala（`.scala`）、Swift（`.swift`）\n- **脚本与动态：** Ruby（`.rb`）、PHP（`.php`）、Shell（`.sh`、`.bash`）\n- **以及其他 40 多种文件类型** - 均通过后备策略进行基础索引处理\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🌐 Web 与前端（点击展开）\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n**框架与库：**\n- Vue（`.vue`）\n- Svelte（`.svelte`）\n- Astro（`.astro`）\n\n**样式：**\n- CSS（`.css`、`.scss`、`.less`、`.sass`、`.stylus`、`.styl`）\n- HTML（`.html`）\n\n**模板：**\n- Handlebars（`.hbs`、`.handlebars`）\n- EJS（`.ejs`）\n- Pug（`.pug`）\n- FreeMarker（`.ftl`）\n- Mustache（`.mustache`）\n- Liquid（`.liquid`）\n- ERB（`.erb`）\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>🗄️ 数据库与 SQL（点击展开）\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n**SQL 变体：**\n- 标准 SQL（`.sql`、`.ddl`、`.dml`）\n- 数据库特定格式（`.mysql`、`.postgresql`、`.psql`、`.sqlite`、`.mssql`、`.oracle`、`.ora`、`.db2`）\n\n**数据库对象：**\n- 存储过程与函数（`.proc`、`.procedure`、`.func`、`.function`）\n- 视图与触发器（`.view`、`.trigger`、`.index`）\n\n**迁移与工具：**\n- 迁移文件（`.migration`、`.seed`、`.fixture`、`.schema`）\n- 工具专用格式（`.liquibase`、`.flyway`）\n\n**NoSQL 与现代数据库：**\n- 图数据库与查询语言（`.cql`、`.cypher`、`.sparql`、`.gql`）\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>📄 文档与配置（点击展开）\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n- Markdown（`.md`、`.mdx`）\n- 配置文件（`.json`、`.xml`、`.yml`、`.yaml`、`.properties`）\n\n\u003C\u002Fdetails>\n\n### 🛠️ **开发设置**\n\n如需贡献或本地开发：\n\n1. **克隆并安装：**\n   ```bash\n   git clone https:\u002F\u002Fgithub.com\u002Fjohnhuang316\u002Fcode-index-mcp.git\n   cd code-index-mcp\n   uv sync\n   ```\n\n2. **配置本地开发环境：**\n   ```json\n   {\n     \"mcpServers\": {\n       \"code-index\": {\n         \"command\": \"uv\",\n         \"args\": [\"run\", \"code-index-mcp\"]\n       }\n     }\n   }\n   ```\n\n3. **使用 MCP Inspector 调试：**\n   ```bash\n   npx @modelcontextprotocol\u002Finspector uv run code-index-mcp\n   ```\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>替代方案：手动 pip 安装\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n如果您更倾向于传统的 pip 管理方式：\n\n```bash\npip install code-index-mcp\n```\n\n然后配置：\n```json\n{\n  \"mcpServers\": {\n    \"code-index\": {\n      \"command\": \"code-index-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\n\u003C\u002Fdetails>\n\n\n## 可用工具\n\n### 🏗️ **项目管理**\n| 工具 | 描述 |\n|------|-------------|\n| **`set_project_path`** | 初始化项目目录的索引 |\n| **`refresh_index`** | 文件变更后重建浅层文件索引 |\n| **`build_deep_index`** | 生成深度分析使用的完整符号索引 |\n| **`get_settings_info`** | 查看当前项目配置和状态 |\n\n*当需要符号级数据时，请运行 `build_deep_index`；默认的浅层索引则用于快速文件发现。*\n\n### 🔍 **搜索与发现**\n| 工具 | 描述 |\n|------|-------------|\n| **`search_code_advanced`** | 智能搜索，默认按字面匹配，可选 `regex=True`、模糊匹配、文件过滤及分页结果（默认每页 10 条）；正则模式需要原生搜索工具，因为基础后备策略仅支持字面匹配 |\n| **`find_files`** | 使用 glob 模式查找文件（例如 `**\u002F*.py`） |\n| **`get_file_summary`** | 分析文件结构、函数、导入及复杂度（需深索引） |\n\n### 🔄 **监控与自动刷新**\n| 工具 | 描述 |\n|------|-------------|\n| **`get_file_watcher_status`** | 检查文件监视器的状态和配置 |\n| **`configure_file_watcher`** | 启用\u002F禁用自动刷新并配置相关设置 |\n\n### 🛠️ **系统与维护**\n| 工具 | 描述 |\n|------|-------------|\n| **`create_temp_directory`** | 设置索引数据的存储目录 |\n| **`check_temp_directory`** | 验证索引存储位置及权限 |\n| **`clear_settings`** | 重置所有缓存数据和配置 |\n| **`refresh_search_tools`** | 重新检测可用的搜索工具（ugrep、ripgrep 等） |\n\n## 使用示例\n\n### 🎯 **快速入门流程**\n\n**1. 初始化项目**\n```\n将项目路径设置为 \u002FUsers\u002Fdev\u002Fmy-react-app\n```\n*自动索引您的代码库，并创建可搜索的缓存*\n\n**2. 探索项目结构**\n```\n查找 src\u002Fcomponents 目录下的所有 TypeScript 组件文件\n```\n*使用：`find_files`，模式为 `src\u002Fcomponents\u002F**\u002F*.tsx`*\n\n**3. 分析关键文件**\n```\n请给我 src\u002Fapi\u002FuserService.ts 的概要信息\n```\n*使用：`get_file_summary` 显示函数、导入和复杂度*\n*提示：如果收到 `needs_deep_index` 的响应，请先运行 `build_deep_index`。*\n\n### 🔍 **高级搜索示例**\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>代码模式搜索\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n使用 `regex=True` 搜索所有匹配 \"get.*Data\" 的函数调用\n```\n*匹配结果：`getData()`、`getUserData()`、`getFormData()` 等。正则表达式搜索需要显式启用；请安装原生搜索工具并使用 `regex=True`，因为基础的回退行为仅支持字面量匹配。*\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>模糊函数搜索\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n通过模糊搜索查找与认证相关的函数 'authUser'\n```\n*匹配结果：`authenticateUser`、`authUserToken`、`userAuthCheck` 等。*\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>特定语言搜索\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n仅在 Python 文件中搜索 \"API_ENDPOINT\"\n```\n*使用：`search_code_advanced` 进行字面量匹配，并设置 `file_pattern: \"*.py\"`（默认返回 10 条结果；可通过 `max_results` 扩展或 `start_index` 进行分页）。*\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>自动刷新配置\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n配置文件更改时自动更新索引\n```\n*使用：`configure_file_watcher` 启用\u002F禁用监控，并设置防抖延迟时间。*\n\n\u003C\u002Fdetails>\n\n\u003Cdetails>\n\u003Csummary>\u003Cstrong>项目维护\u003C\u002Fstrong>\u003C\u002Fsummary>\n\n```\n我添加了新组件，请刷新项目索引。\n```\n*使用：`refresh_index` 更新可搜索缓存。*\n\n\u003C\u002Fdetails>\n\n## 故障排除\n\n### 🔄 **自动刷新未生效**\n\n如果文件更改时自动索引更新未生效，请尝试：\n- `pip install watchdog`（可能解决环境隔离问题）\n- 使用手动刷新：在修改文件后调用 `refresh_index` 工具\n- 检查文件监视器状态：使用 `get_file_watcher_status` 验证监控是否已启用\n\n### **macOS 文件监视选项**\n\n默认的 FSEvents 监视器适用于大多数项目。若遇到问题，可通过 `configure_file_watcher` 切换到其他监视器：\n\n- `\"auto\"`（默认）：平台默认（macOS 上为 FSEvents）\n- `\"kqueue\"`：Kqueue 监视器（macOS\u002FBSD）\n- `\"fsevents\"`：强制使用 FSEvents（仅限 macOS）\n- `\"polling\"`：跨平台轮询后备方案\n\n注意：Kqueue 每个被监视的文件会占用一个文件描述符。对于大型项目，若使用 Kqueue，可能需要提高限制：`ulimit -n 10240`\n\n## 开发与贡献\n\n### 🔧 **从源码构建**\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fjohnhuang316\u002Fcode-index-mcp.git\ncd code-index-mcp\nuv sync\nuv run code-index-mcp\n```\n\n### 🐛 **调试**\n```bash\nnpx @modelcontextprotocol\u002Finspector uvx code-index-mcp\n```\n\n### 🤝 **贡献**\n欢迎贡献！请随时提交 Pull Request。\n\n---\n\n### 📜 **许可证**\n[MIT 许可证](LICENSE)\n\n### 🌐 **翻译**\n- [繁體中文](README_zh.md)\n- [日本語](README_ja.md)","# Code Index MCP 快速上手指南\n\nCode Index MCP 是一个基于模型上下文协议（MCP）的服务器工具，旨在帮助 AI 助手智能地索引、搜索和分析代码库。它支持多种编程语言的 AST 解析，让 AI 能更深入地理解你的项目结构。\n\n## 环境准备\n\n在开始之前，请确保满足以下系统要求：\n\n*   **操作系统**：Windows, macOS, 或 Linux\n*   **Python 版本**：3.10 或更高版本\n*   **包管理工具**：推荐安装 [uv](https:\u002F\u002Fgithub.com\u002Fastral-sh\u002Fuv)（比传统 pip 更快速、高效）\n    *   安装 uv (官方脚本): `curl -LsSf https:\u002F\u002Fastral.sh\u002Fuv\u002Finstall.sh | sh` (Mac\u002FLinux) 或 `powershell -c \"irm https:\u002F\u002Fastral.sh\u002Fuv\u002Finstall.ps1 | iex\"` (Windows)\n\n## 安装与配置\n\nCode Index MCP 无需手动安装到全局环境，推荐通过 MCP 客户端配置文件直接调用 `uvx` 进行按需运行和自动安装。\n\n### 1. 配置 MCP 客户端\n\n根据你的 AI 客户端类型，将以下配置添加到对应的配置文件中。\n\n#### 方案 A：Claude Desktop \u002F 通用 JSON 配置\n编辑 `claude_desktop_config.json` 或 `~\u002F.claude.json`：\n\n```json\n{\n  \"mcpServers\": {\n    \"code-index\": {\n      \"command\": \"uvx\",\n      \"args\": [\"code-index-mcp\"]\n    }\n  }\n}\n```\n\n> **提示**：若希望启动时自动锁定项目路径，可在 `args` 数组末尾添加 `--project-path \u002F绝对路径\u002F到\u002F你的\u002F仓库`。\n\n#### 方案 B：Anthropic Codex CLI (TOML 格式)\n编辑 `~\u002F.codex\u002Fconfig.toml` (Windows 位于 `C:\\Users\\\u003C你>\\.codex\\config.toml`)：\n\n```toml\n[mcp_servers.code-index]\ntype = \"stdio\"\ncommand = \"uvx\"\nargs = [\"code-index-mcp\"]\n```\n\n*注意：在 Windows 上运行 Codex CLI 时，可能需要在同一配置块中补充环境变量（HOME, APPDATA 等）以确保 `uvx` 正常找到用户目录。*\n\n### 2. 重启应用\n保存配置文件后，**完全重启**你的 AI 客户端应用程序。`uvx` 会在首次运行时自动下载并执行最新版本的 `code-index-mcp`。\n\n## 基本使用\n\n配置完成后，你可以直接在对话框中向 AI 助手发送指令来使用该项目。\n\n### 第一步：设置项目路径（如未在启动参数中指定）\n如果启动时未添加 `--project-path`，请先告诉 AI 要分析的项目位置：\n```text\nSet the project path to \u002FUsers\u002Fdev\u002Fmy-react-app\n```\n*(请将路径替换为你本地的实际项目绝对路径)*\n\n### 第二步：常用指令示例\n一旦项目路径设定成功，即可尝试以下功能：\n\n*   **查找文件**：\n    ```text\n    Find all TypeScript files in this project\n    ```\n*   **代码搜索**：\n    ```text\n    Search for \"authentication\" functions\n    ```\n*   **深度分析**（触发符号级索引）：\n    ```text\n    Analyze the main App.tsx file\n    ```\n    *(注：首次深度分析可能会触发 `build_deep_index`，稍作等待即可获得详细的类、方法和依赖关系分析)*\n\n*   **架构理解**：\n    ```text\n    Show me the main components of this React project\n    ```\n\n### 核心工具说明\nAI 会自动调用以下底层工具完成任务，你也可以显式要求：\n*   `set_project_path`: 初始化项目索引。\n*   `build_deep_index`: 构建完整的符号索引（用于深度代码分析）。\n*   `search_code_advanced`: 高级搜索（支持正则、模糊匹配）。\n*   `get_file_summary`: 获取单个文件的结构摘要。","资深后端工程师李工正接手一个遗留的百万行代码微服务项目，急需在两天内理清复杂的认证逻辑以便进行安全重构。\n\n### 没有 code-index-mcp 时\n- **盲目搜索效率低**：只能依赖 IDE 全局文本搜索，面对大量同名函数和注释干扰，难以精准定位核心业务逻辑。\n- **上下文理解断裂**：大模型因无法读取完整仓库结构，常产生“幻觉”，给出的修改建议往往忽略跨文件依赖，导致编译失败。\n- **人工梳理耗时久**：为了搞清楚一个接口的调用链路，需要手动打开十几个文件逐行追踪，耗费数小时绘制调用图。\n- **重构风险不可控**：由于缺乏全局视角，不敢轻易改动底层公共模块，担心引发未知的连锁反应。\n\n### 使用 code-index-mcp 后\n- **语义级精准定位**：直接让 AI“查找所有处理 OAuth2 令牌刷新的函数”，code-index-mcp 瞬间索引全库并返回精确的代码位置，无视无关噪声。\n- **全局感知更智能**：AI 通过 MCP 协议实时获取项目拓扑，提出的重构方案自动适配现有接口定义，确保跨文件调用的完整性。\n- **自动化链路分析**：输入“分析用户登录流程”，工具立即生成从网关到数据库的完整调用链摘要，将数小时的工作压缩至几分钟。\n- **安全重构有底气**：基于准确的依赖分析，AI 能预先警告哪些修改会影响下游服务，让重构过程可控且安心。\n\ncode-index-mcp 通过将静态代码库转化为大模型可理解的动态上下文，彻底消除了 AI 辅助编程时的“盲区”，让复杂系统的维护变得像对话一样简单。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fjohnhuang316_code-index-mcp_3f2265cc.png","johnhuang316",null,"https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fjohnhuang316_30877e82.jpg","https:\u002F\u002Fgithub.com\u002Fjohnhuang316",[77,81,85,89,93,97,101,105,109,112],{"name":78,"color":79,"percentage":80},"Python","#3572A5",73,{"name":82,"color":83,"percentage":84},"TypeScript","#3178c6",7.4,{"name":86,"color":87,"percentage":88},"JavaScript","#f1e05a",5.6,{"name":90,"color":91,"percentage":92},"Java","#b07219",5.5,{"name":94,"color":95,"percentage":96},"Go","#00ADD8",4.5,{"name":98,"color":99,"percentage":100},"Zig","#ec915c",3.2,{"name":102,"color":103,"percentage":104},"Objective-C","#438eff",0.3,{"name":106,"color":107,"percentage":108},"C#","#178600",0.2,{"name":110,"color":111,"percentage":108},"Kotlin","#A97BFF",{"name":113,"color":114,"percentage":115},"Dockerfile","#384d54",0.1,890,104,"2026-04-06T23:16:31","MIT","Linux, macOS, Windows","未说明","未说明（文档提及针对大型代码库进行了内存优化）",{"notes":124,"python":125,"dependencies":126},"推荐使用 'uv' 进行包管理和运行；支持通过原生文件系统监控实现跨平台实时文件变更检测；在 Windows 上运行 Codex CLI 时可能需要配置特定的环境变量（如 HOME, APPDATA）以确保 'uvx' 正常工作；核心功能依赖 tree-sitter 对 10 种主要语言进行 AST 解析，其他 50+ 种文件类型使用回退策略。","3.10+",[127,128,129],"uv","tree-sitter","ugrep\u002Fripgrep\u002Fag\u002Fgrep (可选外部工具)",[35,14,52],"2026-03-27T02:49:30.150509","2026-04-07T22:50:53.874946",[134,139,144,148,153,158],{"id":135,"question_zh":136,"answer_zh":137,"source_url":138},22857,"为什么在使用 LangChain 调用工具时会报错\"Project path not set\"（未设置项目路径）？","这通常是因为 `MultiServerMCPClient` 为每次工具调用创建了独立的会话，导致之前通过 `set_project_path` 设置的状态丢失。解决方案是显式管理会话以保持连接持久化。请使用 `client.session(\"code-index\")` 方法获取会话对象，并通过该会话调用工具，而不是直接从客户端获取工具列表。这样可以确保项目路径状态在不同工具调用之间保持一致。","https:\u002F\u002Fgithub.com\u002Fjohnhuang316\u002Fcode-index-mcp\u002Fissues\u002F37",{"id":140,"question_zh":141,"answer_zh":142,"source_url":143},22858,"在大型项目中设置 `set_project_path` 时速度非常慢（需数分钟甚至更久），如何优化索引性能？","从 v2.4.0 版本开始，`set_project_path` 已优化为仅生成轻量级的 JSON 浅层索引，从而实现快速的文件发现。如果您需要深层的符号数据（如函数定义、调用关系等），请显式调用新的 `build_deep_index` 工具来触发深度索引构建。此外，`watcher` 和 `refresh_index` 工具现在也仅针对浅层数据集操作，避免了不必要的耗时计算。建议升级至最新版本以获得最佳性能。","https:\u002F\u002Fgithub.com\u002Fjohnhuang316\u002Fcode-index-mcp\u002Fissues\u002F29",{"id":145,"question_zh":146,"answer_zh":147,"source_url":143},22859,"如何使用工具仅获取匹配结果的数量，以避免在处理大型项目时消耗过多 Token？","为了减少 Token 消耗并防止超出 LLM 限制，建议在检索完整内容前先确认匹配数量。虽然早期版本缺乏此选项，但在新版本的工作流中，推荐结合使用其他工具：首先使用 `mcp-server-everything-search` 进行快速的文件名级别查找；然后对匹配到的文件使用 `code-index` 配合 ripgrep\u002Fregex 进行内容搜索。这种分步策略可以有效控制上下文长度，避免一次性加载大量数据。",{"id":149,"question_zh":150,"answer_zh":151,"source_url":152},22860,"运行正则表达式搜索时是否存在安全风险（如 ReDoS 攻击），如何安全地使用高级搜索功能？","在 v2.14.1 之前的版本中，纯 Python 后备搜索策略存在正则表达式拒绝服务（ReDoS）漏洞。该问题已在 v2.14.1 中修复。现在的机制是：正则搜索必须通过 `regex=True` 参数显式开启，且不再使用纯 Python  fallback 执行正则匹配。启用正则模式时，系统强制要求本地安装原生搜索工具（如 `rg`, `ugrep`, `ag`, 或 `grep`）。请确保升级到 v2.14.1 或更高版本，并尽量依赖原生工具进行正则搜索以确保安全。","https:\u002F\u002Fgithub.com\u002Fjohnhuang316\u002Fcode-index-mcp\u002Fissues\u002F84",{"id":154,"question_zh":155,"answer_zh":156,"source_url":157},22861,"索引无法自动更新以反映文件变更，导致代理找不到最新文件，该如何解决？","自动更新功能依赖于文件监视器（watchdog）。如果在 Windows 上使用 `uvx` 环境运行，可能会因环境隔离导致 watchdog 无法正确访问文件系统监控 API，从而无法自动更新索引。作为临时解决方案，建议手动运行 `refresh_index` 工具来更新索引。维护者正在调查 Windows 下的根本原因，并在 README 中记录了此已知问题。如果是非 Windows 环境遇到此问题，可能是独立于 watchdog 的其他 Bug，请尝试更新至最新版本查看是否已修复。","https:\u002F\u002Fgithub.com\u002Fjohnhuang316\u002Fcode-index-mcp\u002Fissues\u002F14",{"id":159,"question_zh":160,"answer_zh":161,"source_url":143},22862,"在大型代码库上索引过程中如果中断，是否会丢失所有进度？有什么建议的工作流吗？","在旧版本中，中断索引确实会导致进度丢失。建议采用分层工作流来处理大型代码库：1. 使用 `mcp-server-everything-search` 进行快速的文件名查找；2. 对特定文件使用 `code-index` 进行内容搜索；3. 仅在必要时使用自定义的静态分析工具（如 `tree-sitter-analyzer`）进行深度结构分析。升级到 v2.3.0 及以上版本后，通过并行处理和优化的解析策略，索引时间已大幅缩短，降低了中断风险。同时，将浅层索引与深层索引分离（见性能优化问答）也能减少单次长时运行的需求。",[163,168,173,178,183,188,193,198,203,208,213,218,223,228,233,238,243,248,253,258],{"id":164,"version":165,"summary_zh":166,"released_at":167},136601,"v2.15.0","## Bug 修复\n- **修复搜索返回 0 条结果 (#79)** — 使用 ugrep 的 `search_code_advanced` 会因循环变量遮蔽搜索模式、无效的 `--ignore` 命令行参数以及错误被静默吞从而返回空结果。\n\n## 改进\n- **所有搜索后端原生支持 .gitignore** — ripgrep 和 ag 现在使用内置的 .gitignore 处理逻辑，不再依赖自定义实现；ugrep 使用 `--ignore-files` 选项；grep 在 Git 仓库中则回退到 `git grep`。\n- **简化搜索排除机制** — 移除了双重过滤系统（`configure_excludes` + `_filter_results`），改为让每个搜索工具原生处理排除规则，从而减少了约 280 行易出错的代码。\n- **配置迁移** — 将 `additional_exclude_patterns` 从 `file_watcher` 配置移至项目级配置（向后兼容——旧配置会自动迁移）。\n- **Rust 特化深度索引** — 引入新的 Rust 符号提取策略，具有更安全的解析方式（PR #89）。\n- **强化索引功能** — 改进了索引和请求上下文中对边缘情况的处理。","2026-04-03T17:08:06",{"id":169,"version":170,"summary_zh":171,"released_at":172},136602,"v2.14.2","## 亮点\n- 在不支持的平台上保护 kqueue 观察器，以避免平台特定的导入或运行时错误。\n- 为不支持 kqueue 的环境添加负面测试覆盖，以确保在跨平台上验证监视器的行为。\n\n## 验证\n- `uv run pytest`\n- 49 个测试通过","2026-03-23T09:30:35",{"id":174,"version":175,"summary_zh":176,"released_at":177},136603,"v2.14.1","## 摘要\n- 通过 使正则表达式搜索成为可选功能，并将字面匹配保留为默认路径。\n- 在基本回退机制中禁用正则表达式执行，因此正则表达式模式现在需要使用原生搜索工具。","2026-03-21T01:08:12",{"id":179,"version":180,"summary_zh":181,"released_at":182},136604,"v2.14.0","## 变更内容\n\n### 错误修复\n- **fix(indexing)**：跳过二进制文件并改进符号解析 (#75)\n  - 深度索引现在会通过 NUL 字节采样检测二进制文件并将其跳过，从而避免在包含 `.index` 文件的 Unity 项目中出现卡顿。\n  - 调用解析性能从 O(N×M) 提升至 O(1) 查找，使用预计算的唯一名称\u002F后缀映射表实现。\n\n**完整变更日志**：https:\u002F\u002Fgithub.com\u002Fjohnhuang316\u002Fcode-index-mcp\u002Fcompare\u002Fv2.13.0...v2.14.0","2026-03-02T01:07:36",{"id":184,"version":185,"summary_zh":186,"released_at":187},136605,"v2.13.0","- 新增 --indexer-path 选项，用于控制索引的存储位置。\n- 新增 --tool-prefix 选项，用于使用自定义前缀重命名工具。\n- 改进了 CLI 对新选项的处理和清理机制。","2026-01-09T07:07:07",{"id":189,"version":190,"summary_zh":191,"released_at":192},136606,"v2.12.0","- 添加带有 `end_line` 支持的 `get_symbol_body` 工具，用于在不加载完整文件的情况下提取特定符号的代码。\n- 通过设置超时、对大文件进行轻量级解析以及更严格的资源限制，提升守护进程的稳定性。\n- 引入基于 FIFO 的并发限制机制，应用于所有耗时较长的工具，以防止请求被饿死。\n- 为 HTTP 传输添加基于项目的隔离中间件，并提供可配置的 `--port` 选项。","2026-01-09T05:51:20",{"id":194,"version":195,"summary_zh":196,"released_at":197},136607,"v2.11.0","## 亮点\n- 文件监视器现支持可配置的 `observer_type`，并在 macOS 上优先使用 kqueue，以提升可靠性。\n- 索引功能现在会正确遵循排除模式，确保被过滤的路径始终被跳过。\n\n## 感谢\n- @rmk40","2025-12-30T06:16:53",{"id":199,"version":200,"summary_zh":201,"released_at":202},136608,"v2.10.0","- 添加了基于 tree-sitter 的 C# 解析策略，支持符号和调用提取，并附带示例项目及测试。\n- 添加了基于 tree-sitter 的 Kotlin 解析策略，支持符号和调用提取，并附带示例项目及测试。\n- 修复了 C# 解析器：解决了未完成的调用关系问题，并防止命名空间重复。\n- 更新了依赖项和锁定文件，以适配新的 tree-sitter 语言包。\n\n测试\n- .venv\\\\Scripts\\\\python -m pytest tests\u002Fstrategies\u002Ftest_kotlin_discovery.py tests\u002Fstrategies\u002Ftest_csharp_discovery.py -q","2025-12-18T03:11:27",{"id":204,"version":205,"summary_zh":206,"released_at":207},136609,"v2.9.4","## 修复\n- **服务器：** 恢复了 `files:\u002F\u002F` 资源的功能。\n- **服务器：** 添加了对 URL 编码路径的支持，以处理嵌套文件（修复了通配符路由问题）。\n\n## 文档\n- 更新了关于在资源中使用 URL 编码处理嵌套文件路径的指南。","2025-11-27T02:25:46",{"id":209,"version":210,"summary_zh":211,"released_at":212},136610,"v2.9.3","## 亮点\n- 澄清了 search_code_advanced 的自动正则表达式验证错误；现在会在用户意图使用字面量时提示将其 regex 设置为 False（修复 #57、#60）。\n\n## 更改日志\n- 修复（搜索）：澄清无效正则表达式的提示信息\n- 杂项（发布）：v2.9.3","2025-11-26T02:22:02",{"id":214,"version":215,"summary_zh":216,"released_at":217},136611,"v2.9.2","- relax shallow find_files matching (implicit ** fallback, case-insensitive)\n- add regression tests for lenient file patterns\n\nTests: not run in CI here","2025-11-20T06:38:08",{"id":219,"version":220,"summary_zh":221,"released_at":222},136612,"v2.9.1","## Highlights\n- Expanded whitelist now covers Java web artifacts (JSP\u002Ftag files, Grails GSP) plus Gradle\u002FGroovy builds and Protocol Buffers so every search strategy—including Basic—can scan those files.\n- Documentation in all README variants now calls out the new Java web coverage and added template engines (FreeMarker, Mustache, Liquid, ERB).","2025-11-12T03:27:47",{"id":224,"version":225,"summary_zh":226,"released_at":227},136613,"v2.9.0","## Highlights\n- Upgrade to `mcp` 1.21.0 and refresh the uv lockfile so we stay current with the November 2025 SDK. This brings in the latest transport\u002Fauth fixes (SEP-985 OAuth metadata fallback, Starlette 0.49.1) noted in docs\u002Fmcp-upgrade-notes.md.\n- Simplify the FastMCP surface by removing deprecated resource handlers, relying entirely on Context-injected tools to avoid zero-parameter template regressions.\n- Add restart\u002Fupgrade documentation (`docs\u002Fmcp-restart-playbook.md`, `docs\u002Fmcp-upgrade-notes.md`) and update `.well-known\u002Fmcp.llmfeed.json` so downstream agents see version 2.9.0.\n\n## Validation\n- `uv run --no-sync pytest` (Python 3.13.2) — 16 tests passed.\n- Manual smoke via the restart playbook (set_project_path → build_deep_index → search_code_advanced) completed cleanly earlier in this cycle.","2025-11-10T08:59:52",{"id":229,"version":230,"summary_zh":231,"released_at":232},136614,"v2.8.1","- fix: standardize MCP entry-point error propagation so FastMCP surfaces structured failures (closes #54)\n","2025-11-10T03:20:29",{"id":234,"version":235,"summary_zh":236,"released_at":237},136615,"v2.8.0","## Highlights\n- feat: add Go docstring extraction\n- fix: harden Go import parsing and async discovery\n- ci: reworked release workflow with verification\u002Fpublish stages\n- tests: expanded Go\u002FPython discovery coverage\n\n## Verification\n- uv run pytest\n- uv run code-index-mcp --help\n- uv run python -m build\n- uv run twine check dist\u002F*","2025-11-05T08:38:58",{"id":239,"version":240,"summary_zh":241,"released_at":242},136616,"v2.7.0","- Added pagination defaults to search_code_advanced (10 matches per page) with max_results\u002Fstart_index controls.\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fjohnhuang316\u002Fcode-index-mcp\u002Fcompare\u002Fv2.6.0...v2.7.0","2025-10-30T06:39:37",{"id":244,"version":245,"summary_zh":246,"released_at":247},136617,"v2.6.0","### Highlights\n- Added `--project-path` CLI flag so the server can initialize a repository immediately on startup.\n- CLI docs updated across all supported languages to document the new startup flag.\n- Server now guards optional `--mount-path` usage for older FastMCP versions that do not support it.\n\n### Notes\n- Supplying an invalid path with `--project-path` causes startup to fail fast with a clear error.","2025-10-29T08:36:49",{"id":249,"version":250,"summary_zh":251,"released_at":252},136618,"v2.5.1","- Deep index symbol identifiers now use project-relative paths, preventing SQLite uniqueness collisions during rebuilds.\r\n- Added regression coverage to ensure duplicate filenames across directories generate distinct symbol IDs.\r\n- Release notes migrated to Markdown for easier editing.\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fjohnhuang316\u002Fcode-index-mcp\u002Fcompare\u002Fv2.5.0...v2.5.1","2025-10-29T06:00:18",{"id":254,"version":255,"summary_zh":256,"released_at":257},136619,"v2.5.0","### Highlights\r\n- Deep index now persists to SQLite via the new `SQLiteIndexStore`, replacing the legacy JSON cache while keeping build performance stable.\r\n- JavaScript strategy records middleware callbacks in the call graph, giving accurate `called_by` links for Express-style handlers.\r\n- TypeScript strategy captures limiter callbacks, closing gaps for `.ts` middleware exports and aligning coverage with JavaScript.\r\n- Added dedicated regression tests for the SQLite store\u002Fmanager plus JavaScript and TypeScript call graph fixtures.\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fjohnhuang316\u002Fcode-index-mcp\u002Fcompare\u002Fv2.4.1...v2.5.0","2025-10-28T03:44:35",{"id":259,"version":260,"summary_zh":261,"released_at":262},136620,"v2.4.1","- Code search now shares the central FileFilter blacklist, keeping results consistent with indexing (no more `node_modules` noise).\r\n- CLI search strategies emit the appropriate exclusion flags automatically (ripgrep, ugrep, ag, grep).\r\n- Basic fallback search prunes excluded directories during traversal, avoiding unnecessary IO.\r\n- Added regression coverage for the new filtering behaviour (`tests\u002Fsearch\u002Ftest_search_filters.py`).\r\n\r\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fjohnhuang316\u002Fcode-index-mcp\u002Fcompare\u002Fv2.4.0...v2.4.1","2025-10-03T02:32:31"]