Godotmcpplugin

Godot MCP SK插件

  

 ](https://www.nuget.org/packages/GodotMcp.SemanticKernel.Plugin)


A.NET 10语义内核插件，将SK代理/应用程序连接到 GodotMCP.Server 1.2+ （包括当前版本中的较新工具表面，如相机设置）。NET全局工具 godot-mcp，使用官方 模型上下文协议 基于stdio的.NET SDK(initialize, tools/list, tools/call)并将Godot自动化工具作为内核函数动态公开。

主要特点

建筑

• GodotMcp.Core：接口、模型、异常。
• GodotMcp.Infrastructure：stdio客户端、进程管理器、序列化、转换、选项。
• GodotMcp.Plugin：语义内核集成、函数映射、DI扩展。
• GodotMcp.Tests：基于单元/集成/属性的测试。

快速开始

var builder = Host.CreateApplicationBuilder(args);
builder.Services.AddGodotMcp(options =>
{
    options.ExecutablePath = "godot-mcp";
    options.GodotExecutablePath = Environment.GetEnvironmentVariable("GODOT_PATH");
});

using var host = builder.Build();
var plugin = host.Services.GetRequiredService();
await plugin.InitializeAsync();

var result = await plugin.InvokeToolAsync(
    "create_scene",
    new Dictionary
    {
        ["projectPath"] = @"C:\GodotProjects\MyGame",
        ["fileName"] = "Main.tscn",
        ["rootNodeName"] = "Main",
        ["root_type"] = "Node2D"
    });

SK注册模式

• 扩展模式（推荐）： kernel.RegisterGodotTools(host.Services, "godot")

- 将每个发现的方法注册为单独的函数，如 godot_create_scene.

• 路由器模式： kernel.Plugins.AddFromObject(plugin, "godot")

- 暴露单个 invoke_godot_tool(toolName, parameters) 功能。

配置

appsettings.json:

{
  "GodotMcp": {
    "ExecutablePath": "godot-mcp",
    "GodotExecutablePath": null,
    "ConnectionTimeoutSeconds": 30,
    "RequestTimeoutSeconds": 60,
    "MaxRetryAttempts": 3,
    "BackoffStrategy": "Exponential",
    "InitialRetryDelayMs": 1000,
    "EnableProcessPooling": true,
    "MaxIdleTimeSeconds": 300,
    "ToolDefinitionsPath": null,
    "EnableMessageLogging": false
  }
}

环境覆盖：

• GODOT_MCP_PATH：覆盖MCP服务器的可执行路径。
• GODOT_PATH：服务器CLI支持的工具使用的Godot二进制路径。

当前GD工具表面

此插件支持本地数据的完全动态发现和调用 GD_MCP-Server 工具跨越：

• 核心和诊断
• 项目
• 场景和节点
• 脚本
• 资源和进口
• 编辑器/导出自动化
• 集成发现和健康工具

详细参考： Docs/tool-contracts.md.

类型化模块包装和技能

除了动态发现之外，该插件还公开了用于常见工作流的强类型模块包装器（基础设施）和语义内核技能方法（插件）。

项目模块：

• create_godot_project
• get_project_info
• configure_autoload
• add_plugin

UI模块(ui.*):

• ui.list_controls
• ui.add_control （支持回退 ui.create_control)
• ui.set_control_properties （支持回退 ui.update_control)
• ui.set_layout_preset （支持回退 ui.apply_layout_preset)
• ui.list_themes
• ui.apply_theme

照明模块(light.*):

• light.list
• light.create
• light.update
• light.tune
• light.validate

脚本模块：

• create_script
• attach_script
• validate_script

导入模块：

• generate_import_file
• create_texture
• create_audio
• reimport_asset

