mcp-garry-codes — The Principal Garry's Mod Protocol Server

mcp-garry-codes is a specialized, production-grade Model Context Protocol (MCP) server engineered specifically for the Garry's Mod (GLua) ecosystem. It bridges AI coding agents with deep Source Engine awareness, static verification, net-security vulnerability auditing, zero-GC performance profiling, and headless testing.

Created & Maintained by: M A R W A N

⚡ The Garry's Mod Engineering Dilemma

Garry's Mod development represents a notoriously hostile coding environment:

• Three Rigid Execution Realms (SERVER, CLIENT, and MENU) with strict serialization and transmission rules.
• Micro-Allocation Garbage Collection Traps inside high-frequency rendering and simulation hooks (RenderScreenspaceEffects, HUDPaint, Think, Move) triggering severe client FPS drops.
• Pervasive Network Vulnerabilities stemming from unvalidated client-authoritative net messages, rate-limit exploitation, SQL injections, and command execution backdoors.
• Source Engine VGUI & Prediction Peculiarities where standard desktop GUI mental models fail.

mcp-garry-codes equips LLMs and autonomous coding assistants with the deep domain knowledge and verification tools necessary to produce bulletproof GLua code.

🛠️ Tool Suite (9 Core Tools)

| Tool Name | Realm Mode | Primary Function | Side Effects | |---|---|---|---| | search_gmod_wiki | Read-only | Query Facepunch Garry's Mod Wiki and indexed documentation filtered by realm and category. | Cached disk/memory | | get_gmod_symbol | Read-only | Retrieve exact parameter signatures, return values, caveats, and official examples. | Cached | | web_search_glua | Read-only | Targeted search across GitHub GLua repositories, Facepunch archives, and developer discussions. | HTTPS query | | lint_glua | Read-only / Pure | Static analysis parsing GMod C-style syntax (//, /* */, &&, ||, !=), realm mismatches, and global pollution. | None | | audit_net_security | Read-only / Audit | Scan addon message graphs for unauthenticated receivers, SQL injections, and missing util.AddNetworkString. | None | | analyze_performance | Read-only / Audit | Profile GLua code for Zero-GC hot-path violations (allocations in HUDPaint, Think, uncached fonts). | None | | scaffold_gmod_component | Creation | Scaffold idiomatic SWEPs, SENTs, NextBots, STOOLs, VGUI panels, HUDs, Effects, DarkRP modules, or gamemodes. | File creation (Workspace only) | | run_glua_test | Execution / Sandbox | Run headless GLua unit tests using the embedded Source Engine mock runtime via LuaJIT / Python. | Sandboxed subprocess | | package_and_validate | Verification / Build | Validate addon.json and verify file structures against Steam Workshop & GMA packaging rules. | Optional .gma compilation |

📦 Addressable MCP Resources

Connect to rich contextual resources using standard MCP URIs:

• gmod://wiki/hooks — Authoritative list of Garry's Mod hooks across all realms.
• gmod://wiki/libraries — Core functions and libraries available in GLua.
• gmod://realms/matrix — Execution realm boundaries, powers, and restrictions.
• gmod://schemas/addon_json — Steam Workshop addon.json schema specification.

🧭 Guided Workflow Prompts

• audit_addon — Comprehensive security and performance review of an addon folder.
• fix_net_exploit — Guided repair workflow for net message vulnerabilities and authorization checks.
• scaffold_swep — Interactive creation of a predicted, zero-latency weapon.
• build_derma_menu — Responsive, DPI-scaled VGUI Derma interface builder.
• scaffold_nextbot — Autonomous NextBot AI entity with navigation coroutines.
• scaffold_toolgun_stool — Production Toolgun STOOL with CPanel convars, left/right clicks, and language strings.
• scaffold_darkrp_module — Modular DarkRP package with custom jobs, shipments, categories, and hooks.
• scaffold_effect — Custom 3D particle and billboard render effect.
• optimize_zero_gc — Profile and optimize rendering hooks for zero garbage-collection stutter.

🚀 Quick Start & Installation

Option 1: Run instantly with npx (Recommended)

npx -y mcp-garry-codes

Option 2: Global installation via npm

npm install -g mcp-garry-codes
mcp-garry-codes

💻 Client Configuration

1. Antigravity IDE & Cursor (mcp_config.json)

Add the server definition to your mcp_config.json:

{
  "mcpServers": {
    "mcp-garry-codes": {
      "command": "npx",
      "args": ["-y", "mcp-garry-codes"],
      "env": {
        "WORKSPACE_ROOT": "${workspaceFolder}",
        "PYTHON_PATH": "python"
      }
    }
  }
}

2. Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "garrys-mod": {
      "command": "npx",
      "args": ["-y", "mcp-garry-codes"]
    }
  }
}

🛡️ Security Architecture & Threat Model

1. Workspace Path Jail: All file queries, linter checks, and scaffolding operations are verified with PathGuard and strictly quarantined within the user's configured workspace.
2. Subprocess Isolation: External processes (python, glualint, luajit) execute via child_process.execFile with explicit argument arrays—no shell interpolation (shell: false) and strict execution timeouts (5,000ms default).
3. Automated Credential Redaction: Result envelopes pass through sanitization regexes that scrub Steam API keys, MySQL connection strings, and RCON passwords.
4. Net Message Auditing: Receivers executing mutations without checking ply:IsAdmin() or access privileges are flagged as critical vulnerabilities.

🧪 Headless GLua Simulation Engine

mcp-garry-codes includes an embedded Source Engine mock runtime (src/test_harness/lua/glua_mock.lua) and Python test orchestrator (src/test_harness/python/gmod_tester.py). It enables running headless unit tests without launching the Garry's Mod 32-bit or 64-bit client executable:

• Full 3D Vector and Angle metatables (Distance, Dot, Cross, Length2D, RotateAroundAxis).
• Mock Entity and Player objects with health, inventory, and trace methods.
• In-memory FIFO bitstream queue verifying net.Write* and net.Read* alignment.
• Event bus verifying hook.Add and hook.Run.

📄 License

This project is licensed under the MIT License.

Author: M A R W A N