godotbridge 1.0.0__tar.gz

godotbridge-1.0.0/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+.pytest_cache/
+
+# Godot
+.godot/
+*.import
+export_presets.cfg
+/.claude
+
+# scripts/test_tools.py fixture output — a fresh, uniquely-named directory
+# every run (see the script's own comments for why), never meant to be committed
+test/_test_tmp*
+
+# Web backend
+web/app/config.local.php
+web/vendor/

godotbridge-1.0.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.5
+Name: godotbridge
+Version: 1.0.0
+Summary: MCP server that lets AI agents (Claude, Cursor, Windsurf) inspect and control a Godot 4.x editor and running game. 345 tools across 36 categories.
+Project-URL: Homepage, https://godotbridge.dev
+Project-URL: Documentation, https://godotbridge.dev/docs
+Project-URL: Repository, https://github.com/godotbridge/releases
+Project-URL: Issues, https://github.com/godotbridge/releases/issues
+Project-URL: Changelog, https://github.com/godotbridge/releases/releases
+Author-email: DigitalFusion <info@digital-fusion.com.tr>
+License: Proprietary
+Keywords: ai,claude,cursor,gamedev,godot,mcp,windsurf
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Games/Entertainment
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'

godotbridge-1.0.0/pyproject.toml

@@ -0,0 +1,57 @@
+[project]
+name = "godotbridge"
+version = "1.0.0"
+description = "MCP server that lets AI agents (Claude, Cursor, Windsurf) inspect and control a Godot 4.x editor and running game. 345 tools across 36 categories."
+requires-python = ">=3.10"
+license = {text = "Proprietary"}
+authors = [
+    {name = "DigitalFusion", email = "info@digital-fusion.com.tr"},
+]
+keywords = ["godot", "mcp", "ai", "gamedev", "claude", "cursor", "windsurf"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: Other/Proprietary License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Games/Entertainment",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp>=1.2.0",
+    "websockets>=12.0",
+    "pyyaml>=6.0",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+]
+
+[project.urls]
+Homepage = "https://godotbridge.dev"
+Documentation = "https://godotbridge.dev/docs"
+Repository = "https://github.com/godotbridge/releases"
+Issues = "https://github.com/godotbridge/releases/issues"
+Changelog = "https://github.com/godotbridge/releases/releases"
+
+[project.scripts]
+godotbridge = "godot_mcp.__main__:main"
+godot-mcp = "godot_mcp.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/godot_mcp"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

godotbridge-1.0.0/src/godot_mcp/__main__.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+import logging
+
+from .server import build_server
+
+
+def main() -> None:
+    logging.basicConfig(level=logging.INFO)
+    mcp = build_server()
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

godotbridge-1.0.0/src/godot_mcp/bridge/__init__.py

@@ -0,0 +1,4 @@
+from .client import BridgeClient, get_default_client, set_default_client
+from .protocol import BridgeError
+
+__all__ = ["BridgeClient", "BridgeError", "get_default_client", "set_default_client"]

godotbridge-1.0.0/src/godot_mcp/bridge/client.py

