金大哥 - semantic-context-mcp MCP 详情

article

README

🚀 企业代码搜索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"
      }
    }
  }
}

可用工具

| 属性 | 详情 | |------|------| | index_local_project | 对本地目录进行索引 | | search_codebase | 在代码中进行语义搜索 | | list_indexed_projects | 列出所有已索引的项目 | | get_embedding_provider_info | 获取嵌入向量提供商的信息 |

高级配置

文件模式

服务器支持广泛的文件类型识别，包括：

编程语言：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

安全考虑

主要优势

私有数据：Ollama将所有数据保留在本地
无需外部API：使用Ollama时，数据不会离开您的网络
自行托管：对代码和嵌入向量拥有完全控制权
隔离环境：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
调整块大小
验证源文件质量

协作工作流

典型的企业工作流

DevOps对 主要项目进行索引
开发人员使用 Claude搜索代码
通过CI/CD进行自动更新
进行代码分析 以进行代码审查

最佳实践

在重要合并后进行索引
使用描述性的项目名称
维护特定项目的搜索过滤器
记录命名约定

开发

项目结构

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模式，并带有示例和验证。

Docker支持

项目包含完整的Docker设置：

ChromaDB：用于嵌入向量的向量数据库
Ollama：本地嵌入向量生成
PostgreSQL：可选的元数据存储

所有服务都通过Docker Compose进行编排，便于部署。

📄 许可证

本项目采用MIT许可证，详情请参阅LICENSE文件。

🤝 贡献

欢迎贡献代码！请随时提交Pull Request。

分叉项目
创建功能分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
打开Pull Request

📞 支持与问题反馈

📧 问题反馈：GitHub Issues
💬 讨论：GitHub Discussions
☕ 支持项目：Buy Me a Coffee