convez.ai
MCP ServerIntegração & APIsAvançado
AmyJeanes

GMod MCP Server

AmyJeanes/GMod-MCP-Server

Execute Lua e inspecione Garry's Mod via assistente de IA

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor Model Context Protocol que conecta um assistente de IA a uma sessão viva de Garry's Mod, permitindo executar Lua e inspecionar estado do jogo em tempo real. Usa IPC baseado em arquivos para contornar limitações de rede do GMod, sem necessidade de módulos binários.

Instalação

$npx convez-ai AmyJeanes/GMod-MCP-Server

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 5 dias
Versão
—
Issues abertas
2
Contribuidores
2

Casos de uso

  • Desenvolvimento de addons Garry's Mod com IA assistente
  • Debugging e prototipagem em tempo real de scripts Lua
  • Automação de tasks repetitivas dentro do jogo via comandos do assistente

Veredito

Ferramenta especializada e bem-arquitetada para desenvolvedores de Garry's Mod que querem potencializar o workflow com IA, resolvendo problema real de comunicação entre assistentes e game runtime. Exige conhecimento técnico robusto de MCP, C# e Lua.

README

A tradução para o português deste README ainda está na fila.

GMod MCP Server

A Model Context Protocol (MCP) bridge between an AI coding assistant and a running Garry's Mod session. Lets the assistant invoke tools (e.g. run Lua, inspect state) inside the live game, instead of relying on static analysis and copy-pasted console output.

The repo is the GMod addon: clone it directly into garrysmod/addons/. The .NET MCP server lives in server/ and is ignored by the GMod engine.

Quick start

  1. Install the addon
    cd garrysmod/addons
    git clone https://github.com/AmyJeanes/GMod-MCP-Server.git
    
  2. Build the MCP server
    cd GMod-MCP-Server/server/GModMcpServer
    dotnet build
    
  3. Register the MCP server with your client (e.g. Claude Code):
    claude mcp add gmod -- dotnet run --project /absolute/path/to/server/GModMcpServer
    
  4. Have the assistant launch GMod via the host_launch tool, or start GMod yourself. The bridge polls regardless of consent, but tool dispatch requires opting in via convars in the GMod developer console:
    mcp_enable 1
    mcp_allow_unsafe 1
    
    These are FCVAR_ARCHIVE, so once set they persist across game restarts — as long as GMod is shut down cleanly. It writes these to cfg/server.vdf only on a clean window-close, never on a kill, so host_close does a clean shutdown by default (force: true skips it and loses grants set that session). host_launch waits until both the server and client realms are ready before returning, and on Windows — if a background launch leaves GMod's window holding your mouse (a GMod/SDL startup-focus bug) — it detects and releases the cursor with a brief focus flicker (opt out with fix_focus: false).
  5. Verify: mcp__gmod__lua_run_sv and mcp__gmod__lua_run_cl (game-side, dispatched through the file bridge) plus mcp__gmod__host_launch, host_close, host_status (host-side, run by the .NET process) should appear in your assistant's tool list. host_status will report bridge.reachable: true once GMod is running and responsive.

How it works

GMod cannot run a listening socket from pure Lua, and http.Fetch/HTTP() block private-IP destinations on listen and singleplayer servers. This addon uses file-based IPC via garrysmod/data/mcp/ — the server-realm and client-realm bridges run independent poll loops, the .NET host polls the response files, and big payloads (future: screenshots) never traverse net.WriteString. No binary modules required.

Each .NET MCP host generates a per-process session GUID and prefixes its request IDs with it, so multiple MCP clients (Claude Code + MCP Inspector + …) can share the same GMod instance without stealing each other's responses.

See docs/protocol.md for the wire format.

Console & error capture

Output and errors that happen during a tool call are already returned on that call's response (console / warnings). Anything that fires outside a tool call — a hook the assistant registered firing later, a timer, an autorefresh re-run, another addon erroring — would otherwise be invisible. Passive capture records these into a small per-realm ring buffer and surfaces them to the model two ways, both over the existing bridge (MCP has no way to push unsolicited messages into the model's context, so there's no notification channel — it rides tool results):

  • Attached to the next tool response as an events array (per-session cursor, so it isn't re-sent).
  • On demand via the console_read_sv / console_read_cl tools (pass back the returned cursor as since to get only newer events).

It's realm-local — _sv shows server-side errors/prints, _cl shows client-side. Controlled by mcp_capture (only active while mcp_enable is 1):

mcp_capture 2   # default: Lua errors + console (print/Msg)
mcp_capture 1   # Lua errors only
mcp_capture 0   # off

Adding tools

Drop a Lua file in lua/mcp/functions/ with the conventional sh_/cl_/sv_ prefix. The realm is implicit from the prefix, and the framework appends _sv/_cl to the MCP tool name automatically:

MCP:AddFunction({
    id = "list_players",
    description = "List all connected players.",
    schema = { type = "object", properties = {}, required = {} },
    handler = function(args, ctx)
        local names = {}
        for _, ply in ipairs(player.GetAll()) do
            names[#names + 1] = ply:Nick()
        end
        return { ok = true, result = names }
    end,
})

Saving the file is enough — GMod's autorefresh re-runs it, the registry replaces the existing entry, and a debounced manifest write (100 ms) propagates the change to the .NET host, which emits notifications/tools/list_changed. mcp_reload is still available in the GMod console for forced rebuilds (e.g. when a tool file has been deleted, since autorefresh has nothing to fire on for removals).

Capabilities (security gating)

Sensitive tools declare a requires list. The capability ships with an auto-derived convar (mcp_allow_<id>) that defaults to off:

MCP:AddCapability({
    id = "unsafe",
    description = "Arbitrary code execution (Lua + console) — effectively full control.",
    default = false,
})

MCP:AddFunction({
    id = "lua_run",
    requires = { "unsafe" },
    -- ...
})

The bridge refuses dispatch when any required capability is off, so a buggy or compromised handler cannot bypass the gate.

License

MIT — see LICENSE.

Ver o original no GitHub

Bom para

Relacionados