search-page

Instructions

Implementation Reference

• src/tools/search-page.ts:1-78 (handler)

  The main handler for the 'search-page' tool. Defines the inputSchema (query string + optional limit 1-100), exports the Tool object with name 'search-page', and implements the handle() function that calls the MediaWiki API search (action=query, list=search) with the provided terms. Returns results with title, pageId, snippet, size, wordCount, timestamp, and url. Handles truncation when more results are available via response.continue.

  import { z } from 'zod';
  import type { CallToolResult, ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
  import type { ApiSearchResult } from 'mwn';
  import type { Tool } from '../runtime/tool.js';
  import type { ToolContext } from '../runtime/context.js';
  import { getPageUrl } from '../wikis/utils.js';
  import type { TruncationInfo } from '../results/truncation.js';
  
  const inputSchema = {
  	query: z.string().describe('Search terms'),
  	limit: z
  		.number()
  		.int()
  		.min(1)
  		.max(100)
  		.optional()
  		.describe('Maximum number of search results to return'),
  } as const;
  
  export const searchPage: Tool<typeof inputSchema> = {
  	name: 'search-page',
  	description:
  		'Searches wiki page titles and page content (full-text) for the provided terms. Returns matching pages with a snippet, size, and timestamp. Accepts up to 100 matches per call (default 10); additional matches beyond the cap are flagged in the response — narrow the query to surface more. For title-prefix lookup (e.g. autocomplete), use search-page-by-prefix.',
  	inputSchema,
  	annotations: {
  		title: 'Search page',
  		readOnlyHint: true,
  		destructiveHint: false,
  		idempotentHint: true,
  		openWorldHint: true,
  	} as ToolAnnotations,
  	failureVerb: 'retrieve search data',
  	target: (a) => a.query,
  
  	async handle({ query, limit }, ctx: ToolContext): Promise<CallToolResult> {
  		const mwn = await ctx.mwn();
  
  		const params: Record<string, string | number | boolean> = {
  			action: 'query',
  			list: 'search',
  			srsearch: query,
  			srwhat: 'text',
  			srprop: 'snippet|size|timestamp|wordcount',
  			formatversion: '2',
  		};
  
  		if (limit !== undefined) {
  			params.srlimit = limit;
  		}
  
  		const response = await mwn.request(params);
  		const searchResults: ApiSearchResult[] = response.query?.search ?? [];
  
  		const truncation: TruncationInfo | null = response.continue
  			? {
  					reason: 'capped-no-continuation',
  					returnedCount: searchResults.length,
  					limit: limit ?? 10,
  					itemNoun: 'matches',
  					narrowHint: 'narrow the query or raise limit (max 100)',
  				}
  			: null;
  
  		return ctx.format.ok({
  			results: searchResults.map((r) => ({
  				title: r.title,
  				pageId: r.pageid,
  				snippet: r.snippet,
  				size: r.size,
  				wordCount: (r as ApiSearchResult & { wordcount?: number }).wordcount,
  				timestamp: r.timestamp,
  				url: getPageUrl(r.title, ctx.selection),
  			})),
  			...(truncation !== null ? { truncation } : {}),
  		});
  	},
  };

• src/tools/search-page.ts:9-18 (schema)

  Input schema using Zod: requires a 'query' string, optional 'limit' integer between 1-100.

  const inputSchema = {
  	query: z.string().describe('Search terms'),
  	limit: z
  		.number()
  		.int()
  		.min(1)
  		.max(100)
  		.optional()
  		.describe('Maximum number of search results to return'),
  } as const;

• src/tools/index.ts:15-15 (registration)

  Import of the searchPage tool from the search-page module.

  import { searchPage } from './search-page.js';

• src/tools/index.ts:42-64 (registration)

  The searchPage tool is included in the standardTools array (line 47) and registered with the MCP server via register() in registerAllTools() (line 83), which calls server.registerTool() with the tool's name, description, inputSchema, and annotations.

  const standardTools: Tool<any>[] = [
  	getPage,
  	getPages,
  	getPageHistory,
  	getRecentChanges,
  	searchPage,
  	searchPageByPrefix,
  	parseWikitext,
  	comparePages,
  	getFile,
  	getRevision,
  	getCategoryMembers,
  	createPage,
  	updatePage,
  	deletePage,
  	undeletePage,
  	uploadFile,
  	uploadFileFromUrl,
  	updateFile,
  	updateFileFromUrl,
  	oauthStatus,
  	oauthLogout,
  ];

• src/wikis/utils.ts:3-10 (helper)

  The getPageUrl helper function used by search-page to construct full URLs from page titles and the current wiki selection configuration.

  export function getPageUrl(title: string, wikiSelection: WikiSelection): string {
  	const { server, articlepath } = wikiSelection.getCurrent().config;
  	// MediaWiki convention: spaces become underscores. encodeURI preserves
  	// '/' (subpages) and ':' (namespace prefixes) while encoding spaces and
  	// non-ASCII characters. Characters disallowed in MW titles ('#', '?',
  	// '|', '[', ']', etc.) cannot reach this function via a real page title.
  	return `${server}${articlepath}/${encodeURI(title.replace(/ /g, '_'))}`;
  }