Skip to main content

​
Overview

The search tool enables you to search through documentation content using text queries. It supports boolean operators (AND, OR) for advanced search capabilities and returns up to 10 most relevant results ranked by relevance score. The search tool uses two search strategies:
  1. Semantic search (when available): Uses Oxygen Feedback service for intelligent, context-aware search
  2. Index-based search (fallback): Traditional keyword-based search using pre-built documentation indexes

​
Parameters

​
query
string
required
Search query string. Supports boolean operators for advanced searching:
  • AND - Require all terms (e.g., “XML AND schema”)
  • OR - Match any term (e.g., “WSDL OR WADL”)
  • Combine operators for complex queries (e.g., “XML AND (schema OR DTD)“)

​
Response Format

The tool returns a JSON array of search results, with each result containing:
​
id
string
required
Unique document identifier in the format index:relativePath. This ID is required for the fetch tool to retrieve full document content.Examples:
  • 0:topics/wsdl-converter.html
  • 1:reference/api-guide.html
​
title
string
required
Document title extracted from the documentation page.
​
url
string
required
Complete URL to the documentation page. Can be used for direct browser access or reference links.

​
Success Response

[
  {
    "title": "WSDL Converter",
    "id": "0:topics/wsdl-converter.html",
    "url": "https://www.oxygenxml.com/doc/versions/27.1/ug-editor/topics/wsdl-converter.html"
  },
  {
    "title": "Working with WSDL Files",
    "id": "0:topics/working-with-wsdl.html",
    "url": "https://www.oxygenxml.com/doc/versions/27.1/ug-editor/topics/working-with-wsdl.html"
  }
]

​
Error Response

When an error occurs, the tool returns an error message: 
"Search error: Failed to load index: Connection timeout"
Common error scenarios:
  • Index loading failure: The documentation index cannot be accessed or downloaded
  • Search parsing error: Invalid query syntax or search operation failure
  • Network errors: Connection issues or timeout when accessing remote resources

​
Usage Examples

import { Client } from '@modelcontextprotocol/sdk/client';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp';

const transport = new StreamableHTTPClientTransport(
  'http://localhost:3000/www.oxygenxml.com/doc/versions/27.1/ug-editor'
);
const client = new Client({ name: 'my-app', version: '1.0.0' });
await client.connect(transport);

// Simple search
const response = await client.callTool({ 
  name: 'search', 
  arguments: { query: 'wsdl' } 
});

const results = JSON.parse(response.content[0].text);
console.log(`Found ${results.length} results`);
console.log(`First result: ${results[0].title}`);

​
Real-World Example

Here’s a complete example from the test suite showing how to search and then fetch document content: 
import { Client } from '@modelcontextprotocol/sdk/client';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp';

const WEBHELP_ENDPOINT = 'www.oxygenxml.com/doc/versions/27.1/ug-editor';

const transport = new StreamableHTTPClientTransport(
  `http://localhost:3000/${WEBHELP_ENDPOINT}`
);
const client = new Client({ name: 'e2e-test-client', version: '1.0.0' });
await client.connect(transport);

// Search for WSDL-related documentation
const searchResp = await client.callTool({ 
  name: 'search', 
  arguments: { query: 'wsdl' } 
});

const searchResults = JSON.parse(searchResp.content[0].text);
console.log(`Found ${searchResults.length} results`);

// Get the first result
const first = searchResults[0];
console.log(`Top result: ${first.title}`);
console.log(`Document ID: ${first.id}`);

// Fetch full content of the top result
const fetchResp = await client.callTool({ 
  name: 'fetch', 
  arguments: { id: first.id } 
});

const doc = JSON.parse(fetchResp.content[0].text);
console.log(`Retrieved document: ${doc.title}`);
console.log(`Content length: ${doc.text.length} characters`);

await client.close();

​
Implementation Details

The search tool is implemented in app/[...site]/route.ts:37-84:
The tool returns a maximum of 10 results to balance comprehensiveness with performance. Results are ranked by relevance score, with the most relevant documents appearing first.

​
Search Strategies

  1. Semantic Search (Single site only):
    • Attempts to use Oxygen Feedback’s AI-powered search
    • Provides context-aware, intelligent results
    • Automatically falls back to index search if unavailable
  2. Index-Based Search (All sites):
    • Uses pre-built search indexes from WebHelp output
    • Supports boolean operators (AND, OR)
    • Works for both single and federated multi-site search
When searching across multiple documentation sites, results are merged and sorted by relevance score: 
const encoded = encodeUrls([
  'https://www.oxygenxml.com/doc/versions/27.1/ug-editor/',
  'https://www.oxygenxml.com/doc/versions/27.1/ug-author/'
]);

const transport = new StreamableHTTPClientTransport(
  `http://localhost:3000/federated/${encoded}`
);

const searchResp = await client.callTool({ 
  name: 'search', 
  arguments: { query: 'XML' } 
});

const results = JSON.parse(searchResp.content[0].text);
// Results include documents from both sites, sorted by relevance
Use the search tool to discover relevant documentation pages, then use the fetch tool with the document ID to retrieve the full content for detailed analysis and citation.
  • fetch - Retrieve complete document content by ID

Build docs developers (and LLMs) love

Get started for freeTalk to us