# FiveM MCP

> A focused MCP server for FiveM teams who want faster scaffolding, safer file edits, and stronger UI/NUI starting points.

<p align="left">
  <strong>Open source</strong> • Built for local stdio workflows • Designed for Cursor, Trae, and Claude
</p>

## Why This Exists

`FiveM MCP` was built to make AI agents actually useful inside a FiveM workflow.

Instead of giving a generic assistant a pile of loose files and hoping for the best, this server exposes a practical toolkit for:

- creating new FiveM resources
- adding or scaffolding NUI quickly
- generating UI templates with multiple variants and themes
- editing files more safely with hash-aware and line-based operations
- giving MCP clients enough structured context to act with fewer mistakes

It is especially opinionated around **UI work**, where most FiveM projects end up needing consistency, speed, and visual quality at the same time.

---

## Quick Start

### 1. Install

```bash
npm install
```

### 2. Build

```bash
npm run build
```

### 3. Point the MCP host to the compiled server

This project runs as a **local stdio MCP server**.

Use:

- `command`: `node`
- `args`: `["./dist/index.js"]` in repo-local configs, or `["${workspaceFolder}/dist/index.js"]` in hosts that support workspace interpolation
- `env.FIVEM_MCP_ALLOWED_DIRS`: the resource folders the server is allowed to read/write

Example allowed dirs:

```text
D:\FiveM\server-data\resources
D:\FiveM\server-data\resources\[local]
```

If you want more than one root, separate them with `;`.

```text
D:\FiveM\server-data\resources;D:\FiveM\server-data\resources\[local]
```

---

## First-Time User Layer

If you are new to MCP or new to this repo, this is the minimum you need to understand:

1. Your IDE starts this server locally through `stdio`.
2. The server exposes tools, resources, and prompts.
3. The agent can then inspect, scaffold, and edit FiveM resources for you.
4. File access is intentionally restricted to the directories declared in `FIVEM_MCP_ALLOWED_DIRS`.

### What it is good at

- FiveM resource scaffolding
- NUI bootstrap and visual template generation
- safe local file reads/writes
- line-based edits for more controlled patching
- quick starting points for dashboards, HUDs, inventories, and modal UIs

### What it is not trying to be

- a hosted multi-user MCP platform
- a generic backend automation server
- a remote HTTP MCP service

This repo is optimized for **local dev flow**, especially for AI IDEs working directly on a FiveM codebase.

---

## Template System

This project currently ships with UI variants and visual themes so new resources can start from something that already feels intentional.

### UI Variants

| Variant | Best for |
|---|---|
| `modal` | menus, shops, dialogues, forms |
| `hud` | status bars, needs, overlay widgets |
| `inventory` | slot grids, item panels, loot/shop layouts |
| `dashboard` | tablets, admin panels, dispatcher/ops interfaces |

### UI Themes

| Theme | Visual direction |
|---|---|
| `violet` | futuristic, flexible, general-purpose |
| `police` | institutional, tactical, cold |
| `amber` | commerce, crafting, marketplace, garage |
| `emerald` | clean ops, admin, support, health-style flows |

### Example idea combinations

- `dashboard` + `police` for a police tablet
- `inventory` + `amber` for a premium garage/shop
- `hud` + `emerald` for clean status overlays
- `modal` + `violet` for general roleplay menus

---

## Tooling Layer

### Filesystem Tools

| Tool | Purpose |
|---|---|
| `fs.list` | list directories inside allowed roots |
| `fs.read_text` | read text files with SHA256 |
| `fs.write_text` | write text files with optional hash validation |
| `fs.edit_lines` | apply line-range edits |
| `fs.mkdirp` | create directories recursively |

### FiveM Tools

| Tool | Purpose |
|---|---|
| `fivem.resource_create` | create a new FiveM resource with optional UI |
| `fivem.resource_inspect` | inspect `fxmanifest.lua` basics |
| `fivem.ui_add` | attach NUI scaffolding to an existing resource |
| `fivem.framework_detect` | infer `standalone`, `qb-core`, or `esx` |
| `fivem.resource_audit` | audit resource/NUI structure |
| `fivem.ui_scaffold` | generate or replace the UI bundle |

### MCP Resources

| Resource | Purpose |
|---|---|
| `fivem://docs/core-notes` | core FiveM + NUI reminders |
| `fivem://docs/ui-patterns` | quick UI variant/theme guidance |

### MCP Prompts

| Prompt | Purpose |
|---|---|
| `fivem-ui-task` | guide an agent toward the right template and visual direction |

---

## Stack

| Layer | Choice |
|---|---|
| Language | TypeScript |
| Runtime | Node.js |
| MCP SDK | `@modelcontextprotocol/sdk` |
| Validation | `zod` |
| Transport | `stdio` |
| Build | `tsc` |
| Dev runner | `tsx` |

Project scripts:

```bash
npm run dev
npm run build
npm run start
```

---

## For Repository Scanners

The block below is intentionally compact and machine-friendly.

```yaml
name: fivem-mcp
category: model-context-protocol-server
domain: fivem
focus:
  - fivem-resource-scaffolding
  - nui-ui-templates
  - safe-local-filesystem-edits
transport: stdio
runtime: node
language: typescript
entrypoint: dist/index.js
source_entrypoint: src/index.ts
capabilities:
  tools: true
  resources: true
  prompts: true
hosts:
  - cursor
  - trae
  - claude-desktop
framework_detection:
  - standalone
  - qb-core
  - esx
ui_variants:
  - modal
  - hud
  - inventory
  - dashboard
ui_themes:
  - violet
  - police
  - amber
  - emerald
env:
  required:
    - FIVEM_MCP_ALLOWED_DIRS
license: MIT
author: Luan Silva
studio: Tekton
```

