Skip to content

[spec] Add get-store-categories tool #1367

Description

@baldasseva

Problem

With the issue #1366, we have introduced categories to MCP search. However there is a 💩 ton of categories and they could change in time, so it is impossible to fit them in a tool description.

Proposed solution

Add a get-store-categories tool that renders the taxonomy from @apify/consts — static, no API call, no cache. Takes an optional group (default USE_CASE), returns the use-case tree (or a flat list for other groups) with id, name and short description, hidden categories excluded. Default-on, unauth-enabled, registered before search-actors in the actors category.

Plan

  • Add STORE_CATEGORIES_GET: 'get-store-categories' to HELPER_TOOLS, place it in the actors registry category ahead of search-actors (discover → search), and add it to the unauth-enabled list since it never touches the API.
  • Build the taxonomy helpers on top of @apify/consts. A getter that returns the categories of one group, mapped to a plain shape; a tree builder that nests use-case categories by parentCategoryId; and a formatter that renders the tree as an indented Markdown list (- ID — Name: description).
  • Implement the tool. Single group argument as a Zod enum over the taxonomy's group values, defaulting to USE_CASE, with the option list generated from the enum (same pattern as search-apify-docs' docSource). Description explains what categories are, that use-case ids are hierarchical and the most specific fitting id should be picked, and — gated on hasTool(search-actors) — that one id goes into search-actors' category. Result is the rendered tree plus structuredContent (group, categories, count, instructions) validated by a new output schema; the search-actors hint in the result text is gated on loadedToolNames. Read-only/idempotent annotations; it cannot fail, so always respondOk.
  • Wire the new tool to search-actors that has been set to accept categories in issue [spec] Add use case categories to search-actors tool #1366 .
  • Update every place that pins the default tool set. Mode-contract and category-ordering tests, server_card expected names, the unauth test, server-instructions gating test, registration integration cases (expected actors tools, total default count, sibling not.toContain checks), e2e tools-list length assertions, README tool table and unauth allowlist, src/tools/AGENTS.md and the root AGENTS.md tool enumeration (pnpm run check:agents). Decide with the ai-team whether the Claude connector allowlist includes the new tool.
  • Add tests, docs, evals, hosted repo. Flag in the PR that tools/list, server_card and the default tool count change, so apify-mcp-server-internal's contract suite needs a matching update.

Alternatives considered

No response

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    t-discoveryIssues owned by the discovery team.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions