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

# FiveM Enhanced MCP

[![CI](https://github.com/ghost-maxi/fivem-enhanced-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ghost-maxi/fivem-enhanced-mcp/actions/workflows/ci.yml)
[![Security](https://github.com/ghost-maxi/fivem-enhanced-mcp/actions/workflows/security.yml/badge.svg)](https://github.com/ghost-maxi/fivem-enhanced-mcp/actions/workflows/security.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-42D3C8.svg)](LICENSE)
[![Node.js 22+](https://img.shields.io/badge/node-%3E%3D22-F5A65B.svg)](package.json)

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](docs/adr/0001-enhanced-only-read-first.md) 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

```bash
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:

```bash
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:

```bash
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

```bash
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:

```bash
docker compose run --rm fivem-enhanced-mcp
```

### Use Docker MCP Gateway

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

```bash
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](docs/runbooks/docker-mcp-gateway.md).

## 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

```mermaid
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](docs/architecture.md) and
[source policy](docs/source-policy.md).

## Sources and licensing

Canonical inputs include:

- [Cfx.re documentation](https://docs.fivem.net/docs/)
- [Native Reference](https://docs.fivem.net/natives/)
- [Cfx.re native repository](https://github.com/citizenfx/natives)
- [CFX native declarations](https://github.com/citizenfx/fivem/tree/master/ext/native-decls)
- [FiveM source repository](https://github.com/citizenfx/fivem)
- [GTAV Enhanced differences](https://docs.fivem.net/docs/developers/legacy-vs-enhanced/)

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](docs/source-policy.md) and the current
[Creator Platform License Agreement](https://fivem.net/terms).

## Development

```bash
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:

```bash
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](CONTRIBUTING.md) before opening a pull request.
- Report vulnerabilities privately according to [SECURITY.md](SECURITY.md).
- Review notable changes in [CHANGELOG.md](CHANGELOG.md).
- Use [GitHub Issues](https://github.com/ghost-maxi/fivem-enhanced-mcp/issues)
  for non-sensitive defects and proposals.

## License

Original project code and documentation are available under the
[MIT License](LICENSE).