Local Falcon MCP Server

Instructions

Implementation Reference

• server.ts:89-103 (registration)

  MCP server.tool registration for the 'listAllLocalFalconLocations' tool, including description, Zod input schema, and the handler function that delegates to fetchAllLocalFalconLocations.

  server.tool(
    "listAllLocalFalconLocations",
    "Lists all business locations already configured in the Local Falcon account. Check here BEFORE using getLocalFalconGoogleBusinessLocations - if the business is already in the account, you'll get the Place ID instantly without needing to search Google. Saves time and ensures consistency with previous scans.",
    {
      query: z.string().nullish().describe("Search query. Matches against location name, address, Place ID, or store code.")
    },
    async ({ query }, ctx) => {
      const apiKey = getApiKey(ctx);
      if (!apiKey) {
        return { content: [{ type: "text", text: "Missing LOCAL_FALCON_API_KEY in environment variables or request headers" }] };
      }
      const resp = await fetchAllLocalFalconLocations(apiKey, handleNullOrUndefined(query));
      return { content: [{ type: "text", text: JSON.stringify(resp, null, 2) }] };
    }
  );

• localfalcon.ts:430-457 (helper)

  The core helper function implementing the API call to fetch all configured business locations from Local Falcon's /locations endpoint, supporting optional query parameter for filtering.

  /**
   * Fetches all locations from the Local Falcon API.
   * @param {string} apiKey - Your Local Falcon API key
   * @param {string} query - Optional search query
   * @returns {Promise<any>} API response
   */
  export async function fetchAllLocalFalconLocations(apiKey: string, query?: string) {
    const url = new URL(`${API_BASE}/locations`);
    url.searchParams.set("api_key", apiKey);
  
    if (query) url.searchParams.set("query", query);
  
    await rateLimiter.waitForAvailableSlot();
  
    return withRetry(async () => {
      const res = await fetchWithTimeout(url.toString(), {
        method: "POST",
        headers: HEADERS,
      });
  
      if (!res.ok) {
        const errorText = await res.text();
        throw new Error(`Local Falcon API error: ${res.status} ${res.statusText} - ${errorText}`);
      }
  
      return await safeParseJson(res);
    });
  }