Lint模块(lint.* +兼容性）：

• lint.scene_advanced
• lint.project_advanced
• lint_project （通过兼容性包装）

物理模块(physics.*):

• physics.list_bodies
• physics.create_body
• physics.update_body
• physics.list_shapes
• physics.create_shape
• physics.update_shape
• physics.set_layers
• physics.run_checks
• physics.validate

摄像头模块(camera.*):

• camera.list
• camera.create
• camera.update
• camera.validate

文档模块(docs.*):

• query_system_documentation --搜索此存储库的DocFX输出(_site/manifest.json)和/或Markdown下 docs/ （参数与Godot MCP服务器工具相同）。
• query_godot_engine_documentation --通过阅读文档（HTTPS至 docs.godotengine.org；需要MCP服务器上的出站网络）。

本地系统文档： 服务器需要 docs/docfx.json 在Godot MCP git仓库中。对于清单搜索，首先构建网站（例如 dotnet docfx docs/docfx.json)，生产 _site/manifest.json.如果 godot-mcp 作为仓库外的全局工具运行，set GODOT_MCP_REPO_ROOT 到存储库根目录（包含以下内容的文件夹 docs/docfx.json)因此服务器可以解析路径。

Godot引擎文档： 在MCP服务器可以访问的任何机器上工作 https://docs.godotengine.org （阅读文档JSON API）。

键入结果使用 GodotMcpDocumentationToolResult 在C#中，映射MCP字段 success, message，可选 suggestedRemediation，以及用于代理中可靠解析的结构化有效载荷数据。

这些类型化表面是可添加的：如果服务器不公开给定的命令，动态发现仍然会提供权威的运行时列表。

类型化模块快速示例

var mcpClient = host.Services.GetRequiredService();
const string projectRoot = @"C:\GodotProjects\MyGame";

// UI: apply a theme to a control
var uiTheme = await mcpClient.UiApplyThemeAsync(
  new UiApplyThemeRequest(new McpProjectFile(projectRoot, "scenes/ui.tscn"), "./RootPanel", "dark_flat"));

// Lighting: tune an existing light
var tunedLight = await mcpClient.LightTuneAsync(
  new LightTuneRequest(
    new McpProjectFile(projectRoot, "scenes/main.tscn"),
    "./Sun",
    new Dictionary
    {
      ["energy"] = 2.5,
      ["color"] = new { r = 1.0, g = 0.95, b = 0.85, a = 1.0 }
    }));

// Physics: set layers and run checks
var layerResult = await mcpClient.PhysicsSetLayersAsync(
  new PhysicsSetLayersRequest(new McpProjectFile(projectRoot, "scenes/main.tscn"), "./Player", collisionLayer: 2, collisionMask: 5));

var checks = await mcpClient.PhysicsRunChecksAsync(
  new PhysicsRunChecksRequest(new McpProjectFile(projectRoot, "scenes/main.tscn"), "./Player"));

文档

• Docs/tool-contracts.md
• Docs/godot-cli-setup.md
• Docs/docker-mcp-setup.md
• Docs/testing-guide.md
• Skills/SKILL.md

测试

dotnet test GodotMcp.sln
dotnet test GodotMcp.sln --collect:"XPlat Code Coverage" --settings coverlet.runsettings

配置选项

退缩策略

• 线性：延迟=初始重试延迟毫秒×尝试次数
• 指数：延迟=初始重试延迟毫秒×2^（尝试次数）

可用功能

该插件首先进行发现，并从中映射服务器广告工具 tools/list 在运行时。

最近可用的典型家庭 GD_MCP-Server 构建包括：

• 核心： health_check, get_server_info, get_server_capabilities
• 项目： create_godot_project, get_project_info
• 场景/节点： create_scene, add_node, set_node_property, remove_node
• 脚本/资源： create_script, attach_script, create_resource, reimport_asset
• 类型化模块（由服务器公开时）： ui.*, light.*, physics.*, camera.*

确切的列表取决于连接的服务器版本和安装的集成。使用 ListToolsAsync() 检查权威运行时界面。

高级用法

自定义类型转换器

为特殊类型注册自定义转换器：

var parameterConverter = host.Services.GetRequiredService();

parameterConverter.RegisterConverter(new MyCustomTypeConverter());

public class MyCustomTypeConverter : ITypeConverter
{
    public object? ToMcp(MyCustomType value)
    {
        // Convert to MCP format
        return new { /* ... */ };
    }

