search_genres

Instructions

Implementation Reference

• src/index.ts:194-227 (registration)

  Registration of the 'search_genres' tool on the MCP server via server.tool(), which both registers the tool and defines its handler inline.

  server.tool(
    "search_genres",
    "Browse Rakuten Ichiba product categories/genres",
    {
      genreId: z
        .string()
        .default("0")
        .describe("Parent genre ID (0 for top-level)"),
    },
    async ({ genreId }) => {
      const data = (await rakutenRequest(ENDPOINTS.ichibaGenreSearch, {
        genreId,
      })) as {
        current?: Record<string, unknown>;
        children?: Array<{ child: Record<string, unknown> }>;
      };
  
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                current: data.current,
                children: data.children?.map((c) => c.child),
              },
              null,
              2
            ),
          },
        ],
      };
    }
  );

• src/index.ts:197-202 (schema)

  Zod schema for the 'search_genres' tool input: genreId (string, default '0') describing the parent genre ID.

  {
    genreId: z
      .string()
      .default("0")
      .describe("Parent genre ID (0 for top-level)"),
  },

• src/index.ts:203-226 (handler)

  The async handler function that calls the Rakuten Ichiba Genre Search API with the genreId, then returns the current genre and its children as JSON.

  async ({ genreId }) => {
    const data = (await rakutenRequest(ENDPOINTS.ichibaGenreSearch, {
      genreId,
    })) as {
      current?: Record<string, unknown>;
      children?: Array<{ child: Record<string, unknown> }>;
    };
  
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify(
            {
              current: data.current,
              children: data.children?.map((c) => c.child),
            },
            null,
            2
          ),
        },
      ],
    };
  }

• src/index.ts:15-15 (helper)

  The endpoint constant ichibaGenreSearch used by the search_genres tool to make the API request.

  ichibaGenreSearch: "https://openapi.rakuten.co.jp/ichibagt/api/IchibaGenre/Search/20170711",

• src/index.ts:49-83 (helper)

  The rakutenRequest helper function used by the search_genres handler to make authenticated HTTP requests to Rakuten APIs.

  async function rakutenRequest(
    endpointUrl: string,
    params: Record<string, string> = {}
  ): Promise<unknown> {
    const appId = getAppId();
    const accessKey = getAccessKey();
    const origin = getOrigin();
    const searchParams = new URLSearchParams({
      applicationId: appId,
      accessKey,
      format: "json",
      ...params,
    });
    const url = `${endpointUrl}?${searchParams}`;
    const res = await fetch(url, {
      headers: {
        Origin: origin,
        Referer: origin,
      },
    });
  
    if (!res.ok) {
      const status = res.status;
      const body = await res.text();
      throw new Error(`Rakuten API error (HTTP ${status}) on ${endpointUrl}: ${body.slice(0, 200)}`);
    }
  
    const text = await res.text();
    if (!text) return { success: true };
    try {
      return JSON.parse(text);
    } catch {
      throw new Error(`Rakuten API returned malformed JSON on ${endpointUrl}`);
    }
  }