semantic-code-search

The Semantic Code Search MCP Server exposes a set of tools that let an AI coding agent interact with an indexed codebase in a structured way. It leverages the Elastic-backed semantic code search indexer output, including a content-deduplicated index of code chunks and a separate locations index that maps each chunk to its file path and line ranges. The available tools include semantic_code_search for performing semantic queries over code chunks, map_symbols_by_query to retrieve symbol maps grouped by file, symbol_analysis to generate symbol usage reports, read_file_from_chunks to reconstruct file content from indexed chunks, and document_symbols to identify key documentation opportunities in a file. You can run the server in STDIO mode for local development or in HTTP mode inside a container to expose an API endpoint for agents to query over HTTP. All tools support an optional index override, so you can point queries at a different Elasticsearch index if needed. Connect agents like Gemini either over HTTP or STDIO by configuring their MCP server settings to point at http://localhost:3000/mcp/ or by supplying a docker-based STDIO command that runs the server inside the container.

Prerequisites:

• Docker installed and available in PATH (for the Docker-based setup shown here).
• Access to an Elasticsearch v8+ instance with the semantic-code-search index deployed (ELSER model requirements noted in the project).

Installation steps:

1. Pull and run the Docker image (recommended):

# Pull the latest image
docker pull simianhacker/semantic-code-search-mcp-server

# Run in STDIO mode with your Elasticsearch endpoint and index
docker run --rm -i \
  -e ELASTICSEARCH_ENDPOINT=<your_elasticsearch_endpoint> \
  -e ELASTICSEARCH_INDEX=<your_index> \
  simianhacker/semantic-code-search-mcp-server \
  node dist/src/mcp_server/bin.js stdio

2. Alternative: Run in HTTP mode (exposes HTTP API at port 3000 by default):

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

3. Environment configuration (optional but recommended):

• Copy .env.example to .env and populate credentials if you are using a local Elasticsearch instance that requires authentication.

cp .env.example .env

4. Build from source (if you prefer to run directly from the repository):

# Prerequisites: Node.js v20+ and npm
git clone <repository-url>
cd semantic-code-search-mcp-server
npm install
npm run build

# Run in STDIO mode from the built distribution
ELASTICSEARCH_ENDPOINT=http://localhost:9200 npm run mcp-server

Note: When using NPX or running directly from the repository, ensure your environment variables (ELASTICSEARCH_ENDPOINT, ELASTICSEARCH_INDEX) are properly set for your deployment.

Tips and common issues:

• Ensure your Elasticsearch index name matches the one configured in ELASTICSEARCH_INDEX. The default is semantic-code-search.
• If you see authentication errors, verify that ELASTICSEARCH_ENDPOINT includes basic auth or token or use an accessible Elasticsearch instance.
• The Docker STDIO mode requires interactive mode (-i) to allow input/output with the MCP server.
• The index model used by this MCP server relies on a two-index setup: <index> for chunk content and <index>_locations for per-chunk location data; the tools in the MCP server join on chunk_id where needed.
• You can override the index on a per-query basis by supplying an index parameter to the tools.
• When running HTTP mode behind a reverse proxy, be mindful of CORS and authentication requirements for your environment.