Semantic Context MCP

🚀 企業代碼搜索MCP服務器

這是一個強大的模型上下文協議（MCP） 服務器，用於進行語義代碼搜索，並配備共享向量數據庫。它支持使用OpenAI和Ollama生成嵌入向量，能夠對本地項目或Git倉庫進行索引。

🚀 快速開始

1. 克隆倉庫

git clone https://github.com/your-username/semantic-context-mcp.git
cd semantic-context-mcp

2. 安裝依賴

npm install

3. 配置環境

cp .env.example .env
# 編輯.env文件，進行配置

4. 啟動服務

# 啟動ChromaDB和Ollama
docker-compose up -d

# 等待Ollama下載模型
docker-compose logs -f ollama-setup

5. 構建並運行

npm run build
npm start

✨ 主要特性

• 基於AI嵌入向量的語義代碼搜索
• 雙提供商支持：可使用OpenAI或Ollama（本地、私有）
• 靈活的索引方式：支持本地項目或Git倉庫
• 使用ChromaDB的共享向量數據庫
• 多項目管理：可同時處理多個項目
• 自動項目結構分析
• 基於代碼片段的相似代碼搜索
• 企業級適用：私有、安全、可自行託管

📦 安裝指南

系統要求

• Node.js 18+
• Docker和Docker Compose
• Git（用於倉庫索引）

💻 使用示例

基礎用法

索引本地項目

將位於/home/user/my-app的本地項目以“frontend-app”的名稱進行索引

在代碼中搜索

在所有已索引的項目中搜索“main application function”

查找相似代碼

def authenticate_user(username, password):
    return check_credentials(username, password)

分析項目結構

分析項目“frontend-app”的結構

高級用法

功能搜索

• "認證邏輯在哪裡？"
• "處理數據庫操作的函數"
• "環境變量配置"
• "API的單元測試"

代碼分析

• "使用了哪些設計模式？"
• "項目中最複雜的函數"
• "代碼中的錯誤處理"

特定技術搜索

• "使用React鉤子的代碼"
• "PostgreSQL查詢"
• "Docker配置"

📚 詳細文檔

配置

使用Ollama（企業推薦）

# .env
EMBEDDING_PROVIDER=ollama
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=nomic-embed-text
CHROMA_HOST=localhost
CHROMA_PORT=8000

使用OpenAI

# .env
EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=your-api-key
OPENAI_MODEL=text-embedding-3-small

與Claude Desktop集成

要將此MCP服務器與Claude Desktop一起使用，請在claude_desktop_config.json中添加以下內容：

{
  "mcpServers": {
    "enterprise-code-search": {
      "command": "node",
      "args": ["/path/to/semantic-context-mcp/dist/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "ollama",
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_MODEL": "nomic-embed-text",
        "CHROMA_HOST": "localhost",
        "CHROMA_PORT": "8000",
        "COMPANY_NAME": "YourCompany"
      }
    }
  }
}

可用工具

高級配置

推薦的Ollama模型

# 用於代碼嵌入向量
ollama pull nomic-embed-text    # 最適合代碼（384維）
ollama pull all-minilm         # 輕量級替代方案（384維）
ollama pull mxbai-embed-large  # 更高精度（1024維）

文件模式

服務器支持廣泛的文件類型識別，包括：

• 編程語言：Python、JavaScript/TypeScript、Java、C/C++、Go、Rust、PHP、Ruby、Swift、Kotlin、Scala等
• Web技術：HTML、CSS、SCSS、Vue、Svelte
• 配置文件：JSON、YAML、TOML、Docker、Terraform
• 文檔：Markdown、reStructuredText、AsciiDoc
• 數據庫：SQL文件

性能調優

# 最大塊大小（字符數）
MAX_CHUNK_SIZE=1500

# 最大文件大小（KB）
MAX_FILE_SIZE=500

# 索引的批量大小
BATCH_SIZE=100

企業部署

選項1：專用服務器

# 在企業服務器上
docker-compose up -d

選項2：網絡部署

# 配置網絡訪問
CHROMA_HOST=192.168.1.100
OLLAMA_HOST=http://192.168.1.100:11434

安全考慮

主要優勢

1. 私有數據：Ollama將所有數據保留在本地
2. 無需外部API：使用Ollama時，數據不會離開您的網絡
3. 自行託管：對代碼和嵌入向量擁有完全控制權
4. 隔離環境：Docker容器提供隔離

安全最佳實踐

# 限制ChromaDB訪問
CHROMA_SERVER_HOST=127.0.0.1  # 僅本地訪問

# 在生產環境中使用HTTPS
OLLAMA_HOST=https://ollama.company.com

監控與故障排除

有用的日誌

# 查看索引日誌
docker-compose logs -f enterprise-mcp-server

# ChromaDB性能
docker-compose logs -f chromadb

# 監控Ollama
curl http://localhost:11434/api/tags

常見問題

Ollama無響應：

curl http://localhost:11434/api/tags
# 如果失敗：docker-compose restart ollama

ChromaDB速度慢：

# 檢查磁盤空間
docker system df
# 必要時清理
docker system prune

嵌入向量質量不佳：

• 嘗試不同的模型：all-minilm 與 nomic-embed-text
• 調整塊大小
• 驗證源文件質量

協作工作流

典型的企業工作流

1. DevOps對 主要項目進行索引
2. 開發人員使用 Claude搜索代碼
3. 通過CI/CD進行自動更新
4. 進行代碼分析 以進行代碼審查

最佳實踐

• 在重要合併後進行索引
• 使用描述性的項目名稱
• 維護特定項目的搜索過濾器
• 記錄命名約定

開發

項目結構

src/
├── index.ts          # 主MCP服務器
└── http-server.ts    # HTTP服務器變體

scripts/              # 安裝和實用腳本
docker-compose.yml    # 服務編排
package.json         # 依賴項和腳本

可用腳本

npm run build        # 編譯TypeScript
npm run dev          # 開發模式
npm run start        # 生產模式
npm run clean        # 清理構建目錄

🔧 技術細節

API參考

MCP服務器實現了標準的模型上下文協議，提供以下特定工具：

• index_local_project：使用可配置的文件模式對本地目錄進行索引
• search_codebase：帶有項目過濾和相似度評分的語義搜索
• list_indexed_projects：列出所有已索引的項目及其元數據
• get_embedding_provider_info：獲取當前嵌入向量提供商的狀態和配置

每個工具都包含詳細的JSON模式，並帶有示例和驗證。

推薦的AI模型

用於嵌入向量（Ollama）

• nomic-embed-text：針對代碼進行了優化
• all-minilm：平衡、快速
• mxbai-embed-large：高精度

用於嵌入向量（OpenAI）

• text-embedding-3-small：經濟高效
• text-embedding-3-large：更高精度

Docker支持

項目包含完整的Docker設置：

• ChromaDB：用於嵌入向量的向量數據庫
• Ollama：本地嵌入向量生成
• PostgreSQL：可選的元數據存儲

所有服務都通過Docker Compose進行編排，便於部署。

📄 許可證

本項目採用MIT許可證，詳情請參閱LICENSE文件。

🤝 貢獻

歡迎貢獻代碼！請隨時提交Pull Request。

1. 分叉項目
2. 創建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打開Pull Request

📞 支持與問題反饋

• 📧 問題反饋：GitHub Issues
• 💬 討論：GitHub Discussions
• ☕ 支持項目：Buy Me a Coffee