redm-mcp MCP Server

Resolve a RedM game-data asset (ped model, weapon, object, door, vehicle) by exact name, 32-bit hash, or partial-name search. O(1) structured lookup against pre-parsed discoveries tables — replaces the common workflow of grepping `a_c_bear_01` in peds_list.lua, then cross-referencing RELATIONSHIP/README.md for its relationship group. Returns: type, name, normalized hash (`0x` + 8 uppercase hex), source file + line, plus type-specific metadata (peds get `variants` + `relationship`, weapons get `group`, doors get `coords` + `model_hash`, objects get `category`/`subcategory`). Catalog ~22,500 entries (mostly objects). Typical latency p50 ~15ms, p95 ~65ms. NOT for: - **Script natives** like `SET_ENTITY_COORDS`, `GetPedHealth`, or hashes from `Citizen.InvokeNative(0x...)` — use `lookup_native`. Native hashes are 64-bit (`0x06843DA7060A026B`); asset hashes are 32-bit (`0xBCFD0E7F`). Different namespaces, never collide. - **Flag enums, settings, clipsets, scenario keys** like `CPED_CONFIG_FLAGS`, `MP_Style_Casual`, `mech_loco_m@`, `MAGGIE_SEAT_CHAIR_DESK_WRITING`. Those live as tokens in lua source but not in this catalog. Use `grep_docs`. - **Behavior queries** ("which animal is the bear", "weapons in the lemat family") — use `semantic_search`. Pass exactly ONE of `name` / `hash` / `search`. Optional `type` narrows to a category (useful when a fragment like "horse" hits both peds and vehicles). Note: `type` reflects the SOURCE FILE — the same asset name can exist under multiple `type`s. e.g. `mp006_p_mshine_int_door01x` appears as `type=object` (1 row from object_list.lua) AND `type=door` (2 rows from doorhashes.lua, different door hashes for distinct in-world instances with `coords`). Pick `type=door` when you want lockable in-world doors with positions; `type=object` for the model itself. Examples: - `{name: "a_c_bear_01"}` → exact ped lookup, returns variants=11 + relationship=REL_WILD_ANIMAL_PREDATOR. - `{hash: "0xBCFD0E7F"}` → resolves to ped `a_c_bear_01` (omit `0x` ok). - `{search: "lemat", type: "weapon"}` → substring match → `weapon_revolver_lemat`. - `{search: "moonshine", type: "door"}` → exact substring misses (no door name contains "moonshine"), fuzzy trigram fallback fires → `mp006_p_mshine_int_door01x`. Fuzzy mainly fires when `type` narrows out the exact-substring matches; without `type`, common terms find substring hits first and never reach fuzzy.

Enumerate doc paths in a category/namespace. Use to discover what exists before calling `get_document` or a targeted `grep_docs`. NOT a content search — use `semantic_search` for behavior/concept lookups or `grep_docs` for token lookups. Returns `{path, title, chunks}[]`.

Fetch full markdown of a doc by `path` (as returned by `browse`, `semantic_search`, or `grep_docs`). Use to retrieve full content after a search snippet looks promising. Pass `heading` (full breadcrumb like `Character Management > Inventory Management`, or just the leaf — case-insensitive, fuzzy) to fetch only that section. Deep-heading matches auto-prepend the H2 parent's intro for context. For individual script natives prefer `lookup_native`. The largest rdr3_discoveries lua data tables are keyed catalogs: call with no `heading` to list their top-level keys, then pass a key as `heading` to fetch that one entry; use `grep_docs` to search values inside. For code symbols (`addItem`) use `grep_docs`. Community findings use `learning:N` paths, not `learnings/<slug>.md`. On 404 returns available headings + cross-file hints.

Find an EXACT literal token in raw doc files (markdown + lua). Use for specific weapon/ped/animation/prop/interior/zone names (`weapon_pistol_volcanic`, `a_c_bear_01`, `p_campfire01x`), known hashes (`0x020D13FF`), walkstyles/clipsets (`MP_Style_Casual`, `mech_loco_m@`), or any string you'd `grep` for. NOT for behavior/concept queries (use `semantic_search`) or script-native hash/name lookup (use `lookup_native`). REQUIRED for tokens inside the largest rdr3_discoveries data tables (audio_banks, ingameanims_list, cloth_drawable, cloth_hash_names, object_list, megadictanims, entity_extensions, imaps_with_coords, propsets_list, vehicle_bones) — only preview-indexed for embeddings, so `semantic_search` will NOT find tokens in them. Optional: `contextBefore`/`contextAfter` for ±N surrounding lines (saves a follow-up `get_document` call); `filesOnly: true` to get paths only (cheap exploration); `multiline: true` for cross-line patterns (`(?s)foo.*bar`). Pattern uses Rust regex syntax (rg engine). PREFER one targeted call over giant `a|b|c|d|e` alternations — split into separate calls; alternations rarely improve recall and bloat the regex automaton. Returns matched lines with path + line number. Long matched lines are windowed ±60 chars around the match (…); to read around a hit, use `read_lines({path, start})` for the preview-only mega-tables listed above (get_document holds only their ~80-line head), or `get_document({path})` for ordinary docs. If you are retrying after a previous pattern returned no matches, populate `prior_attempt` so the server can record what didn't work and steer alternative spellings.

