searchProcedures
Search for administrative procedures using specific keywords on the eRegulations MCP Server. Simplify access to structured data for AI models and user queries.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | Yes | The keyword or phrase to search for procedures. This will be wrapped in a JSON object with a 'keyword' property when sent to the API. |
Implementation Reference
- Creates and returns the MCP tool handler for 'searchProcedures', including input schema, description, and the async handler function that performs the search using ERegulationsApi, filters results to procedures, formats output using SearchProceduresFormatter, and returns structured text content.export function createSearchProceduresHandler( api: ERegulationsApi ): ToolHandler { return { name: ToolName.SEARCH_PROCEDURES, description: `Search for procedures by keyword or phrase. The search uses OR logic between words in the keyword phrase. For best results, prefer using a single, specific keyword whenever possible.`, inputSchema: zodToJsonSchema(SearchProceduresSchema), inputSchemaDefinition: SearchProceduresSchema, handler: async (args) => { // Use the inferred type for args const { keyword } = args as SearchProceduresArgs; logger.log(`Handling searchProcedures with keyword: ${keyword}`); try { const results = await api.searchProcedures(keyword); // Filter results to only include actual procedures based on links const filteredProcedures = results.filter( (item) => item.links && Array.isArray(item.links) && item.links.some((link) => link && link.rel === "procedure") ); logger.log( `searchProcedures API returned ${results.length} items, filtered to ${filteredProcedures.length} procedures` ); // Format the filtered results using the search procedures formatter const formattedResult = formatters.searchProcedures.format( filteredProcedures, // Pass filtered procedures keyword // Pass keyword for context ); logger.log( `searchProcedures found ${filteredProcedures.length} results` ); // Always return only text content return { content: [ { type: "text", text: formattedResult.text, }, ], }; } catch (error) { logger.error( `Error searching procedures with keyword "${keyword}":`, error ); const errorMessage = error instanceof Error ? error.message : String(error); return { content: [ { type: "text", text: `Error searching for procedures: ${errorMessage}`, }, ], }; } }, }; }
- Zod input schema for the searchProcedures tool, defining the required 'keyword' string parameter with description.export const SearchProceduresSchema = z.object({ keyword: z .string() .describe( "The keyword or phrase to search for procedures. This will be wrapped in a JSON object with a 'keyword' property when sent to the API." ), });
- src/mcp-capabilities/tools/handlers/index.ts:13-20 (registration)Registers the searchProcedures handler by including createSearchProceduresHandler(api) in the array returned by createHandlers, which initializes all MCP tool handlers.export function createHandlers(api: ERegulationsApi): ToolHandler[] { return [ createListProceduresHandler(api), createGetProcedureDetailsHandler(api), createGetProcedureStepHandler(api), createSearchProceduresHandler(api), ]; }
- Core API method in ERegulationsApi class that performs the HTTP POST request to /Objectives/Search endpoint with the keyword, handles response, and returns array of matching objectives/procedures.async searchProcedures( keyword: string ): Promise<ObjectiveWithDescriptionBaseModel[]> { if (!keyword || typeof keyword !== "string") { throw new Error("Search keyword is required"); } return this.fetchData<ObjectiveWithDescriptionBaseModel[]>(async () => { logger.log(`Searching objectives with keyword "${keyword}"...`); // Get the base URL at execution time const baseUrl = this.getBaseUrl(); try { // Use POST for the search endpoint as specified in the API docs const url = `${baseUrl}/Objectives/Search`; // Create a specific axios instance for this POST request // Wrap keyword in an object as per the new API format const requestBody = { keyword }; const response = await this.axiosInstance.post< ObjectiveWithDescriptionBaseModel[] >(url, JSON.stringify(requestBody), { headers: { "Content-Type": "application/json", Accept: "application/json", }, timeout: REQUEST_CONFIG.TIMEOUT, }); if (!response || !response.data) { logger.warn(`No objectives found for search keyword "${keyword}"`); return []; } // API should return ObjectiveWithDescriptionBaseModel[] directly if (Array.isArray(response.data)) { logger.log( `Found ${response.data.length} objective search results for "${keyword}"` ); // No need to map or add searchKeyword, return data directly return response.data; } else { // Log unexpected responses, but still try to return an empty array logger.warn( `Unexpected search API response type for objectives: ${typeof response.data}. Expected Array.` ); return []; } } catch (error) { logger.error( `Error searching objectives with keyword "${keyword}":`, error ); // Don't expose internal errors directly, return empty array return []; } }); }
- Formatter class used in the searchProcedures handler to convert raw API search results into LLM-friendly formatted text and essential data summary.export class SearchProceduresFormatter implements DataFormatter<ObjectiveData[], FormattedProcedureList> { // Renamed class /** * Format procedure search results for LLM consumption. * @param results The search result data to format (ObjectiveWithDescriptionBaseModel[]). * @param keyword The search keyword used. * @returns Formatted procedure search results text and essential data. */ public format( results: ObjectiveData[], keyword?: string ): FormattedProcedureList { // Renamed variable if (!results || !Array.isArray(results) || results.length === 0) { return { text: `No procedures found matching "${keyword || "search term"}"`, data: [], }; } const formattedText = this.formatText(results, keyword); // Pass new params const essentialData = this.extractEssentialData(results); // Pass results return { text: formattedText, data: essentialData, }; } /** * Extract essential data from search results (objectives) for procedure list. * @param results The full search results (objectives). * @returns A simplified array with essential fields (id, name, description). */ private extractEssentialData(results: ObjectiveData[]): any[] { return results.map((res) => ({ id: res.id, name: res.name, ...(res.description ? { description: res.description } : {}), })); } /** * Format search results (objectives) as human-readable text representing procedures. * @param results The search data to format (objectives). * @param keyword The search keyword used. * @returns Formatted text optimized for LLM context. */ private formatText(results: ObjectiveData[], keyword?: string): string { const searchTerm = keyword ? ` for "${keyword}"` : ""; const resultCount = results.length; let header = `Found ${resultCount} procedure${ resultCount !== 1 ? "s" : "" }${searchTerm}:\n\n`; // Use "procedure" in text const shownResults = results; // Always show all results now if (shownResults.length > 0) { shownResults.forEach((res, index) => { const id = res.id || "N/A"; const name = res.name || "Unknown"; let description = ""; if (res.description) { description = `\n ${res.description}`; } header += `${index + 1}. ${name} (ID:${id})${description}\n`; }); header += `\n\nTo get details about a specific procedure, use the getProcedureDetails tool with the procedure ID.`; // Keep instruction } else { header += "No procedures found."; } return header; } }