Source MCP

🔍 Source-MCP

A Model Context Protocol (MCP) server for semantic search and Retrieval-Augmented Generation (RAG) over local codebases and documents.

______________________________________________________________________

📖 概述

来源MCP 利用 模型上下文协议 为人工智能助手（如Claude、Gemini等）提供通过语义搜索直接访问本地文件的功能。

Source MCP不会手动将粘贴代码或文档复制到您的提示中，而是自动为您的本地存储库建立索引，生成向量嵌入，并使AI能够语义搜索和检索最相关的文件。

✨ 主要特点

• 双重嵌入支持：

- OpenAI： 使用稳健 text-embedding-3-small （1536个维度），用于高质量的企业嵌入。 - 快速嵌入（本地）： 用途 sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 （384调暗）。完全在本地运行，不需要API密钥，并支持多语言查询。

• 智能增量索引： 使用文件指纹（修改时间+大小）仅索引新的或修改过的文件，确保闪电般快速的启动时间。
• 自动迁移： 自动检测嵌入维度的变化（例如，从OpenAI切换到FastEmbed），并安全地重新创建向量索引。
• Web仪表板（端口8000）：

- 实时日志： 通过自动滚动查看实时索引和搜索活动。 - Reindex基础： 强制擦除矢量数据库和清单，以进行全新的完整扫描。 - Reindex基础： 强制擦除矢量数据库和清单，以进行全新的完整扫描。 - 搜索调试： 特殊端点(/api/search/debug?q=...)以测试原始语义搜索分数。

🤔 为什么本地嵌入和 zvec?

我们使用 实验，一个由阿里巴巴维护的轻量级、高性能的矢量数据库。 zvec 直接嵌入到Python进程中，无需设置或运行外部向量服务器（如Pinecone、Milvus或Qdrant）。结合 FastEmbed，这允许Source MCP构建整个语义搜索管道 完全离线，快速且完全在您的本地计算机上。

🚀 安装和设置

1. 先决条件： 确保你有Python 3.10+和 uv 安装。

1. 克隆存储库：

   git clone https://github.com/AlexShimmy/source-mcp.git
   cd source-mcp

1. 安装依赖关系：

   # uv will automatically handle virtual environment creation and dependencies
   uv sync

⚙️ 配置

创建一个 .env 根目录中的文件（您可以复制 .env.example 如果可用）。

# Choose your provider: "openai" or "fastembed"
EMBEDDING_PROVIDER=openai

# Required ONLY if using OpenAI
# Required ONLY if using OpenAI
OPENAI_API_KEY=sk-your-openai-api-key

# Optional: Path to store the vector database (Defaults to `.source-mcp/zvec_db` in the index dir)
ZVEC_PATH=./zvec_db

# Optional: Which directory to index (Defaults to current directory)
SOURCE_MCP_INDEX_DIR=/path/to/your/project

# Optional: Port for the Web Dashboard (Defaults to 8000)
WEB_PORT=8000

🖱️ 用法

手动运行（终端和仪表板）

要手动启动MCP服务器并访问web仪表板：

uv run python -m src.main --path .

• 这 MCP协议 会继续听 stdio.
• 这 Web仪表板 将在 http://localhost:8000.

🔌 MCP配置

所有客户端的配置都是相同的（Claude Desktop、Cursor、VS Code/Cline等）：

{
  "mcpServers": {
    "source-mcp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/source-mcp", "run", "python", "-m", "src.main"]
    }
  }
}

所有其他设置（例如 SOURCE_MCP_INDEX_DIR, EMBEDDING_PROVIDER 或 OPENAI_API_KEY)应通过配置 .env 源MCP根目录中的文件。

🧪 测试

该项目使用 pytest 用于单元和端到端测试。要运行测试套件，请执行以下操作：

uv run python -m pytest tests/ -v

📜 许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。