wuwa-helper

wuwa-helper is a stdio Model Context Protocol server for Wuthering Waves read-only lookup workflows.

It proxies two public upstreams:

• https://mc.yakitahome.com: multilingual in-game text search data
• https://api.kurobbs.com: public Kuro Wiki catalogue tree and catalogue cards

Tools

The server exposes 8 tools:

• wuwa_game_text_meta: inspect text dataset version, languages, and indexed file preview
• wuwa_game_text_search: search multilingual game text by keyword, speaker, or stateKey
• wuwa_game_text_context: fetch surrounding lines for a known fileIdx + entryId
• wuwa_dialogue_search: search dialogue-focused lines with reduced non-dialogue noise
• wuwa_dialogue_block: expand a dialogue hit into a contiguous dialogue block
• wuwa_wiki_catalogue_tree: inspect the Kuro Wiki catalogue tree and validate route paths
• wuwa_wiki_catalogue_page: fetch paged Kuro Wiki catalogue cards by catalogueKey, catalogueId, or strict fid/sid/thid route
• wuwa_wiki_catalogue_lookup: fuzzy-match wiki cards by proper name across supported catalogue families

Selected Catalogue Keys

Common wuwa_wiki_catalogue_page and wuwa_wiki_catalogue_lookup scopes include:

• character, weapon, echo, enemy, recipe
• hot_boss, hot_exploration
• tutorial_encyclopedia, map_text, world_insight, exploration_report
• glossary_background, glossary_activity

Example page calls:

{
  "catalogueKey": "hot_boss",
  "page": 1,
  "limit": 10
}

{
  "catalogueKey": "glossary_activity",
  "page": 1,
  "limit": 10
}

Install And Run

npm install
npm run build
npm start

After publishing, you can also launch it with:

npx -y wuwa-helper

MCP Host Example

Example mcpServers entry for a stdio host:

{
  "mcpServers": {
    "wuwa-helper": {
      "command": "node",
      "args": ["F:\\wuwa-helper\\dist\\index.js"]
    }
  }
}

If the package is installed globally or published, command: "npx" with args: ["-y", "wuwa-helper"] also works.

Cache And Refresh

The server uses in-process TTL caches for upstream data that is reused across calls:

• text meta: 10 minutes
• wiki catalogue tree: 10 minutes
• wiki catalogue snapshots: 10 minutes

Important behavior:

• Caches are not permanent; stale data ages out automatically.
• Tools that depend on cached upstream data expose a refresh flag.
• refresh: true forces a new upstream fetch before the tool completes.
• wuwa_wiki_catalogue_page now paginates locally from the cached catalogue snapshot so page, pageSize, total, totalPages, and records.length stay consistent even when the upstream page API reports inconsistent pagination fields.

Route And Pagination Semantics

• pathIds for wuwa_wiki_catalogue_tree are strict tree paths. Invalid or disconnected paths now return an error.
• fid/sid/thid for wuwa_wiki_catalogue_page are also strict. sid requires fid, and thid requires sid.
• catalogueId direct lookup is still supported, but it is validated against the catalogue tree.
• Some catalogueKey aliases resolve to third-level wiki paths and therefore populate requestedPath.thid as well as fid and sid.
• For wiki page output, structured content includes a pagination object that shows the local pagination mode and the raw upstream pagination fields.

Common Failure Modes

• upstream timeout: all external fetches now use AbortController and return a clear upstream timeout error
• upstream schema change: if mc.yakitahome.com or api.kurobbs.com changes response shape, tool calls may fail fast instead of returning misleading structured content
• invalid wiki route: malformed pathIds or broken fid/sid/thid paths return an explicit error instead of falling back to an unrelated node
• upstream partial data: the wiki page tool exposes raw upstream pagination metadata because Kuro Wiki currently reports page fields that do not match requested limit

Development

npm run lint
npm run build
npm test