@keeveeg/godot-mcp 1.0.0

package/dist/tools/visual_testing.js

@@ -0,0 +1,81 @@
+/**
+ * Visual testing tools - 6 tools for visual regression testing
+ */
+import { callGodot } from '../server.js';
+import { z, Name, FilePath } from './shared-types.js';
+export function registerVisualTestingTools(server, bridge) {
+  // 1. take_screenshot_with_context
+  server.registerTool(
+    'take_screenshot_with_context',
+    {
+      description: 'Take a screenshot with scene context metadata (node tree, properties of specified nodes)',
+      inputSchema: {
+        name: Name.describe('Name for this screenshot (used as filename, e.g. "main_menu")'),
+        include_nodes: z.array(z.string()).optional().describe('Node paths to include property data for (requires include_props=true)'),
+        include_props: z.boolean().optional().default(false).describe('Whether to include property snapshots for listed include_nodes (default: false)'),
+      },
+    },
+    async (args) => callGodot(bridge, 'take_screenshot_with_context', args),
+  );
+  // 2. compare_screenshots
+  server.registerTool(
+    'compare_screenshots',
+    {
+      description: 'Compare two screenshots pixel-by-pixel and return a diff result with mismatch percentage',
+      inputSchema: {
+        baseline: FilePath.describe('Path to the baseline screenshot'),
+        current: FilePath.describe('Path to the current screenshot'),
+        threshold: z.number().min(0).max(1).optional().default(0.01).describe('Pixel difference threshold 0-1 (default: 0.01)'),
+      },
+    },
+    async (args) => callGodot(bridge, 'compare_screenshots', args),
+  );
+  // 3. assert_visual_match
+  server.registerTool(
+    'assert_visual_match',
+    {
+      description: 'Assert that a screenshot matches a baseline within a threshold - pass/fail result',
+      inputSchema: {
+        name: Name.describe('Screenshot name to check — must match a name previously used with take_screenshot_with_context'),
+        baseline: FilePath.describe('Path or name of the baseline screenshot (resolves against baselines directory if not a full path)'),
+        threshold: z.number().min(0).max(1).optional().default(0.01).describe('Acceptable difference threshold (default: 0.01)'),
+      },
+    },
+    async (args) => callGodot(bridge, 'assert_visual_match', args),
+  );
+  // 4. record_visual_regression
+  server.registerTool(
+    'record_visual_regression',
+    {
+      description: 'Record multiple frames over time for visual regression testing',
+      inputSchema: {
+        test_name: Name.describe('Name for this recording session'),
+        frames: z.number().int().min(1).max(100).optional().default(10).describe('Number of frames to capture (default: 10)'),
+        interval: z.number().min(0.1).max(10).optional().default(0.5).describe('Seconds between captures (default: 0.5)'),
+      },
+    },
+    async (args) => callGodot(bridge, 'record_visual_regression', args),
+  );
+  // 5. get_visual_diff_report
+  server.registerTool(
+    'get_visual_diff_report',
+    {
+      description: 'Get the aggregated visual regression report from all assert_visual_match calls in this session',
+      inputSchema: {},
+    },
+    async () => callGodot(bridge, 'get_visual_diff_report'),
+  );
+  // 6. set_visual_baseline
+  server.registerTool(
+    'set_visual_baseline',
+    {
+      description: 'Set or update a visual baseline for future comparisons',
+      inputSchema: {
+        name: Name.describe('Baseline name identifier'),
+        screenshot_path: FilePath.describe('Path to the screenshot to use as baseline'),
+      },
+    },
+    async (args) => callGodot(bridge, 'set_visual_baseline', args),
+  );
+}
+//# sourceMappingURL=visual_testing.js.map

