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