<div align="center"> <img src="assets/banner.svg" alt="FiveM Enhanced MCP — unofficial, source-grounded, read-first" width="100%" /> </div>

FiveM Enhanced MCP

An unofficial, source-grounded MCP server and Codex skill for professional development on FiveM for GTAV Enhanced.

It gives coding agents exact native lookups, current platform constraints, manifest and security reviews, NUI compatibility evidence, and direct primary sources. Unknown, stale, ambiguous, and conflicting facts remain explicit instead of being guessed.

[!IMPORTANT] This independent project is not approved, sponsored, endorsed, or maintained by Rockstar Games or Cfx.re. It supports GTAV Enhanced only and contains no Rockstar or Cfx.re brand assets.

Why this exists

FiveM answers are often technically plausible but wrong for the target product, runtime, API set, artifact, or gamebuild. Legacy guidance and third-party framework assumptions can make that worse. This project provides a deliberately narrow context layer that:

• distinguishes GTAV Enhanced behavior from Legacy behavior;
• resolves natives by exact name or hash and preserves client/server scope;
• cites official Cfx.re or Rockstar-controlled sources directly;
• validates resource structure, manifests, events, State Bags, and NUI targets;
• treats remote content as untrusted data;
• requires runtime evidence before calling code performant.

The MCP server supplies facts and diagnostics. The host agent still writes and edits code. v0.1 does not generate code, modify project files, administer a server, deploy resources, or download FiveM artifacts.

Product boundary

Included	Intentionally excluded
FiveM for GTAV Enhanced	FiveM Legacy and RedM
Framework-neutral resources	ESX, QBCore, ox_lib, and other frameworks
Client, server, shared, and NUI facts with explicit scope	Marketplace, escrowed, paid, leaked, or private resources
Official documentation, native declarations, and source metadata	Game assets, artifact binaries, and server administration
Read-only reviews and cache refresh	Code generation, filesystem changes, deployment, and administration

See ADR 0001 for the rationale.

Quickstart

Requirements

• Node.js 22 or newer
• npm 10 or newer
• Git

A current Docker Desktop installation with MCP Toolkit enabled is optional for container or Docker MCP Gateway usage.

Run from source

git clone https://github.com/ghost-maxi/fivem-enhanced-mcp.git
cd fivem-enhanced-mcp
npm ci
npm run build
npm start

The server communicates over stdio. Standard output is reserved for MCP messages.

On Windows, use npm.cmd if PowerShell blocks npm.ps1.

Connect to Codex

Add the GitHub-backed marketplace and install the bundled plugin:

codex plugin marketplace add ghost-maxi/fivem-enhanced-mcp
codex plugin add fivem-enhanced-mcp@fivem-enhanced

Alternatively, build the project and register the absolute path to the compiled entry point:

codex mcp add fivem-enhanced -- node /absolute/path/to/fivem-enhanced-mcp/dist/index.cjs
codex mcp list

Restart the Codex app after changing MCP configuration. For the intended workflow, the plugin bundles the fivem-enhanced-engineering Codex skill with the MCP server. The skill guides source verification and review; the server provides typed evidence.

Run with Docker

docker build -t fivem-enhanced-mcp:local .
docker run --rm -i \
  --read-only \
  --tmpfs /tmp \
  --mount source=fivem-enhanced-cache,target=/data/cache \
  --env FIVEM_ENHANCED_MCP_CACHE_DIR=/data/cache \
  fivem-enhanced-mcp:local

Or use the checked-in Compose definition:

docker compose run --rm fivem-enhanced-mcp

Use Docker MCP Gateway

Docker MCP Toolkit supports local YAML server descriptors. From the repository root:

docker build -t fivem-enhanced-mcp:local .
docker mcp profile create --name fivem-enhanced --server docker://fivem-enhanced-mcp:local
docker mcp gateway run --profile fivem_enhanced --dry-run
docker mcp client connect codex --global --profile fivem_enhanced

Review the dry-run output before connecting. Keep this profile limited to the expected server. See the full Docker MCP Gateway runbook.

Configuration

All settings are optional:

Variable	Purpose	Default
FIVEM_ENHANCED_MCP_CACHE_DIR	Local normalized source cache	Platform cache directory
FIVEM_ENHANCED_MCP_REQUEST_TIMEOUT_MS	Official-source request timeout	15000

MCP tools in v0.1

Tool	Purpose	Effect
search_fivem_docs	Search allowlisted official Enhanced documentation with scope and citations	Read-only
get_native	Resolve an exact native name or hash without guessing missing definitions	Read-only
get_platform_capabilities	Retrieve the dated Enhanced capability baseline and required context	Read-only
get_cef_target	Report the source-backed CEF/Chromium target and its evidence scope	Read-only
audit_nui_compatibility	Check supplied NUI source against the live verified browser milestone	Read-only
validate_fxmanifest	Validate manifest entries, dependencies, runtime constraints, and deprecations	Read-only
review_resource_structure	Review a supplied resource tree against framework-neutral boundaries	Read-only
review_event_security	Detect client-trust and network-event security risks	Read-only
review_state_bag_usage	Detect replication and serialization hazards in supplied usage	Read-only
create_performance_test_plan	Produce a reproducible profiler, resmon, network, and NUI measurement plan	Read-only
source_health	Report freshness and failures for sources checked by this process	Read-only
refresh_sources	Refresh only the local source cache from allowlisted official origins	Cache write only

Analysis tools do not modify the user's repository. refresh_sources is the only tool that writes, and its write boundary is the configured cache directory.

Results use explicit states such as verified, inferred, ambiguous, conflict, stale, and not_found, with direct source URLs and scope metadata.

Architecture

flowchart LR
  Host["Codex or another MCP host"]
  Skill["Enhanced engineering skill"]
  Server["Typed MCP tools over stdio"]
  Domain["Enhanced-only domain services"]
  Index["Exact native lookup + weighted docs search"]
  Cache["Provenance-aware local cache"]
  Official["Allowlisted official sources"]
  Result["Status + scope + citations"]

  Host --> Skill
  Host --> Server --> Domain
  Domain --> Index --> Cache
  Cache <--> Official
  Domain --> Result --> Host

Exact native identifiers take precedence over full-text search. Source updates are validated before replacing the last known-good cache. Remote documents are data, never instructions.

Current v0.1 limits

• Original GTA V natives are resolved by exact name or hash from the official client-native JSON.
• CFX declarations are resolved by exact name and preserve their declared API set. If the declaration does not publish a hash, the MCP returns no hash instead of deriving one.
• Official-document search covers the focused Enhanced engineering corpus listed in the source policy; it is not a general web search.
• Static validators are heuristics. A clean result does not replace FiveM, browser, profiler, resmon, or security testing.
• The embedded Enhanced capability baseline becomes stale after 30 days and must then be checked against current official documentation.

Read the full architecture and source policy.

Sources and licensing

Canonical inputs include:

• Cfx.re documentation
• Native Reference
• Cfx.re native repository
• CFX native declarations
• FiveM source repository
• GTAV Enhanced differences

The repository's MIT License applies only to this project's original code and documentation. It does not relicense FiveM, GTA, official documentation, native corpora, or third-party content. Because several official source repositories do not expose a repository-wide license, this project references or locally caches necessary data at runtime and does not vendor or redistribute those corpora.

Marketplace, Asset Escrow, paid, leaked, and private resources are excluded. See the Source Policy and the current Creator Platform License Agreement.

Development

npm ci
npm run format:check
npm run lint
npm run typecheck
npm test
npm run test:coverage
npm run build
npm run plugin:validate
npm run smoke:mcp

Run every check with:

npm run validate

Behavioral changes need tests for success, ambiguity, conflict, stale data, and failure paths. Performance claims need reproducible runtime evidence.

Contributing and security

• Read CONTRIBUTING.md before opening a pull request.
• Report vulnerabilities privately according to SECURITY.md.
• Review notable changes in CHANGELOG.md.
• Use GitHub Issues for non-sensitive defects and proposals.

License

Original project code and documentation are available under the MIT License.