---

## Project Structure

```text
FivemMcp/
├─ src/
│  ├─ index.ts
│  ├─ fivem-tools.ts
│  ├─ fs-tools.ts
│  ├─ security.ts
│  └─ templates.ts
├─ dist/
├─ package.json
├─ tsconfig.json
└─ README.md
```

### Source map

- [`src/index.ts`](src/index.ts): MCP server registration
- [`src/fivem-tools.ts`](src/fivem-tools.ts): FiveM-oriented actions
- [`src/fs-tools.ts`](src/fs-tools.ts): safe file operations
- [`src/security.ts`](src/security.ts): directory boundary enforcement
- [`src/templates.ts`](src/templates.ts): UI variants and themes

---

## Add to Cursor

You can add this server either globally or per project.

### Suggested project config

Create:

```text
.cursor/mcp.json
```

```json
{
  "mcpServers": {
    "fivem-mcp": {
      "command": "node",
      "args": [
        "${workspaceFolder}/dist/index.js"
      ],
      "env": {
        "FIVEM_MCP_ALLOWED_DIRS": "D:\\FiveM\\server-data\\resources;D:\\FiveM\\server-data\\resources\\[local]"
      }
    }
  }
}
```

### Good to know

- Cursor also supports a global `mcp.json`.
- If Cursor does not detect the server immediately, reload MCP from Settings.
- Using `${workspaceFolder}/dist/index.js` keeps the config portable across machines.

---

## Add to Trae

Prefer a **project-level** config so the server path stays relative to the repo instead of pointing to one machine.

Create:

```text
.trae/mcp.json
```

### Suggested config

```json
{
  "mcpServers": {
    "fivem-mcp": {
      "command": "node",
      "args": [
        "./dist/index.js"
      ],
      "env": {
        "FIVEM_MCP_ALLOWED_DIRS": "D:\\FiveM\\server-data\\resources;D:\\FiveM\\server-data\\resources\\[local]",
        "START_MCP_TIMEOUT_MS": "60000",
        "RUN_MCP_TIMEOUT_MS": "60000"
      }
    }
  }
}
```

### Notes

- In Trae, `command` should be a clean executable name or full executable path.
- Put file paths in `args`, not inside `command`.
- For portability, keep the config inside the repo and keep `args` relative to the repo build output.

---

## Add to Claude

For a repo-portable setup, prefer **Claude Code** with a project-level `.mcp.json`.

Create:

```text
.mcp.json
```

```json
{
  "mcpServers": {
    "fivem-mcp": {
      "command": "node",
      "args": [
        "./dist/index.js"
      ],
      "env": {
        "FIVEM_MCP_ALLOWED_DIRS": "D:\\FiveM\\server-data\\resources;D:\\FiveM\\server-data\\resources\\[local]"
      }
    }
  }
}
```

### Why this version is preferred

- it lives inside the repo
- it does not leak one developer's machine path
- it stays portable when the repository moves

### Claude Desktop note

Claude Desktop uses a global config file, so repo-relative paths are not as clean there. If you must use Desktop, prefer a tiny launcher or env-based wrapper instead of hardcoding one developer's home directory into docs or committed config.

---

## Example Calls

### Create a new resource

```json
{
  "tool": "fivem.resource_create",
  "arguments": {
    "resourceName": "police-tablet",
    "withUi": true,
    "framework": "qb-core",
    "uiVariant": "dashboard",
    "uiTheme": "police",
    "title": "Police Operations"
  }
}
```

### Scaffold a UI into an existing resource

```json
{
  "tool": "fivem.ui_scaffold",
  "arguments": {
    "resourceDir": "garage-ui",
    "uiVariant": "inventory",
    "uiTheme": "amber",
    "overwrite": true,
    "title": "Premium Garage"
  }
}
```

### Audit a resource

```json
{
  "tool": "fivem.resource_audit",
  "arguments": {
    "resourceDir": "police-tablet"
  }
}
```

---

## Security Model

This server does **not** expose unrestricted filesystem access.

It resolves all user-supplied paths against the directories listed in:

```text
FIVEM_MCP_ALLOWED_DIRS
```

That means:

- no arbitrary disk traversal by default
- no writes outside approved FiveM roots
- safer agent behavior when multiple resources exist on the same machine

If you want broader access, expand the allowed roots deliberately.

---

## Development

### Run in dev mode

```bash
npm run dev
```

### Build for IDE use

```bash
npm run build
```

### Run the compiled server

```bash
node dist/index.js
```

---

## Roadmap Direction

This repo is already useful as a local FiveM MCP server, but its natural evolution is clear:

- stronger template catalog for real FiveM products
- richer UI families like banking, garage, MDT/tablet, dispatch, shops
- more polished visual systems around the current variant/theme model
- tighter onboarding for teams adopting MCP in game scripting workflows

---

## License

This project is **open source under the MIT License**.

Produced by **Luan Silva** at **Tekton**.

---

## Credits

Created for builders who want AI assistance to feel native inside a FiveM workflow, not bolted on after the fact.