elastic / elastic/semantic-code-search-mcp-server
Add reranker option to semantic_code_search tool
- Dominant language
- TypeScript
- Stars
- 12
- Forks
- 7
- PR merge metrics
- No merged PRs in 30d
Description
# Feature: Reranker Option for Semantic Search
## Overview
Add a `use_reranker` flag to `semantic_code_search` so callers can opt into Elastic's text-similarity reranker pipeline for higher quality ranking, surface `max_score` in responses, and make the reranker `inference_id` configurable via environment variable (defaulting to `.rerank-v1-elasticsearch`).
## Implementation Roadmap
### Task 1: Extend Configuration ✅
**File**: `src/config.ts`
**Changes**: Add `rerankerInferenceId` (env var e.g. `SEMANTIC_CODE_SEARCH_RERANKER_INFERENCE_ID`, default `.rerank-v1-elasticsearch`) into the exported config, update typings/usages.
**Why**: Centralize inference ID configuration with sane default.
**Dependencies**: None
### Task 2: Extend Schema and Params ✅
**File**: `src/mcp_server/tools/semantic_code_search.ts`
**Changes**: Add optional boolean `use_reranker` with defaults/documentation to `semanticCodeSearchSchema` and inferred params.
**Why**: Input contract needs to surface the flag.
**Dependencies**: Task 1
### Task 3: Build Reranker Query Flow ✅
**File**: `src/mcp_server/tools/semantic_code_search.ts`
**Changes**:
- Introduce branching that, when `use_reranker` is true, constructs the `retriever.text_similarity_reranker` body matching the sample structure, pulling `inference_id` from config.
- Ensure the semantic query populates both the inner `semantic` clause and `inference_text`; guard that reranker requires `query`.
- Merge any KQL filter by embedding it in the `bool.must` array within the standard retriever's query.
- Preserve existing non-reranker path.
**Why**: Enable Elastic reranking without breaking the current behavior.
**Dependencies**: Task 2
### Task 4: Include `max_score` in Results ✅
**File**: `src/mcp_server/tools/semantic_code_search.ts`
**Changes**: Capture `response.hits.max_score` and inject alongside the hit list (e.g., as a sibling field in the serialized payload).
**Why**: Provide score reference for consumers.
**Dependencies**: Task 3
### Task 5: Update Documentation ✅
**File**: `src/mcp_server/tools/semantic_code_search.md`
**Changes**: Document new `use_reranker` option, environment variable for inference ID, behavior constraints (requires `query`, scoring context).
**Why**: Keep tool guidance current.
**Dependencies**: Task 4
### Task 6: Expand Tests ✅
**File**: `tests/mcp_server/semantic_code_search.test.ts`
**Changes**:
- Add test verifying reranker request body (mock client) when flag set, including inference values from config and KQL handling.
- Assert `max_score` presence in responses.
- Add coverage for configurable inference ID (e.g., override env in test).
**Why**: Guarantee new logic functions and remains stable.
**Dependencies**: Task 3
## Technical Details
- Introduce helper to build base `bool` query so both retriever and traditional paths share KQL + semantic clauses.
- Reranker payload mirrors:
```typescript
const retriever = {
text_similarity_reranker: {
retriever: { standard: { query: baseBoolQuery } },
field: 'semantic_text',
inference_id: elasticsearchConfig.rerankerInferenceId,
inference_text: query,
rank_window_size: 100,
min_score: 0.5,
},
};
```
- When `kql` is present, include the translated DSL in `baseBoolQuery.bool.must`.
- For responses, return JSON like `{ hits, max_score: response.hits.max_score }` (or similar structure) to keep compatibility while exposing the new metric.
- Ensure documentation and tests note the new environment variable and default value.
## Example Reranker Query
```json
POST kibana-repo/_search
{
"size": 20,
"retriever": {
"text_similarity_reranker": {
"retriever": {
"standard": {
"query": {
"bool": {
"must": [
{
"semantic": {
"query": "Agent Builder one chat plugin",
"field": "semantic_text"
}
}
],
"should": [
{
"term": {
"language": {
"value": "markdown",
"boost": 2
}
}
}
]
}
}
}
},
"field": "semantic_text",
"inference_id": ".rerank-v1-elasticsearch",
"inference_text": "Agent Builder one chat plugin",
"rank_window_size": 100,
"min_score": 0.5
}
}
}
```
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.