elastic / elastic/semantic-code-search-mcp-server

Enhancement: Return pagination metadata in semantic_code_search response

Open
#31 0 comments 0 reactions 0 assignees View on GitHub
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.