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

[![npm version](https://img.shields.io/npm/v/mcp-garry-codes.svg?style=flat-square&color=blue)](https://www.npmjs.com/package/mcp-garry-codes)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Standard-purple?style=flat-square)](https://modelcontextprotocol.io)
[![Author](https://img.shields.io/badge/Author-M%20A%20R%20W%20A%20N-success?style=flat-square)](https://github.com/MarwanDevSpace)

> **`mcp-garry-codes`** is a specialized, production-grade [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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)
```bash
npx -y mcp-garry-codes
```

### Option 2: Global installation via `npm`
```bash
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`:
```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`)
```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](LICENSE).

**Author:** [M A R W A N](https://github.com/MarwanDevSpace)