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.

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.

Related MCP server: mcp-minecraft-forge

Product boundary

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:

MCP tools in v0.1

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.