Search Streets

Instructions

Implementation Reference

• src/tools/search/searchStreets.ts:7-138 (handler)

  Main handler that registers the 'searchStreets' tool on the MCP server. Defines input schema (country_code, locality_id, search), validates params, calls the API client, and formats the response.

  export function registerSearchStreetsTool(server: McpServer): void {
    // Create API client instance
  
    // Register searchStreets tool
    server.registerTool(
      "searchStreets",
      {
        title: "Search Streets",
        description:
          "Search for streets in a specific locality. Parameters: country_code (required), locality_id (required), search (required)",
        inputSchema: {
          country_code: z
            .enum(["RO"])
            .describe("The country code - must be 'RO' (Romania)"),
          locality_id: z
            .number()
            .min(1)
            .describe("The locality ID to search within"),
          search: z
            .string()
            .min(2)
            .describe("The search term for street names (minimum 2 characters)"),
        },
      },
      async (args: any) => {
        // Get API key from async context
        const apiKey = apiKeyStorage.getStore();
  
        if (!apiKey) {
          return {
            content: [
              {
                type: "text",
                text: "Error: X-API-KEY header is required",
              },
            ],
          };
        }
  
        // Create API client with customer's API key
        const client = new EuroparcelApiClient(apiKey);
  
        try {
          // Validate required parameters
          if (!args.country_code) {
            return {
              content: [
                {
                  type: "text",
                  text: "Error: country_code parameter is required",
                },
              ],
            };
          }
  
          if (!args.locality_id || !Number.isInteger(Number(args.locality_id))) {
            return {
              content: [
                {
                  type: "text",
                  text: "Error: locality_id parameter is required and must be a number",
                },
              ],
            };
          }
  
          if (
            !args.search ||
            typeof args.search !== "string" ||
            args.search.length < 1
          ) {
            return {
              content: [
                {
                  type: "text",
                  text: "Error: search parameter is required",
                },
              ],
            };
          }
  
          logger.info("Searching streets", {
            country_code: args.country_code,
            locality_id: args.locality_id,
            search: args.search,
          });
  
          const streets = await client.searchStreets(
            args.country_code.toUpperCase(),
            Number(args.locality_id),
            args.search,
          );
  
          logger.info(`Found ${streets.length} streets`);
  
          let formattedResponse = `Found ${streets.length} streets matching "${args.search}" in locality #${args.locality_id}:\n\n`;
  
          if (streets.length === 0) {
            formattedResponse += "No streets found.";
          } else {
            streets.forEach((street) => {
              formattedResponse += `🛣️  ${street.street_name}\n`;
              formattedResponse += `   ID: ${street.id}\n`;
              formattedResponse += `   Postal Code: ${street.postal_code}\n\n`;
            });
          }
  
          return {
            content: [
              {
                type: "text",
                text: formattedResponse,
              },
            ],
          };
        } catch (error: any) {
          logger.error("Failed to search streets", error);
  
          return {
            content: [
              {
                type: "text",
                text: `Error searching streets: ${error.message || "Unknown error"}`,
              },
            ],
          };
        }
      },
    );
  
    logger.info("searchStreets tool registered successfully");
  }

• src/tools/search/searchStreets.ts:17-29 (schema)

  Input schema for searchStreets using Zod: country_code (enum RO), locality_id (number min 1), search (string min 2 chars).

  inputSchema: {
    country_code: z
      .enum(["RO"])
      .describe("The country code - must be 'RO' (Romania)"),
    locality_id: z
      .number()
      .min(1)
      .describe("The locality ID to search within"),
    search: z
      .string()
      .min(2)
      .describe("The search term for street names (minimum 2 characters)"),
  },

• src/tools/search/index.ts:10-12 (registration)

  Registration of searchStreets tool via registerSearchStreetsTool(server) in the search tools index.

  // Register all search-related tools
  registerSearchLocalitiesTool(server);
  registerSearchStreetsTool(server);

• src/api/client.ts:300-312 (helper)

  API client method searchStreets that makes a GET request to /search/streets/{countryCode}/{localityId}/{search} and returns StreetSearchResult[].

  /**
   * Search streets by country, locality and name
   */
  async searchStreets(
    countryCode: string,
    localityId: number,
    search: string,
  ): Promise<StreetSearchResult[]> {
    const response = await this.client.get<StreetSearchResult[]>(
      `/search/streets/${countryCode}/${localityId}/${search}`,
    );
    return response.data;
  }

• src/types/index.ts:224-228 (schema)

  Type definition StreetSearchResult with id, street_name, and postal_code fields.

  export interface StreetSearchResult {
    id: number;
    street_name: string;
    postal_code: string;
  }