语义代码搜索服务器

语义代码搜索MCP服务器

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

先决条件

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

此MCP服务器所需的索引模型

此MCP服务器需要 位置优先 索引器PR的索引模型 elastic/semantic-code-search-indexer#135:

• <index> 商店 已消除重复内容的块文档 （语义搜索+元数据）。
• <index>_locations 商店 每个块出现一个文档 （文件路径+行范围+目录/git元数据）和引用块 chunk_id.

几种工具查询 <index>_locations 并重新加入 <index> 通过 chunk_id （通常使用 mget).

使用Docker运行

运行MCP服务器最简单的方法是使用Docker。该服务器在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

使用弹性云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.编译代码

多线程worker需要将项目编译为JavaScript。

npm run build

运行服务器

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

1.标准模式： 这是默认模式。服务器通过以下方式进行通信 stdin 和 stdout.

npm run mcp-server

2.HTTP模式： 此模式对于在Docker等容器化环境中运行服务器非常有用。

npm run mcp-server:http

默认情况下，服务器将侦听端口3000。您可以通过设置来更改端口 PORT 环境变量。

使用NPX

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

标准模式：

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 --task="add a new route to the kibana server"

可用工具

MCP服务器提供以下工具：

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

OAuth 2.0身份验证（HTTP模式）

HTTP服务器支持OAuth 2.0承载令牌身份验证。启用后，MCP客户端（Claude Code、VS Code、Cursor）会自动发现授权服务器，获取令牌，并在每次请求时显示它。服务器只验证令牌，从不发出令牌。

先决条件

• 符合OIDC标准的授权服务器（Okta、Auth0、Keycloak等）
• 服务器必须可以在其自己的专用（子）域中访问。 MCP客户端获取 /.well-known/oauth-protected-resource 从服务器域的根目录查找授权服务器。此众所周知的URI必须在域根解析 RFC 8615 第3节和 RFC 9728 第3节。子路径部署（例如。 https://shared.example.com/my-mcp)不会工作。
• Okta应用程序类型必须是SPA（不是Web）。 MCP客户端使用授权码+PKCE流(RFC 7636)没有客户秘密。Web应用程序类型需要客户端密码才能进行代码交换，因此将失败。

JWKS验证（默认--不需要机密）

服务器使用从颁发者的OIDC配置中发现的提供程序的公共JWKS端点在本地验证JWT。

SCS_MCP_OAUTH_ENABLED=true
SCS_MCP_OAUTH_ISSUER=https://your-okta.okta.com/oauth2/default
SCS_MCP_SERVER_URL=https://your-server.example.com     # must be the server's public URL
# Optional:
SCS_MCP_OAUTH_AUDIENCE=api://default                   # for Okta non-URL audience strings
SCS_MCP_OAUTH_REQUIRED_SCOPES=openid                   # space-separated; minimum "openid" for Okta

令牌自检（选择加入——需要客户端凭据）

当两者都激活时 SCS_MCP_OAUTH_CLIENT_ID 和 SCS_MCP_OAUTH_CLIENT_SECRET 设置。服务器调用提供者的 RFC 7662 每个请求的自省端点。当提供程序发出不透明（非JWT）令牌或需要实时吊销检查时，请使用此选项。

SCS_MCP_OAUTH_ENABLED=true
SCS_MCP_OAUTH_ISSUER=https://your-keycloak.com/realms/myrealm
SCS_MCP_OAUTH_CLIENT_ID=my-resource-server
SCS_MCP_OAUTH_CLIENT_SECRET=super-secret
SCS_MCP_SERVER_URL=https://your-server.example.com

Docker（使用OAuth的HTTP模式）

docker run --rm -p 3000:3000 \
  -e ELASTICSEARCH_ENDPOINT=https://... \
  -e SCS_MCP_OAUTH_ENABLED=true \
  -e SCS_MCP_OAUTH_ISSUER=https://your-okta.okta.com/oauth2/default \
  -e SCS_MCP_SERVER_URL=https://your-server.example.com \
  -e SCS_MCP_OAUTH_REQUIRED_SCOPES=openid \
  simianhacker/semantic-code-search-mcp-server

所需范围

SCS_MCP_OAUTH_REQUIRED_SCOPES 控制服务器在每个令牌上通告和要求的范围。Okta的最小推荐值为 openid。将其设置为空字符串会导致Okta以“未配置作用域”错误拒绝授权请求。

注意：范围如 offline_access 和 email 与Okta和主要IDE合作，但不受任何标准的保证。如果您需要M2M（客户端凭据）访问，请避免使用它们。

没有OAuth的本地开发

当 SCS_MCP_SERVER_URL 如果未设置（或指向localhost），服务器将绑定到 127.0.0.1 只有。集 SCS_MCP_SERVER_URL 绑定到非本地主机URL以绑定到所有接口（Docker容器和反向代理部署所需）。

限制对特定OAuth客户端的访问

默认情况下，接受配置的授权服务器颁发的任何令牌。要限制对特定应用程序的访问，请执行以下操作：

SCS_MCP_OAUTH_ALLOWED_CLIENT_IDS=0oa1abc123def456gh78  # space-separated for multiple IDs

当多个OAuth应用程序共享同一个授权服务器（在Okta中很常见）时，建议这样做。没有它，租户中任何针对同一受众的应用程序的令牌都将被接受。服务器检查 client_id, azp，或 cid （Okta特定）JWT中的索赔，以存在者为准。

正在检查您的身份验证状态

启用OAuth后 auth_status 该工具在所有MCP客户端中都可用。让人工智能助手称之为：

“调用auth_status工具”

它返回您的客户端ID、授予的作用域和令牌到期时间——不敏感（令牌本身从不包括在内）。

令牌寿命

客户端在访问令牌过期时重新进行身份验证。为了减少身份验证提示，请延长授权服务器中的访问令牌寿命。对于Okta：管理员→ 安全→ API → 授权服务器→ 默认→ 访问策略。

配置

配置通过环境变量进行管理 .env 文件。