list_locations

Instructions

Implementation Reference

• src/tools/inventory.ts:111-135 (handler)

  The async handler function for the 'list_locations' tool. Executes the LIST_LOCATIONS_QUERY GraphQL query, maps over the returned location edges, formats each location's name, active status, city, country, and GID, and returns the result as text content.

    async (args) => {
      const data = await client.graphql<{
        locations: {
          edges: Array<{
            node: {
              id: string;
              name: string;
              isActive: boolean;
              address?: { city?: string | null; countryCode?: string | null };
            };
          }>;
        };
      }>(LIST_LOCATIONS_QUERY, { first: args.first });
      const lines = [
        `Found ${data.locations.edges.length} location(s):`,
        ...data.locations.edges.map(({ node }) => {
          const city = node.address?.city ?? "?";
          const country = node.address?.countryCode ?? "?";
          const active = node.isActive ? "active" : "inactive";
          return `  ${node.name} (${active}) — ${city}, ${country} — ${node.id}`;
        }),
      ];
      return { content: [{ type: "text" as const, text: lines.join("\n") }] };
    },
  );

• src/tools/inventory.ts:53-61 (schema)

  Zod schema for the 'list_locations' tool input. Defines a single 'first' parameter (number, 1-100, default 20) for page size.

  const listLocationsSchema = {
    first: z
      .number()
      .int()
      .min(1)
      .max(100)
      .default(20)
      .describe("Page size (1-100). Most stores have under a dozen locations."),
  };

• src/tools/inventory.ts:107-135 (registration)

  Registration of the 'list_locations' tool on the MCP server via server.tool(), with its name, description, schema, and handler.

  server.tool(
    "list_locations",
    "List the store's locations — physical or virtual places where inventory is stocked or fulfilled from (warehouses, retail stores, drop-ship partners). Returns each location's name, active/inactive flag, city + country, and GID. The location GID is required by set_inventory_quantity and create_fulfillment. Inactive locations still exist but cannot accept new inventory or fulfillments.",
    listLocationsSchema,
    async (args) => {
      const data = await client.graphql<{
        locations: {
          edges: Array<{
            node: {
              id: string;
              name: string;
              isActive: boolean;
              address?: { city?: string | null; countryCode?: string | null };
            };
          }>;
        };
      }>(LIST_LOCATIONS_QUERY, { first: args.first });
      const lines = [
        `Found ${data.locations.edges.length} location(s):`,
        ...data.locations.edges.map(({ node }) => {
          const city = node.address?.city ?? "?";
          const country = node.address?.countryCode ?? "?";
          const active = node.isActive ? "active" : "inactive";
          return `  ${node.name} (${active}) — ${city}, ${country} — ${node.id}`;
        }),
      ];
      return { content: [{ type: "text" as const, text: lines.join("\n") }] };
    },
  );

• src/tools/inventory.ts:17-25 (helper)

  The LIST_LOCATIONS_QUERY GraphQL query used by the handler to fetch locations (id, name, isActive, address city/countryCode).

  const LIST_LOCATIONS_QUERY = /* GraphQL */ `
    query ListLocations($first: Int!) {
      locations(first: $first) {
        edges {
          node { id name isActive address { city countryCode } }
        }
      }
    }
  `;