d2r_lookup_unique

Instructions

Implementation Reference

• d2r_mcp/server.py:18-28 (registration)

  The tool 'd2r_lookup_unique' is registered with @mcp.tool() decorator on async function d2r_lookup_unique, which delegates to lookup_unique(query) from d2r_mcp.lookups.

  @mcp.tool()
  async def d2r_lookup_unique(query: str | int) -> str:
      """Look up a D2R unique item by name or numeric UID.
  
      Searches unique_items.py data. Returns item info + stats.
      Supports substring matching (e.g. "harlequin" finds Harlequin Crest).
  
      Args:
          query: Item name (or substring) or numeric UID
      """
      return lookup_unique(query)

• d2r_mcp/lookups.py:81-123 (handler)

  Core handler logic: lookup_unique() accepts a name (substring match) or numeric UID, looks up UNIQUE_ITEMS dict, fetches stats from UNIQUE_ITEM_STATS, and returns formatted JSON with uid, name, code, qlvl, base_name, and stats.

  def lookup_unique(query):
      """Look up a unique item by name (substring match) or numeric ID.
  
      Returns JSON with: uid, name, code, qlvl, base_name, stats.
      """
      if not _HAS_DATA:
          return _NO_DATA_MSG
      # Try numeric ID
      try:
          uid = int(query)
          if uid in UNIQUE_ITEMS:
              item = UNIQUE_ITEMS[uid]
              stats = UNIQUE_ITEM_STATS.get(uid, {}).get("stats", [])
              base = ITEM_BASES.get(item["code"], {})
              return _fmt({
                  "uid": uid, "name": item["name"], "code": item["code"],
                  "qlvl": item["qlvl"], "base_name": base.get("name", "?"),
                  "stats": stats,
              })
          return f"No unique item with ID {uid}"
      except ValueError:
          pass
  
      # Try exact name match (case-insensitive)
      q = query.lower()
      if q in _UNIQUE_NAME_TO_ID:
          return lookup_unique(str(_UNIQUE_NAME_TO_ID[q]))
  
      # Substring search
      matches = _substring_matches(query, _UNIQUE_NAME_TO_ID)
      if matches:
          results = []
          for name, uid in matches:
              item = UNIQUE_ITEMS[uid]
              results.append({
                  "uid": uid, "name": item["name"],
                  "code": item["code"], "qlvl": item["qlvl"],
              })
          if len(results) == 1:
              return lookup_unique(str(results[0]["uid"]))
          return _fmt({"matches": results, "count": len(results)})
  
      return f"No unique item found matching '{query}'"

• d2r_mcp/lookups.py:73-76 (helper)

  Helper _substring_matches used by lookup_unique to find case-insensitive substring matches capped at 10 results.

  def _substring_matches(query, name_to_id, limit=10):
      """Find entries where query is a case-insensitive substring of the name."""
      q = query.lower()
      return [(name, id_) for name, id_ in name_to_id.items() if q in name][:limit]

• d2r_mcp/lookups.py:47-47 (helper)

  Reverse index _UNIQUE_NAME_TO_ID built at import time mapping lower-cased item names to UIDs for fast lookups.

  _UNIQUE_NAME_TO_ID = {v["name"].lower(): k for k, v in UNIQUE_ITEMS.items()}

• d2r_mcp/lookups.py:68-70 (helper)

  Helper _fmt used by lookup_unique to format result dicts as pretty-printed JSON.

  def _fmt(obj):
      """Format a result dict as readable JSON."""
      return json.dumps(obj, indent=2, default=str)