elastic / elastic/semantic-code-search-mcp-server
Enhancement: Return pagination metadata in semantic_code_search response
- Dominant language
- TypeScript
- Stars
- 12
- Forks
- 7
- PR merge metrics
- No merged PRs in 30d
Description
## Summary
Add `totalHits` to the `semantic_code_search` response to help agents make informed decisions about whether to paginate further or switch to other tools like `map_symbols_by_query`.
## Current Behavior
The tool accepts `page` and `size` parameters but returns only the hits array:
```typescript
// src/mcp_server/tools/semantic_code_search.ts:84-101
return {
content: [
{
type: 'text',
text: JSON.stringify(
response.hits.hits.map((hit) => {
const { type, language, kind, filePath, content } = hit._source;
return { score: hit._score, type, language, kind, filePath, content };
})
),
},
],
};
```
Response shape:
```json
[
{ "score": 0.92, "type": "code", "filePath": "...", "content": "..." },
{ "score": 0.87, "type": "code", "filePath": "...", "content": "..." }
]
```
## Proposed Behavior
Include pagination metadata from the already-available `response.hits.total`:
```json
{
"hits": [
{ "score": 0.92, "type": "code", "filePath": "...", "content": "..." },
{ "score": 0.87, "type": "code", "filePath": "...", "content": "..." }
],
"total": 142
}
```
## Why This Helps Agents
```
┌────────────────────────────────────────────────────────────────────┐
│ Agent receives: { hits: [...25 items], total: 142 } │
├────────────────────────────────────────────────────────────────────┤
│ │
│ Agent can now reason: │
│ │
│ • "142 total results, I have 25 - there's more if I need it" │
│ • "142 is a lot - maybe map_symbols_by_query is better for │
│ exhaustive coverage" │
│ • "Only 8 total results - no need to paginate" │
│ │
└────────────────────────────────────────────────────────────────────┘
```
## Implementation
Minimal change in `src/mcp_server/tools/semantic_code_search.ts`:
```typescript
// Extract total from ES response (already available)
const total = typeof response.hits.total === 'number'
? response.hits.total
: response.hits.total?.value ?? 0;
return {
content: [
{
type: 'text',
text: JSON.stringify({
hits: response.hits.hits.map((hit) => {
const { type, language, kind, filePath, content } = hit._source;
return { score: hit._score, type, language, kind, filePath, content };
}),
total,
}),
},
],
};
```
## Acceptance Criteria
- [ ] Response includes `total` field with the total number of matching documents
- [ ] Existing `hits` array structure unchanged (backward compatible for agents parsing the array)
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.