    public MyCustomType? FromMcp(object? mcpValue)
    {
        // Convert from MCP format
        return new MyCustomType(/* ... */);
    }
}

错误处理

该插件提供了一个全面的异常层次结构：

try
{
    await plugin.InvokeToolAsync("Godot_create_scene", parameters);
}
catch (TimeoutException ex)
{
    Console.WriteLine($"Request timed out after {ex.Timeout}");
}
catch (McpServerException ex)
{
    Console.WriteLine($"Godot server error: {ex.Message} (Code: {ex.ErrorCode})");
}
catch (NetworkException ex)
{
    Console.WriteLine($"Network error: {ex.Message}");
}
catch (ProtocolException ex)
{
    Console.WriteLine($"Protocol violation: {ex.Message}");
}
catch (GodotMcpException ex)
{
    Console.WriteLine($"General error: {ex.Message}");
}

健康监测

检查连接健康状况：

var mcpClient = host.Services.GetRequiredService();

bool isHealthy = await mcpClient.PingAsync();
Console.WriteLine($"Connection healthy: {isHealthy}");

var state = mcpClient.State;
Console.WriteLine($"Connection state: {state}");

优雅降级

使用预定义的工具定义作为后备：

{
  "GodotMcp": {
    "ToolDefinitionsPath": "Godot-tools.json"
  }
}

创建 Godot-tools.json:

[
  {
    "name": "Godot_create_scene",
    "description": "Creates a new Godot scene",
    "parameters": {
      "sceneName": {
        "name": "sceneName",
        "type": "string",
        "description": "Name of the scene",
        "required": true
      }
    }
  }
]

项目结构

Godot-MCP-SK-Plugin/
├── src/
│   ├── GodotMcp.Core/              # Domain models, interfaces, and exceptions
│   │   ├── Interfaces/             # Core abstractions (IMcpClient, IParameterConverter, etc.)
│   │   ├── Models/                 # DTOs and domain models (McpRequest, McpResponse, etc.)
│   │   ├── Exceptions/             # Custom exception types
│   │   └── Utilities/              # Helper utilities (LogSanitizer)
│   ├── GodotMcp.Infrastructure/    # MCP client and process management
│   │   ├── Client/                 # StdioMcpClient implementation
│   │   ├── Process/                # ProcessManager for godot-mcp lifecycle
│   │   ├── Serialization/          # JSON-RPC request/response handling
│   │   ├── Conversion/             # Parameter type conversion
│   │   └── Configuration/          # Configuration options and validation
│   └── GodotMcp.Plugin/            # Semantic Kernel integration
│       ├── Mapping/                # FunctionMapper for tool discovery
│       ├── Extensions/             # ServiceCollectionExtensions for DI
│       ├── Validation/             # Input validation
│       └── GodotPlugin.cs          # Main plugin class
└── tests/
    └── GodotMcp.Tests/             # Unit and integration tests
        ├── CoreTests/              # Core layer tests
        ├── InfrastructureTests/    # Infrastructure layer tests
        └── PluginTests/            # Plugin layer tests

技术栈

• .NET 10 （2026 LTS）-最新的长期支持版本
• C#13 -文件范围的命名空间、集合表达式、必需成员
• 微软。语义内核 -AI代理框架集成
• 系统。文本。JSON -使用源代码生成器进行高性能JSON序列化
• x单位 -单元测试框架
• N替代品 -模拟测试框架
• FsCheck -基于属性的测试库

安全

该插件实现了全面的安全措施：

安全日志

所有日志记录操作都会自动清理敏感信息：

• 密码和令牌：从未以纯文本方式登录
• API密钥：从日志中自动编辑
• 电子邮件地址：替换为 [EMAIL_REDACTED]
• JWT代币：检测到并编辑（eyJ…格式）
• 持有者代币：已从授权标头中删除
• 连接串：密码字段已编辑

这 LogSanitizer 该实用程序提供敏感数据模式的自动检测和编辑。

输入验证

所有参数在发送到godot mcp服务器之前都经过验证：