Load the calling-convention reference for RedM/RDR3 natives in `js` or `lua`. Call ONCE per session before writing native-calling code — every native doc page only shows Lua examples, so JS/TS authors need this to translate correctly. Covers result modifiers (`Citizen.resultAsInteger/Float/String/Vector`), `Citizen.invokeNative` vs `invokeNativeByHash`, type mapping, pointer-arg gotchas, worked examples. Cheap, no embedding.

Read an exact line range from a raw doc file by absolute line number — the windowed-read companion to `grep_docs`. When `grep_docs` returns a hit at `path:line` inside a large file, call `read_lines({ path, start, end })` to pull the surrounding block. This is the ONLY way to read around a hit in the largest rdr3_discoveries data tables (audio_banks, ingameanims_list, ptfx, soundsets, imaps_with_coords, megadictanims, etc.): their full bodies are NOT in the vector/heading index (only an ~80-line preview is), so `semantic_search` can't reach them and `get_document` resolves real section headings only — NOT synthetic `lines N-M` offsets. `start`/`end` are 1-based and inclusive; omit `end` for a 50-line window; one call returns at most 400 lines (narrow the range for more). For prose `.md` docs prefer `get_document` with a `heading`; to search values use `grep_docs`; for individual script natives use `lookup_native`.

Resolve a RedM/RDR3 SCRIPT native by hash or name — O(1), exact. Use whenever you see `Citizen.InvokeNative(0x...)`, `Citizen.invokeNative('0x...')`, `GetHashKey('NAME')`, or a SCREAMING_SNAKE_CASE native name (e.g. `SET_ENTITY_COORDS`, `GetPedHealth`) in Lua/JS/TS. NOT for game-data hashes (weapon/ped/animation names) — use `grep_docs`. Pass `hash` (0x… optional, case-insensitive) or `name` (exact first, ILIKE substring fallback). Returns name, hash, namespace, return type, params, description, full content, plus `findings[]` — community gotchas linked to that native. Inspect `findings[].id` and call `get_document({path: 'learning:<id>'})` for full body. Also returns `refDocs[]` — enum/flag value tables for that native (the constants to pass for params like flagId/attributeIndex/eventType). When `refDocs[].content` is set, it's the inline enum table — use those values directly. When `content` is null but `refDocs[].fetch` is present, the table was too large to inline — run that exact call (e.g. `get_document({ path: "refdoc:eEventType" })`) to get the full table; `refDocs[].preview` shows the first lines. github entries (no `fetch`) are url-only. A miss also reports if the native exists in the other game (GTA5/FiveM) — do not call those in RedM — and says so when it is in neither database (likely fabricated).

Orient yourself: list available doc categories and their namespaces. Use once at session start (or when unsure) before applying a `category=` / `namespace=` filter to `browse` / `semantic_search`. NOT a content search. Categories: `natives` (PLAYER, ENTITY, VEHICLE, …), `vorp`, `rsgcore`, `oxmysql`, `discoveries` (AI, weapons, peds, animations, clothes, objects, …), `jo_libs` (menu, notification, callback, framework-bridge, …, dev_resources, redm_scripts), `cfx` (Cfx runtime/scripting API from docs.fivem.net: scripting-reference, scripting-manual, server-manual, client-manual, resources, cookbook, …), `guides`, `learnings`.

Search RedM/RDR3 docs by behavior, concept, OR exact token. Use when you don't have a specific native hash/name (use `lookup_native`) and the term isn't a known asset name in a large data table (use `grep_docs`). Hybrid mode (default) handles 'how do I X' queries ('teleport player', 'spawn vehicle', 'inventory add item') AND tokens ('addItem', 'weapon_pistol_volcanic', 'CPED_CONFIG_FLAG_') — fused via RRF over vector + BM25. Returns ranked snippets (path, breadcrumb, heading, snippet, score). Call `get_document({path, heading})` for full chunk content. `mode=semantic` for pure vector; `mode=lexical` for pure BM25. Filter via `category=vorp|rsgcore|oxmysql|natives|discoveries|jo_libs|cfx|learnings` or `namespace`. `category=cfx` = Cfx runtime/scripting API (RegisterCommand, exports, events, statebags, fxmanifest, convars, OneSync, NUI) — not natives, not framework docs. Community findings merged by default; `category=learnings` returns only findings. If you are retrying after a previous call returned no useful results, populate `prior_attempt` so the server can surface alternative wordings and learn what's missing from the docs.

Share a verified finding back to the docs corpus so the next agent can find it. Use AFTER solving a non-trivial problem to record what would have saved you time: a gotcha, a working parameter combo, an undocumented constraint, a relationship between two natives that isn't obvious. Other agents will find this via `semantic_search` (findings are merged into default results; `category: 'learnings'` returns only findings). WHEN to use: - You burned multiple iterations on something not in the docs. - You discovered an undocumented quirk (param order, hash collision, framework export that isn't in `vorp`/`rsgcore`). - You verified that a specific combination works (e.g. native A + flag B for behavior C). WHEN NOT to use: - The information is already in the docs (verify with `semantic_search`/`grep_docs` first). - You're guessing — only contribute verified findings. - It's project-specific (your repo's auth flow, your DB schema). Keep it general to RedM/RDR3. Keep `title` short and searchable. `body` should explain WHY, not just WHAT — context, the trap, the fix.