# Eigene Tools — Godot · AI Game Developer Wiki

Eigene Godot-MCP-Tools in C# schreiben, API-Aufrufe im Main Thread ausführen und Tools, Prompts und Ressourcen im laufenden Spiel bereitstellen.

Diese Seite wurde maschinell aus dem Englischen übersetzt. [Englisches Original lesen](https://ai-game.dev/docs/wiki/godot/custom-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.

```csharp
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](https://ai-game.dev/de/docs/wiki/godot/tools#rql).

## 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:

```csharp
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

| Aufruf | Was er bewirkt |
| --- | --- |
| `WithConfig(...)` | Legt `Host`, `Token`, `ConnectionMode` und `AuthOption` im Code fest. |
| `WithToolsFromAssembly(...)` / `WithTools(...)` | Registriert `[AiToolType]`-Klassen aus einer Assembly oder bestimmte Typen. |
| `WithPromptsFromAssembly(...)` / `WithPrompts(...)` | Registriert Prompt-Klassen mit `[AiPromptType]`. |
| `WithResourcesFromAssembly(...)` / `WithResources(...)` | Registriert Ressourcen-Klassen mit `[AiResourceType]`. |
| `WithRuntimeErrorCapture()` | Zeichnet Fehler im Spiel auf und registriert `runtime-errors-get` / `runtime-errors-clear`. Standardmäßig aus. |
| `WithScriptExecute()` | Registriert `script-execute` im Spiel. Standardmäßig aus; erfordert ein Opt-in in der `.csproj`. |
| `ConnectWhenRunFromEditor()` | Verbindet sich auch, wenn das Spiel über Play im Editor gestartet wird. Standardmäßig aus. |
| `WithoutMainThreadDispatcher()` | Überspringt den automatischen Main-Thread-Dispatcher (nur wenn du einen eigenen installierst). |

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:

```xml
<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.

**Warnung**

`script-execute` im Spiel bedeutet beliebige Codeausführung, und die Erfassung von Laufzeitfehlern überträgt vollständige Meldungen und Stacktraces, die Pfade, Benutzernamen oder Geheimnisse enthalten können. Verwende beides nur in Entwicklungs-Builds, auf einem Loopback-Host mit einem echten Token, und liefere sie niemals aktiviert in einem öffentlichen Release aus.

## 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](https://ai-game.dev/de/docs/wiki/godot/tools); zu gebündelten Tool-Sets siehe [Extensions](https://ai-game.dev/de/docs/wiki/godot/extensions).

---

Source (HTML): https://ai-game.dev/de/docs/wiki/godot/custom-tools

Machine-translated (de) from the English page: https://ai-game.dev/docs/wiki/godot/custom-tools