Installation

npm install -g @konggithubdev/samp-mcp
# or
yarn global add @konggithubdev/samp-mcp

The package is published to GitHub Packages, so installs and updates require authentication — create a personal access token (classic) with read:packages scope and add it to ~/.npmrc:

//npm.pkg.github.com/:_authToken=TOKEN
@konggithubdev:registry=https://npm.pkg.github.com

Requires Node.js ≥ 18 and a functional SA-MP server directory.

File tools need the mcp-file-tools binary — samp-mcp finds it at its default install location, or you can point to it explicitly with the SAMP_MCP_FILE_TOOLS_COMMAND environment variable.

Textdraw Editor

samp-mcp can design SA-MP textdraws (HUD, UI, logos, sprite/txd art) as project files and show you the result on a web page — no server restart, no launching the game.

Workflow

1. textdraw_create (or textdraw_import from existing TextDrawCreate code / another editor's project JSON) — textdraws are stored in <server root>/.samp-mcp/textdraws/<project>.json, so a UI can be reviewed, diffed and versioned next to the gamemode.
2. txd_scan — reads the .txd texture dictionaries on the machine, lists their textures (size/format) and decodes them to PNG (8888/888/565/555/4444/LUM8 and DXT1/3/5).
3. model_scan + model_preview — for font 5 (3D preview) textdraws: finds the .dff models on the machine (loose files, the server's models/ folder, or inside a VER2 .img archive such as gta3.img/samp.img), pairs them with their .txd textures, and renders the model to the PNG the textdraw shows. model_export writes OBJ+MTL or glTF for Blender/three.js. See 3D models below.
4. textdraw_preview — renders every textdraw on a web page using the classic 640x448 grid scaled to real resolutions, with boxes, alignment, colours, outline/shadow, decoded font 4 sprites and real rendered font 5 model previews (drag a model to orbit it, wheel to zoom). serve=true also starts a live editor server (127.0.0.1) where textdraws can be dragged on screen and saved straight back into the project file.
5. textdraw_export — emits ready-to-use Pawn: statements, declarations, a full system-module .inc (y_hooks + show/hide stocks), a markdown table or raw JSON.

Sprite / image / UI notes

• Font 4 sprite textdraws use text in the form txdname:texturename (e.g. demo:demo_logo) — the preview resolves them against the scanned dictionaries and shows the real texture.
• Working on art that has no .txd yet? Drop the bitmap at .samp-mcp/textdraw-assets/sprites/<txdname>__<texturename>.png (or .jpg) and the preview draws it as a stand-in; validation reports it as a design-time image so it is clear the game will not show it until the same texture is shipped inside <txdname>.txd.
• Font 5 model previews use previewModel + previewRot/previewZoom and show the real model: the .dff is parsed and rasterised with its .txd textures, and the result is cached at .samp-mcp/textdraw-assets/models/<modelid>.png (drop your own PNG there to override it).
• Custom 0.3.DL UI textures are supported: AddSimpleModel(...) lines found by textdraw_import are kept with the project, they map model ids to their .dff/.txd, and they are re-emitted as hints by the module export.

3D models

model_scan finds what a server can actually show and model_preview renders it — the same idea as browser GTA SA model viewers (e.g. gtastuff.com/viewer), applied to font 5 textdraws:

• Reads .dff clumps the way RenderWare writes them: clump → frame list (with the node-name extension) → geometry list → geometry struct (format flags, vertices, normals, texture coordinates, per-triangle material ids) → material list (colour, texture, addressing) → atomics, then applies the frame hierarchy so instanced parts land in the right place.
• Finds models in loose files, the server's models/, .samp-mcp/model-export/, or inside VER2 .img archives (models/gta3.img, samp.img, …) — the index of an archive is read on its own, so a stock 1 GB gta3.img is scanned without loading it.
• Pairs each material texture with a matching .txd (the model's sibling dictionary, the AddSimpleModel txd, the .txd files found by the scan, or a design-time PNG), decodes 8888/888/565/555/4444/LUM8/DXT1/3/5, and falls back to .samp-mcp/textdraw-assets/sprites/<txd>__<texture>.png for art that has no dictionary yet.
• Renders with z-buffering, bilinear texture sampling (wrap/mirror/clamp), per-vertex colours, material colour and alpha, camera-fixed key/fill/rim lighting and 2x supersampling. rot follows TextDrawSetPreviewRot (rx tilts, rz yaws), zoom follows the zoom argument, vehCol recolours the body parts vehicle materials mark, and yaw/pitch orbit the camera.
• model_export writes Wavefront OBJ + MTL or glTF 2.0 (one primitive per material, textures dumped as PNG next to it).
  Fidelity — what is exact, what is approximated

Exact (data level, verified by the round-trip check in npm run demo:textdraw):

• Every property round-trips Pawn → project → Pawn → project unchanged (position, letter/text size, colours, font, alignment, box/selectable/proportional, preview model/rotation/zoom/vehicle colours, global vs per-player).
• Pawn escapes: a newline escape inside a string literal becomes a real line break in the project and on the preview page, and is re-emitted as exactly one escape when exporting; the underscore placeholder is kept in the data and drawn as a space (the SA-MP convention for blank filler).
• Text metrics come from the game itself: the per-character advance tables of both HUD atlases (proportional prop[] and the monospace advance), a glyph box of 10 units × letterSizeY, a line height of 9 units × letterSizeY, and the in-string colour codes ~r~ ~g~ ~b~ ~w~ ~p~ ~h~ ~n~ with the client's exact palette. Verified in-browser against the rendered pixels.
• Outline/shadow are drawn in TextDrawBackgroundColor (the client's behaviour, and why a transparent background hides the outline); the outline also widens each character's advance, and ~h~ lightens the current colour — all matching the client.
• Screen scaling uses the game's grid maths (x * W/640, y * H/448 — the textdraw canvas is 640x448).
• Font 4 draws the texture itself and modulates it with TextDrawColor: rgb multiplied by the colour, alpha multiplied by its alpha, so a full-colour UI sheet (white colour) appears exactly as authored — it is not a flat silhouette. When the texture is missing the slot is painted with that colour instead, as the client does.
• A box is only painted when UseBox is set (TextDrawUseBox), for every font — sprites and model previews included — which is what the client does; font 4 box fill uses TextDrawColor, font 5 uses TextDrawColor ∩ TextDrawBackgroundColor.
• .txd decoding is pixel-level verified (8888/888/565/555/4444/LUM8 and DXT1/3/5 blocks).
• .dff parsing is verified against an independently written RenderWare fixture (npm run test:model): clump/geometry/material/atomic counts, the frame hierarchy (an atomic on a translated child frame is placed at the translated position), frame/dummy names, material texture names, the per-triangle material split, and the texture actually appearing in the rendered pixels.

Approximated (the client rasterises these itself):

• Fonts 0-3 render with system fonts, so the glyph shapes differ slightly; character positions and total line width use the game's own advance tables (matching Leonardo541's TextDrawEditor, which supplies those tables), and a glyph size control tunes the vertical glyph multiplier.
• The box uses the wiki's corner semantics by default; a checkbox switches to the "box hugs the text" model of that editor (4 unit margin, height from the line count) for comparison.
• The font 5 renderer is a software rasteriser, not the game's renderer: the camera is a 3/4 orbit with a fixed field of view (the client's exact preview camera is internal), lighting approximates the game's key/fill setup, and skinned/bone-animated geometry is drawn in its bind pose. Colours, alpha, texture addressing and the model's own geometry are exact.
• Material colour bytes are read as r, g, b, a (the documented RenderWare order); vehicle body markers (alpha ≤ 3) only take effect when vehCol is supplied.

Credit: the glyph advance tables and several client behaviours above were read out of Leonardo541/TextDrawEditor (MIT); samp-mcp also imports its project .json exports through textdraw_import.

Validation is authoritative: it encodes the real client limits (fonts that never render, y < 1 hiding the first row, trailing-space text rendering blank, empty text crashing older servers, the 800-character limit, selectable without a text size, the 2048/256 textdraw limits). Textdraws whose text is deliberately blank filler (a clickable slot, for example) are not flagged, and a sprite that resolves through a design-time image is reported as information rather than a missing texture.

Validation runs on every list/preview/export: font values that never render, malformed sprite references, missing textures, text beyond the client string limit, off-grid positions, selectable textdraws without a text size, duplicate variable names and the 2048/256 textdraw limits.

Module-aware design

For projects that organize code as system modules (e.g. gamemodes/includes/system/*.inc — the system-module pattern), samp-mcp auto-detects the architecture and aligns its tooling with it:

• get_coding_standards reports the module layout (count, categories, StartProgress, message macros, dialog & command conventions).
• generate_boilerplate (type=module|job|autofarm) emits a complete, self-contained module skeleton matching the project's own conventions (y_hooks, hook OnGameModeInit/..., StartProgress, ErrorMsg/ServerMsg/SyntaxMsg, CMD: + flags:), instead of generic snippets.
• design_feature plans propose a concrete module file (system/<name>.inc or system/job/j_<name>.inc) plus its #include registration in main.pwn, and guide implementation through the module's hooks.
• Built-in rules tell agents to put new features in modules — never gameplay logic in main.pwn or filterscripts.
• study_project self-analyzes whatever gamemode it connects to (include graph, libraries, command/dialog/message/state conventions, timer/MySQL/loop patterns) and writes a per-project SAMP_STUDY.md with verbatim idioms — so any environment gets docs that match its actual script.

Quick Start

1. Configure MCP Client

Add the following to your MCP client configuration (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "samp-mcp": {
      "command": "npx",
      "args": ["-y", "samp-mcp"]
    }
  }
}

2. Connect to Project

Once initialized, tell the AI agent:
"Connect to my SAMP server at C:\path\to\server" (samp-mcp: set_server_root)

3. File Handling

samp-mcp exposes file_* tools (file_read, file_write, file_edit, file_grep, …)
that delegate to the encoding-aware mcp-file-tools server — it auto-detects and
preserves Windows-874 (Thai) and CRLF, so .pwn/.inc text never gets garbled.
(You can also configure mcp-file-tools directly as a separate MCP server — samp-mcp
works either way.)

To update or install the mcp-file-tools binary itself, run update_file_tools:
it downloads the latest GitHub release for your platform and replaces the installed
binary, keeping a backup of the previous version (<binary>.v<old>.bak).

4. Initialize AI Agent

Copy and paste this as your first prompt to the AI:

"SAMP Project. Read SAMP_RULES.md and follow the encoding rules. Run set_server_root to connect samp-mcp."

Tool Categories

Server Management

File Access (encoding-safe, via mcp-file-tools)

Pawn Intelligence

Plugin & Include Management

Web & Info

Auditing & Diagnostics

Automation

Textdraw Editor

Meta

Features

• SAMP Server Operations — query (status/players/rules/dashboard), RCON, player actions, process management
• Pawn Intelligence — pawncc compile with structured errors, audits (SQL / performance / shadowing), include checks, log diagnostics
• Encoding-Safe File Access — built-in file_read/file_write/file_edit/file_grep/… tools delegate to mcp-file-tools, which auto-detects Windows-874 (Thai) and preserves CRLF
• Textdraw Editor — textdraw projects (JSON), txd sprite decoding, DFF model rendering (loose .dff/.txd, .img archives), web preview page + live drag-and-save editor with model orbiting, Pawn import/export
• Plugin Auto-Install — GitHub release discovery with ZIP auto-extraction
• Web Search — DuckDuckGo integration for SAMP-related queries
• Caching — Project info cached for 5 minutes to reduce token usage
• AI-Powered — Designed for seamless integration with LLMs

Development

npm install        # includes dev tooling (eslint, typescript-eslint, ts-prune)
npm run check      # lint + dead-code checks + build + model/textdraw tests (also runs before publish)

Smoke test / demo of the textdraw editor (writes a throwaway project + synthetic .txd under .freebuff/textdraw-demo):

npm run demo:textdraw

Smoke test of the model pipeline (builds a cube .dff/.txd/.img from the RenderWare spec, then parses, renders, exports and previews it — 33 checks, under .freebuff/model-demo):

npm run test:model

End-to-end test of the textdraw MCP tools — it starts the real stdio server and calls all nine tools the way an agent does, so tool names, argument schemas and result shapes are covered too (part of npm run check):

npm run test:textdraw

Individual gates:

Releasing

npm publish runs npm run check first (prepublishOnly), so a red gate blocks the release.
.github/workflows/publish.yml publishes to GitHub Packages on any of these triggers:

npm version 1.2.1 --no-git-tag-version && git commit -am "chore: release v1.2.1"
git push origin main
git tag v1.2.1 && git push origin v1.2.1   # tag push -> workflow publishes

Publishing a GitHub Release, or running the workflow manually (workflow_dispatch), does the same thing.

License

MIT © Watcharapong Namsaeng