search_onyx
Search the Onyx backend to find relevant documents by topic, retrieve matching chunks or full documents, and filter results by document sets.
Instructions
Search the Onyx backend for relevant documents
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The topic to search for | |
| 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) | |
| retrieveFullDocuments | No | Whether to retrieve full documents instead of just matching chunks (default: false) | |
| documentSets | No | List of document set names to search within (empty for all) | |
| maxResults | No | Maximum number of results to return (default: 5) |
Implementation Reference
- src/tools/searchTool.ts:15-74 (handler)Main handler function that validates input, performs semantic search via OnyxApiService, retrieves relevant content, builds formatted context, and returns MCP tool 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)MCP tool schema definition including input schema for validation with properties like query, documentSets, maxResults, etc.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)Registers the call_tool request handler that dispatches 'search_onyx' calls to the handleSearchOnyx function.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)Registers the list_tools request handler that exposes the search_onyx schema.this.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ toolSchemas.search_onyx, toolSchemas.chat_with_onyx, ], }; });
- src/services/onyxApi.ts:41-75 (helper)Core helper method in OnyxApiService that performs the actual API call to Onyx for semantic search.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)}`); } }