@@ -0,0 +1,88 @@
+"""WebSocket client for the editor-channel bridge hosted by the Godot addon."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+
+from websockets.asyncio.client import ClientConnection, connect
+from websockets.exceptions import ConnectionClosed
+
+from .protocol import BridgeError, RequestCorrelator
+
+logger = logging.getLogger("godot_mcp.bridge")
+
+
+class BridgeClient:
+    """Auto-reconnecting client for ws://host:port (the editor channel).
+
+    The Godot editor addon is the long-lived side and hosts the server; this
+    client is spawned/torn down per MCP session, so it reconnects with backoff
+    whenever the editor isn't up yet or restarts mid-session.
+    """
+
+    def __init__(self, host: str = "127.0.0.1", port: int = 8765) -> None:
+        self._uri = f"ws://{host}:{port}"
+        self._correlator = RequestCorrelator()
+        self._connection: ClientConnection | None = None
+        self._recv_task: asyncio.Task | None = None
+        self._connect_lock = asyncio.Lock()
+
+    async def call(self, tool: str, params: dict | None = None, timeout: float | None = None) -> dict:
+        await self._ensure_connected()
+        request_id, payload = self._correlator.encode_request(tool, params or {})
+        assert self._connection is not None
+        try:
+            await self._connection.send(payload)
+        except ConnectionClosed as exc:
+            raise BridgeError("NOT_CONNECTED", "Lost connection to Godot editor bridge") from exc
+        return await self._correlator.wait_for(request_id, timeout)
+
+    async def close(self) -> None:
+        if self._recv_task is not None:
+            self._recv_task.cancel()
+            self._recv_task = None
+        if self._connection is not None:
+            await self._connection.close()
+            self._connection = None
+
+    async def _ensure_connected(self) -> None:
+        if self._connection is not None:
+            return
+        async with self._connect_lock:
+            if self._connection is not None:
+                return
+            try:
+                self._connection = await connect(self._uri, open_timeout=5)
+            except OSError as exc:
+                raise BridgeError(
+                    "NOT_CONNECTED",
+                    f"Could not reach Godot editor bridge at {self._uri}. Is the project open with the addon enabled?",
+                ) from exc
+            self._recv_task = asyncio.create_task(self._recv_loop())
+
+    async def _recv_loop(self) -> None:
+        assert self._connection is not None
+        try:
+            async for raw in self._connection:
+                self._correlator.resolve(raw)
+        except ConnectionClosed:
+            pass
+        finally:
+            self._correlator.fail_all("NOT_CONNECTED", "Connection to Godot editor bridge closed")
+            self._connection = None
+
+
+_default_client: BridgeClient | None = None
+
+
+def set_default_client(client: BridgeClient) -> None:
+    """Registers the process-wide bridge client used by the tools/* modules."""
+    global _default_client
+    _default_client = client
+
+
+def get_default_client() -> BridgeClient:
+    if _default_client is None:
+        raise RuntimeError("Bridge client not initialized — call set_default_client() during server startup")
+    return _default_client

godotbridge-1.0.0/src/godot_mcp/bridge/game_process.py

@@ -0,0 +1,61 @@
+"""Manages a Godot game process launched directly by this server, bypassing
+EditorInterface.play_custom_scene(). The editor-Play path spawns the game as
+a child of the *editor* process, and its stdout/stderr never reaches
+GDScript — confirmed empirically (see the project's EditorDebuggerPlugin
+capture experiment, which received zero messages from a played session).
+Launching the game as our own subprocess sidesteps that entirely: we own the
+pipes directly. The runtime probe autoload still connects back over the
+runtime channel as normal either way, so every other game_* tool keeps
+working unchanged against an instance launched this way.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections import deque
+
+_MAX_BUFFERED_LINES = 2000
+
+
+class GameProcess:
+    def __init__(self, process: asyncio.subprocess.Process) -> None:
+        self.process = process
+        self.stdout_lines: deque[str] = deque(maxlen=_MAX_BUFFERED_LINES)
+        self.stderr_lines: deque[str] = deque(maxlen=_MAX_BUFFERED_LINES)
+        assert process.stdout is not None and process.stderr is not None
+        self._stdout_task = asyncio.create_task(self._pump(process.stdout, self.stdout_lines))
+        self._stderr_task = asyncio.create_task(self._pump(process.stderr, self.stderr_lines))
+
+    @staticmethod
+    async def _pump(stream: asyncio.StreamReader, buffer: deque[str]) -> None:
+        while True:
+            line = await stream.readline()
+            if not line:
+                return
+            buffer.append(line.decode(errors="replace").rstrip("\r\n"))
+
+    def is_running(self) -> bool:
+        return self.process.returncode is None
+
+    async def stop(self) -> None:
+        if self.is_running():
+            self.process.terminate()
+            try:
+                await asyncio.wait_for(self.process.wait(), timeout=5)
+            except asyncio.TimeoutError:
+                self.process.kill()
+                await self.process.wait()
+        self._stdout_task.cancel()
+        self._stderr_task.cancel()
+
+
+_current: GameProcess | None = None
+
+
+def get_current() -> GameProcess | None:
+    return _current
+
+
+def set_current(proc: GameProcess | None) -> None:
+    global _current
+    _current = proc

godotbridge-1.0.0/src/godot_mcp/bridge/protocol.py

@@ -0,0 +1,79 @@
+"""Wire framing and request/response correlation for the editor-channel bridge.
+
+Matches protocol/MESSAGES.md: one JSON object per WebSocket text frame,
+`{id, tool, params}` requests answered by `{id, ok, result | error}` responses.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import uuid
+from dataclasses import dataclass
+
+
+class BridgeError(Exception):
+    """Raised when a tool call fails, times out, or the bridge isn't connected."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.message = message
+
+
+@dataclass
+class _PendingCall:
+    future: asyncio.Future
+
+
+class RequestCorrelator:
+    """Tracks in-flight requests by id and resolves them as responses arrive."""
+
+    def __init__(self, default_timeout: float = 10.0) -> None:
+        self._default_timeout = default_timeout
+        self._pending: dict[str, _PendingCall] = {}
+
+    def encode_request(self, tool: str, params: dict) -> tuple[str, str]:
+        request_id = str(uuid.uuid4())
+        payload = json.dumps({"id": request_id, "tool": tool, "params": params})
+        return request_id, payload
+
+    async def wait_for(self, request_id: str, timeout: float | None = None) -> dict:
+        loop = asyncio.get_running_loop()
+        future: asyncio.Future = loop.create_future()
+        self._pending[request_id] = _PendingCall(future=future)
+        try:
+            return await asyncio.wait_for(future, timeout or self._default_timeout)
+        except asyncio.TimeoutError as exc:
+            raise BridgeError("TIMEOUT", f"No response for '{request_id}' within timeout") from exc
+        finally:
+            self._pending.pop(request_id, None)
+
+    def resolve(self, raw_frame: str) -> None:
+        """Feed one received frame in; resolves the matching pending call, if any."""
+        try:
+            message = json.loads(raw_frame)
+        except json.JSONDecodeError:
+            return
+
+        request_id = message.get("id")
+        if request_id is None or request_id not in self._pending:
+            return
+
+        pending = self._pending[request_id]
+        if pending.future.done():
+            return
+
+        if message.get("ok"):
+            pending.future.set_result(message.get("result"))
+        else:
+            error = message.get("error", {})
+            pending.future.set_exception(
+                BridgeError(error.get("code", "UNKNOWN"), error.get("message", "no message"))
+            )
+
+    def fail_all(self, code: str, message: str) -> None:
+        """Fail every in-flight call, e.g. when the connection drops."""
+        for pending in list(self._pending.values()):
+            if not pending.future.done():
+                pending.future.set_exception(BridgeError(code, message))

godotbridge-1.0.0/src/godot_mcp/server.py

@@ -0,0 +1,49 @@
+"""Builds the FastMCP app and registers every tool from the manifest-driven registry."""
+
+from __future__ import annotations
+
+import functools
+import logging
+
+from mcp.server.fastmcp import FastMCP
+
+from .bridge.client import BridgeClient, set_default_client
+from .tools._licensing import LITE_CATEGORIES, is_tool_available, ensure_env_activation
+from .tools.registry import load_registry
+
+logger = logging.getLogger("godot_mcp.server")
+
+_UPGRADE_MSG = (
+    "This tool requires a GodotBridge Full license. "
+    "Call activate_license with your key, or visit https://godotbridge.dev to purchase one."
+)
+
+
+def _gated(handler, category: str):
+    """Wrap a tool handler so it checks the license at call time."""
+
+    @functools.wraps(handler)
+    async def wrapper(*args, **kwargs):
+        await ensure_env_activation()
+        if not is_tool_available(category):
+            return {"__error_code__": "UPGRADE_REQUIRED", "__error_message__": _UPGRADE_MSG}
+        return await handler(*args, **kwargs)
+
+    return wrapper
+
+
+def build_server(host: str = "127.0.0.1", port: int = 8765) -> FastMCP:
+    set_default_client(BridgeClient(host=host, port=port))
+
+    mcp = FastMCP("godot-mcp")
+    for spec in load_registry():
+        is_lite = spec.category in LITE_CATEGORIES
+        handler = spec.handler if is_lite else _gated(spec.handler, spec.category)
+        desc = spec.description or ""
+        if not is_lite:
+            desc = "[Full] " + desc
+        mcp.add_tool(handler, name=spec.name, description=desc or None)
+        logger.debug("Registered tool %s (phase %d, category %s, tier %s)",
+                      spec.name, spec.phase, spec.category, "lite" if is_lite else "full")
+
+    return mcp

godotbridge-1.0.0/src/godot_mcp/tools/_licensing.py

@@ -0,0 +1,257 @@
+"""Freemium licensing — Lite (free) / Full (paid) tier gating.
+
+Validates license keys against the LicenseManager API at
+``https://license.digital-fusion.com.tr``.  After a successful online
+activation the response (including the offline-until window) is cached
+in memory so the server keeps working without internet until that
+window expires.
+
+The active license is held in memory only, never persisted to disk.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import os
+import platform
+import uuid
+from datetime import datetime, timezone
+
+import httpx
+
+log = logging.getLogger(__name__)
+
+_BASE_URL = "https://license.digital-fusion.com.tr"
+_APPLICATION = "GodotBridge"
+_TIMEOUT = 15.0
+
+LITE_CATEGORIES: frozenset[str] = frozenset({
+    "api_reference",
+    "editor_interaction",
+    "file_operations",
+    "input_setup",
+    "node_composition",
+    "project_configuration",
+    "project_health",
+    "project_management",
+    "project_statistics",
+    "scene_analysis",
+    "script_management",
+    "signals_groups",
+})
+
+_license: dict | None = None
+_license_key: str = ""
+_fingerprint: str | None = None
+
+
+# ---------------------------------------------------------------------------
+# Machine fingerprint
+# ---------------------------------------------------------------------------
+
+def _machine_fingerprint() -> str:
+    global _fingerprint
+    if _fingerprint is not None:
+        return _fingerprint
+    raw = f"{platform.node()}|{platform.system()}|{platform.machine()}|{uuid.getnode()}"
+    _fingerprint = hashlib.sha256(raw.encode()).hexdigest()
+    return _fingerprint
+
+
+# ---------------------------------------------------------------------------
+# LicenseManager API calls
+# ---------------------------------------------------------------------------
+
+async def _api_activate(key: str) -> dict:
+    fp = _machine_fingerprint()
+    async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
+        resp = await client.post(
+            f"{_BASE_URL}/api/v2/license/activate",
+            json={
+                "LicenseKey": key,
+                "Application": _APPLICATION,
+                "FingerprintHash": fp,
+                "MachineName": platform.node(),
+                "OsName": f"{platform.system()} {platform.release()}",
+                "ActivationType": "AppDevice",
+            },
+        )
+        resp.raise_for_status()
+    return resp.json()
+
+
+async def _api_validate(key: str) -> dict:
+    fp = _machine_fingerprint()
+    async with httpx.AsyncClient(timeout=_TIMEOUT) as client:
+        resp = await client.post(
+            f"{_BASE_URL}/api/v2/license/validate",
+            json={
+                "LicenseKey": key,
+                "Application": _APPLICATION,
+                "FingerprintHash": fp,
+            },
+        )
+        resp.raise_for_status()
+    return resp.json()
+
+
+# ---------------------------------------------------------------------------
+# Response parsing helpers
+# ---------------------------------------------------------------------------
+
+_CODE_MAP = {
+    "InvalidKey": ("INVALID_LICENSE", "License key not found."),
+    "Expired": ("LICENSE_EXPIRED", "License has expired."),
+    "Revoked": ("LICENSE_REVOKED", "License has been revoked."),
+    "Suspended": ("LICENSE_SUSPENDED", "License has been suspended."),
+    "ActivationLimitReached": ("ACTIVATION_LIMIT", "Maximum activations reached. Deactivate another device first."),
+    "PendingPayment": ("PENDING_PAYMENT", "License is pending payment confirmation."),
+    "Cancelled": ("LICENSE_CANCELLED", "License has been cancelled."),
+}
+
+
+def _parse_response(api_resp: dict) -> dict:
+    """Convert a LicenseManager API response into our internal format."""
+    success = api_resp.get("Success", False)
+    code = api_resp.get("Code", "")
+    data = api_resp.get("Data") or {}
+
+    if not success:
+        mapped = _CODE_MAP.get(code, ("LICENSE_ERROR", api_resp.get("Message", "License validation failed.")))
+        return {"__error_code__": mapped[0], "__error_message__": mapped[1]}
+
+    can_run = data.get("CanRun", False)
+    if not can_run:
+        status = data.get("Status", code)
+        mapped = _CODE_MAP.get(status, ("LICENSE_ERROR", f"License cannot run: {status}"))
+        return {"__error_code__": mapped[0], "__error_message__": mapped[1]}
+
+    license_info = data.get("License") or {}
+    return {
+        "activated": True,
+        "tier": "full",
+        "email": license_info.get("CustomerEmail", ""),
+        "expires": license_info.get("ExpiresAt", "never"),
+        "license_type": license_info.get("LicenseType", ""),
+        "status": data.get("Status", "Active"),
+        "offline_until": data.get("OfflineUntil", ""),
+    }
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+async def activate(key: str) -> dict:
+    """Activate a license key via the LicenseManager API."""
+    global _license, _license_key
+
+    key = key.strip()
+    if not key:
+        return {"__error_code__": "INVALID_PARAMS", "__error_message__": "license_key must not be empty"}
+
+    try:
+        api_resp = await _api_activate(key)
+    except httpx.HTTPStatusError as exc:
+        return {
+            "__error_code__": "LICENSE_SERVER_ERROR",
+            "__error_message__": "License server returned HTTP %d" % exc.response.status_code,
+        }
+    except Exception as exc:
+        log.exception("License activation failed")
+        if _license is not None and _is_offline_valid():
+            return {**_license, "note": "Offline mode — using cached license."}
+        return {
+            "__error_code__": "LICENSE_SERVER_UNREACHABLE",
+            "__error_message__": "Could not reach license server: %s" % str(exc)[:200],
+        }
+
+    result = _parse_response(api_resp)
+    if result.get("activated"):
+        _license = result
+        _license_key = key
+    return result
+
+
+async def validate() -> dict:
+    """Re-validate the current license with the server."""
+    if not _license_key:
+        return {"__error_code__": "NO_LICENSE", "__error_message__": "No license activated."}
+
+    try:
+        api_resp = await _api_validate(_license_key)
+    except Exception:
+        if _license is not None and _is_offline_valid():
+            return {**_license, "note": "Offline mode — using cached license."}
+        return {"__error_code__": "LICENSE_SERVER_UNREACHABLE", "__error_message__": "Could not reach license server."}
+
+    result = _parse_response(api_resp)
+    if result.get("activated"):
+        global _license
+        _license = result
+    return result
+
+
+def deactivate() -> None:
+    global _license, _license_key
+    _license = None
+    _license_key = ""
+
+
+def _is_offline_valid() -> bool:
+    if _license is None:
+        return False
+    offline_until = _license.get("offline_until", "")
+    if not offline_until:
+        return False
+    try:
+        deadline = datetime.fromisoformat(offline_until.replace("Z", "+00:00"))
+        return datetime.now(timezone.utc) < deadline
+    except (ValueError, TypeError):
+        return False
+
+
+def get_tier() -> str:
+    if _license is not None and _license.get("tier") == "full":
+        if _is_offline_valid() or _license.get("activated"):
+            return "full"
+    return "lite"
+
+
+def get_info() -> dict:
+    tier = get_tier()
+    if _license is not None:
+        return {
+            "tier": tier,
+            "email": _license.get("email", ""),
+            "expires": _license.get("expires", ""),
+            "status": _license.get("status", ""),
+            "offline_until": _license.get("offline_until", ""),
+        }
+    return {"tier": "lite", "email": "", "expires": "", "status": "", "offline_until": ""}
+
+
+def is_tool_available(category: str) -> bool:
+    if category in LITE_CATEGORIES:
+        return True
+    return get_tier() == "full"
+
+
+_env_checked: bool = False
+
+
+async def ensure_env_activation() -> None:
+    """Auto-activate from GODOT_MCP_LICENSE_KEY on first call, then no-op."""
+    global _env_checked
+    if _env_checked:
+        return
+    _env_checked = True
+    key = os.environ.get("GODOT_MCP_LICENSE_KEY", "").strip()
+    if not key:
+        return
+    result = await activate(key)
+    if result.get("activated"):
+        log.info("License auto-activated from GODOT_MCP_LICENSE_KEY (tier: full)")
+    else:
+        log.warning("GODOT_MCP_LICENSE_KEY activation failed: %s", result.get("__error_message__", "unknown"))