package/dist/tools/visual_testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"visual_testing.js","sourceRoot":"","sources":["../../src/tools/visual_testing.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,77 @@
+/**
+ * TypeScript types for Godot MCP Server
+ *
+ * Shared Zod schemas and tool-result helpers live in tools/shared-types.ts.
+ * This file re-exports them for backward compatibility.
+ */
+export type { ToolContent, ToolResult } from './tools/shared-types.js';
+export { toolResult, errorResult } from './tools/shared-types.js';
+import type { ToolResult } from './tools/shared-types.js';
+/** @deprecated Use toolResult() from tools/shared-types.ts */
+export declare function createToolResult(text: string): ToolResult;
+/** @deprecated Use errorResult() from tools/shared-types.ts */
+export declare function createErrorResult(message: string): ToolResult;
+/** JSON-RPC 2.0 Request */
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id: string | number;
+    method: string;
+    params?: Record<string, unknown>;
+}
+/** JSON-RPC 2.0 Success Response */
+export interface JsonRpcSuccessResponse {
+    jsonrpc: '2.0';
+    id: string | number;
+    result: unknown;
+}
+/** JSON-RPC 2.0 Error Response */
+export interface JsonRpcErrorResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    error: JsonRpcError;
+}
+/** JSON-RPC 2.0 Error object */
+export interface JsonRpcError {
+    code: number;
+    message: string;
+    data?: unknown;
+}
+/** JSON-RPC 2.0 Response (union) */
+export type JsonRpcResponse = JsonRpcSuccessResponse | JsonRpcErrorResponse;
+/** JSON-RPC 2.0 Notification (no id) */
+export interface JsonRpcNotification {
+    jsonrpc: '2.0';
+    method: string;
+    params?: Record<string, unknown>;
+}
+/** Any JSON-RPC message */
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcResponse | JsonRpcNotification;
+/** Pending request tracking */
+export interface PendingRequest {
+    id: string | number;
+    method: string;
+    resolve: (value: unknown) => void;
+    reject: (reason: Error) => void;
+    timer: ReturnType<typeof setTimeout>;
+}
+/** Godot bridge connection state */
+export type ConnectionState = 'disconnected' | 'connecting' | 'connected';
+/** Bridge event types */
+export interface BridgeEvents {
+    connected: () => void;
+    disconnected: () => void;
+    error: (error: Error) => void;
+}
+/** Standard error codes for JSON-RPC */
+export declare const JsonRpcErrorCode: {
+    readonly PARSE_ERROR: -32700;
+    readonly INVALID_REQUEST: -32600;
+    readonly METHOD_NOT_FOUND: -32601;
+    readonly INVALID_PARAMS: -32602;
+    readonly INTERNAL_ERROR: -32603;
+};
+/** Type guard for JSON-RPC success response */
+export declare function isSuccessResponse(response: JsonRpcResponse): response is JsonRpcSuccessResponse;
+/** Type guard for JSON-RPC error response */
+export declare function isErrorResponse(response: JsonRpcResponse): response is JsonRpcErrorResponse;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACvE,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAGlE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D,8DAA8D;AAC9D,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAIzD;AAED,+DAA+D;AAC/D,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU,CAK7D;AAMD,2BAA2B;AAC3B,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,oCAAoC;AACpC,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IACpB,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,kCAAkC;AAClC,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,YAAY,CAAC;CACrB;AAED,gCAAgC;AAChC,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,oCAAoC;AACpC,MAAM,MAAM,eAAe,GAAG,sBAAsB,GAAG,oBAAoB,CAAC;AAE5E,wCAAwC;AACxC,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED,2BAA2B;AAC3B,MAAM,MAAM,cAAc,GAAG,cAAc,GAAG,eAAe,GAAG,mBAAmB,CAAC;AAEpF,+BAA+B;AAC/B,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC;IAClC,MAAM,EAAE,CAAC,MAAM,EAAE,KAAK,KAAK,IAAI,CAAC;IAChC,KAAK,EAAE,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC;CACtC;AAED,oCAAoC;AACpC,MAAM,MAAM,eAAe,GAAG,cAAc,GAAG,YAAY,GAAG,WAAW,CAAC;AAE1E,yBAAyB;AACzB,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,MAAM,IAAI,CAAC;IACtB,YAAY,EAAE,MAAM,IAAI,CAAC;IACzB,KAAK,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAC/B;AAED,wCAAwC;AACxC,eAAO,MAAM,gBAAgB;;;;;;CAMnB,CAAC;AAEX,+CAA+C;AAC/C,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,eAAe,GAAG,QAAQ,IAAI,sBAAsB,CAE/F;AAED,6CAA6C;AAC7C,wBAAgB,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,QAAQ,IAAI,oBAAoB,CAE3F"}

package/dist/types.js

@@ -0,0 +1,37 @@
+/**
+ * TypeScript types for Godot MCP Server
+ *
+ * Shared Zod schemas and tool-result helpers live in tools/shared-types.ts.
+ * This file re-exports them for backward compatibility.
+ */
+export { toolResult, errorResult } from './tools/shared-types.js';
+/** @deprecated Use toolResult() from tools/shared-types.ts */
+export function createToolResult(text) {
+  return {
+    content: [{ type: 'text', text }],
+  };
+}
+/** @deprecated Use errorResult() from tools/shared-types.ts */
+export function createErrorResult(message) {
+  return {
+    content: [{ type: 'text', text: message }],
+    isError: true,
+  };
+}
+/** Standard error codes for JSON-RPC */
+export const JsonRpcErrorCode = {
+  PARSE_ERROR: -32700,
+  INVALID_REQUEST: -32600,
+  METHOD_NOT_FOUND: -32601,
+  INVALID_PARAMS: -32602,
+  INTERNAL_ERROR: -32603,
+};
+/** Type guard for JSON-RPC success response */
+export function isSuccessResponse(response) {
+  return 'result' in response;
+}
+/** Type guard for JSON-RPC error response */
+export function isErrorResponse(response) {
+  return 'error' in response;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAKlE,8DAA8D;AAC9D,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC3C,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;KAClC,CAAC;AACJ,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QAC1C,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAmED,wCAAwC;AACxC,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,WAAW,EAAE,CAAC,KAAK;IACnB,eAAe,EAAE,CAAC,KAAK;IACvB,gBAAgB,EAAE,CAAC,KAAK;IACxB,cAAc,EAAE,CAAC,KAAK;IACtB,cAAc,EAAE,CAAC,KAAK;CACd,CAAC;AAEX,+CAA+C;AAC/C,MAAM,UAAU,iBAAiB,CAAC,QAAyB;IACzD,OAAO,QAAQ,IAAI,QAAQ,CAAC;AAC9B,CAAC;AAED,6CAA6C;AAC7C,MAAM,UAAU,eAAe,CAAC,QAAyB;IACvD,OAAO,OAAO,IAAI,QAAQ,CAAC;AAC7B,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@keeveeg/godot-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Godot Engine — 300+ AI-powered tools for game development",
+  "author": "KeeVeeG",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/KeeVeeG/godot-mcp",
+    "directory": "server"
+  },
+  "homepage": "https://keeveeg.github.io/godot-mcp",
+  "keywords": [
+    "godot",
+    "mcp",
+    "model-context-protocol",
+    "game-development",
+    "ai",
+    "godot-engine",
+    "gamedev"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "godot-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "ws": "^8.18.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.13",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}