search_onyx

Instructions

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)}`);
    }
  }