使用说明

🚀 MCP代码库服务器

全面 模型上下文协议（MCP） 为Claude等LLM提供高级代码库交互功能的服务器。将其视为赋予Claude“开发人员超能力”来理解、搜索和分析整个代码库。

✨ 特性

功能	描述	状态
🔍 代码库索引	递归扫描目录、检测语言、提取元数据	✅ 准备好了
📂 文件操作	带过滤器的智能列表（类型、大小、深度、元数据）	✅ 准备好了
📄 文件读取	使用行范围、令牌限制、智能分块进行读取	✅ 准备好了
🔤 快速搜索	带上下文的Grep式关键字/正则表达式搜索	✅ 准备好了
🧱 符号提取	函数、类、导入的AST解析（Python）	✅ 准备好了
🧠 语义搜索	使用嵌入的AI驱动的相似性搜索	✅ 准备好了

🎯 你能做什么？

👤 "Index my Django project and find all authentication-related code"
🤖 Claude uses index_codebase → semantic_search → extracts relevant files

👤 "Show me all TODO comments across the codebase"  
🤖 Claude uses search_in_codebase with pattern "TODO"

👤 "What's the structure of the main API file?"
🤖 Claude uses extract_symbols → shows all classes, functions, imports

👤 "Find files similar to database connection handling"
🤖 Claude uses semantic_search → finds semantically similar code

🛠️ 可用工具

1.️⃣ 指数_贬值

递归扫描并索引代码库。

index_codebase(
    directory_path: str,                      # Root directory to scan
    include_extensions: Optional[List[str]],  # e.g., [".py", ".js"]
    exclude_patterns: Optional[List[str]],    # e.g., ["node_modules"]
    max_file_size_mb: float = 10.0           # Skip files larger than this
)

例子： "Index my Python project at ~/code/myapp"

2.️⃣ 列表文件

列出并筛选目录中的文件。

list_files(
    directory_path: str,
    file_type: Optional[str] = None,          # e.g., ".py"
    max_depth: Optional[int] = None,          # Directory depth limit
    include_metadata: bool = False,           # Show size, date, language
    min_size_kb: Optional[float] = None,
    max_size_kb: Optional[float] = None
)

例子： "List all Python files in src/ with metadata"

3.️⃣ read_file

使用可选的行范围读取文件内容。

read_file(
    file_path: str,
    start_line: Optional[int] = None,         # 1-indexed
    end_line: Optional[int] = None,           # Inclusive
    max_tokens: Optional[int] = 4000          # Truncate if larger
)

例子： "Show me lines 50-100 of auth.py"

4.️⃣ 搜索_下载

快速关键字或正则表达式搜索。

search_in_codebase(
    query: str,                               # Search query or regex
    directory_path: Optional[str] = None,     # Search entire directory
    file_path: Optional[str] = None,          # Or search specific file
    use_regex: bool = False,                  # Enable regex matching
    case_sensitive: bool = False,
    file_extensions: Optional[List[str]] = None,
    max_results: int = 50
)

例子： "Find all TODO comments in auth.py" 或 "Search for 'async def' in Python files"

5.️⃣ 提取_符号

使用AST解析提取代码结构。

extract_symbols(
    file_path: str,
    symbol_types: Optional[List[str]] = None  # ["function", "class", "method", "import", "variable"]
)

例子： "Show me all classes and functions in main.py"

注：目前仅支持Python。更多语言即将推出！

6.️⃣ 语义研究

使用AI嵌入查找语义相似的代码。

semantic_search(
    query: str,                               # Natural language query
    directory_path: str,                      # Must be indexed first
    top_k: int = 10,                         # Number of results
    min_similarity: float = 0.5,             # Similarity threshold
    file_extensions: Optional[List[str]] = None
)

例子： "Find code that handles database connections"

注：需要 sentence-transformers 和 faiss-cpu 依赖性。

📚 用法示例

开始使用新的代码库

👤 Index my project at /home/user/myapp

🤖 [Indexes codebase]
   📊 Indexed 156 files, 12,450 lines
   Languages: Python (89 files), JavaScript (45 files), HTML (22 files)

👤 Show me the directory structure

🤖 [Lists files as tree]
   📂 myapp/
   ├── src/
   │   ├── api/
   │   ├── models/
   │   └── utils/
   ├── tests/
   └── config/

👤 What's in the main API file?

🤖 [Extracts symbols]
   Found 5 classes and 12 functions including:
   - AuthManager class with authenticate(), create_token() methods
   - validate_password() function
   - rate_limit decorator

查找和理解代码

👤 Find all database query functions

🤖 [Searches codebase]
   Found 12 matches:
   📄 models/user.py:45 - query_user_by_email()
   📄 models/posts.py:23 - query_posts()
   📄 utils/db.py:67 - execute_query()

👤 Show me the implementation of query_user_by_email

🤖 [Reads file with context]
   [Displays function code with line numbers]

👤 Are there any similar functions?

🤖 [Semantic search]
   Found semantically similar code:
   - query_user_by_id() (similarity: 0.89)
   - find_user() (similarity: 0.82)

🏗️ 项目结构

mcp-codebase-server/
├── server.py                    # Main MCP server
├── codebase_tools/
│   ├── __init__.py             # Package init
│   ├── indexer.py              # Codebase indexing
│   ├── file_ops.py             # File operations
│   ├── searcher.py             # Text/regex search
│   ├── symbol_extractor.py     # AST parsing
│   └── semantic_search.py      # Embedding-based search
├── requirements.txt            # Python dependencies
├── pyproject.toml             # Project config
├── README.md                  # This file
├── USAGE_EXAMPLES.md          # Detailed examples
└── INSTALL.sh                 # Quick install script

🙏 致谢

内置 Anthropic的MCP SDK
语义搜索由句子转换器
矢量相似性通过 FAISS

内置❤️ 对于那些希望他们的人工智能真正理解他们的代码的开发人员#光标状MCP