Semantic MCP Search

语义代码库搜索MCP服务器

基于语义理解和向量嵌入的智能代码搜索

](https://www.python.org/downloads/)  

特性 • 安装 • 快速开始 • 文档 • 贡献

______________________________________________________________________

✨ 特性

🧠 语义搜索

• 查找代码 意义，而不仅仅是关键字
• 了解自然语言查询
• 即使关键字不匹配，也会返回语义相似的代码

🌐 多语言支持

• python, JavaScript, TypeScript, 去, 锈，以及更多
• 使用Tree sitter进行健壮的、与语言无关的解析
• 易于扩展到新语言

🚀 高性能

• 增量索引 使用Merkle树（仅重新索引更改的文件）
• 本地优先 可选云嵌入设计
• 200毫秒以下 缓存的搜索延迟
• 并行处理 用于批量操作

🔌 可插拔架构

• 多个嵌入提供商：OpenAI，C2LLM，句子转换
• 矢量存储后端：ChromaDB、FAISS、Qdrant等
• 易于通过自定义实现进行扩展

🔒 隐私和安全

• 本地优先：代码永远不会离开你的机器（使用本地嵌入）
• 默认情况下没有遥测或分析
• 输入验证和净化
• 安全的API密钥管理

______________________________________________________________________

📦 安装

来自PyPI（发布时）

pip install semantic-code-search

来源

git clone https://github.com/yourusername/semantic-mcp-search.git
cd semantic-mcp-search
pip install -e .

具有可选依赖关系

# With OpenAI support
pip install -e ".[openai]"

# With development tools
pip install -e ".[dev]"

# With everything
pip install -e ".[openai,dev]"

______________________________________________________________________

🚀 快速开始

1.配置

创建一个 .env 文件：

# MCP Server
MCP_HOST=localhost
MCP_PORT=8000
MCP_TRANSPORT=stdio

# Vector Store
VECTORSTORE_TYPE=chroma
VECTORSTORE_PATH=./data/vectorstore

# Embeddings (choose one)
# Option 1: OpenAI (recommended for best quality)
EMBEDDINGS_PROVIDER=openai
EMBEDDINGS_MODEL=text-embedding-3-small
EMBEDDINGS_API_KEY=sk-your-key-here

# Option 2: C2LLM (local, free, code-specific)
EMBEDDINGS_PROVIDER=c2llm
EMBEDDINGS_MODEL=codefuse-ai/C2LLM-0.5B

# Option 3: Sentence Transformers (local, free)
EMBEDDINGS_PROVIDER=sentence-transformers
EMBEDDINGS_MODEL=all-MiniLM-L6-v2

# Codebase
PATHS_CODEBASE_PATH=./codebase

2.启动服务器

# Start MCP server
semantic-search start

# Or with custom port
semantic-search start --port 9000

# Or with HTTP transport
semantic-search start --transport http

3.执行第一次搜索

服务器公开了您可以调用的MCP工具：

{
  "tool": "semantic_search",
  "arguments": {
    "query": "how is authentication handled?"
  }
}

回应:

[
  {
    "filepath": "src/auth/middleware.py",
    "snippet": "def authenticate(request):\n    token = request.headers.get('Authorization')",
    "score": 0.92,
    "line_numbers": [42, 43]
  }
]

______________________________________________________________________

📚 文档

使用示例

Python API

from semantic_search import SearchPipeline, get_settings
from semantic_search.storage import ChromaDBVectorStore
from semantic_search.embeddings import OpenAIEmbeddingGenerator

# Initialize
settings = get_settings()
embedder = OpenAIEmbeddingGenerator(api_key=settings.embeddings.api_key)
vector_store = ChromaDBVectorStore(path=settings.vectorstore.path)
pipeline = SearchPipeline(embedder, vector_store)

# Search
results = await pipeline.search("authentication middleware", top_k=5)

for result in results:
    print(f"{result.chunk.file_path}:{result.chunk.start_line}")
    print(f"Score: {result.score:.2f}")
    print(f"Code:\n{result.chunk.content}\n")

命令行界面

# Index a directory
semantic-search index ./src

# Search for code
semantic-search search "authentication middleware"

# Search with filters
semantic-search search "database connection" --language python --path "src/db/*"

# Check indexing status
semantic-search status --watch

MCP客户端集成

添加到您的Claude Desktop MCP配置中：

{
  "mcpServers": {
    "semantic-search": {
      "command": "semantic-search",
      "args": ["start"],
      "env": {
        "EMBEDDINGS_PROVIDER": "openai",
        "EMBEDDINGS_API_KEY": "sk-your-key",
        "PATHS_CODEBASE_PATH": "/path/to/your/code"
      }
    }
  }
}

______________________________________________________________________

🏗️ 建筑

该系统遵循模块化管道架构：

MCP Client
    ↓
MCP Server (stdio/HTTP)
    ↓
┌─────────────────────────────────────┐
│  Search Pipeline (cached, expanded) │
├─────────────────────────────────────┤
│  Embedding Service (pluggable)      │
│  ├─ OpenAI                           │
│  ├─ C2LLM (local)                    │
│  └─ Sentence Transformers (local)   │
├─────────────────────────────────────┤
│  Vector Store (abstraction layer)   │
│  ├─ ChromaDB (default)               │
│  ├─ FAISS                            │
│  └─ Qdrant                           │
├─────────────────────────────────────┤
│  Indexing Engine (incremental)      │
│  ├─ Merkle Tree (change detection)  │
│  ├─ Tree-sitter (AST parsing)       │
│  └─ File Watcher                    │
└─────────────────────────────────────┘

关键设计决策:

• Merkle树：高效的增量索引（仅处理更改的文件）
• 树保姆：强大的多语言AST解析
• 策略模式：可插入嵌入和向量存储
• 本地优先：默认情况下，隐私与可选的云嵌入

看 建筑.md 详细的系统设计、组件图、性能特征和安全架构。

______________________________________________________________________

🧪 发展

设置

# Clone repository
git clone https://github.com/yourusername/semantic-mcp-search.git
cd semantic-mcp-search

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install with dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

测试

# Run all tests
pytest

# Run with coverage
pytest --cov=src/semantic_code_search --cov-report=html

# Run only unit tests
pytest -m unit

# Skip slow tests
pytest -m "not slow"

# Run specific test
pytest tests/test_searcher.py::test_search_returns_results

代码质量

# Format code
ruff format src/ tests/

# Lint code
ruff check src/ tests/

# Type checking
mypy src/

# Security scan
bandit -r src/

# Pre-commit hooks (run all checks)
pre-commit run --all-files

项目结构

semantic-mcp-search/
├── src/semantic_search/
│   ├── __init__.py
│   ├── config.py              # Configuration management
│   ├── main.py                # Entry point
│   ├── cli.py                 # CLI interface
│   ├── server/
│   │   └── tools.py           # MCP tool implementations
│   ├── searcher.py            # Search pipeline
│   ├── indexer/               # Indexing engine
│   │   ├── merkle.py          # Merkle tree
│   │   ├── watcher.py         # File watcher
│   │   └── scheduler.py       # Task scheduler
│   ├── processing/
│   │   ├── chunker.py         # Tree-sitter chunker
│   │   └── ast_parser.py      # AST parser
│   ├── embeddings/            # Embedding providers
│   │   ├── base.py            # Abstract interface
│   │   ├── openai.py          # OpenAI provider
│   │   ├── c2llm.py           # C2LLM provider
│   │   └── huggingface.py     # HuggingFace provider
│   └── storage/               # Vector stores
│       ├── base.py            # Abstract interface
│       ├── chromadb_store.py  # ChromaDB implementation
│       └── factory.py         # Backend selection
├── tests/
│   ├── unit/                  # Unit tests
│   ├── integration/           # Integration tests
│   └── conftest.py            # Test fixtures
├── docs/
│   ├── api.md                 # API reference
│   ├── user-guide.md          # User guide
│   └── openapi.yaml           # OpenAPI specification
├── ARCHITECTURE.md            # System architecture
├── CONTRIBUTING.md            # Contribution guidelines
├── README.md
└── pyproject.toml

______________________________________________________________________

🤝 贡献

我们欢迎捐款！请参阅 贡献.md 作为指导方针。

贡献方式

• 🐛 报告错误
• 💡 建议新功能
• 📝 改进文档
• 🔧 提交拉取请求
• 🧪 编写测试
• 👀 审查拉取请求

开发指南

• 为所有新功能编写测试（要求覆盖率>80%）
• 遵循PEP 8风格指南（由ruff强制执行）
• 向所有函数添加类型提示（由mypy强制执行）
• 更新API变更文档
• 保持公关的专注和原子性

______________________________________________________________________

📊 演出

看 建筑.md 进行详细的性能分析。

______________________________________________________________________

🔐 安全

• 输入验证：所有输入均已Pydantic验证
• 路径横向保护：仅限于配置的代码库路径
• API密钥安全：环境变量，.gitignore
• 本地优先：代码永远不会离开机器（具有本地嵌入）
• 无遥测：默认情况下没有分析或跟踪

看 建筑.md 威胁模型和安全措施。

______________________________________________________________________

🗺️ 路线图

v0.2（下一版本）

• \[\]混合搜索（语义+关键字）
• \[\]查询建议/自动完成
• \[\]多文件上下文搜索
• \[\]搜索结果排名反馈

v0.3

• \[\]交叉编码器重新排序
• \[\]代码差异搜索
• \[\]存储库级搜索
• \[\]搜索分析仪表板

v1.0

• \[\]多用户支持
• \[\]团队协作功能
• \[\]IDE集成（VS代码、JetBrains）
• \[\]高级筛选（作者、时间、分支）

______________________________________________________________________

📄 许可证

MIT许可证-请参阅 许可证 了解详情。

______________________________________________________________________

🙏 致谢

使用令人惊叹的开源工具构建：

• 模型上下文协议 -AI代理通信
• 树保姆 -AST解析
• 色度数据库 -矢量数据库
• C2LLM -代码嵌入
• 快速API -Web框架
• 派丹蒂克 -数据验证

______________________________________________________________________

📞 支持

• 问题:
• 讨论:
• 文档: docs/

______________________________________________________________________

⭐ 在GitHub上为我们投票 --它有帮助！

制作❤️ 语义MCP搜索社区