• 根据注册的工具验证工具名称
• 检查参数类型的兼容性
• 适当处理空值
• 防止注入攻击和格式错误的请求

错误消息清理

对错误消息进行净化，以防止有关内部系统详细信息的信息泄露，同时保留有用的诊断信息。

演出

该插件针对高性能进行了优化：

• 系统。文本。Json-源生成器：零反射序列化
• 弗罗森词典：工具定义的不可变、高性能查找
• PipeReader/PipeWriter：高效的stdio通信
• ValueTask：减少了热路径的分配
• 记录器消息源生成器：零分配结构化日志记录
• 进程池：跨请求重用godot-mcp流程

贡献

欢迎投稿！请遵循以下指南：

开发设置

1. 克隆存储库
2. 安装。净10 SDK
3. 安装godot-mcp服务器： dotnet tool install -g godot-mcp
4. 恢复依赖关系： dotnet restore
5. 构建解决方案： dotnet build
6. 运行测试： dotnet test

代码的风格

• 遵循干净的架构原则
• 使用文件范围的命名空间
• 启用可为null的引用类型
• 使用集合表达式进行初始化
• 向所有公共API添加XML文档注释
• 为所有新功能编写单元测试
• 保持80%以上的代码覆盖率

拉取请求流程

1. 从以下位置创建要素分支 main
2. 通过测试实现您的更改
3. 确保所有测试通过： dotnet test
4. 根据需要更新文档
5. 提交一个带有明确描述的拉取请求

测试指南

• 编写单元测试和基于属性的测试
• 使用NSreplace来模拟依赖关系
• 测试错误处理和边缘情况
• 验证并发场景的线程安全性
• 包括端到端流的集成测试

建造和测试

构建

# Build entire solution
dotnet build GodotMcp.sln

# Build specific project
dotnet build src/GodotMcp.Plugin/GodotMcp.Plugin.csproj

# Build in Release mode
dotnet build -c Release

测试

# Run all tests
dotnet test GodotMcp.sln

# Run tests with coverage
dotnet test --collect:"XPlat Code Coverage"

# Run specific test project
dotnet test tests/GodotMcp.Tests/GodotMcp.Tests.csproj

# Run tests with detailed output
dotnet test --logger "console;verbosity=detailed"

包

# Create NuGet package
dotnet pack -c Release

# Package will be created in bin/Release/

故障排除

连接问题

问题: NetworkException: Failed to connect to godot-mcp server

解决方案:

• 验证godot mcp是否已安装： dotnet tool list -g
• 检查Godot编辑器是否正在运行
• 增加 ConnectionTimeoutSeconds 在配置中
• 检查godot mcp日志是否有错误

超时错误

问题: TimeoutException: Request timed out

解决方案:

• 增加 RequestTimeoutSeconds 用于长时间运行的操作
• 检查Godot编辑器是否响应
• 验证网络连接
• 启用 EnableMessageLogging 调试请求/响应流

未找到工具

问题: GodotMcpException: Tool not found: Godot_xxx

解决方案:

• 验证godot-mcp服务器版本是否支持该工具
• 呼叫 ListToolsAsync() 查看可用工具
• 检查工具名称拼写
• 提供 ToolDefinitionsPath 作为后备

流程管理问题

问题：多个godot mcp进程正在运行

解决方案:

• 启用 EnableProcessPooling 重用流程
• 妥善处理 GodotPlugin 和服务
• 检查 MaxIdleTimeSeconds 配置
• 手动终止孤立进程

许可证

MIT许可证-有关详细信息，请参阅许可证文件

致谢

• 建立在 微软语义内核
• 与集成 godot-mcp服务器
• 跟随 模型上下文协议 规格

支持

• 问题：在GitHub Issues上报告错误和功能请求
• 讨论：在GitHub讨论中加入commGodot讨论
• 文档：完整的API文档以XML注释形式提供

版本历史记录

1.0.0（初始版本）

• 基于标准的MCP通信
• 自动工具发现
• 类型安全参数转换
• 具有可配置回退的重试逻辑
• 健康监测
• 安全日志记录
• 综合测试覆盖率（>80%）
• 清洁架构实施