searchProcedures

Implementation Reference

• src/mcp-capabilities/tools/handlers/search-procedures.ts:17-82 (handler)

  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}`,
              },
            ],
          };
        }
      },
    };
  }

• src/mcp-capabilities/tools/schemas.ts:27-33 (schema)

  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),
    ];
  }

• src/services/eregulations-api.ts:711-769 (helper)

  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 [];
      }
    });
  }

• src/mcp-capabilities/tools/formatters/search-procedures-formatter.ts:11-91 (helper)

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