Eigene Tools

Du kannst eigene MCP-Tools in reinem C# innerhalb deines Projekts zu Godot MCP hinzufügen. Ein eigenes Tool ist eine Methode, die der AI-Agent aufrufen kann, mit einer Beschreibung, die dem Modell sagt, was es tut. Diese Seite behandelt Editor-Tools, die Main-Thread-Regel und die optionale Runtime, mit der ein Agent mit einem laufenden Spiel kommunizieren kann.

Ein Editor-Tool schreiben#

Eine Tool-Familie ist eine partial class, die mit [AiToolType] markiert ist. Jedes Tool ist eine Methode, die mit [AiTool("tool-name")] markiert ist, mit einer [Description] an der Methode und an jedem Parameter, damit das Modell weiß, wann und wie es sie aufrufen soll.

using System.ComponentModel;
using com.IvanMurzak.McpPlugin;           // [AiToolType], [AiTool]
using com.IvanMurzak.ReflectorNet.Utils;  // MainThread

[AiToolType]
public partial class Tool_MyFeature
{
    [AiTool("my-custom-task", Title = "Do a custom task")]
    [Description("Explain to the LLM what this does and when to call it.")]
    public string CustomTask
    (
        [Description("Explain to the LLM what this parameter is.")]
        string inputData
    )
    {
        // Work that does not touch the Godot API can run here, on a background thread.

        return MainThread.Instance.Run(() =>
        {
            // Touch EditorInterface, Node or Resource here, on the main thread.
            return "[Success] Operation completed.";
        });
    }
}

Baue das C#-Projekt (über die Schaltfläche Build im Editor, godot-cli build oder indem du den Agenten bittest, script-build auszuführen). Godot lädt die Assembly neu, das Addon verbindet sich erneut, und das neue Tool erscheint in der Tool-Liste des Agenten und im Fenster Tools des Docks.

Regeln für zuverlässige Tools#

• Godot-Objekte nur im Main Thread. Tool-Methoden werden außerhalb des Main Threads aufgerufen. Jeder Aufruf auf Node, Resource, SceneTree oder EditorInterface muss über MainThread.Instance.Run(...) laufen. Greift man aus dem Hintergrund-Thread darauf zu, kann der Editor abstürzen.
• Daten zurückgeben, keinen formatierten Text. Gib eine Klasse mit Eigenschaften zurück (sie wird für das Modell serialisiert) oder void für Tools, die nur Nebenwirkungen haben. Vermeide handgebaute Strings für alles, was der Agent parsen muss.
• Optionale Parameter kennzeichnen. Verwende einen nullbaren Typ mit Standardwert, zum Beispiel string? filter = null, und das Modell behandelt den Parameter als optional.
• Alles beschreiben. Die Beschreibungen sind das, was das Modell liest. Sag, was das Tool tut, wann man es verwendet und was jeder Parameter bedeutet.
• Editor-only-Code hinter #if TOOLS. Code, der Editor-APIs verwendet, darf nicht in ein exportiertes Spiel kompiliert werden.

Hinweise und Ziele#

[AiTool] akzeptiert optionale Hinweise wie ReadOnlyHint = true und IdempotentHint = true, die den Clients mitteilen, dass das Tool nichts verändert oder gefahrlos wiederholt werden kann. Ein Target entscheidet, wo ein Tool registriert wird: ToolTarget.Editor (nur Editor), ToolTarget.Runtime (nur Spiel) oder der Standard, beides.

Den Agenten das Tool schreiben lassen#

Das System-Tool godot-skill-create schreibt eine neue C#-Tool-Datei in dein Projekt; das Tool ist nach dem nächsten Build aufrufbar. Prüfe vor dem Schreiben eines neuen Tools, ob RQL die Aufgabe bereits abdeckt: Der meiste Editor-Datenzugriff (Nodes, Ressourcen, Dateien, Projekteinstellungen) ist nur einen rql-query oder rql-mutate entfernt. Siehe Tools.

