search_onyx
Search the Onyx backend to retrieve relevant document chunks or full documents based on a query. Customize results by specifying document sets, surrounding chunks, and max results for precise information retrieval.
Instructions
Search the Onyx backend for relevant documents
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| chunksAbove | No | Number of chunks to include above the matching chunk (default: 1) | |
| chunksBelow | No | Number of chunks to include below the matching chunk (default: 1) | |
| documentSets | No | List of document set names to search within (empty for all) | |
| maxResults | No | Maximum number of results to return (default: 5) | |
| query | Yes | The topic to search for | |
| retrieveFullDocuments | No | Whether to retrieve full documents instead of just matching chunks (default: false) |
Input Schema (JSON Schema)
{
"properties": {
"chunksAbove": {
"default": 1,
"description": "Number of chunks to include above the matching chunk (default: 1)",
"type": "integer"
},
"chunksBelow": {
"default": 1,
"description": "Number of chunks to include below the matching chunk (default: 1)",
"type": "integer"
},
"documentSets": {
"description": "List of document set names to search within (empty for all)",
"items": {
"type": "string"
},
"type": "array"
},
"maxResults": {
"description": "Maximum number of results to return (default: 5)",
"maximum": 10,
"minimum": 1,
"type": "integer"
},
"query": {
"description": "The topic to search for",
"type": "string"
},
"retrieveFullDocuments": {
"default": false,
"description": "Whether to retrieve full documents instead of just matching chunks (default: false)",
"type": "boolean"
}
},
"required": [
"query"
],
"type": "object"
}
Implementation Reference
- src/tools/searchTool.ts:15-74 (handler)Main handler function that executes the search_onyx tool logic: validates input, performs semantic search via OnyxApiService, sorts and limits results, fetches content/chunks, builds context, and returns MCP-formatted response.export async function handleSearchOnyx(args: unknown, onyxApiService: OnyxApiService) { try { if (typeof args !== 'object' || args === null) { throw new McpError(ErrorCode.InvalidParams, 'Invalid arguments'); } const { query, documentSets = [], maxResults = 5, chunksAbove = 1, chunksBelow = 1, retrieveFullDocuments = false } = args as SearchParams; if (!query || typeof query !== 'string') { throw new McpError(ErrorCode.InvalidParams, 'Query is required'); } // Step 1: Perform semantic search to find relevant documents const searchResults = await onyxApiService.searchOnyx(query, documentSets, chunksAbove, chunksBelow); // Step 2: Get the most relevant results const relevantResults = searchResults .sort((a, b) => b.score - a.score) .slice(0, maxResults); // Step 3: For each relevant document, fetch either the specific chunk or full document content const relevantContent = await Promise.all( relevantResults.map(result => retrieveFullDocuments ? onyxApiService.fetchDocumentContent(result.document_id) : onyxApiService.fetchDocumentChunk(result.document_id, result.chunk_ind) ) ); // Step 4: Combine into comprehensive context const context = onyxApiService.buildContext(relevantResults, relevantContent); return { content: [ { type: 'text', text: context, }, ], }; } catch (error) { console.error('Error in handleSearchOnyx:', error); return { content: [ { type: 'text', text: `Error searching Onyx: ${error instanceof Error ? error.message : String(error)}`, }, ], isError: true, }; } }
- src/types/index.ts:89-130 (schema)Input schema and metadata definition for the search_onyx tool, used for validation and tool listing.search_onyx: { name: 'search_onyx', description: 'Search the Onyx backend for relevant documents', inputSchema: { type: 'object', properties: { query: { type: 'string', description: 'The topic to search for', }, chunksAbove: { type: 'integer', description: 'Number of chunks to include above the matching chunk (default: 1)', default: 1 }, chunksBelow: { type: 'integer', description: 'Number of chunks to include below the matching chunk (default: 1)', default: 1 }, retrieveFullDocuments: { type: 'boolean', description: 'Whether to retrieve full documents instead of just matching chunks (default: false)', default: false }, documentSets: { type: 'array', items: { type: 'string', }, description: 'List of document set names to search within (empty for all)', }, maxResults: { type: 'integer', description: 'Maximum number of results to return (default: 5)', minimum: 1, maximum: 10, }, }, required: ['query'], }, },
- src/server.ts:62-75 (registration)Registration of the search_onyx tool handler in the MCP server's CallToolRequestSchema handler (switch case dispatching to handleSearchOnyx).this.server.setRequestHandler(CallToolRequestSchema, async (request) => { switch (request.params.name) { case 'search_onyx': return handleSearchOnyx(request.params.arguments, this.onyxApiService); case 'chat_with_onyx': return handleChatWithOnyx(request.params.arguments, this.onyxApiService); default: throw new McpError( ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}` ); } }); }
- src/server.ts:87-94 (registration)Registration of the search_onyx tool schema in the MCP server's ListToolsRequestSchema response.this.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ toolSchemas.search_onyx, toolSchemas.chat_with_onyx, ], }; });
- src/services/onyxApi.ts:41-75 (helper)Core searchOnyx method in OnyxApiService that performs the actual API call to Onyx backend for semantic search, called by the tool handler.async searchOnyx( query: string, documentSets: string[] = [], chunksAbove = 0, chunksBelow = 0 ): Promise<OnyxSearchResult[]> { try { const response = await axios.post( `${this.config.apiUrl}/admin/search`, { query, filters: { document_set: documentSets.length > 0 ? documentSets : null, source_type: null, time_cutoff: null, tags: null }, chunks_above: chunksAbove, chunks_below: chunksBelow, evaluation_type: 'basic' // Enable LLM relevance filtering }, { headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${this.config.apiToken}` } } ); return response.data.documents || []; } catch (error) { console.error('Error searching Onyx:', error); throw new Error(`Failed to search Onyx: ${error instanceof Error ? error.message : String(error)}`); } }