cocos-web-inspector-mcp 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 el1pn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,186 @@
+# cocos-web-inspector-mcp
+
+Read-only MCP server for inspecting Cocos Creator 3.x games running in a local Chromium browser.
+
+## Scope
+
+The current MVP supports:
+
+- Chromium connected through a loopback Chrome DevTools Protocol (CDP) endpoint
+- Cocos Creator 3.x web builds served from loopback
+- stdio MCP transport
+- Scene, node, component, and public-property inspection
+- Temporary DOM-only node highlighting
+
+It does not edit Cocos game state, launch browsers, expose browser network/storage data, or support Firefox/WebKit.
+
+## Requirements
+
+- Node.js 20+
+- A Chromium browser started with remote debugging bound to loopback
+- A Cocos Creator 3.x web build served from loopback
+
+Start Chrome on Windows with a disposable profile:
+
+```powershell
+chrome.exe --remote-debugging-address=127.0.0.1 --remote-debugging-port=9222 --user-data-dir="$env:TEMP\cocos-mcp-profile"
+```
+
+Keep this browser profile separate from normal browsing. CDP provides code-execution-level access to attached pages.
+
+## Install and run
+
+Clone the repository, then install and build it:
+
+```powershell
+npm install
+npm run build
+```
+
+Run with the default CDP endpoint, `http://127.0.0.1:9222`:
+
+```powershell
+npm start
+```
+
+Run with an explicit endpoint:
+
+```powershell
+npm start -- --cdp-endpoint http://127.0.0.1:9222
+```
+
+Endpoint precedence is:
+
+1. `--cdp-endpoint`
+2. `COCOS_CDP_ENDPOINT`
+3. `http://127.0.0.1:9222`
+
+`--cdp-endpoint` is the only supported CLI option. It identifies the browser CDP endpoint, not a game page URL.
+
+The server uses stdio for MCP. Standard output is reserved for protocol traffic; startup diagnostics are written to standard error.
+
+## MCP configuration
+
+Build the project first, then replace `<absolute-path-to-repository>` with the cloned repository path:
+
+```json
+{
+  "mcpServers": {
+    "cocos-web-inspector": {
+      "command": "node",
+      "args": [
+        "<absolute-path-to-repository>/dist/src/index.js",
+        "--cdp-endpoint",
+        "http://127.0.0.1:9222"
+      ]
+    }
+  }
+}
+```
+
+Forward slashes work in Windows JSON paths. If backslashes are used, escape each one as `\\`.
+
+The endpoint may instead be provided through the MCP process environment:
+
+```json
+{
+  "mcpServers": {
+    "cocos-web-inspector": {
+      "command": "node",
+      "args": ["<absolute-path-to-repository>/dist/src/index.js"],
+      "env": {
+        "COCOS_CDP_ENDPOINT": "http://127.0.0.1:9222"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+All tool input objects are strict. Unknown fields are rejected. Inspection tools are annotated as read-only, idempotent, non-destructive, and closed-world. The highlight tool is annotated as a non-destructive, non-idempotent, closed-world temporary mutation because repeated calls reset its removal timer.
+
+| Tool | Purpose | Inputs |
+| --- | --- | --- |
+| `cocos_scene_tree` | Return a bounded scene tree with node and component summaries. | `pageUrl?`; `maxDepth?` integer `0..20`, default `6`; `maxNodes?` integer `1..5000`, default `500` |
+| `cocos_find_node` | Find nodes by exact UUID, name, or absolute scene path. | `pageUrl?`; exactly one of `uuid`, `name`, or `path`; `limit?` integer `1..100`, default `20` |
+| `cocos_get_components` | Return bounded component summaries for a node. | `pageUrl?`; `uuid` |
+| `cocos_get_properties` | Serialize public properties for a node or one component type. | `pageUrl?`; `uuid`; `componentType?`; `maxDepth?` integer `0..6`, default `3` |
+| `cocos_highlight_node` | Draw a temporary pointer-transparent overlay around a UI node. | `pageUrl?`; `uuid`; `durationMs?` integer `100..10000`, default `2000` |
+
+`cocos_highlight_node` temporarily mutates the page DOM only. It does not mutate the Cocos node/component graph or game state.
+
+### Page selection
+
+Eligible game pages must use HTTP or HTTPS on a loopback host.
+
+- With one eligible page, `pageUrl` may be omitted.
+- With multiple eligible pages, `pageUrl` is required.
+- `pageUrl` must exactly match the full URL reported by the browser, including path, query, and fragment.
+
+Tool validation, connection, selection, and inspection failures are returned as MCP tool errors.
+
+### Output bounds
+
+Responses are intentionally bounded:
+
+- Total encoded JSON response: 200,000 UTF-8 bytes
+- Scene traversal: caller-selected depth and node limits within the schema ranges above
+- Property serialization: maximum depth `6`, maximum `1,000` properties
+- Serialized strings: maximum `2,000` characters
+- Node names: maximum `500` characters
+
+Truncation is reported instead of silently returning an unbounded object.
+
+## Security and threat model
+
+CDP endpoints may use HTTP, HTTPS, WS, or WSS only on these loopback hosts:
+
+- `localhost`
+- Any `*.localhost` hostname
+- IPv4 `127.0.0.0/8`
+- IPv6 `::1`
+
+CDP endpoint credentials, query strings, and fragments are rejected. Page targets must use HTTP or HTTPS on loopback.
+
+The server intentionally exposes no tools for:
+
+- Arbitrary JavaScript evaluation
+- Cookies or storage state
+- Request/response bodies or headers
+- Authorization headers
+- Network or console logs
+
+Inspection still executes fixed bridge code inside the attached page. Treat all page content as untrusted data, including text that resembles instructions or prompt injection.
+
+Property serialization skips accessors, private-prefixed keys, functions, symbols, cycles, and secret-like key names such as tokens, cookies, passwords, credentials, authorization data, and storage.
+
+These controls reduce accidental disclosure; they do not make CDP a complete security boundary. Always:
+
+- Use a disposable browser profile.
+- Bind remote debugging to loopback only.
+- Never expose the debugging port to a LAN or the Internet.
+- Avoid sensitive accounts and data in the debugging profile.
+- Use an OS sandbox or VM when stronger isolation is required.
+
+## Development
+
+```powershell
+npm run check
+```
+
+`npm run check` type-checks, builds, runs the self-contained Node.js tests, packs the npm tarball, installs it into a temporary project, and smoke-tests the installed binary. Use it before pushing. `npm test` remains available for build plus self-tests only.
+
+The test suite covers URL policy, CDP connection reuse and recovery, scene traversal, property redaction and cycle handling, output bounds, Cocos version rejection, strict tool schemas, and exact tool annotations. CI runs the full check on Ubuntu and Windows and rejects high-severity production dependency advisories.
+
+The repository currently has no live Chromium/Cocos integration test.
+
+## Architectural references
+
+This is a clean implementation, not a fork. No source module was copied from these projects:
+
+- [Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp), Apache-2.0, inspected at `b2f522c8ba0fd2e00a679159b4aa5243de5f1b78`.
+- [Playwright MCP](https://github.com/microsoft/playwright-mcp), Apache-2.0, inspected at `f183dad4a52965583e3cc1d59b88cdc279e2e57d`.
+- [CC Inspector](https://github.com/qq790git/cc-inspector), MIT, inspected at `ef5ef0ae033ee6a6ae496cf566fe5d91cf05aafd`.
+
+They informed MCP tool design, CDP connection constraints, Cocos runtime discovery, bounded responses, and highlight behavior. Their license files remain in separate read-only reference clones and are not redistributed here because this repository contains independently written code.

package/dist/src/bridge.d.ts

@@ -0,0 +1,26 @@
+import type { Page } from 'playwright-core';
+export type BridgeRequest = {
+    action: 'sceneTree';
+    maxDepth?: number | undefined;
+    maxNodes?: number | undefined;
+} | {
+    action: 'findNode';
+    uuid?: string | undefined;
+    name?: string | undefined;
+    path?: string | undefined;
+    limit?: number | undefined;
+} | {
+    action: 'getComponents';
+    uuid: string;
+} | {
+    action: 'getProperties';
+    uuid: string;
+    componentType?: string | undefined;
+    maxDepth?: number | undefined;
+} | {
+    action: 'highlightNode';
+    uuid: string;
+    durationMs?: number | undefined;
+};
+export declare function runBridge(page: Page, request: BridgeRequest): Promise<unknown>;
+export declare function inspectCocos(request: BridgeRequest): unknown;

package/dist/src/bridge.js

@@ -0,0 +1,307 @@
+const MAX_BYTES = 200_000;
+export async function runBridge(page, request) {
+    const result = await page.evaluate(inspectCocos, request);
+    const text = JSON.stringify(result);
+    const encoded = JSON.stringify({ content: [{ type: 'text', text }], structuredContent: result });
+    if (Buffer.byteLength(encoded, 'utf8') > MAX_BYTES - 4_096) {
+        return { truncated: true, reason: `Response exceeded ${MAX_BYTES} bytes` };
+    }
+    return result;
+}
+export function inspectCocos(request) {
+    const root = globalThis;
+    if (root.location) {
+        const target = new URL(root.location.href);
+        const host = target.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+        const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+        const loopback = host === 'localhost' || host.endsWith('.localhost') || host === '::1'
+            || !!ipv4 && ipv4.slice(1).every(part => Number(part) <= 255) && ipv4[1] === '127';
+        if (!['http:', 'https:'].includes(target.protocol) || !loopback)
+            throw new Error('Only localhost pages are allowed');
+    }
+    const cc = root.cc ?? root.CC;
+    const version = String(cc?.ENGINE_VERSION ?? cc?.version ?? '');
+    if (!cc || !version.startsWith('3.'))
+        throw new Error('Cocos Creator 3.x runtime not found');
+    const scene = cc.director?.getScene?.();
+    if (!scene)
+        throw new Error('Active Cocos scene not found');
+    const sensitiveParts = ['token', 'cookie', 'authorization', 'password', 'secret', 'credential', 'storage', 'jwt', 'apikey', 'privatekey', 'accesskey', 'signingkey', 'authheader'];
+    const isSensitiveKey = (key) => {
+        const normalized = key.toLowerCase().replace(/[^a-z]/g, '');
+        return sensitiveParts.some(part => normalized.includes(part))
+            || normalized.includes('bearer')
+            || normalized.startsWith('session') && ['id', 'key', 'token'].some(part => normalized.includes(part));
+    };
+    const dataProperty = (value, key) => {
+        let current = value;
+        const prototypes = new Set();
+        for (let depth = 0; current && depth < 20 && !prototypes.has(current); depth++) {
+            prototypes.add(current);
+            const descriptor = Object.getOwnPropertyDescriptor(current, key);
+            if (descriptor)
+                return 'value' in descriptor ? descriptor.value : undefined;
+            current = Object.getPrototypeOf(current);
+        }
+        return undefined;
+    };
+    const componentName = (component) => {
+        // ponytail: constructor metadata is the compatibility ceiling; add explicit engine adapters if minified builds need more.
+        const name = dataProperty(component, 'constructor')?.name || dataProperty(component, '__classname__') || 'Component';
+        return String(name).replace(/^cc\./, '').slice(0, 120);
+    };
+    const components = (node) => {
+        const value = node?.components;
+        return Array.isArray(value) ? value.filter(Boolean) : [];
+    };
+    const children = (node) => {
+        const value = node?.children;
+        return Array.isArray(value) ? value.filter(Boolean) : [];
+    };
+    const summary = (node) => ({
+        uuid: String(node?.uuid ?? ''),
+        name: String(node?.name ?? '').slice(0, 500),
+        active: node?.active !== false,
+        activeInHierarchy: node?.activeInHierarchy !== false,
+        componentTypes: components(node).slice(0, 100).map(componentName),
+    });
+    const walk = (visit, limit = 5_000) => {
+        const stack = [{ node: scene, path: `/${String(scene.name ?? '')}`, depth: 0 }];
+        const seen = new Set();
+        let count = 0;
+        let truncated = false;
+        while (stack.length && count < limit) {
+            const current = stack.pop();
+            if (!current.node || seen.has(current.node))
+                continue;
+            seen.add(current.node);
+            count++;
+            if (visit(current.node, current.path, current.depth) === false)
+                return { truncated: false };
+            const next = children(current.node);
+            const start = Math.max(0, next.length - (limit - stack.length));
+            if (start > 0)
+                truncated = true;
+            for (let index = next.length - 1; index >= start; index--) {
+                const child = next[index];
+                const childName = String(child?.name ?? '').slice(0, 500);
+                const childPath = `${current.path}/${childName}`;
+                stack.push({ node: child, path: childPath.length <= 10_000 ? childPath : `${childPath.slice(0, 9_999)}…`, depth: current.depth + 1 });
+            }
+        }
+        return { truncated: truncated || stack.length > 0 };
+    };
+    const findByUuid = (uuid) => {
+        let match;
+        const traversal = walk(node => {
+            if (node?.uuid === uuid) {
+                match = node;
+                return false;
+            }
+        });
+        if (!match)
+            throw new Error(traversal.truncated ? 'Node not found within traversal limit' : 'Node not found');
+        return match;
+    };
+    if (request.action === 'sceneTree') {
+        const maxDepth = Math.min(Math.max(request.maxDepth ?? 6, 0), 20);
+        const maxNodes = Math.min(Math.max(request.maxNodes ?? 500, 1), 5_000);
+        let count = 0;
+        let truncated = false;
+        const build = (node, depth, seen) => {
+            if (count >= maxNodes) {
+                truncated = true;
+                return undefined;
+            }
+            count++;
+            const item = summary(node);
+            if (depth >= maxDepth) {
+                if (children(node).length)
+                    truncated = true;
+                return item;
+            }
+            if (seen.has(node))
+                return { ...item, circular: true };
+            seen.add(node);
+            item.children = [];
+            for (const child of children(node)) {
+                if (count >= maxNodes) {
+                    truncated = true;
+                    break;
+                }
+                const built = build(child, depth + 1, seen);
+                if (built)
+                    item.children.push(built);
+            }
+            seen.delete(node);
+            return item;
+        };
+        return { version, scene: build(scene, 0, new Set()), nodeCount: count, truncated };
+    }
+    if (request.action === 'findNode') {
+        if (![request.uuid, request.name, request.path].filter(Boolean).length)
+            throw new Error('uuid, name, or path is required');
+        const limit = Math.min(Math.max(request.limit ?? 20, 1), 100);
+        const matches = [];
+        let more = false;
+        const traversal = walk((node, path) => {
+            const matched = request.uuid ? node?.uuid === request.uuid
+                : request.path ? path === request.path
+                    : node?.name === request.name;
+            if (matched) {
+                if (matches.length < limit)
+                    matches.push({ ...summary(node), path });
+                else {
+                    more = true;
+                    return false;
+                }
+            }
+        });
+        return { version, matches, ambiguous: matches.length > 1 || more, truncated: more || traversal.truncated };
+    }
+    if (request.action === 'getComponents') {
+        const node = findByUuid(request.uuid);
+        return {
+            version,
+            node: summary(node),
+            components: components(node).slice(0, 200).map(component => ({
+                type: componentName(component),
+                uuid: String(component.uuid ?? ''),
+                enabled: component.enabled !== false,
+            })),
+            truncated: components(node).length > 200,
+        };
+    }
+    if (request.action === 'getProperties') {
+        const node = findByUuid(request.uuid);
+        const selected = request.componentType
+            ? components(node).find(component => componentName(component) === request.componentType)
+            : node;
+        if (!selected)
+            throw new Error('Component not found');
+        const maxDepth = Math.min(Math.max(request.maxDepth ?? 3, 0), 6);
+        let propertyCount = 0;
+        let truncated = false;
+        const seen = new WeakSet();
+        const serialize = (value, depth, reference = true) => {
+            if (value === null || typeof value === 'boolean' || typeof value === 'number')
+                return value;
+            if (typeof value === 'string') {
+                if (value.length > 2_000)
+                    truncated = true;
+                return value.slice(0, 2_000);
+            }
+            if (typeof value !== 'object')
+                return undefined;
+            const uuid = dataProperty(value, 'uuid');
+            if (reference && uuid && Array.isArray(dataProperty(value, 'children'))) {
+                return { $type: 'Node', uuid: String(uuid), name: String(dataProperty(value, 'name') ?? '').slice(0, 500) };
+            }
+            if (reference && uuid && dataProperty(value, 'node'))
+                return { $type: 'Component', uuid: String(uuid), type: componentName(value) };
+            if (depth >= maxDepth) {
+                truncated = true;
+                return '[MaxDepth]';
+            }
+            if (seen.has(value)) {
+                truncated = true;
+                return '[Circular]';
+            }
+            seen.add(value);
+            const output = Array.isArray(value) ? [] : {};
+            let inspected = 0;
+            for (const key in value) {
+                if (!Object.prototype.hasOwnProperty.call(value, key))
+                    continue;
+                inspected++;
+                if (inspected > 1_000) {
+                    truncated = true;
+                    break;
+                }
+                if (propertyCount >= 1_000) {
+                    truncated = true;
+                    break;
+                }
+                propertyCount++;
+                if (key.startsWith('_') || isSensitiveKey(key))
+                    continue;
+                const descriptor = Object.getOwnPropertyDescriptor(value, key);
+                if (!descriptor || !('value' in descriptor))
+                    continue;
+                const item = serialize(descriptor.value, depth + 1);
+                if (item !== undefined) {
+                    if (Array.isArray(output)) {
+                        const index = Number(key);
+                        if (Number.isInteger(index) && index >= 0 && index < 1_000)
+                            output[index] = item;
+                        else
+                            truncated = true;
+                    }
+                    else
+                        output[key] = item;
+                }
+            }
+            seen.delete(value);
+            return output;
+        };
+        return { version, node: summary(node), componentType: request.componentType, properties: serialize(selected, 0, false), truncated, propertyCount };
+    }
+    const node = findByUuid(request.uuid);
+    const document = root.document;
+    if (!document?.body)
+        throw new Error('Page document is unavailable');
+    const transform = components(node).find(component => componentName(component) === 'UITransform');
+    if (!transform?.contentSize || !transform?.anchorPoint)
+        throw new Error('Node has no UITransform');
+    const canvas = cc.game?.canvas ?? document.querySelector('#GameCanvas');
+    if (!(canvas instanceof HTMLCanvasElement))
+        throw new Error('Cocos canvas not found');
+    const canvasRect = canvas.getBoundingClientRect();
+    const visible = cc.view?.getVisibleSize?.() ?? { width: canvasRect.width, height: canvasRect.height };
+    const position = node.worldPosition ?? node.getWorldPosition?.();
+    if (!position)
+        throw new Error('Node world position is unavailable');
+    const scale = node.worldScale ?? node.scale ?? { x: 1, y: 1 };
+    const localWidth = Number(transform.contentSize.width);
+    const localHeight = Number(transform.contentSize.height);
+    const anchorX = Number(transform.anchorPoint.x);
+    const anchorY = Number(transform.anchorPoint.y);
+    const left = -localWidth * anchorX;
+    const bottom = -localHeight * anchorY;
+    const points = typeof transform.convertToWorldSpaceAR === 'function' && cc.Vec3
+        ? [[left, bottom], [left + localWidth, bottom], [left, bottom + localHeight], [left + localWidth, bottom + localHeight]]
+            .map(([x, y]) => transform.convertToWorldSpaceAR(new cc.Vec3(x, y, 0)))
+        : [{ x: Number(position.x) + left * Number(scale.x ?? 1), y: Number(position.y) + bottom * Number(scale.y ?? 1) },
+            { x: Number(position.x) + (left + localWidth) * Number(scale.x ?? 1), y: Number(position.y) + (bottom + localHeight) * Number(scale.y ?? 1) }];
+    const worldX = Math.min(...points.map(point => Number(point.x)));
+    const worldY = Math.min(...points.map(point => Number(point.y)));
+    const width = Math.max(...points.map(point => Number(point.x))) - worldX;
+    const height = Math.max(...points.map(point => Number(point.y))) - worldY;
+    const visibleOrigin = cc.view?.getVisibleOrigin?.() ?? { x: 0, y: 0 };
+    const scaleX = canvasRect.width / Number(visible.width);
+    const scaleY = canvasRect.height / Number(visible.height);
+    const bounds = {
+        x: canvasRect.left + (worldX - Number(visibleOrigin.x ?? 0)) * scaleX,
+        y: canvasRect.top + (Number(visibleOrigin.y ?? 0) + Number(visible.height) - worldY - height) * scaleY,
+        width: width * scaleX,
+        height: height * scaleY,
+    };
+    let overlay = root.__cocosWebInspectorOverlay;
+    if (!overlay?.isConnected) {
+        overlay = document.createElement('div');
+        root.__cocosWebInspectorOverlay = overlay;
+        document.body.appendChild(overlay);
+    }
+    Object.assign(overlay.style, {
+        position: 'fixed', pointerEvents: 'none', zIndex: '2147483647', boxSizing: 'border-box',
+        border: '2px solid #27c2ff', background: 'rgba(39, 194, 255, 0.2)',
+        left: `${bounds.x}px`, top: `${bounds.y}px`, width: `${bounds.width}px`, height: `${bounds.height}px`,
+    });
+    clearTimeout(root.__cocosWebInspectorHighlightTimer);
+    root.__cocosWebInspectorHighlightTimer = setTimeout(() => {
+        overlay?.remove();
+        if (root.__cocosWebInspectorOverlay === overlay)
+            root.__cocosWebInspectorOverlay = undefined;
+    }, Math.min(Math.max(request.durationMs ?? 2_000, 100), 10_000));
+    return { version, uuid: request.uuid, highlighted: true, bounds };
+}

package/dist/src/browser.d.ts

@@ -0,0 +1,14 @@
+import { type Browser, type Page } from 'playwright-core';
+export declare function validateLocalUrl(raw: string, page?: boolean): URL;
+export declare function sanitizeUrl(raw: string): string;
+export declare class BrowserConnection {
+    #private;
+    private readonly endpoint;
+    private readonly timeout;
+    private readonly connectOverCDP;
+    constructor(endpoint: string, timeout?: number, connectOverCDP?: (endpoint: string, options: {
+        timeout: number;
+    }) => Promise<Browser>);
+    page(pageUrl?: string): Promise<Page>;
+    close(): Promise<void>;
+}

package/dist/src/browser.js

@@ -0,0 +1,126 @@
+import { chromium } from 'playwright-core';
+const LOOPBACK_PROTOCOLS = new Set(['http:', 'https:', 'ws:', 'wss:']);
+const PAGE_PROTOCOLS = new Set(['http:', 'https:']);
+function isLoopbackHostname(hostname) {
+    const host = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+    if (host === 'localhost' || host.endsWith('.localhost') || host === '::1')
+        return true;
+    const match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);
+    return !!match && match.slice(1).every(part => Number(part) <= 255) && match[1] === '127';
+}
+export function validateLocalUrl(raw, page = false) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error('Invalid URL');
+    }
+    const protocols = page ? PAGE_PROTOCOLS : LOOPBACK_PROTOCOLS;
+    if (!protocols.has(url.protocol))
+        throw new Error(`Unsupported ${page ? 'page' : 'CDP'} URL protocol`);
+    if (url.username || url.password)
+        throw new Error('URL credentials are not allowed');
+    if (!page && (url.search || url.hash))
+        throw new Error('CDP URL query and fragment are not allowed');
+    if (!isLoopbackHostname(url.hostname))
+        throw new Error('Only localhost targets are allowed');
+    return url;
+}
+export function sanitizeUrl(raw) {
+    try {
+        const url = new URL(raw);
+        url.username = '';
+        url.password = '';
+        url.search = '';
+        url.hash = '';
+        return url.toString().slice(0, 2_000);
+    }
+    catch {
+        return '<invalid-url>';
+    }
+}
+export class BrowserConnection {
+    endpoint;
+    timeout;
+    connectOverCDP;
+    #browser;
+    #connecting;
+    #closed = false;
+    constructor(endpoint, timeout = 10_000, connectOverCDP = (target, options) => chromium.connectOverCDP(target, options)) {
+        this.endpoint = endpoint;
+        this.timeout = timeout;
+        this.connectOverCDP = connectOverCDP;
+        validateLocalUrl(endpoint);
+    }
+    async page(pageUrl) {
+        if (this.#closed)
+            throw new Error('Browser connection is closed');
+        const browser = await this.#connect();
+        if (this.#closed)
+            throw new Error('Browser connection is closed');
+        const pages = browser.contexts().flatMap(context => context.pages()).filter(candidate => {
+            try {
+                validateLocalUrl(candidate.url(), true);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        if (pageUrl) {
+            const wanted = validateLocalUrl(pageUrl, true).href;
+            const selected = pages.filter(candidate => new URL(candidate.url()).href === wanted);
+            if (selected.length === 0)
+                throw new Error(`Local page not found: ${sanitizeUrl(pageUrl)}`);
+            if (selected.length > 1)
+                throw new Error(`Multiple localhost pages match pageUrl: ${sanitizeUrl(pageUrl)}`);
+            return selected[0];
+        }
+        if (pages.length === 0)
+            throw new Error('No localhost page is attached to Chromium');
+        if (pages.length > 1) {
+            const choices = pages.slice(0, 10).map(candidate => sanitizeUrl(candidate.url())).join(', ');
+            throw new Error(`Multiple localhost pages found; pass pageUrl: ${choices}`);
+        }
+        return pages[0];
+    }
+    async close() {
+        this.#closed = true;
+        const current = this.#browser;
+        const connecting = this.#connecting;
+        this.#browser = undefined;
+        const pending = await connecting?.catch(() => undefined);
+        if (this.#browser === pending)
+            this.#browser = undefined;
+        await Promise.all([...new Set([current, pending].filter((browser) => !!browser))].map(browser => browser.close()));
+    }
+    async #connect() {
+        if (this.#closed)
+            throw new Error('Browser connection is closed');
+        if (this.#browser?.isConnected())
+            return this.#browser;
+        if (this.#connecting)
+            return this.#connecting;
+        const connecting = this.connectOverCDP(this.endpoint, { timeout: this.timeout }).then(async (browser) => {
+            if (this.#closed) {
+                await browser.close();
+                throw new Error('Browser connection is closed');
+            }
+            this.#browser = browser;
+            browser.on('disconnected', () => {
+                if (this.#browser === browser)
+                    this.#browser = undefined;
+            });
+            return browser;
+        });
+        this.#connecting = connecting;
+        try {
+            return await connecting;
+        }
+        finally {
+            if (this.#connecting === connecting)
+                this.#connecting = undefined;
+        }
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/index.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { BrowserConnection } from './browser.js';
+import { createServer } from './server.js';
+function endpointFromArgs(args) {
+    const index = args.indexOf('--cdp-endpoint');
+    if (index !== -1) {
+        const value = args[index + 1];
+        if (!value)
+            throw new Error('--cdp-endpoint requires a value');
+        return value;
+    }
+    const unknown = args.find(arg => arg.startsWith('-'));
+    if (unknown)
+        throw new Error(`Unknown argument: ${unknown}`);
+    return process.env.COCOS_CDP_ENDPOINT ?? 'http://127.0.0.1:9222';
+}
+async function main() {
+    const browser = new BrowserConnection(endpointFromArgs(process.argv.slice(2)));
+    const server = createServer(browser);
+    let closing = false;
+    const close = async () => {
+        if (closing)
+            return;
+        closing = true;
+        await Promise.allSettled([browser.close(), server.close()]);
+    };
+    process.once('SIGINT', () => void close());
+    process.once('SIGTERM', () => void close());
+    await server.connect(new StdioServerTransport());
+}
+main().catch(error => {
+    process.stderr.write(`${error instanceof Error ? error.message : 'Failed to start server'}\n`);
+    process.exitCode = 1;
+});

package/dist/src/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { BrowserConnection } from './browser.js';
+export declare function createServer(browser: BrowserConnection): McpServer;

package/dist/src/server.js

@@ -0,0 +1,54 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { runBridge } from './bridge.js';
+const pageUrl = z.url().optional();
+const readOnly = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+const temporaryMutation = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
+function response(data) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(data) }],
+        structuredContent: data,
+    };
+}
+function failure(error) {
+    const message = error instanceof Error ? error.message : 'Inspector request failed';
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+export function createServer(browser) {
+    const server = new McpServer({ name: 'cocos-web-inspector-mcp', version: '0.1.1' });
+    const execute = async (request, selectedPage) => {
+        try {
+            return response(await runBridge(await browser.page(selectedPage), request));
+        }
+        catch (error) {
+            return failure(error);
+        }
+    };
+    server.registerTool('cocos_scene_tree', {
+        description: 'Return a bounded Cocos Creator 3.x scene tree from a localhost Chromium page.',
+        inputSchema: z.object({ pageUrl, maxDepth: z.number().int().min(0).max(20).optional(), maxNodes: z.number().int().min(1).max(5_000).optional() }).strict(),
+        annotations: readOnly,
+    }, input => execute({ action: 'sceneTree', maxDepth: input.maxDepth, maxNodes: input.maxNodes }, input.pageUrl));
+    server.registerTool('cocos_find_node', {
+        description: 'Find Cocos nodes by exact UUID, name, or absolute scene path.',
+        inputSchema: z.object({ pageUrl, uuid: z.string().min(1).optional(), name: z.string().min(1).optional(), path: z.string().min(1).optional(), limit: z.number().int().min(1).max(100).optional() }).strict()
+            .refine(value => [value.uuid, value.name, value.path].filter(Boolean).length === 1, 'Provide exactly one of uuid, name, or path'),
+        annotations: readOnly,
+    }, input => execute({ action: 'findNode', uuid: input.uuid, name: input.name, path: input.path, limit: input.limit }, input.pageUrl));
+    server.registerTool('cocos_get_components', {
+        description: 'List bounded component summaries for one Cocos node UUID.',
+        inputSchema: z.object({ pageUrl, uuid: z.string().min(1) }).strict(),
+        annotations: readOnly,
+    }, input => execute({ action: 'getComponents', uuid: input.uuid }, input.pageUrl));
+    server.registerTool('cocos_get_properties', {
+        description: 'Read bounded, cycle-safe public properties from a Cocos node or component.',
+        inputSchema: z.object({ pageUrl, uuid: z.string().min(1), componentType: z.string().min(1).optional(), maxDepth: z.number().int().min(0).max(6).optional() }).strict(),
+        annotations: readOnly,
+    }, input => execute({ action: 'getProperties', uuid: input.uuid, componentType: input.componentType, maxDepth: input.maxDepth }, input.pageUrl));
+    server.registerTool('cocos_highlight_node', {
+        description: 'Temporarily draw a pointer-transparent DOM overlay around one Cocos UI node.',
+        inputSchema: z.object({ pageUrl, uuid: z.string().min(1), durationMs: z.number().int().min(100).max(10_000).optional() }).strict(),
+        annotations: temporaryMutation,
+    }, input => execute({ action: 'highlightNode', uuid: input.uuid, durationMs: input.durationMs }, input.pageUrl));
+    return server;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "cocos-web-inspector-mcp",
+  "version": "0.1.1",
+  "description": "Read-only MCP inspector for Cocos Creator 3.x running in local Chromium",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/el1pn/cocos-web-inspector-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/el1pn/cocos-web-inspector-mcp/issues"
+  },
+  "homepage": "https://github.com/el1pn/cocos-web-inspector-mcp#readme",
+  "type": "module",
+  "bin": {
+    "cocos-web-inspector-mcp": "dist/src/index.js"
+  },
+  "files": [
+    "dist/src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test:built": "node --test dist/test/self-test.js",
+    "test": "npm run build && npm run test:built",
+    "test:package": "node test/package-test.mjs",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "prepack": "npm run clean && npm run build",
+    "check": "npm run build && npm run test:built && npm run test:package",
+    "audit:prod": "npm audit --omit=dev --audit-level=high",
+    "start": "node dist/src/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.0",
+    "playwright-core": "^1.63.0",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "typescript": "^7.0.2"
+  }
+}