语义代码搜索MCP服务器

该项目包含一个模型上下文协议（MCP）服务器，该服务器通过一组标准化工具公开索引数据。这使得AI编码代理能够以结构化的方式与索引代码库进行交互。

预备条件

您必须使用此处找到的语义代码搜索索引器对您的代码库进行索引：https://github.com/elastic/semantic-code-search-indexer

使用Docker运行

最简单的方法是使用Docker运行MCP服务器。该服务器在Docker Hub上可用，地址为simianhacker/semantic-code-search-mcp-server。

为了确保您拥有最新版本的镜像，在运行服务器之前，请执行以下命令：

docker pull simianhacker/semantic-code-search-mcp-server

HTTP模式

此模式适用于需要在网络中可访问的容器化环境中运行服务器的情况。

docker run --rm -p 3000:3000 \
  -e ELASTICSEARCH_ENDPOINT=<your_elasticsearch_endpoint> \
  simianhacker/semantic-code-search-mcp-server

请将<your_elasticsearch_endpoint>替换为您Elasticsearch实例的实际端点。

STDIO模式

此模式适用于作为本地进程运行服务器的情况，该服务器可以通过stdin和stdout与代理通信。

带有Elasticsearch端点：

docker run -i --rm \
  -e ELASTICSEARCH_ENDPOINT=<your_elasticsearch_endpoint> \
  simianhacker/semantic-code-search-mcp-server \
  node dist/src/mcp_server/bin.js stdio

带有Elastic Cloud ID：

docker run -i --rm \
  -e ELASTICSEARCH_CLOUD_ID=<your_cloud_id> \
  -e ELASTICSEARCH_API_KEY=<your_api_key> \
  simianhacker/semantic-code-search-mcp-server \
  node dist/src/mcp_server/bin.js stdio

-i标志很重要，因为它告诉Docker以交互模式运行容器，这对于服务器从stdin接收输入是必要的。

连接编码代理

您可以连接到服务器的编码代理，无论是HTTP模式还是STDIO模式。

HTTP模式： 对于通过HTTP连接的代理，如Gemini CLI，您可以在~/.gemini/settings.json文件中添加以下内容：

{
  "mcpServers": {
    "Semantic Code Search": {
      "trust": true,
      "httpUrl": "http://localhost:3000/mcp/",
    }
  }
}

STDIO模式： 对于通过STDIO连接的代理，您需要配置它们直接运行Docker命令。这是Gemini CLI在~/.gemini/settings.json文件中的示例：

{
  "mcpServers": {
    "SemanticCodeSearch": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "ELASTICSEARCH_CLOUD_ID=<your_cloud_id>",
        "-e", "ELASTICSEARCH_API_KEY=<your_api_key>",
        "-e", "ELASTICSEARCH_INDEX=<your_index>",
        "simianhacker/semantic-code-search-mcp-server",
        "node", "dist/src/mcp_server/bin.js", "stdio"
      ]
    }
  }
}

请记得用您的Cloud ID、API密钥和索引名称替换占位符值。

安装和设置

1. 预备条件

• Node.js（v20或更高版本）
• npm
• 运行中的Elasticsearch实例（v8.0或更高版本），并已下载和部署了ELSER模型。

2. 克隆仓库并安装依赖项

git clone <repository-url>
cd semantic-code-search-mcp-server
npm install

3. 配置环境变量

复制.env.example文件，并用您的Elasticsearch凭据更新它。

cp .env.example .env

4. 编译代码

多线程工作者要求项目被编译成JavaScript。

npm run build

运行服务器

MCP服务器可以以两种模式运行：

1. STDIO模式： 这是默认模式。服务器通过stdin和stdout进行通信。

npm run mcp-server

2. HTTP模式： 此模式适用于在类似Docker的容器化环境中运行服务器的情况。

npm run mcp-server:http

服务器默认监听3000端口。您可以通过设置PORT环境变量来更改端口。

使用NPX运行

您还可以直接从git仓库使用npx运行MCP服务器。这是一种无需克隆仓库即可运行服务器的便捷方式。

STDIO模式：

ELASTICSEARCH_ENDPOINT=http://localhost:9200 npx github:elastic/semantic-code-search-mcp-server

HTTP模式：

PORT=8080 ELASTICSEARCH_ENDPOINT=http://localhost:9200 npx github:elastic/semantic-code-search-mcp-server http

可用提示

提示	描述
StartInvestigation	此提示帮助您开始“调查链”，以理解代码库并完成任务。它遵循一个利用可用工具探索代码、分析其组件并制定计划的结构化工作流程。

示例：

/StartInvestigation --task="向kibana服务器添加新路由"

可用工具

MCP服务器提供以下工具：

工具	描述
semantic_code_search	在索引中的代码片段上执行语义搜索。此工具可以结合语义查询和KQL过滤器，提供灵活且强大的搜索能力。
map_symbols_by_query	查询包含特定符号的文件的结构化映射，按文件路径分组。这对于查找特定文件或目录中的所有符号很有用。接受一个可选的size参数来控制返回的文件数量。
symbol_analysis	分析一个符号并返回其定义、调用位置和引用的报告。这对于了解符号在代码库中的作用很有用。
read_file_from_chunks	从索引中读取文件的内容，提供基于最重要索引块的重建视图。
document_symbols	分析文件以识别最能受益于文档的关键符号。这对于自动化提高代码库语义质量的过程很有用。

注意： 所有工具都接受一个可选的index参数，允许您覆盖单个查询的ELASTICSEARCH_INDEX。

---

配置

配置通过.env文件中的环境变量管理。

变量	描述	默认值
ELASTICSEARCH_CLOUD_ID	您的Elastic Cloud实例的Cloud ID。
ELASTICSEARCH_API_KEY	用于Elasticsearch身份验证的API密钥。
ELASTICSEARCH_INDEX	要使用的Elasticsearch索引的名称。	semantic-code-search