Tools in einem laufenden Spiel#

Godot MCP kann auch in einem laufenden oder exportierten Spiel laufen, in Debug oder Release. So kann ein Agent den Live-Spielzustand lesen und steuern, zum Beispiel ein Schachspiel, dessen Bot-Züge von einem LLM stammen. Zwei Dinge sind bewusst so gestaltet:

• Es verbindet sich nie von selbst. Dein Code entscheidet, ob und wann Connect() aufgerufen wird.
• Standardmäßig wird nichts bereitgestellt. Du registrierst jedes Tool, jeden Prompt und jede Ressource selbst. Die Editor-Tools des Addons werden nicht in einen Spiel-Build kompiliert.

Starte es, sobald ein SceneTree existiert, zum Beispiel in _Ready() eines Autoloads:

using System.Reflection;
using com.IvanMurzak.Godot.MCP.Connection;
using com.IvanMurzak.Godot.MCP.Runtime;
using McpServerConsts = com.IvanMurzak.McpPlugin.Common.Consts.MCP.Server;
using Godot;

public partial class GameMcp : Node
{
    private GodotMcpRuntimeHandle? _mcp;

    public override async void _Ready()
    {
        _mcp = GodotMcpRuntime.Initialize(builder =>
        {
            builder.WithConfig(config =>
            {
                config.ConnectionMode = GodotMcpConnectionMode.Custom;
                config.Host = "http://localhost:8080";
                config.AuthOption = McpServerConsts.AuthOption.token;
                config.Token = "your-secret-token";
            });
            builder.WithToolsFromAssembly(Assembly.GetExecutingAssembly());
        }).Build();

        await _mcp.Connect();
    }

    public override async void _ExitTree()
    {
        if (_mcp is not null)
            await _mcp.Disconnect();
    }
}

Markiere reine Spiel-Tool-Klassen mit [AiToolType(Target = ToolTarget.Runtime)] (aus com.IvanMurzak.McpPlugin.Common), damit der Editor sie nicht registriert und der Agent das Spiel auch dann erreicht, wenn der Editor verbunden ist.

Builder-Optionen#

Host und Token können auch aus GODOT_MCP_*-Umgebungsvariablen oder einer .env-Datei stammen, die Vorrang vor dem Code haben. Ein Spiel liest nie die gespeicherten Einstellungen des Editors.

Prompts und Ressourcen#

Neben Tools kann ein Spiel auch MCP-Prompts (benannte Anweisungsvorlagen, [AiPromptType] mit [AiPrompt]-Methoden) und Ressourcen (schreibgeschützte Inhalte, die per URI abgerufen werden, [AiResourceType] mit [AiResource]-Methoden) bereitstellen. Jede Art ist optional und wird genauso registriert wie Tools.

C# im Spiel ausführen#

Damit der Agent C# im Spiel ausführen kann, musst du es in der .csproj des Spiels aktivieren und WithScriptExecute() aufrufen:

<PropertyGroup>
  <GodotMcpCodeExecInGame>true</GodotMcpCodeExecInGame>
  <DefineConstants>$(DefineConstants);GODOT_MCP_CODE_EXEC_IN_GAME</DefineConstants>
</PropertyGroup>

Das funktioniert nur bei Desktop-CoreCLR-Builds, nicht mit NativeAOT oder iOS.

Sicherheits-Checkliste für Spiel-Builds#

• Bevorzuge den Custom-Modus auf localhost oder 127.0.0.1 mit AuthOption.token und einem echten Token.
• Registriere nur die Tools, die du brauchst; die Angriffsfläche besteht genau aus den Tools, die du registrierst.
• Stelle die Verbindung in einem Release-Build nicht über eine öffentliche Netzwerkschnittstelle bereit, es sei denn, du hast sie dafür entworfen und abgesichert.

Die vollständige Tool-Liste findest du unter Tools; zu gebündelten Tool-Sets siehe Extensions.