godot-daedalus_backend 1.0.0

package/src/tools/llm-tools.ts

@@ -0,0 +1,1415 @@
+import { createHash } from "node:crypto";
+import type { ChatCompletionTool } from "openai/resources/chat/completions";
+
+export const DEFAULT_TOOL_STEPS: number = 10;
+export const CUSTOM_MCP_TOOLS_SENTINEL: string = "__custom_mcp_tools__";
+export const CUSTOM_MCP_TOOL_PREFIX: string = "mcp_custom_";
+const MAX_DYNAMIC_TOOLS_TOTAL: number = 96;
+const MAX_DYNAMIC_TOOLS_PER_SERVER: number = 32;
+const MAX_DYNAMIC_SCHEMA_CHARS: number = 8000;
+
+export type ToolBudgetLevel = "simple" | "normal" | "codegen" | "project_edit";
+
+const TOOL_BUDGET_MAP: Record<ToolBudgetLevel, number> = {
+	simple: 4,
+	normal: 10,
+	codegen: 20,
+	project_edit: 30
+};
+
+const SKILL_BUDGET_MAP: Record<string, number> = {
+	"gdscript.review": 8,
+	"godot.project_init": 12,
+	"file.creator": 16,
+	"scene.builder": 20,
+	"backend.helper": 10
+};
+
+export function resolveToolBudget(
+	budgetLevel?: ToolBudgetLevel | string,
+	skillId?: string
+): number {
+	if (budgetLevel && TOOL_BUDGET_MAP[budgetLevel as ToolBudgetLevel]) {
+		return TOOL_BUDGET_MAP[budgetLevel as ToolBudgetLevel];
+	}
+
+	if (skillId && SKILL_BUDGET_MAP[skillId]) {
+		return SKILL_BUDGET_MAP[skillId];
+	}
+
+	return DEFAULT_TOOL_STEPS;
+}
+
+export const MAX_TOOL_RESULT_CHARS: number = 12000;
+export const MAX_TOTAL_TOOL_RESULT_CHARS: number = 48000;
+
+type ToolMapping = {
+	serverId: string;
+	toolName: string;
+};
+
+export type DynamicMcpToolSource = {
+	serverId: string;
+	serverName: string;
+	toolName: string;
+	description?: string | undefined;
+	inputSchema?: unknown;
+};
+
+export type DynamicMcpToolMetadata = DynamicMcpToolSource & {
+	llmToolName: string;
+};
+
+const dynamicToolDefinitions: ChatCompletionTool[] = [];
+const dynamicToolMap: Map<string, ToolMapping> = new Map();
+const dynamicToolMetadata: Map<string, DynamicMcpToolMetadata> = new Map();
+
+function slugifyToolPart(value: string, maxLength: number): string {
+	const slug: string = value
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, "_")
+		.replace(/^_+|_+$/g, "")
+		.slice(0, maxLength);
+	return slug.length > 0 ? slug : "tool";
+}
+
+function createDynamicToolName(source: DynamicMcpToolSource): string {
+	const serverSlug: string = slugifyToolPart(source.serverName || source.serverId, 16);
+	const toolSlug: string = slugifyToolPart(source.toolName, 27);
+	const hash: string = createHash("sha1")
+		.update(`${source.serverId}\n${source.toolName}`)
+		.digest("hex")
+		.slice(0, 8);
+	return `${CUSTOM_MCP_TOOL_PREFIX}${serverSlug}_${toolSlug}_${hash}`;
+}
+
+function sanitizeDynamicInputSchema(inputSchema: unknown): Record<string, unknown> {
+	if (inputSchema === null || typeof inputSchema !== "object" || Array.isArray(inputSchema)) {
+		return {
+			type: "object",
+			properties: {},
+			additionalProperties: true
+		};
+	}
+
+	const schema: Record<string, unknown> = { ...(inputSchema as Record<string, unknown>) };
+	delete schema.$schema;
+	if (schema.type !== "object") {
+		schema.type = "object";
+	}
+	if (JSON.stringify(schema).length > MAX_DYNAMIC_SCHEMA_CHARS) {
+		return {
+			type: "object",
+			properties: {},
+			additionalProperties: true
+		};
+	}
+
+	return schema;
+}
+
+function createDynamicToolDefinition(source: DynamicMcpToolSource, llmToolName: string): ChatCompletionTool {
+	const descriptionParts: string[] = [
+		`自定义 MCP 工具，来自 server "${source.serverName}" 的工具 "${source.toolName}"。`,
+		"该工具由用户配置的外部 MCP server 提供，默认按写风险处理，调用前会走审批。"
+	];
+	if (source.description !== undefined && source.description.trim().length > 0) {
+		descriptionParts.push(source.description.trim());
+	}
+
+	return {
+		type: "function",
+		function: {
+			name: llmToolName,
+			description: descriptionParts.join(" ").slice(0, 1024),
+			parameters: sanitizeDynamicInputSchema(source.inputSchema)
+		}
+	};
+}
+
+export function replaceDynamicMcpTools(sources: readonly DynamicMcpToolSource[]): void {
+	dynamicToolDefinitions.length = 0;
+	dynamicToolMap.clear();
+	dynamicToolMetadata.clear();
+
+	const perServerCounts: Map<string, number> = new Map();
+	for (const source of sources) {
+		if (dynamicToolDefinitions.length >= MAX_DYNAMIC_TOOLS_TOTAL) {
+			break;
+		}
+
+		const nextServerCount: number = (perServerCounts.get(source.serverId) ?? 0) + 1;
+		if (nextServerCount > MAX_DYNAMIC_TOOLS_PER_SERVER) {
+			continue;
+		}
+		perServerCounts.set(source.serverId, nextServerCount);
+
+		const llmToolName: string = createDynamicToolName(source);
+		const definition: ChatCompletionTool = createDynamicToolDefinition(source, llmToolName);
+		dynamicToolDefinitions.push(definition);
+		dynamicToolMap.set(llmToolName, {
+			serverId: source.serverId,
+			toolName: source.toolName
+		});
+		dynamicToolMetadata.set(llmToolName, {
+			...source,
+			llmToolName
+		});
+	}
+}
+
+export function getDynamicMcpToolNames(): string[] {
+	return Array.from(dynamicToolMap.keys());
+}
+
+export function isDynamicMcpToolName(toolName: string): boolean {
+	return toolName.startsWith(CUSTOM_MCP_TOOL_PREFIX);
+}
+
+export function getDynamicMcpToolMetadata(toolName: string): DynamicMcpToolMetadata | undefined {
+	return dynamicToolMetadata.get(toolName);
+}
+
+const TOOL_MAP: Record<string, ToolMapping> = {
+	"mcp_godot_get_project_summary": {
+		serverId: "godot",
+		toolName: "get_project_summary"
+	},
+	"mcp_godot_list_project_files": {
+		serverId: "godot",
+		toolName: "list_project_files"
+	},
+	"mcp_godot_list_scenes": {
+		serverId: "godot",
+		toolName: "list_scenes"
+	},
+	"mcp_godot_list_scripts": {
+		serverId: "godot",
+		toolName: "list_scripts"
+	},
+	"mcp_godot_read_text_file": {
+		serverId: "godot",
+		toolName: "read_text_file"
+	},
+	"mcp_godot_search_text": {
+		serverId: "godot",
+		toolName: "search_text"
+	},
+	"mcp_godot_get_project_log_config": {
+		serverId: "godot",
+		toolName: "get_project_log_config"
+	},
+	"mcp_godot_list_project_logs": {
+		serverId: "godot",
+		toolName: "list_project_logs"
+	},
+	"mcp_godot_read_project_log": {
+		serverId: "godot",
+		toolName: "read_project_log"
+	},
+	"mcp_godot_get_project_settings": {
+		serverId: "godot",
+		toolName: "get_project_settings"
+	},
+	"mcp_godot_get_editor_config_summary": {
+		serverId: "godot",
+		toolName: "get_editor_config_summary"
+	},
+	"mcp_godot_get_editor_settings": {
+		serverId: "godot",
+		toolName: "get_editor_settings"
+	},
+	"mcp_godot_list_editor_config_files": {
+		serverId: "godot",
+		toolName: "list_editor_config_files"
+	},
+	"mcp_godot_read_editor_config_file": {
+		serverId: "godot",
+		toolName: "read_editor_config_file"
+	},
+	"mcp_godot_get_editor_project_state": {
+		serverId: "godot",
+		toolName: "get_editor_project_state"
+	},
+	"mcp_godot_get_recent_projects": {
+		serverId: "godot",
+		toolName: "get_recent_projects"
+	},
+	"mcp_godot_propose_set_project_setting": {
+		serverId: "godot",
+		toolName: "propose_set_project_setting"
+	},
+	"mcp_godot_set_project_setting": {
+		serverId: "godot",
+		toolName: "set_project_setting"
+	},
+	"mcp_godot_propose_unset_project_setting": {
+		serverId: "godot",
+		toolName: "propose_unset_project_setting"
+	},
+	"mcp_godot_unset_project_setting": {
+		serverId: "godot",
+		toolName: "unset_project_setting"
+	},
+	"mcp_godot_propose_create_text_file": {
+		serverId: "godot",
+		toolName: "propose_create_text_file"
+	},
+	"mcp_godot_create_text_file": {
+		serverId: "godot",
+		toolName: "create_text_file"
+	},
+	"mcp_godot_propose_overwrite_text_file": {
+		serverId: "godot",
+		toolName: "propose_overwrite_text_file"
+	},
+	"mcp_godot_overwrite_text_file": {
+		serverId: "godot",
+		toolName: "overwrite_text_file"
+	},
+	"mcp_godot_propose_replace_text_in_file": {
+		serverId: "godot",
+		toolName: "propose_replace_text_in_file"
+	},
+	"mcp_godot_replace_text_in_file": {
+		serverId: "godot",
+		toolName: "replace_text_in_file"
+	},
+	"mcp_godot_delete_file": {
+		serverId: "godot",
+		toolName: "delete_file"
+	},
+	"mcp_terminal_run_safe_preset": {
+		serverId: "terminal",
+		toolName: "run_safe_preset"
+	},
+	"mcp_terminal_run_write_preset": {
+		serverId: "terminal",
+		toolName: "run_write_preset"
+	},
+	"mcp_terminal_get_capabilities": {
+		serverId: "terminal",
+		toolName: "get_terminal_capabilities"
+	},
+	"mcp_godot_inspect_scene_tree": {
+		serverId: "godot",
+		toolName: "inspect_scene_tree"
+	},
+	"mcp_godot_propose_create_scene": {
+		serverId: "godot",
+		toolName: "propose_create_scene"
+	},
+	"mcp_godot_create_scene": {
+		serverId: "godot",
+		toolName: "create_scene"
+	},
+	"mcp_godot_propose_add_node_to_scene": {
+		serverId: "godot",
+		toolName: "propose_add_node_to_scene"
+	},
+	"mcp_godot_add_node_to_scene": {
+		serverId: "godot",
+		toolName: "add_node_to_scene"
+	},
+	"mcp_godot_propose_attach_script_to_node": {
+		serverId: "godot",
+		toolName: "propose_attach_script_to_node"
+	},
+	"mcp_godot_attach_script_to_node": {
+		serverId: "godot",
+		toolName: "attach_script_to_node"
+	},
+	"mcp_godot_propose_connect_signal_in_scene": {
+		serverId: "godot",
+		toolName: "propose_connect_signal_in_scene"
+	},
+	"mcp_godot_connect_signal_in_scene": {
+		serverId: "godot",
+		toolName: "connect_signal_in_scene"
+	},
+	"mcp_godot_propose_apply_scene_patch": {
+		serverId: "godot",
+		toolName: "propose_apply_scene_patch"
+	},
+	"mcp_godot_apply_scene_patch": {
+		serverId: "godot",
+		toolName: "apply_scene_patch"
+	},
+	"mcp_godot_editor_get_context": {
+		serverId: "godot_editor",
+		toolName: "get_context"
+	},
+	"mcp_godot_editor_get_selected_nodes": {
+		serverId: "godot_editor",
+		toolName: "get_selected_nodes"
+	},
+	"mcp_godot_editor_inspect_node": {
+		serverId: "godot_editor",
+		toolName: "inspect_node"
+	},
+	"mcp_godot_editor_apply_scene_patch": {
+		serverId: "godot_editor",
+		toolName: "apply_scene_patch"
+	},
+	"mcp_godot_lsp_get_status": {
+		serverId: "godot_diagnostics",
+		toolName: "lsp_get_status"
+	},
+	"mcp_godot_lsp_get_file_diagnostics": {
+		serverId: "godot_diagnostics",
+		toolName: "lsp_get_file_diagnostics"
+	},
+	"mcp_godot_lsp_get_document_symbols": {
+		serverId: "godot_diagnostics",
+		toolName: "lsp_get_document_symbols"
+	},
+	"mcp_godot_lsp_hover": {
+		serverId: "godot_diagnostics",
+		toolName: "lsp_hover"
+	},
+	"mcp_godot_lsp_goto_definition": {
+		serverId: "godot_diagnostics",
+		toolName: "lsp_goto_definition"
+	},
+	"mcp_godot_dap_get_status": {
+		serverId: "godot_diagnostics",
+		toolName: "dap_get_status"
+	},
+	"mcp_godot_dap_get_last_error": {
+		serverId: "godot_diagnostics",
+		toolName: "dap_get_last_error"
+	},
+	"mcp_godot_dap_get_stack_trace": {
+		serverId: "godot_diagnostics",
+		toolName: "dap_get_stack_trace"
+	},
+	"mcp_godot_dap_get_variables": {
+		serverId: "godot_diagnostics",
+		toolName: "dap_get_variables"
+	},
+	"mcp_terminal_run_godot_scene_script": {
+		serverId: "terminal",
+		toolName: "run_godot_scene_script"
+	}
+};
+
+const TOOL_DEFINITIONS: ChatCompletionTool[] = [
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_get_project_summary",
+			description: "获取 Godot 项目的摘要信息，包括项目名称、主场景、场景和脚本数量、插件列表等",
+			parameters: {
+				type: "object",
+				properties: {},
+				required: []
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_list_project_files",
+			description: "递归列出 Godot 项目文件，可按子目录和扩展名过滤",
+			parameters: {
+				type: "object",
+				properties: {
+					subdir: {
+						type: "string",
+						description: "相对于项目根目录的子目录路径"
+					},
+					extensions: {
+						type: "array",
+						items: { type: "string" },
+						description: "扩展名过滤，例如 ['.gd', '.tscn']"
+					},
+					includeAddons: {
+						type: "boolean",
+						description: "是否包含 addons 目录"
+					}
+				},
+				required: []
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_list_scenes",
+			description: "列出 Godot 项目中所有 .tscn 场景文件",
+			parameters: {
+				type: "object",
+				properties: {
+					includeAddons: {
+						type: "boolean",
+						description: "是否包含 addons 目录"
+					}
+				},
+				required: []
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_list_scripts",
+			description: "列出 Godot 项目中所有 .gd 脚本文件",
+			parameters: {
+				type: "object",
+				properties: {
+					includeAddons: {
+						type: "boolean",
+						description: "是否包含 addons 目录"
+					}
+				},
+				required: []
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_read_text_file",
+			description: "读取 Godot 项目中的文本文件内容",
+			parameters: {
+				type: "object",
+				properties: {
+					relativePath: {
+						type: "string",
+						description: "相对于项目根目录的文件路径"
+					}
+				},
+				required: ["relativePath"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_search_text",
+			description: "在项目文本文件中搜索关键词，返回匹配的文件路径和行号",
+			parameters: {
+				type: "object",
+				properties: {
+					query: {
+						type: "string",
+						description: "要搜索的文本关键词"
+					},
+					extensions: {
+						type: "array",
+						items: { type: "string" },
+						description: "扩展名过滤，例如 ['.gd']"
+					},
+					limit: {
+						type: "integer",
+						description: "最多返回多少条匹配，默认 50"
+					}
+				},
+				required: ["query"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_get_project_log_config",
+			description: "读取 Godot 项目日志配置并解析 user://。当用户询问日志位置、运行报错或 user://logs/godot.log 时，先用本工具获取真实路径，不要自己猜 user://。",
+			parameters: {
+				type: "object",
+				properties: {},
+				required: []
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_list_project_logs",
+			description: "列出当前 Godot 项目日志目录中的 godot.log 和轮转日志，包含大小和修改时间。排查运行错误时先列出日志再读取最新日志。",
+			parameters: {
+				type: "object",
+				properties: {},
+				required: []
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_read_project_log",
+			description: "读取 Godot 项目日志尾部。默认读取 godot.log；如果不存在则读取最新轮转日志。只读取日志目录内文件，返回 user:// 解析说明。",
+			parameters: {
+				type: "object",
+				properties: {
+					fileName: {
+						type: "string",
+						description: "可选，来自 mcp_godot_list_project_logs 的纯文件名，例如 godot.log"
+					},
+					lines: {
+						type: "integer",
+						description: "读取尾部行数，默认 200，最多 1000"
+					}
+				},
+				required: []
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_get_project_settings",
+			description: "结构化读取 project.godot 中显式写出的项目设置。key 使用 Godot 完整路径，例如 application/config/name 或 debug/file_logging/log_path。",
+			parameters: {
+				type: "object",
+				properties: {
+					keys: {
+						type: "array",
+						items: { type: "string" },
+						description: "按完整 key 精确读取，例如 ['debug/file_logging/log_path']"
+					},
+					prefix: {
+						type: "string",
+						description: "按完整 key 前缀过滤，例如 debug/file_logging/"
+					}
+				},
+				required: []
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_get_editor_config_summary",
+			description: "读取 Godot 编辑器全局设置和当前项目 .godot/editor 状态摘要，包括主题、字体、打开场景/脚本、最近项目数量等。默认脱敏本机路径；只有用户明确要求原始配置/路径时才设置 raw=true。",
+			parameters: {
+				type: "object",
+				properties: {
+					raw: {
+						type: "boolean",
+						description: "是否返回原始本机路径。默认 false，会脱敏用户名和非当前项目绝对路径。"
+					}
+				},
+				required: []
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_get_editor_settings",
+			description: "按 key 或 prefix 读取 editor_settings-*.tres 中的 Godot 编辑器设置，例如 interface/theme/、interface/editor/fonts/、text_editor/。默认脱敏路径值。",
+			parameters: {
+				type: "object",
+				properties: {
+					keys: {
+						type: "array",
+						items: { type: "string" },
+						description: "按完整 EditorSettings key 精确读取，例如 ['interface/theme/style']"
+					},
+					prefix: {
+						type: "string",
+						description: "按 key 前缀过滤，例如 interface/theme/"
+					},
+					raw: {
+						type: "boolean",
+						description: "是否返回原始路径值。默认 false。"
+					}
+				},
+				required: []
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_list_editor_config_files",
+			description: "列出只读白名单中的 Godot 编辑器配置文件，包括 editor_settings、projects.cfg、recent_dirs、text_editor_themes、script_templates 和当前项目 .godot/editor/*.cfg。读取原文前先用本工具拿 fileId。",
+			parameters: {
+				type: "object",
+				properties: {
+					raw: {
+						type: "boolean",
+						description: "是否返回原始绝对路径。默认 false。"
+					}
+				},
+				required: []
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_read_editor_config_file",
+			description: "读取 mcp_godot_list_editor_config_files 返回的白名单编辑器配置文件。默认脱敏内容中的本机路径；只有用户明确要求原始内容时才设置 raw=true。",
+			parameters: {
+				type: "object",
+				properties: {
+					fileId: {
+						type: "string",
+						description: "来自 list_editor_config_files 的 fileId，例如 global_config:editor_settings-4.7.tres"
+					},
+					filePath: {
+						type: "string",
+						description: "可选路径写法；推荐优先使用 fileId"
+					},
+					raw: {
+						type: "boolean",
+						description: "是否返回原始内容。默认 false。"
+					}
+				},
+				required: []
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_get_editor_project_state",
+			description: "结构化读取当前项目 .godot/editor/editor_layout.cfg 与 script_editor_cache.cfg，返回打开场景、当前场景、FileSystem Dock 选中项、打开脚本、当前脚本和光标行列。默认脱敏路径。",
+			parameters: {
+				type: "object",
+				properties: {
+					raw: {
+						type: "boolean",
+						description: "是否返回原始路径。默认 false。"
+					}
+				},
+				required: []
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_get_recent_projects",
+			description: "读取 Godot projects.cfg 和 recent_dirs，返回最近项目与最近目录。默认脱敏非当前项目路径；只有用户明确要求原始路径时才设置 raw=true。",
+			parameters: {
+				type: "object",
+				properties: {
+					raw: {
+						type: "boolean",
+						description: "是否返回原始路径。默认 false。"
+					}
+				},
+				required: []
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_propose_set_project_setting",
+			description: "预览设置 project.godot 中的某个项目设置，不写入磁盘。修改项目设置前优先先读取当前值，再调用本工具预览。valueExpression 是 project.godot 右侧原始表达式，例如 '\"Daedalus\"'、true、PackedStringArray(...)。",
+			parameters: {
+				type: "object",
+				properties: {
+					key: {
+						type: "string",
+						description: "完整项目设置 key，例如 debug/file_logging/log_path"
+					},
+					valueExpression: {
+						type: "string",
+						description: "project.godot 右侧原始表达式，例如 '\"user://logs/godot.log\"'"
+					}
+				},
+				required: ["key", "valueExpression"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_set_project_setting",
+			description: "实际修改 project.godot 中的某个项目设置，会触发用户审批。修改前应读取当前值并用 mcp_godot_propose_set_project_setting 预览。",
+			parameters: {
+				type: "object",
+				properties: {
+					key: {
+						type: "string",
+						description: "完整项目设置 key，例如 debug/file_logging/log_path"
+					},
+					valueExpression: {
+						type: "string",
+						description: "project.godot 右侧原始表达式，例如 '\"user://logs/godot.log\"'"
+					}
+				},
+				required: ["key", "valueExpression"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_propose_unset_project_setting",
+			description: "预览移除 project.godot 中的某个显式项目设置，不写入磁盘。移除后 Godot 会回退默认值。",
+			parameters: {
+				type: "object",
+				properties: {
+					key: {
+						type: "string",
+						description: "完整项目设置 key，例如 debug/file_logging/log_path"
+					}
+				},
+				required: ["key"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_unset_project_setting",
+			description: "实际移除 project.godot 中的某个显式项目设置，会触发用户审批。移除后 Godot 会回退默认值。",
+			parameters: {
+				type: "object",
+				properties: {
+					key: {
+						type: "string",
+						description: "完整项目设置 key，例如 debug/file_logging/log_path"
+					}
+				},
+				required: ["key"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_inspect_scene_tree",
+			description: "解析并检查 Godot .tscn 场景树，返回节点、脚本和连接等结构信息",
+			parameters: {
+				type: "object",
+				properties: {
+					relativePath: {
+						type: "string",
+						description: "场景文件的相对路径，例如 'scenes/main.tscn'"
+					}
+				},
+				required: ["relativePath"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_editor_get_context",
+			description: "读取在线 Godot 编辑器上下文，包括在线状态、当前打开场景、选中节点和上下文新鲜度。若编辑器离线会返回 editor_unavailable，可回退到离线 Godot MCP 工具。",
+			parameters: {
+				type: "object",
+				properties: {},
+				required: []
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_lsp_get_status",
+			description: "探测 Godot GDScript LSP 是否可用，返回 host/port、编辑器设置来源和最近错误。LSP 默认端口通常是 6005。",
+			parameters: {
+				type: "object",
+				properties: {},
+				required: []
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_lsp_get_file_diagnostics",
+			description: "读取指定 GDScript 文件的 Godot LSP 诊断，返回 1-based 行列、severity、message 和 code。修改 .gd 后应优先调用该工具，再运行 Godot check-only。",
+			parameters: {
+				type: "object",
+				properties: {
+					resourcePath: {
+						type: "string",
+						description: "脚本路径，可用 res://、项目相对路径或项目内绝对路径，例如 'res://scripts/player.gd' 或 'scripts/player.gd'。"
+					}
+				},
+				required: ["resourcePath"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_lsp_get_document_symbols",
+			description: "读取指定 GDScript 文件的 document symbols 摘要，用于理解类、函数、变量和枚举结构。",
+			parameters: {
+				type: "object",
+				properties: {
+					resourcePath: {
+						type: "string",
+						description: "脚本路径，可用 res://、项目相对路径或项目内绝对路径。"
+					}
+				},
+				required: ["resourcePath"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_lsp_hover",
+			description: "读取指定 GDScript 文件某个位置的 hover 信息，用于确认 API、变量或类型含义。line/column 使用 1-based。",
+			parameters: {
+				type: "object",
+				properties: {
+					resourcePath: {
+						type: "string",
+						description: "脚本路径，可用 res://、项目相对路径或项目内绝对路径。"
+					},
+					line: {
+						type: "integer",
+						description: "1-based 行号。"
+					},
+					column: {
+						type: "integer",
+						description: "1-based 列号。"
+					}
+				},
+				required: ["resourcePath", "line", "column"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_lsp_goto_definition",
+			description: "读取指定 GDScript 文件某个位置的 definition 位置，用于追踪函数、变量、类或资源定义。line/column 使用 1-based。",
+			parameters: {
+				type: "object",
+				properties: {
+					resourcePath: {
+						type: "string",
+						description: "脚本路径，可用 res://、项目相对路径或项目内绝对路径。"
+					},
+					line: {
+						type: "integer",
+						description: "1-based 行号。"
+					},
+					column: {
+						type: "integer",
+						description: "1-based 列号。"
+					}
+				},
+				required: ["resourcePath", "line", "column"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_dap_get_status",
+			description: "探测 Godot DAP 是否可用，并只读检查当前是否可 attach 到正在运行的调试会话。DAP 默认端口通常是 6006。",
+			parameters: {
+				type: "object",
+				properties: {},
+				required: []
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_dap_get_last_error",
+			description: "只读读取当前 Godot DAP stopped/output 事件和顶部调用栈摘要。遇到运行时报错时优先调用；DAP 不可用时回退到项目日志。",
+			parameters: {
+				type: "object",
+				properties: {},
+				required: []
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_dap_get_stack_trace",
+			description: "只读读取当前 Godot 调试会话调用栈和 frame scopes。不会 pause/continue/step，也不会 evaluate。",
+			parameters: {
+				type: "object",
+				properties: {},
+				required: []
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_dap_get_variables",
+			description: "只读读取 DAP variablesReference 对应的变量摘要。variablesReference 来自 mcp_godot_dap_get_stack_trace 的 scopes 或变量结果。",
+			parameters: {
+				type: "object",
+				properties: {
+					variablesReference: {
+						type: "integer",
+						description: "来自 DAP scopes 或变量结果的 variablesReference。"
+					}
+				},
+				required: ["variablesReference"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_editor_get_selected_nodes",
+			description: "读取当前 Godot 编辑器中多个选中节点的路径、类型、脚本、owner 和关键属性摘要。适合用户说“这些节点/当前选中按钮”等实时编辑器上下文。",
+			parameters: {
+				type: "object",
+				properties: {},
+				required: []
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_editor_inspect_node",
+			description: "检查在线 Godot 编辑器中指定节点的实时结构，能看到尚未保存到 .tscn 的当前状态。若编辑器离线或上下文不匹配，应回退到 mcp_godot_inspect_scene_tree。",
+			parameters: {
+				type: "object",
+				properties: {
+					scenePath: {
+						type: "string",
+						description: "可选场景路径；为空时使用当前打开场景。"
+					},
+					nodePath: {
+						type: "string",
+						description: "相对当前场景根节点的 NodePath，例如 '.'、'CanvasLayer/Button'。"
+					}
+				},
+				required: ["nodePath"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_editor_apply_scene_patch",
+			description: "在在线 Godot 编辑器中应用场景 patch，会使用 EditorUndoRedoManager 合并为一个可撤销动作，并默认保存当前场景。该工具会实际修改场景，必须经过用户审批；编辑器离线时回退到离线 mcp_godot_apply_scene_patch 或 headless 工具。",
+			parameters: {
+				type: "object",
+				properties: {
+					title: {
+						type: "string",
+						description: "UndoRedo 动作标题，例如 'Daedalus: 调整按钮文本'。"
+					},
+					scenePath: {
+						type: "string",
+						description: "可选场景路径；为空时使用当前打开场景。"
+					},
+					saveAfter: {
+						type: "boolean",
+						description: "提交 UndoRedo 动作后是否保存当前场景，默认 true。"
+					},
+					operations: {
+						type: "array",
+						description: "按顺序执行的在线场景操作。第一版支持 set_property、add_node、rename_node、attach_script、connect_signal。",
+						items: {
+							oneOf: [
+								{
+									type: "object",
+									properties: {
+										type: { const: "set_property" },
+										nodePath: { type: "string" },
+										property: { type: "string" },
+										value: {}
+									},
+									required: ["type", "nodePath", "property", "value"]
+								},
+								{
+									type: "object",
+									properties: {
+										type: { const: "add_node" },
+										parentPath: { type: "string" },
+										nodeType: { type: "string" },
+										nodeName: { type: "string" },
+										properties: {
+											type: "object",
+											additionalProperties: true
+										}
+									},
+									required: ["type", "parentPath", "nodeType", "nodeName"]
+								},
+								{
+									type: "object",
+									properties: {
+										type: { const: "rename_node" },
+										nodePath: { type: "string" },
+										name: { type: "string" }
+									},
+									required: ["type", "nodePath", "name"]
+								},
+								{
+									type: "object",
+									properties: {
+										type: { const: "attach_script" },
+										nodePath: { type: "string" },
+										scriptPath: { type: "string" }
+									},
+									required: ["type", "nodePath", "scriptPath"]
+								},
+								{
+									type: "object",
+									properties: {
+										type: { const: "connect_signal" },
+										fromNode: { type: "string" },
+										signal: { type: "string" },
+										toNode: { type: "string" },
+										method: { type: "string" },
+										flags: { type: "integer" }
+									},
+									required: ["type", "fromNode", "signal", "toNode", "method"]
+								}
+							]
+						},
+						minItems: 1,
+						maxItems: 50
+					}
+				},
+				required: ["operations"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_propose_create_text_file",
+			description: "仅预览新建文本文件方案，不会实际写入磁盘，也不会创建审批。只能创建 .gd/.tres/.tscn/.json/.md/.txt 文件。.tscn 文件必须包含 [gd_scene ...] 头部和至少一个 [node ...] 根节点。不允许覆盖已有文件。需要真正写入时，必须改用 mcp_godot_create_text_file。",
+			parameters: {
+				type: "object",
+				properties: {
+					relativePath: {
+						type: "string",
+						description: "相对于项目根目录的新文件路径，例如 'scripts/enemy.gd'"
+					},
+					content: {
+						type: "string",
+						description: "文件的完整内容"
+					}
+				},
+				required: ["relativePath", "content"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_create_text_file",
+			description: "创建一个新的 Godot 项目文本文件。该工具会实际写入磁盘，默认需要用户在 Godot 客户端审批。支持创建 .gd/.tres/.tscn/.json/.md/.txt 文件。.tscn 文件必须包含 [gd_scene ...] 头部和至少一个 [node ...] 根节点。不允许覆盖已有文件，不允许写入 .godot/ 或 addons/。写入后建议运行 godot.check_only 验证。",
+			parameters: {
+				type: "object",
+				properties: {
+					relativePath: {
+						type: "string",
+						description: "相对于项目根目录的新文件路径，例如 'scripts/enemy.gd'"
+					},
+					content: {
+						type: "string",
+						description: "文件的完整内容"
+					}
+				},
+				required: ["relativePath", "content"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_propose_overwrite_text_file",
+			description: "仅预览覆盖已有文件方案，不会实际写入，也不会创建审批。支持 .gd/.tres/.tscn/.json/.md/.txt 文件。.tscn 文件必须包含 [gd_scene ...] 头部和至少一个 [node ...] 根节点。文件必须已存在，会返回新旧内容对比。需要真正覆盖时，必须改用 mcp_godot_overwrite_text_file。",
+			parameters: {
+				type: "object",
+				properties: {
+					relativePath: { type: "string", description: "要覆盖的已有文件路径" },
+					content: { type: "string", description: "新的完整文件内容" }
+				},
+				required: ["relativePath", "content"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_overwrite_text_file",
+			description: "覆盖已有文本文件，会实际写入磁盘，默认需要用户在 Godot 客户端审批。支持写入 .gd/.tres/.tscn/.json/.md/.txt 文件。.tscn 文件必须包含 [gd_scene ...] 头部和至少一个 [node ...] 根节点。不允许写入 .godot/、addons/ 或隐藏目录。写入后建议运行 godot.check_only 验证。",
+			parameters: {
+				type: "object",
+				properties: {
+					relativePath: { type: "string", description: "要覆盖的已有文件路径" },
+					content: { type: "string", description: "新的完整文件内容" }
+				},
+				required: ["relativePath", "content"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_propose_replace_text_in_file",
+			description: "仅预览替换文件中指定文本的方案，不会实际写入，也不会创建审批。oldText 必须精确匹配（含空白和缩进），只替换首次出现。需要真正替换时，必须改用 mcp_godot_replace_text_in_file。",
+			parameters: {
+				type: "object",
+				properties: {
+					relativePath: { type: "string", description: "已有文件路径" },
+					oldText: { type: "string", description: "要被替换的原文本，必须精确匹配" },
+					newText: { type: "string", description: "替换后的新文本" }
+				},
+				required: ["relativePath", "oldText", "newText"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_replace_text_in_file",
+			description: "替换已有文本文件中首次出现的指定文本，会实际写入磁盘，默认需要用户在 Godot 客户端审批。oldText 必须精确匹配。",
+			parameters: {
+				type: "object",
+				properties: {
+					relativePath: { type: "string", description: "已有文件路径" },
+					oldText: { type: "string", description: "要被替换的原文本，必须精确匹配" },
+					newText: { type: "string", description: "替换后的新文本" }
+				},
+				required: ["relativePath", "oldText", "newText"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_delete_file",
+			description: "删除项目中的文件。此操作不可逆，需要用户确认。不能删除 .godot/ 中的文件。",
+			parameters: {
+				type: "object",
+				properties: {
+					relativePath: { type: "string", description: "要删除的文件路径" }
+				},
+				required: ["relativePath"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_terminal_get_capabilities",
+			description: "获取终端 MCP 支持的所有预设命令列表及其风险等级。首次使用终端工具前应先调用此工具了解可用命令。",
+			parameters: {
+				type: "object",
+				properties: {},
+				required: []
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_terminal_run_safe_preset",
+			description: "执行安全的（read/verify 风险）终端预设命令，自动允许。包括：backend.typecheck（TypeScript 类型检查）、git.status（Git 工作区状态）、git.diff（Git 差异）、godot.check_only（Godot 语法检查）、godot.validate_scene（Godot 场景加载验证）。Godot 预设建议传 resourcePath 精确检查目标 .gd 或 .tscn，工具结果会返回实际执行命令和 cwd。",
+			parameters: {
+				type: "object",
+				properties: {
+					presetName: {
+						type: "string",
+						description: "安全预设名称，如 'backend.typecheck'、'git.status'、'git.diff'、'godot.check_only'、'godot.validate_scene'"
+					},
+					resourcePath: {
+						type: "string",
+						description: "Godot 资源路径，仅 Godot 预设需要。可用 res://、项目相对路径或项目内绝对路径，例如 scripts/main.gd、scenes/main.tscn。检查脚本用 godot.check_only + .gd；验证场景用 godot.validate_scene + .tscn。"
+					}
+				},
+				required: ["presetName"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_terminal_run_godot_scene_script",
+			description: "通过 Godot headless 模式调用 scene_operator.gd 执行场景创建/编辑操作。支持 create_scene（创建场景）、add_node（添加节点）、attach_script（挂载脚本）、connect_signal（连接信号）、inspect（查看场景树）。传入 JSON 格式的 operationJson 参数。此工具需要用户审批。",
+			parameters: {
+				type: "object",
+				properties: {
+					operationJson: {
+						type: "string",
+						description: "JSON 格式的场景操作。create_scene: {\"operation\":\"create_scene\",\"path\":\"scenes/foo.tscn\",\"root_type\":\"Node2D\",\"root_name\":\"Main\"}。add_node: {\"operation\":\"add_node\",\"scene_path\":\"...\",\"parent_path\":\".\",\"node_type\":\"Label\",\"node_name\":\"Hello\",\"properties\":{}}。attach_script: {\"operation\":\"attach_script\",\"scene_path\":\"...\",\"node_path\":\"Main\",\"script_path\":\"res://scripts/main.gd\"}。connect_signal: {\"operation\":\"connect_signal\",\"scene_path\":\"...\",\"signal\":\"pressed\",\"from\":\"Button\",\"to\":\".\",\"method\":\"_on_pressed\"}。inspect: {\"operation\":\"inspect\",\"scene_path\":\"...\"}"
+					}
+				},
+				required: ["operationJson"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_terminal_run_write_preset",
+			description: "执行写操作（write 风险）终端预设命令，需要通过审批系统批准。可用的写预设：git.init。此工具调用后不会立即执行，需要用户在 Godot 客户端批准。",
+			parameters: {
+				type: "object",
+				properties: {
+					presetName: {
+						type: "string",
+						description: "写操作预设名称，如 'git.init'"
+					}
+				},
+				required: ["presetName"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_propose_apply_scene_patch",
+			description: "仅预览批量修改已有 Godot .tscn 场景的方案，不会实际写入，也不会创建审批。支持一次添加多个节点、挂载脚本、连接信号。需要真正修改场景时，必须改用 mcp_godot_apply_scene_patch。",
+			parameters: {
+				type: "object",
+				properties: {
+					scenePath: {
+						type: "string",
+						description: "已有场景文件路径，例如 'scenes/guess_number.tscn'"
+					},
+					operations: {
+						type: "array",
+						description: "按顺序执行的场景操作列表。节点属性值必须是 .tscn 表达式字符串，例如 text 写成 '\"Hello\"'，数值可写成 '15'。",
+						items: {
+							oneOf: [
+								{
+									type: "object",
+									properties: {
+										type: { const: "add_node" },
+										parentPath: { type: "string" },
+										nodeType: { type: "string" },
+										nodeName: { type: "string" },
+										properties: {
+											type: "object",
+											additionalProperties: { type: "string" }
+										}
+									},
+									required: ["type", "parentPath", "nodeType", "nodeName"]
+								},
+								{
+									type: "object",
+									properties: {
+										type: { const: "attach_script" },
+										nodePath: { type: "string" },
+										scriptPath: { type: "string" }
+									},
+									required: ["type", "nodePath", "scriptPath"]
+								},
+								{
+									type: "object",
+									properties: {
+										type: { const: "connect_signal" },
+										signal: { type: "string" },
+										fromNode: { type: "string" },
+										toNode: { type: "string" },
+										method: { type: "string" },
+										flags: { type: "integer" },
+										binds: { type: "string" }
+									},
+									required: ["type", "signal", "fromNode", "toNode", "method"]
+								}
+							]
+						},
+						minItems: 1,
+						maxItems: 50
+					}
+				},
+				required: ["scenePath", "operations"]
+			}
+		}
+	},
+	{
+		type: "function",
+		function: {
+			name: "mcp_godot_apply_scene_patch",
+			description: "批量修改已有 Godot .tscn 场景，会实际写入磁盘并触发用户审批。支持一次添加多个节点、挂载脚本、连接信号。创建复杂 UI 或小游戏场景时，应优先使用本工具，不要逐个调用 add_node_to_scene。",
+			parameters: {
+				type: "object",
+				properties: {
+					scenePath: {
+						type: "string",
+						description: "已有场景文件路径，例如 'scenes/guess_number.tscn'"
+					},
+					operations: {
+						type: "array",
+						description: "按顺序执行的场景操作列表。节点属性值必须是 .tscn 表达式字符串，例如 text 写成 '\"Hello\"'，数值可写成 '15'。",
+						items: {
+							oneOf: [
+								{
+									type: "object",
+									properties: {
+										type: { const: "add_node" },
+										parentPath: { type: "string" },
+										nodeType: { type: "string" },
+										nodeName: { type: "string" },
+										properties: {
+											type: "object",
+											additionalProperties: { type: "string" }
+										}
+									},
+									required: ["type", "parentPath", "nodeType", "nodeName"]
+								},
+								{
+									type: "object",
+									properties: {
+										type: { const: "attach_script" },
+										nodePath: { type: "string" },
+										scriptPath: { type: "string" }
+									},
+									required: ["type", "nodePath", "scriptPath"]
+								},
+								{
+									type: "object",
+									properties: {
+										type: { const: "connect_signal" },
+										signal: { type: "string" },
+										fromNode: { type: "string" },
+										toNode: { type: "string" },
+										method: { type: "string" },
+										flags: { type: "integer" },
+										binds: { type: "string" }
+									},
+									required: ["type", "signal", "fromNode", "toNode", "method"]
+								}
+							]
+						},
+						minItems: 1,
+						maxItems: 50
+					}
+				},
+				required: ["scenePath", "operations"]
+			}
+		}
+	}
+];
+
+export function getToolDefinitions(): ChatCompletionTool[] {
+	return [...TOOL_DEFINITIONS, ...dynamicToolDefinitions];
+}
+
+export function getToolDefinitionsForNames(toolNames: readonly string[]): ChatCompletionTool[] {
+	const allowedNames: Set<string> = new Set(toolNames);
+	const includeDynamicTools: boolean = allowedNames.has(CUSTOM_MCP_TOOLS_SENTINEL);
+	return getToolDefinitions().filter((tool: ChatCompletionTool): boolean => {
+		if (tool.type !== "function" || !("function" in tool)) {
+			return false;
+		}
+
+		if (includeDynamicTools && isDynamicMcpToolName(tool.function.name)) {
+			return true;
+		}
+
+		return allowedNames.has(tool.function.name);
+	});
+}
+
+export function resolveToolMapping(llmToolName: string): ToolMapping {
+	const mapping: ToolMapping | undefined = TOOL_MAP[llmToolName] ?? dynamicToolMap.get(llmToolName);
+
+	if (!mapping) {
+		throw new Error(`Unknown tool: ${llmToolName}`);
+	}
+
+	return mapping;
+}