Release v0.3.3

.github/workflows/ci.yml

@@ -76,5 +76,11 @@ jobs:
       - name: Run tests
         run: npm test
 
+      - name: Check generated docs
+        run: npm run docs:check
+
       - name: Run release metadata checks
         run: npm run release:check
+
+      - name: Run npm package dry-run
+        run: npm run pack:dry-run

.gitignore

@@ -1,4 +1,5 @@
 .DS_Store
+.mcpregistry_*
 node_modules/
 temp/
 Temp/

CHANGELOG.md

@@ -6,6 +6,31 @@ This project follows a simple changelog format inspired by [Keep a Changelog](ht
 
 ## [Unreleased]
 
+## [0.3.3] - 2026-05-20
+
+### Added
+
+- Added generated tool reference documentation in `docs/TOOLS.md`.
+- Added `docs:generate` and `docs:check` scripts to keep tool counts, profiles, categories, and descriptions synchronized with `lib/tool-registry.js`.
+- Added CI and release validation for generated tool documentation.
+- Added a read-only `GET /tools` debug endpoint with curl examples for quick local troubleshooting.
+- Added panel activity previews for recent tool calls and runtime logs.
+- Added panel curl copy actions for `/health` and `/tools`.
+
+### Changed
+
+- Refined tool category inference so `get_tool_catalog` is grouped with project/context tools.
+- Updated the MCP client config panel so the preview follows the selected client target.
+- Split file-system tools and asset refresh helpers into `lib/tools/files.js` as the first registry modularization step.
+
+## [0.3.2] - 2026-05-20
+
+### Added
+
+- Added an npm-installable `funplay-cocos-mcp` stdio wrapper that bridges MCP clients to the local Cocos HTTP endpoint.
+- Added MCP Registry metadata in `server.json`, including npm package ownership metadata via `mcpName`.
+- Added wrapper tests, npm pack dry-run verification, and registry validation scripts.
+
 ## [0.3.1] - 2026-05-20
 
 ### Added

README.md

@@ -73,8 +73,10 @@ The panel is intentionally small:
 - Change the server port
 - Switch tool exposure between `core`, `full`, and `custom`
 - Check the installed version against the latest GitHub release
+- Inspect recent tool calls and runtime log previews
 - Tune tool exposure by category or individual tool
-- Configure AI clients with one click
+- Configure AI clients with one click and preview the selected client config
+- Copy quick `curl` commands for `/health` and `/tools`
 - Expand debug output only when needed
 
 ### 3. Configure Your AI Client
@@ -179,6 +181,31 @@ url = "http://127.0.0.1:8765/"
 
 </details>
 
+### Optional: npm stdio Wrapper
+
+If your MCP client prefers a local `stdio` command, install the npm wrapper after starting the Cocos editor server:
+
+```bash
+npm install -g funplay-cocos-mcp
+```
+
+Example MCP client entry:
+
+```json
+{
+  "mcpServers": {
+    "funplay_cocos": {
+      "command": "funplay-cocos-mcp",
+      "env": {
+        "FUNPLAY_COCOS_MCP_URL": "http://127.0.0.1:8765/"
+      }
+    }
+  }
+}
+```
+
+The wrapper bridges stdio MCP traffic to the embedded Cocos HTTP endpoint. You can also run it with `npx funplay-cocos-mcp --url http://127.0.0.1:8765/`.
+
 ### 4. Verify the Connection
 
 Open your AI client and try a few safe requests first:
@@ -190,6 +217,13 @@ Open your AI client and try a few safe requests first:
 
 If these work, the MCP server, resources, prompts, and primary execution tool are connected correctly.
 
+For local transport debugging, the panel can copy these commands, or you can run them directly:
+
+```bash
+curl http://127.0.0.1:8765/health
+curl http://127.0.0.1:8765/tools
+```
+
 ### 5. Start Building
 
 Try a higher-level prompt in your AI client:
@@ -201,6 +235,7 @@ Try a higher-level prompt in your AI client:
 - This extension is **Editor-only**. It is meant to automate Cocos Creator, not to add runtime dependencies to your final game build.
 - The MCP server listens on `http://127.0.0.1:8765/` by default.
 - If the configured port is busy, the server automatically falls back to the next available port and the panel/client config use the actual running port.
+- `GET /health` and `GET /tools` are read-only debug endpoints for quick local checks outside an MCP client.
 - The default `core` profile exposes 34 high-signal tools. Switch to `full` for all 89 tools, or use `custom` to include/exclude tool categories and individual tools.
 - The panel includes a manual update check against the latest GitHub release.
 - Streamable HTTP responses follow the MCP transport requirements for `Accept`, `MCP-Protocol-Version`, JSON-RPC notifications/responses, and optional `Mcp-Session-Id` sessions.
@@ -224,7 +259,7 @@ Try a higher-level prompt in your AI client:
 - **89 Built-in Tools** — Scene hierarchy, editor state, selection workflows, prefabs, assets, project instructions, UI creation, components, files, logs, script diagnostics, screenshots, runtime control, and input simulation
 - **Primary Unified Tool** — `execute_javascript` supports both `scene` and `editor` contexts
 - **Resources & Prompts** — Live project/log resources plus reusable workflows like script fixing, scene validation, and playable prototype creation
-- **Cocos Panel UI** — A minimal `Funplay > MCP Server` panel for service management, update checks, tool exposure, and MCP client setup
+- **Cocos Panel UI** — A compact `Funplay > MCP Server` panel for service management, update checks, tool exposure, recent activity, logs, curl diagnostics, and MCP client setup
 - **Screenshot and Input Support** — Capture editor/scene/game/preview screenshots and send Electron-level mouse/keyboard events
 - **Vendor Agnostic** — Works with any AI client that supports MCP over HTTP JSON-RPC
 
@@ -251,6 +286,8 @@ The current package exposes four capability layers:
 - **Prompts** — `fix_script_errors`, `create_playable_prototype`, `scene_validation`, and `auto_wire_scene`
 - **Resources** — project context, scene summaries, current selection, script diagnostics, asset selection, logs, and MCP interaction history
 
+For the generated tool reference, including categories, profiles, and read/mutation hints, see [docs/TOOLS.md](./docs/TOOLS.md).
+
 The default `core` set is intentionally small: `execute_javascript`, `execute_scene_script`, `execute_editor_script`, `get_editor_state`, `get_tool_catalog`, `check_for_updates`, `get_selection`, `list_project_instructions`, `read_project_instruction`, `set_selection`, `get_project_info`, `get_scene_info`, `get_hierarchy`, `list_scenes`, `open_scene`, `inspect_prefab`, `validate_prefab_references`, `inspect_prefab_instance`, `list_assets`, `inspect_asset`, `open_asset`, `select_asset`, `run_script_diagnostics`, `get_recent_logs`, `search_project_logs`, `clear_logs`, `validate_scene`, `get_performance_snapshot`, `get_script_diagnostic_context`, `get_runtime_state`, `capture_editor_screenshot`, `capture_scene_screenshot`, `capture_preview_screenshot`, and `list_editor_windows`.
 
 ## Built-in Resources
@@ -360,7 +397,7 @@ Cocos Creator Extension
         └─ server, resources, prompts, tool registry
 ```
 
-The server speaks MCP-style HTTP JSON-RPC 2.0 and supports tools, resources, resource templates, prompts, and health checks.
+The server speaks MCP-style HTTP JSON-RPC 2.0 and supports tools, resources, resource templates, prompts, health checks, and a read-only `/tools` debug endpoint.
 
 ## Development
 
@@ -369,7 +406,15 @@ Run checks before publishing changes:
 ```bash
 npm run check
 npm test
+npm run docs:check
 npm run release:check
+npm run pack:dry-run
+```
+
+Regenerate the tool reference after changing `lib/tool-registry.js`:
+
+```bash
+npm run docs:generate
 ```
 
 To generate a GitHub Release-ready extension package:
@@ -380,6 +425,12 @@ npm run release:package
 
 The package is written to `releases/<version>/` with a zip, manifest, checksum file, and release README. See [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) and [RELEASE_CHECKLIST.md](./RELEASE_CHECKLIST.md) for the full process.
 
+Validate MCP Registry metadata before publishing:
+
+```bash
+npm run registry:validate
+```
+
 ## License
 
 MIT License. See [LICENSE](./LICENSE).

README_CN.md

@@ -73,8 +73,10 @@ Funplay > MCP Server
 - 修改服务端口
 - 在 `core` / `full` / `custom` 工具暴露模式之间切换
 - 检查当前安装版本是否落后于 GitHub 最新 Release
+- 查看最近工具调用和运行日志预览
 - 按工具分类或单个工具调整暴露范围
-- 一键配置 AI 客户端
+- 一键配置 AI 客户端，并随目标客户端预览对应配置
+- 复制 `/health` 和 `/tools` 的快速 `curl` 排障命令
 - 需要时再展开 Debug Output
 
 ### 3. 配置 AI 客户端
@@ -179,6 +181,31 @@ url = "http://127.0.0.1:8765/"
 
 </details>
 
+### 可选：npm stdio Wrapper
+
+如果 MCP 客户端更适合使用本地 `stdio` 命令，可以在启动 Cocos 编辑器内置服务后安装 npm wrapper：
+
+```bash
+npm install -g funplay-cocos-mcp
+```
+
+示例 MCP 客户端配置：
+
+```json
+{
+  "mcpServers": {
+    "funplay_cocos": {
+      "command": "funplay-cocos-mcp",
+      "env": {
+        "FUNPLAY_COCOS_MCP_URL": "http://127.0.0.1:8765/"
+      }
+    }
+  }
+}
+```
+
+这个 wrapper 会把 stdio MCP 流量桥接到 Cocos 内置 HTTP endpoint。也可以直接运行 `npx funplay-cocos-mcp --url http://127.0.0.1:8765/`。
+
 ### 4. 验证连接
 
 先在 AI 客户端里试几个安全请求：
@@ -190,6 +217,13 @@ url = "http://127.0.0.1:8765/"
 
 如果这些都正常返回，说明 MCP server、resources、prompts 和主执行工具已经连通。
 
+如果要排查本地传输链路，面板可以直接复制下面的命令，也可以手动执行：
+
+```bash
+curl http://127.0.0.1:8765/health
+curl http://127.0.0.1:8765/tools
+```
+
 ### 5. 开始构建
 
 可以在 AI 客户端里尝试：
@@ -201,6 +235,7 @@ url = "http://127.0.0.1:8765/"
 - 这是一个 **仅限 Editor** 的扩展，用于自动化 Cocos Creator，不会给最终游戏包添加运行时依赖。
 - MCP Server 默认监听 `http://127.0.0.1:8765/`。
 - 如果配置端口被占用，服务会自动回退到下一个可用端口，面板与一键客户端配置会使用实际运行端口。
+- `GET /health` 和 `GET /tools` 是只读调试端点，方便不用 MCP 客户端也能快速检查本地服务。
 - 默认 `core` profile 暴露 34 个高频工具；如果需要完整工具集，可在面板切到 `full`，暴露全部 89 个工具；也可以用 `custom` 按分类或工具名增删。
 - 面板提供手动更新检查，会对比当前安装版本和 GitHub 最新 Release。
 - Streamable HTTP 响应已补齐 MCP 传输层要求，包括 `Accept`、`MCP-Protocol-Version`、JSON-RPC notification/response，以及可选 `Mcp-Session-Id` session。
@@ -224,7 +259,7 @@ url = "http://127.0.0.1:8765/"
 - **89 个内置工具** — 覆盖场景层级、编辑器状态、选择工作流、Prefab、资产、项目指令、UI 创建、组件、文件、日志、脚本诊断、截图、运行态控制和输入模拟
 - **统一主工具** — `execute_javascript` 同时支持 `scene` 和 `editor` 两种上下文
 - **Resources 与 Prompts** — 实时项目/日志资源，以及脚本修复、场景验证、可玩原型等可复用工作流
-- **Cocos 图形面板** — `Funplay > MCP Server` 提供服务管理、更新检查、工具暴露和 MCP 客户端配置
+- **Cocos 图形面板** — `Funplay > MCP Server` 提供服务管理、更新检查、工具暴露、最近活动、日志、curl 排障和 MCP 客户端配置
 - **截图与输入支持** — 支持编辑器/场景/Game/Preview 截图，以及 Electron 级鼠标键盘事件
 - **厂商无关** — 兼容任意支持 HTTP JSON-RPC MCP 的 AI 客户端
 
@@ -251,6 +286,8 @@ Funplay MCP for Cocos 延续 Funplay MCP for Unity 的设计原则，并针对 C
 - **Prompts** — `fix_script_errors`、`create_playable_prototype`、`scene_validation`、`auto_wire_scene`
 - **Resources** — 项目上下文、场景摘要、当前选择、脚本诊断、资产选择、日志和 MCP 交互历史
 
+自动生成的工具参考文档见 [docs/TOOLS.md](./docs/TOOLS.md)，里面包含工具分类、profile 和读写/变更提示。
+
 当前默认 `core` 工具集刻意保持精简，只包含：`execute_javascript`、`execute_scene_script`、`execute_editor_script`、`get_editor_state`、`get_tool_catalog`、`check_for_updates`、`get_selection`、`list_project_instructions`、`read_project_instruction`、`set_selection`、`get_project_info`、`get_scene_info`、`get_hierarchy`、`list_scenes`、`open_scene`、`inspect_prefab`、`validate_prefab_references`、`inspect_prefab_instance`、`list_assets`、`inspect_asset`、`open_asset`、`select_asset`、`run_script_diagnostics`、`get_recent_logs`、`search_project_logs`、`clear_logs`、`validate_scene`、`get_performance_snapshot`、`get_script_diagnostic_context`、`get_runtime_state`、`capture_editor_screenshot`、`capture_scene_screenshot`、`capture_preview_screenshot`、`list_editor_windows`。
 
 ## 内置 Resources
@@ -360,7 +397,7 @@ Cocos Creator Extension
         └─ server, resources, prompts, tool registry
 ```
 
-服务使用 MCP 风格的 HTTP JSON-RPC 2.0，支持 tools、resources、resource templates、prompts 和 health check。
+服务使用 MCP 风格的 HTTP JSON-RPC 2.0，支持 tools、resources、resource templates、prompts、health check 和只读 `/tools` 调试端点。
 
 ## 开发
 
@@ -369,7 +406,15 @@ Cocos Creator Extension
 ```bash
 npm run check
 npm test
+npm run docs:check
 npm run release:check
+npm run pack:dry-run
+```
+
+修改 `lib/tool-registry.js` 后可以重新生成工具参考：
+
+```bash
+npm run docs:generate
 ```
 
 生成可上传到 GitHub Release 的扩展包：
@@ -380,6 +425,12 @@ npm run release:package
 
 产物会写入 `releases/<version>/`，包含 zip、manifest、checksum 和 release README。完整流程见 [RELEASE_WORKFLOW.md](./RELEASE_WORKFLOW.md) 和 [RELEASE_CHECKLIST.md](./RELEASE_CHECKLIST.md)。
 
+发布 MCP Registry 前可以验证元数据：
+
+```bash
+npm run registry:validate
+```
+
 ## 协议
 
 MIT License。详见 [LICENSE](./LICENSE)。

RELEASE_CHECKLIST.md

@@ -14,7 +14,10 @@ Use this checklist before publishing a new release of Funplay MCP for Cocos.
 
 - [ ] `npm run check` passes
 - [ ] `npm test` passes
+- [ ] `npm run docs:check` passes
 - [ ] `npm run release:check` passes
+- [ ] `npm run pack:dry-run` passes
+- [ ] `npm run registry:validate` passes when `mcp-publisher` is available
 - [ ] `npm run release:package` creates `releases/<version>/`
 - [ ] `shasum -a 256 -c releases/<version>/SHA256SUMS.txt` passes
 
@@ -23,6 +26,7 @@ Use this checklist before publishing a new release of Funplay MCP for Cocos.
 - [ ] The zip is named `Funplay.CocosMcp.v<version>.zip`
 - [ ] The zip contains a single top-level `funplay-cocos-mcp/` folder
 - [ ] The zip contains runtime files: `package.json`, `browser.js`, `scene.js`, `panel/`, and `lib/`
+- [ ] The zip contains stdio wrapper metadata: `bin/funplay-cocos-mcp.js` and `server.json`
 - [ ] The zip includes docs: `README.md`, `README_CN.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, and `LICENSE`
 - [ ] The zip does not contain `.git/`, `.github/`, `.DS_Store`, `node_modules/`, `Library/`, `Temp/`, `dist/`, `build/`, `test/`, or `scripts/`
 - [ ] `release-manifest.json` references the correct GitHub download URL
@@ -47,8 +51,21 @@ Use this checklist before publishing a new release of Funplay MCP for Cocos.
 - [ ] Confirm `tools/list` returns the expected `core` profile tools
 - [ ] Confirm a tool call succeeds end-to-end from the external client
 - [ ] Verify one-click config output still matches the documented config snippets
+- [ ] Verify the stdio wrapper can connect with `funplay-cocos-mcp --url http://127.0.0.1:8765/`
 
-## 6. GitHub Release Readiness
+## 6. npm And MCP Registry Readiness
+
+- [ ] `package.json` `name` is `funplay-cocos-mcp`
+- [ ] `package.json` `version` matches `server.json` version
+- [ ] `package.json` `mcpName` matches `server.json` name
+- [ ] `package.json` `bin.funplay-cocos-mcp` points to `bin/funplay-cocos-mcp.js`
+- [ ] `server.json` npm package identifier and version match `package.json`
+- [ ] `server.json` npm transport type is `stdio`
+- [ ] npm package dry-run includes `bin/`, `lib/`, `panel/`, `browser.js`, `scene.js`, and `server.json`
+- [ ] npm credentials are available for `npm publish`
+- [ ] MCP Registry credentials are available for `mcp-publisher publish`
+
+## 7. GitHub Release Readiness
 
 - [ ] CI passes on `main`
 - [ ] Release commit message is `Release v<version>`
@@ -57,17 +74,22 @@ Use this checklist before publishing a new release of Funplay MCP for Cocos.
 - [ ] GitHub Release includes the zip, manifest, checksum file, and release README
 - [ ] Public GitHub Release page renders the release notes and assets correctly
 
-## 7. Publish
+## 8. Publish
 
 - [ ] Commit the release changes
 - [ ] Create and push the release tag
 - [ ] Create or update the GitHub Release
 - [ ] Upload generated release assets
 - [ ] Verify the GitHub Release asset list
+- [ ] Publish npm package with `npm publish`
+- [ ] Verify npm package with `npm view funplay-cocos-mcp@<version>`
+- [ ] Publish MCP Registry metadata with `mcp-publisher publish server.json`
+- [ ] Verify MCP Registry latest and specific-version endpoints
 
-## 8. Post-Release
+## 9. Post-Release
 
 - [ ] Re-test installation from the public GitHub Release zip
+- [ ] Re-test stdio wrapper installation from npm
 - [ ] Check the update checker reports the new latest version
 - [ ] Check README install instructions and download links
 - [ ] Announce the release where appropriate

RELEASE_WORKFLOW.md

@@ -5,6 +5,8 @@ This document records the release workflow for publishing Funplay MCP for Cocos
 - Git tags
 - GitHub Releases
 - Downloadable Cocos Creator extension zip packages
+- npm stdio wrapper package
+- Official MCP Registry
 
 ## Published Identity
 
@@ -13,6 +15,9 @@ This document records the release workflow for publishing Funplay MCP for Cocos
 - GitHub Release tag: `v<version>`
 - Extension package asset: `Funplay.CocosMcp.v<version>.zip`
 - Cocos extension folder name inside the zip: `funplay-cocos-mcp`
+- npm package id: `funplay-cocos-mcp`
+- npm command: `funplay-cocos-mcp`
+- MCP Registry server name: `io.github.FunplayAI/funplay-cocos-mcp`
 - Default local MCP endpoint: `http://127.0.0.1:8765/`
 
 ## Version Alignment Rule
@@ -25,6 +30,8 @@ Keep these versions aligned:
 - GitHub Release `v<version>`
 - `releases/<version>/release-manifest.json` `version`
 - Release zip filename `Funplay.CocosMcp.v<version>.zip`
+- `server.json` top-level version
+- `server.json` npm package version
 
 Example:
 
@@ -32,6 +39,8 @@ Example:
 - Git tag: `v0.3.1`
 - GitHub Release: `v0.3.1`
 - Release asset: `Funplay.CocosMcp.v0.3.1.zip`
+- npm package: `funplay-cocos-mcp@0.3.1`
+- MCP Registry: `0.3.1`
 
 ## Files To Update For A New Release
 
@@ -41,12 +50,17 @@ Update:
    - `"version": "<version>"`
 2. `CHANGELOG.md`
    - add a dated release notes block
+3. `server.json`
+   - top-level `"version"`
+   - npm package `"version"`
+4. `docs/TOOLS.md`
+   - regenerate with `npm run docs:generate` after tool registry changes
 
 Optional but recommended:
 
-3. `README.md`
+5. `README.md`
-4. `README_CN.md`
+6. `README_CN.md`
-5. GitHub Release notes text
+7. GitHub Release notes text
 
 ## Release Steps
 
@@ -78,7 +92,9 @@ This runs:
 
 - JavaScript syntax checks
 - Node.js tests
+- generated tool documentation validation
 - release metadata validation
+- npm package dry-run validation
 - release package generation
 
 The generated local artifacts are written to:
@@ -122,6 +138,19 @@ cd releases/<version>
 shasum -a 256 -c SHA256SUMS.txt
 ```
 
+### 4.5 Validate npm And MCP Registry Metadata
+
+```bash
+npm run pack:dry-run
+npm run registry:validate
+```
+
+The npm package must include the stdio wrapper command:
+
+```bash
+npx --yes ./funplay-cocos-mcp-<version>.tgz --version
+```
+
 ### 5. Commit, Tag, And Push
 
 ```bash
@@ -175,7 +204,51 @@ gh release view v<version> \
 
 Confirm the release has all four assets.
 
-### 8. Post-Release Smoke Test
+### 8. Publish To npm
+
+```bash
+npm publish
+```
+
+Verify the published package:
+
+```bash
+npm view funplay-cocos-mcp@<version> version bin mcpName
+```
+
+Notes:
+
+- `package.json` `mcpName` must match `server.json` `name`.
+- If `npm publish` returns `ENEEDAUTH`, run `npm adduser` with a publishing account and retry.
+- If the package name already exists under another owner, choose a scoped package name and update both `package.json` and `server.json`.
+
+### 9. Publish To MCP Registry
+
+Log in if needed:
+
+```bash
+mcp-publisher login github
+```
+
+Publish:
+
+```bash
+mcp-publisher publish server.json
+```
+
+Verify latest:
+
+```bash
+curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.FunplayAI/funplay-cocos-mcp&version=latest"
+```
+
+Check a specific version:
+
+```bash
+curl "https://registry.modelcontextprotocol.io/v0.1/servers/io.github.FunplayAI%2Ffunplay-cocos-mcp/versions/<version>"
+```
+
+### 10. Post-Release Smoke Test
 
 Test the package from the public GitHub Release:
 
@@ -186,12 +259,16 @@ Test the package from the public GitHub Release:
 5. Open `Funplay > MCP Server`.
 6. Start the MCP server.
 7. Connect an MCP client and call `get_project_info`.
+8. Install the npm wrapper with `npm install -g funplay-cocos-mcp`.
+9. Connect an MCP client through the `funplay-cocos-mcp` command and call `tools/list`.
 
 ## Current Verification Commands
 
 ```bash
 npm run release:verify
+npm run registry:validate
 gh release view v<version> -R FunplayAI/funplay-cocos-mcp --json url,assets
+npm view funplay-cocos-mcp@<version> version bin mcpName
 ```
 
 ## Common Failure Cases
@@ -226,3 +303,30 @@ Fix:
 
 - Rerun `npm run release:check`.
 - Confirm the command uses `releases/<version>/` and `v<version>`.
+
+### npm `ENEEDAUTH`
+
+Cause:
+
+- The local machine is not logged in to npm.
+
+Fix:
+
+```bash
+npm adduser
+npm publish
+```
+
+### MCP Registry `Package validation failed`
+
+Cause:
+
+- npm package has not been published yet.
+- `package.json` `mcpName` does not match `server.json` `name`.
+- `server.json` package version does not match the npm package version.
+
+Fix:
+
+- Publish the npm package first.
+- Rerun `npm run release:check`.
+- Rerun `npm run registry:validate`.

bin/funplay-cocos-mcp.js

@@ -0,0 +1,356 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const http = require('http');
+const https = require('https');
+const path = require('path');
+
+const DEFAULT_URL = 'http://127.0.0.1:8765/';
+const DEFAULT_TIMEOUT_SECONDS = 120;
+const ACCEPT_HEADER = 'application/json, text/event-stream';
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (hasFlag(args, '--help') || hasFlag(args, '-h')) {
+    printHelp();
+    return 0;
+  }
+
+  if (hasFlag(args, '--version')) {
+    console.error(`funplay-cocos-mcp ${readPackageVersion()}`);
+    return 0;
+  }
+
+  const urlText = getOption(args, '--url')
+    || process.env.FUNPLAY_COCOS_MCP_URL
+    || DEFAULT_URL;
+  const timeoutText = getOption(args, '--timeout-seconds')
+    || process.env.FUNPLAY_COCOS_MCP_TIMEOUT_SECONDS
+    || String(DEFAULT_TIMEOUT_SECONDS);
+
+  const endpoint = parseEndpoint(urlText);
+  if (!endpoint) {
+    console.error(`Invalid --url value: ${urlText}`);
+    return 2;
+  }
+
+  const timeoutSeconds = Number.parseInt(timeoutText, 10);
+  if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0) {
+    console.error(`Invalid timeout value: ${timeoutText}`);
+    return 2;
+  }
+
+  console.error(`[Funplay Cocos MCP] Bridging stdio to ${endpoint.href}`);
+  await bridgeStdioToHttp({
+    input: process.stdin,
+    output: process.stdout,
+    endpoint,
+    timeoutMs: timeoutSeconds * 1000
+  });
+  return 0;
+}
+
+async function bridgeStdioToHttp({ input, output, endpoint, timeoutMs }) {
+  let sessionId = '';
+
+  while (true) {
+    const message = await readMessage(input);
+    if (message === null) {
+      return;
+    }
+
+    let parsed = null;
+    let requestId = null;
+    try {
+      parsed = JSON.parse(message);
+      requestId = getRequestId(parsed);
+    } catch (error) {
+      await writeJsonRpcError(output, null, -32700, 'Parse error');
+      continue;
+    }
+
+    try {
+      const response = await postJsonRpc(endpoint, message, {
+        timeoutMs,
+        sessionId
+      });
+
+      const nextSessionId = response.headers['mcp-session-id'];
+      if (typeof nextSessionId === 'string' && nextSessionId) {
+        sessionId = nextSessionId;
+      }
+
+      if (response.statusCode >= 200 && response.statusCode < 300 && response.body.trim()) {
+        await writeMessage(output, response.body);
+        continue;
+      }
+
+      if (response.statusCode >= 200 && response.statusCode < 300 && isNotification(parsed)) {
+        continue;
+      }
+
+      if (requestId !== null) {
+        const messageText = response.body.trim()
+          ? `Cocos MCP server returned HTTP ${response.statusCode}: ${response.body}`
+          : `Cocos MCP server returned HTTP ${response.statusCode}.`;
+        await writeJsonRpcError(output, requestId, -32000, messageText);
+      }
+    } catch (error) {
+      console.error(`[Funplay Cocos MCP] ${error.message}`);
+      if (requestId !== null) {
+        await writeJsonRpcError(output, requestId, -32000, `Proxy transport error: ${error.message}`);
+      }
+    }
+  }
+}
+
+function postJsonRpc(endpoint, body, { timeoutMs, sessionId }) {
+  return new Promise((resolve, reject) => {
+    const client = endpoint.protocol === 'https:' ? https : http;
+    const request = client.request(
+      endpoint,
+      {
+        method: 'POST',
+        headers: {
+          Accept: ACCEPT_HEADER,
+          'Content-Type': 'application/json',
+          'Content-Length': Buffer.byteLength(body),
+          ...(sessionId ? { 'Mcp-Session-Id': sessionId } : {})
+        },
+        timeout: timeoutMs
+      },
+      (response) => {
+        const chunks = [];
+        response.on('data', (chunk) => chunks.push(chunk));
+        response.on('end', () => {
+          resolve({
+            statusCode: response.statusCode || 0,
+            headers: response.headers,
+            body: Buffer.concat(chunks).toString('utf8')
+          });
+        });
+      }
+    );
+
+    request.on('timeout', () => {
+      request.destroy(new Error(`HTTP request timed out after ${timeoutMs / 1000} seconds.`));
+    });
+    request.on('error', reject);
+    request.end(body);
+  });
+}
+
+function parseEndpoint(value) {
+  try {
+    const endpoint = new URL(value);
+    if (endpoint.protocol !== 'http:' && endpoint.protocol !== 'https:') {
+      return null;
+    }
+    return endpoint;
+  } catch (error) {
+    return null;
+  }
+}
+
+function getRequestId(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return null;
+  }
+  return Object.prototype.hasOwnProperty.call(value, 'id') ? value.id : null;
+}
+
+function isNotification(value) {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value) && value.method && !Object.prototype.hasOwnProperty.call(value, 'id'));
+}
+
+async function writeJsonRpcError(output, id, code, message) {
+  await writeMessage(output, JSON.stringify({
+    jsonrpc: '2.0',
+    id,
+    error: {
+      code,
+      message
+    }
+  }));
+}
+
+async function readMessage(input) {
+  const headers = new Map();
+
+  while (true) {
+    const line = await readHeaderLine(input);
+    if (line === null) {
+      return headers.size === 0 ? null : Promise.reject(new Error('Unexpected EOF while reading MCP headers.'));
+    }
+
+    if (line === '') {
+      break;
+    }
+
+    const separator = line.indexOf(':');
+    if (separator <= 0) {
+      continue;
+    }
+
+    headers.set(line.slice(0, separator).trim().toLowerCase(), line.slice(separator + 1).trim());
+  }
+
+  const contentLength = Number.parseInt(headers.get('content-length') || '', 10);
+  if (!Number.isFinite(contentLength) || contentLength < 0) {
+    throw new Error('Missing Content-Length header.');
+  }
+
+  const payload = await readExact(input, contentLength);
+  return payload.toString('utf8');
+}
+
+function readHeaderLine(input) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+
+    function cleanup() {
+      input.off('readable', onReadable);
+      input.off('end', onEnd);
+      input.off('error', onError);
+    }
+
+    function onReadable() {
+      let byte;
+      while ((byte = input.read(1)) !== null) {
+        if (byte[0] === 0x0a) {
+          cleanup();
+          if (chunks.length > 0 && chunks[chunks.length - 1][0] === 0x0d) {
+            chunks.pop();
+          }
+          resolve(Buffer.concat(chunks).toString('ascii'));
+          return;
+        }
+        chunks.push(byte);
+      }
+    }
+
+    function onEnd() {
+      cleanup();
+      resolve(chunks.length === 0 ? null : Buffer.concat(chunks).toString('ascii'));
+    }
+
+    function onError(error) {
+      cleanup();
+      reject(error);
+    }
+
+    input.on('readable', onReadable);
+    input.once('end', onEnd);
+    input.once('error', onError);
+    onReadable();
+  });
+}
+
+function readExact(input, length) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let remaining = length;
+
+    function cleanup() {
+      input.off('readable', onReadable);
+      input.off('end', onEnd);
+      input.off('error', onError);
+    }
+
+    function onReadable() {
+      while (remaining > 0) {
+        const chunk = input.read(remaining);
+        if (chunk === null) {
+          return;
+        }
+        chunks.push(chunk);
+        remaining -= chunk.length;
+      }
+      cleanup();
+      resolve(Buffer.concat(chunks, length));
+    }
+
+    function onEnd() {
+      cleanup();
+      reject(new Error('Unexpected EOF while reading MCP payload.'));
+    }
+
+    function onError(error) {
+      cleanup();
+      reject(error);
+    }
+
+    input.on('readable', onReadable);
+    input.once('end', onEnd);
+    input.once('error', onError);
+    onReadable();
+  });
+}
+
+function writeMessage(output, json) {
+  const payload = Buffer.from(json, 'utf8');
+  return new Promise((resolve, reject) => {
+    output.write(`Content-Length: ${payload.length}\r\n\r\n`, 'ascii', (headerError) => {
+      if (headerError) {
+        reject(headerError);
+        return;
+      }
+      output.write(payload, (payloadError) => {
+        if (payloadError) {
+          reject(payloadError);
+          return;
+        }
+        resolve();
+      });
+    });
+  });
+}
+
+function hasFlag(args, name) {
+  return args.some((arg) => arg.toLowerCase() === name.toLowerCase());
+}
+
+function getOption(args, name) {
+  for (let i = 0; i < args.length - 1; i += 1) {
+    if (args[i].toLowerCase() === name.toLowerCase()) {
+      return args[i + 1];
+    }
+  }
+  return '';
+}
+
+function readPackageVersion() {
+  try {
+    const packagePath = path.resolve(__dirname, '..', 'package.json');
+    const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+    return packageJson.version || '0.0.0';
+  } catch (error) {
+    return '0.0.0';
+  }
+}
+
+function printHelp() {
+  console.error('funplay-cocos-mcp');
+  console.error('Bridges stdio MCP traffic to a local Cocos Creator HTTP MCP server.');
+  console.error();
+  console.error('Options:');
+  console.error('  --url <http://127.0.0.1:8765/>   Cocos MCP HTTP endpoint.');
+  console.error('  --timeout-seconds <120>           HTTP timeout per request.');
+  console.error('  --version                         Print the proxy version.');
+  console.error('  --help                            Show this help.');
+  console.error();
+  console.error('Environment:');
+  console.error('  FUNPLAY_COCOS_MCP_URL');
+  console.error('  FUNPLAY_COCOS_MCP_TIMEOUT_SECONDS');
+}
+
+if (require.main === module) {
+  main().then((code) => {
+    process.exitCode = code;
+  }).catch((error) => {
+    console.error(`[Funplay Cocos MCP] ${error.message}`);
+    process.exitCode = 1;
+  });
+}

browser.js

@@ -4,7 +4,7 @@ const path = require('path');
 const fs = require('fs');
 const os = require('os');
 const manifest = require('./package.json');
-const { configureTarget, getTargetStatuses } = require('./lib/client-config');
+const { SERVER_NAME, buildTargets, configureTarget, getTargetStatuses } = require('./lib/client-config');
 const { loadConfig, getProjectPath, getProjectName, getCocosVersion } = require('./lib/config');
 const { McpServer } = require('./lib/server');
 const { createToolRegistry } = require('./lib/tool-registry');
@@ -304,7 +304,21 @@ class ExtensionService {
   }
 
   getClientConfig() {
-    const { url } = this.getEffectiveServerConnection();
+    const effective = this.getEffectiveServerConnection();
+    const { url } = effective;
+    const targetConfig = {
+      ...this.config,
+      host: effective.host,
+      port: effective.port,
+    };
+    const targets = buildTargets(targetConfig).map((target) => ({
+      id: target.id,
+      name: target.name,
+      configPath: target.configPath,
+      isToml: Boolean(target.isToml),
+      preview: this.formatClientTargetPreview(target),
+    }));
+    const baseUrl = url.replace(/\/$/, '');
     return {
       url,
       codex: `[mcp_servers.funplay_cocos]\nurl = "${url}"\n`,
@@ -315,9 +329,28 @@ class ExtensionService {
           },
         },
       }, null, 2),
+      targets,
+      curl: {
+        health: `curl ${baseUrl}/health`,
+        tools: `curl ${baseUrl}/tools`,
+        catalog: `curl ${baseUrl}/tools?catalog=1`,
+      },
     };
   }
 
+  formatClientTargetPreview(target) {
+    if (target.isToml) {
+      return `[mcp_servers.${SERVER_NAME}]\nurl = "${target.url}"\n`;
+    }
+
+    const rootKey = target.rootKey || 'mcpServers';
+    return JSON.stringify({
+      [rootKey]: {
+        [SERVER_NAME]: target.entry,
+      },
+    }, null, 2);
+  }
+
   configureClient(targetId) {
     this.ensureRuntime();
     this.log('info', `Configuring MCP client target: ${targetId}`);

docs/TOOLS.md

@@ -0,0 +1,203 @@
+# Tool Reference
+
+<!-- This file is generated by `npm run docs:generate`. Do not edit by hand. -->
+
+Generated from `lib/tool-registry.js`. The default `core` profile exposes 34 tools; the `full` profile exposes 89 tools.
+
+## Profile Summary
+
+| Profile | Tool Count | Purpose |
+|---|---:|---|
+| `core` | 34 | Focused default surface for common editor automation. |
+| `full` | 89 | All built-in tools, including destructive and low-level helpers. |
+
+## Core Tools
+
+`capture_editor_screenshot`, `capture_preview_screenshot`, `capture_scene_screenshot`, `check_for_updates`, `clear_logs`, `execute_editor_script`, `execute_javascript`, `execute_scene_script`, `get_editor_state`, `get_hierarchy`, `get_performance_snapshot`, `get_project_info`, `get_recent_logs`, `get_runtime_state`, `get_scene_info`, `get_script_diagnostic_context`, `get_selection`, `get_tool_catalog`, `inspect_asset`, `inspect_prefab`, `inspect_prefab_instance`, `list_assets`, `list_editor_windows`, `list_project_instructions`, `list_scenes`, `open_asset`, `open_scene`, `read_project_instruction`, `run_script_diagnostics`, `search_project_logs`, `select_asset`, `set_selection`, `validate_prefab_references`, `validate_scene`
+
+## Tools By Category
+
+### Animation
+
+| Tool | Profiles | Access | Description |
+|---|---|---|---|
+| `add_animation_clip` | `full` | stateful | Add an AnimationClip asset to a node Animation component. |
+| `list_animations` | `full` | read-only | [core] List Animation components in the active scene or under one node. |
+| `play_animation` | `full` | stateful | [core] Play an Animation component clip on a node. |
+| `stop_animation` | `full` | stateful | [core] Stop an Animation component clip on a node. |
+
+### Assets
+
+| Tool | Profiles | Access | Description |
+|---|---|---|---|
+| `delete_asset` | `full` | mutating | Delete an asset from asset-db by uuid, db url, or path. |
+| `inspect_asset` | `core`, `full` | read-only | [specialist] Inspect asset-db info, metadata, and serialized asset data by uuid or path. Prefer this when you need a precise structured asset read. |
+| `list_assets` | `core`, `full` | read-only | [specialist] Query project assets from asset-db by pattern or asset type. Prefer this when you need exact asset discovery; otherwise use execute_javascript for broader automation. |
+| `list_scenes` | `core`, `full` | read-only | [specialist] List scene assets in the project. Prefer this when you need exact scene discovery before opening one; otherwise stay in execute_javascript for broader workflows. |
+| `open_asset` | `core`, `full` | stateful | [specialist] Open an asset inside Cocos Creator by uuid, db url, or path. Use this only when opening the asset itself is the explicit next step. |
+| `open_scene` | `core`, `full` | stateful | [specialist] Open a scene asset in Cocos Creator by uuid, db url, or path. Use this when scene switching is the explicit goal; otherwise keep execute_javascript as the main planning tool. |
+| `run_scene_asset` | `full` | mutating | Load a scene asset by uuid directly into the current runtime scene context. |
+| `select_asset` | `core`, `full` | stateful | [specialist] Select an asset in the Cocos editor. Use this when editor selection state matters; otherwise keep execute_javascript as the primary workflow. |
+
+### Camera
+
+| Tool | Profiles | Access | Description |
+|---|---|---|---|
+| `create_camera` | `full` | stateful | Create a Camera node in the active scene. |
+| `list_cameras` | `full` | read-only | [core] List Camera components in the active scene. |
+| `set_camera_properties` | `full` | mutating | Set selected Camera component properties. |
+
+### Components
+
+| Tool | Profiles | Access | Description |
+|---|---|---|---|
+| `add_component` | `full` | stateful | Add a component to a node by component class name. |
+| `inspect_component` | `full` | read-only | [core] Inspect a component attached to a node. |
+| `invoke_component_method` | `full` | mutating | [core] Invoke a method on a component for runtime validation and test hooks. |
+| `list_components` | `full` | read-only | [core] List components attached to a scene node. |
+| `remove_component` | `full` | mutating | Remove a component from a node by name or index. |
+| `reset_component_property` | `full` | mutating | Reset or clear a component property by dot path. |
+| `set_component_property` | `full` | mutating | Set a component property by dot path using a JSON value. |
+
+### Diagnostics
+
+| Tool | Profiles | Access | Description |
+|---|---|---|---|
+| `get_script_diagnostic_context` | `core`, `full` | read-only | [specialist] Run TypeScript diagnostics and attach source snippets for each error. This is a preferred specialist tool for compile-error triage before repair. |
+| `run_script_diagnostics` | `core`, `full` | stateful | [specialist] Run a TypeScript no-emit check for the current Cocos project and return parsed diagnostics. This is a preferred specialist tool for script errors when diagnostics are needed. |
+| `validate_prefab_references` | `core`, `full` | read-only | [specialist] Validate prefab asset references by checking serialized UUID references against asset-db. |
+| `validate_scene` | `core`, `full` | read-only | [specialist] Run a compact validation pass over the active scene, runtime state, TypeScript diagnostics, and recent project log errors. |
+
+### Execution
+
+| Tool | Profiles | Access | Description |
+|---|---|---|---|
+| `execute_editor_script` | `core`, `full` | mutating | [compat] Execute JavaScript in the editor/browser context. Prefer execute_javascript with context="editor" as the main unified tool; use this when you specifically want the editor-only compatibility entrypoint. |
+| `execute_javascript` | `core`, `full` | mutating | [primary] Execute JavaScript in either the scene or editor context. Use context="scene" for live scene/runtime inspection and mutation, or context="editor" for Editor APIs, asset-db workflows, MCP orchestration, local filesystem access, and higher-level automation. Prefer this as the main flexible tool when many narrow tools would be noisy. |
+
+### Files
+
+| Tool | Profiles | Access | Description |
+|---|---|---|---|
+| `exists` | `full` | read-only | [core] Check whether a project file or directory exists. |
+| `get_file_snippet` | `full` | read-only | [core] Read a focused snippet around a file line number. |
+| `list_directory` | `full` | read-only | [core] List files and directories inside a project directory. |
+| `read_file` | `full` | read-only | [core] Read a file from the Cocos project. |
+| `refresh_assets` | `full` | stateful | [core] Best-effort asset database refresh for a file or the assets root. |
+| `replace_in_file` | `full` | mutating | [core] Replace text in a file, useful for script auto-fix loops. |
+| `search_files` | `full` | read-only | [core] Search project files by simple wildcard pattern. |
+| `write_file` | `full` | mutating | [core] Write or overwrite a file in the Cocos project. |
+
+### Input
+
+| Tool | Profiles | Access | Description |
+|---|---|---|---|
+| `simulate_button_click` | `full` | mutating | [core] Simulate a Cocos Button click by emitting click events on the target button node. |
+| `simulate_key_combo` | `full` | mutating | [core] Send a low-level Electron modified key press such as Ctrl+S or Cmd+P. |
+| `simulate_key_press` | `full` | mutating | [core] Send a low-level Electron key press to the editor, preview, or simulator window. |
+| `simulate_mouse_click` | `full` | mutating | [core] Send a low-level Electron mouse click to the editor, preview, or simulator window. |
+| `simulate_mouse_drag` | `full` | mutating | [core] Send a low-level Electron mouse drag to the editor, preview, or simulator window. |
+| `simulate_preview_input` | `full` | mutating | [core] Convenience wrapper for low-level preview/simulator input. Uses mouse click by default or key press when keyCode is provided. |
+
+### Instructions
+
+| Tool | Profiles | Access | Description |
+|---|---|---|---|
+| `create_project_skill` | `full` | stateful | [core] Create a local Codex project skill under .codex/skills/{skillName}/SKILL.md. |
+| `list_project_instructions` | `core`, `full` | read-only | [specialist] List project AI instruction files and local Codex project skills. |
+| `read_project_instruction` | `core`, `full` | read-only | [specialist] Read a project AI instruction file such as AGENTS.md, CLAUDE.md, or a .codex skill SKILL.md. |
+| `write_project_instruction` | `full` | mutating | [core] Create or update a project AI instruction file inside the Cocos project. |
+
+### Logs
+
+| Tool | Profiles | Access | Description |
+|---|---|---|---|
+| `clear_logs` | `core`, `full` | mutating | [specialist] Clear in-memory MCP logs and, only with explicit confirmation, truncate common project log files. |
+| `get_recent_logs` | `core`, `full` | read-only | [specialist] Return recent MCP runtime logs, recent tool interactions, and tails of common project log files. |
+| `search_project_logs` | `core`, `full` | read-only | [specialist] Search common Cocos project log files for a string or regular expression. |
+
+### Other
+
+| Tool | Profiles | Access | Description |
+|---|---|---|---|
+| `get_performance_snapshot` | `core`, `full` | read-only | [specialist] Return scene scale and runtime performance-oriented counters such as node/component counts, UI counts, depth, memory, and warnings. |
+| `list_editor_windows` | `core`, `full` | read-only | [specialist] List available Electron windows so screenshots or input-targeting can choose the correct window. Use this when window targeting is the explicit problem. |
+
+### Prefabs
+
+| Tool | Profiles | Access | Description |
+|---|---|---|---|
+| `apply_prefab_instance` | `full` | stateful | [core] Apply a scene prefab instance back to its associated prefab asset using the Cocos editor scene apply-prefab message. |
+| `create_prefab_instance` | `full` | stateful | [core] Create a linked prefab instance in the editor hierarchy using Cocos scene create-node when available. |
+| `duplicate_prefab` | `full` | stateful | [core] Create a new prefab asset by duplicating an existing prefab file without copying its .meta UUID. |
+| `edit_prefab_json` | `full` | stateful | [core] Edit a prefab JSON file by JSON path assignment or literal search/replace, then validate references. |
+| `inspect_prefab` | `core`, `full` | read-only | [specialist] Inspect a prefab asset, its metadata, serialized file path, and UUID-like asset references. |
+| `inspect_prefab_instance` | `core`, `full` | read-only | [specialist] Inspect whether a scene node is linked to a prefab instance and return prefab metadata when available. |
+| `instantiate_prefab` | `full` | stateful | Instantiate a prefab into the active scene by prefab uuid. |
+| `list_prefabs` | `full` | read-only | [core] List prefab assets in the project. |
+| `revert_prefab_instance` | `full` | stateful | [core] Revert a scene prefab instance from its associated prefab asset using available Cocos editor prefab revert messages. |
+
+### Project
+
+| Tool | Profiles | Access | Description |
+|---|---|---|---|
+| `get_editor_state` | `core`, `full` | read-only | [specialist] Return a structured editor-state snapshot including project info, runtime server status, current selection, and visible Electron windows. Prefer this when you want one compact editor summary. |
+| `get_project_info` | `core`, `full` | read-only | [specialist] Return the active Cocos project path, version, and MCP server configuration. Prefer this for a fast structured project summary; use execute_javascript when you need to inspect and act in one step. |
+| `get_tool_catalog` | `core`, `full` | read-only | [specialist] Return every built-in MCP tool with profile, category, and current exposure state. Use this before changing custom tool exposure. |
+
+### Runtime
+
+| Tool | Profiles | Access | Description |
+|---|---|---|---|
+| `emit_node_event` | `full` | mutating | [core] Emit a custom event on a target scene node with an optional JSON payload. |
+| `get_runtime_state` | `core`, `full` | read-only | [specialist] Return structured Cocos runtime state including pause state, frame count, and scheduler time scale. Prefer this when you want a compact validation snapshot. |
+| `pause_runtime` | `full` | stateful | [core] Pause Cocos director game logic execution. |
+| `resume_runtime` | `full` | stateful | [core] Resume Cocos director game logic execution. |
+| `set_time_scale` | `full` | mutating | [core] Set Cocos scheduler time scale for runtime validation. |
+
+### Scene
+
+| Tool | Profiles | Access | Description |
+|---|---|---|---|
+| `create_node` | `full` | stateful | Create a new node under the active scene or a specified parent path. |
+| `delete_node` | `full` | mutating | Delete a node by path, uuid, or name. |
+| `execute_scene_script` | `core`, `full` | mutating | [compat] Execute JavaScript in the active Cocos scene context. Prefer execute_javascript with context="scene" as the main unified tool; use this when you specifically want the scene-only compatibility entrypoint. |
+| `find_nodes` | `full` | read-only | [core] Find scene nodes by exact name, partial path, or component type. |
+| `get_hierarchy` | `core`, `full` | read-only | [specialist] Return a structured hierarchy tree from the active scene or a specific node path. Prefer execute_javascript for broader reasoning or repair; use this when you want a predictable hierarchy snapshot. |
+| `get_scene_info` | `core`, `full` | read-only | [specialist] Return a structured summary of the active Cocos scene. Prefer execute_javascript for multi-step inspection or mutation; use this when you specifically want a compact scene snapshot. |
+| `inspect_node` | `full` | read-only | [core] Inspect a specific node by path, uuid, or name. |
+| `set_node_transform` | `full` | mutating | Update node position, rotation, scale, or active state. |
+
+### Screenshots
+
+| Tool | Profiles | Access | Description |
+|---|---|---|---|
+| `capture_desktop_screenshot` | `full` | read-only | [core] Capture a screenshot from the local desktop and return it as an MCP image payload. |
+| `capture_editor_screenshot` | `core`, `full` | read-only | [specialist] Capture the focused Cocos Creator editor window and return it as an MCP image payload. Prefer screenshot tools only when visual verification is explicitly needed. |
+| `capture_game_screenshot` | `full` | read-only | [core] Capture the Game/Preview panel region from the editor window with panel-level cropping when available. |
+| `capture_preview_screenshot` | `core`, `full` | read-only | [specialist] Capture the preview or simulator window as an MCP image payload. Prefer this only when you need visual proof of game or preview output. |
+| `capture_scene_screenshot` | `core`, `full` | read-only | [specialist] Capture the Scene panel region from the editor window with panel-level cropping when available. Prefer this only for visual validation of scene-side results. |
+
+### Selection
+
+| Tool | Profiles | Access | Description |
+|---|---|---|---|
+| `get_editor_selection` | `full` | read-only | [compat] Return the current node and asset selection in the Cocos editor. Prefer get_selection as the primary structured selection read tool. |
+| `get_selection` | `core`, `full` | read-only | [specialist] Return the current editor selection in a compact structured form. Prefer this when selection state matters for the next action. |
+| `set_selection` | `core`, `full` | mutating | [specialist] Set or clear the current editor selection for an asset or node. Use this when downstream editor workflows depend on selection state. |
+
+### Ui
+
+| Tool | Profiles | Access | Description |
+|---|---|---|---|
+| `create_button` | `full` | stateful | Create a UI Button node with child Label. |
+| `create_canvas` | `full` | stateful | Create a Cocos Canvas node with UITransform. |
+| `create_label` | `full` | stateful | Create a UI Label node under a parent. |
+| `create_sprite` | `full` | stateful | Create a UI Sprite node, optionally assigning a SpriteFrame asset uuid. |
+
+### Updates
+
+| Tool | Profiles | Access | Description |
+|---|---|---|---|
+| `check_for_updates` | `core`, `full` | read-only | [specialist] Check the latest Funplay Cocos MCP GitHub release and compare it with the installed extension version. |
+

lib/server.js

@@ -140,11 +140,33 @@ class McpServer {
 
     const requestHandler = async (request, response) => {
       try {
-        if (request.method === 'GET' && request.url === '/health') {
+        const requestUrl = new URL(request.url || '/', 'http://localhost');
+        if (request.method === 'GET' && requestUrl.pathname === '/health') {
           this.log('info', 'GET /health');
           return json(response, 200, { ok: true, name: this.serverName, version: this.serverVersion }, this.negotiatedProtocolVersion);
         }
 
+        if (request.method === 'GET' && requestUrl.pathname === '/tools') {
+          this.log('info', 'GET /tools');
+          const includeCatalog = requestUrl.searchParams.get('catalog') === '1';
+          const tools = includeCatalog && typeof this.toolRegistry.listToolCatalog === 'function'
+            ? this.toolRegistry.listToolCatalog()
+            : this.toolRegistry.listTools();
+          const baseUrl = `http://${request.headers.host || `${this.config.host}:${this.getPort()}`}`;
+          return json(response, 200, {
+            ok: true,
+            name: this.serverName,
+            version: this.serverVersion,
+            count: tools.length,
+            tools,
+            examples: {
+              health: `curl ${baseUrl}/health`,
+              tools: `curl ${baseUrl}/tools`,
+              catalog: `curl ${baseUrl}/tools?catalog=1`,
+            },
+          }, this.negotiatedProtocolVersion);
+        }
+
         if (!this.isAllowedOrigin(request)) {
           this.log('warn', `Rejected ${request.method} ${request.url}: invalid Origin header.`);
           return json(response, 403, { error: 'Forbidden: invalid Origin header' }, this.negotiatedProtocolVersion);

lib/tool-registry.js

@@ -2,7 +2,6 @@
 
 const crypto = require('crypto');
 const fs = require('fs');
-const path = require('path');
 const {
   clearSelection,
   deleteAsset,
@@ -37,12 +36,14 @@ const {
   revertPrefabInstance,
   validatePrefabReferences,
 } = require('./prefabs');
+const { buildSnippet, createFileTools, refreshAssets } = require('./tools/files');
 const { captureDesktopScreenshot, captureEditorWindowScreenshot, capturePanelScreenshot } = require('./screenshots');
 const { checkForUpdate } = require('./update-checker');
 const { safeStringify } = require('./utils');
 const IMAGE_DATA_URI_PREFIX = 'data:image/png;base64,';
 
 const TOOL_CATEGORY_RULES = [
+  ['project', /^(get_project_info|get_editor_state|get_tool_catalog)$/],
   ['updates', /update/],
   ['logs', /log/],
   ['diagnostics', /diagnostic|validate/],
@@ -60,7 +61,6 @@ const TOOL_CATEGORY_RULES = [
   ['runtime', /runtime|time_scale|node_event|invoke_component/],
   ['scene', /scene|hierarchy|node/],
   ['execution', /execute_/],
-  ['project', /project|editor_state|tool_catalog/],
 ];
 
 function createSchema(properties, required) {
@@ -306,91 +306,6 @@ function toOutput(value) {
   return safeStringify(value);
 }
 
-function matchesPattern(fileName, pattern) {
-  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
-  return new RegExp(`^${escaped}$`, 'i').test(fileName);
-}
-
-function searchFiles(rootDir, pattern, limit) {
-  const results = [];
-  if (!fs.existsSync(rootDir)) {
-    return results;
-  }
-
-  const stack = [rootDir];
-  while (stack.length && results.length < limit) {
-    const current = stack.pop();
-    const entries = fs.readdirSync(current, { withFileTypes: true });
-    for (const entry of entries) {
-      if (entry.name === '.git' || entry.name === 'node_modules' || entry.name === 'temp' || entry.name === 'library') {
-        continue;
-      }
-
-      const fullPath = path.join(current, entry.name);
-      if (entry.isDirectory()) {
-        stack.push(fullPath);
-        continue;
-      }
-
-      if (matchesPattern(entry.name, pattern)) {
-        results.push(fullPath);
-        if (results.length >= limit) {
-          break;
-        }
-      }
-    }
-  }
-
-  return results;
-}
-
-function readLines(filePath) {
-  return fs.readFileSync(filePath, 'utf8').split(/\r?\n/);
-}
-
-function buildSnippet(filePath, lineNumber, contextLines = 3) {
-  const lines = readLines(filePath);
-  const start = Math.max(1, Number(lineNumber || 1) - Math.max(0, contextLines));
-  const end = Math.min(lines.length, Number(lineNumber || 1) + Math.max(0, contextLines));
-  const snippet = [];
-  for (let line = start; line <= end; line += 1) {
-    const marker = line === Number(lineNumber || 1) ? '>' : ' ';
-    snippet.push(`${marker} ${String(line).padStart(4, ' ')} | ${lines[line - 1]}`);
-  }
-  return snippet.join('\n');
-}
-
-function replaceAllLiteral(content, search, replacement) {
-  if (!search) {
-    throw new Error('search text is required.');
-  }
-  return content.split(search).join(replacement);
-}
-
-async function refreshAssets(projectPath, targetPath) {
-  if (!global.Editor || !Editor.Message || typeof Editor.Message.request !== 'function') {
-    return 'Asset refresh API is unavailable; Cocos Creator should pick up file changes automatically.';
-  }
-
-  const relative = path.relative(path.join(projectPath, 'assets'), targetPath).replace(/\\/g, '/');
-  if (!relative.startsWith('..')) {
-    const dbUrl = `db://assets/${relative}`;
-    try {
-      await Editor.Message.request('asset-db', 'refresh-asset', dbUrl);
-      return `Refreshed asset database for ${dbUrl}`;
-    } catch (error) {
-      try {
-        await Editor.Message.request('asset-db', 'refresh-asset', 'db://assets');
-        return `Refreshed asset database after writing ${dbUrl}`;
-      } catch (innerError) {
-        return `File written, but asset refresh failed: ${innerError.message}`;
-      }
-    }
-  }
-
-  return 'File written outside assets directory; no asset-db refresh was needed.';
-}
-
 async function resolveNodeUuid(sceneBridge, args) {
   if (args && args.uuid) {
     return String(args.uuid);
@@ -1337,195 +1252,7 @@ function createToolRegistry({ getRuntimeContext, getStatus, interactionLog, runt
       ),
       handler: async (args) => sceneBridge.call('stopAnimation', args),
     },
-    {
+    ...createFileTools({ createSchema, getRuntimeContext }),
-      name: 'read_file',
-      profile: 'full',
-      description: '[core] Read a file from the Cocos project.',
-      inputSchema: createSchema(
-        {
-          path: { type: 'string', description: 'Project-relative or absolute file path.' },
-        },
-        ['path']
-      ),
-      handler: async (args) => {
-        const { projectPath } = getRuntimeContext();
-        const fullPath = resolveProjectPath(projectPath, args.path);
-        if (!fs.existsSync(fullPath)) {
-          throw new Error(`File not found: ${args.path}`);
-        }
-        const content = fs.readFileSync(fullPath, 'utf8');
-        return content.length > 12000 ? `${content.slice(0, 12000)}\n... (truncated)` : content;
-      },
-    },
-    {
-      name: 'get_file_snippet',
-      profile: 'full',
-      description: '[core] Read a focused snippet around a file line number.',
-      inputSchema: createSchema(
-        {
-          path: { type: 'string', description: 'Project-relative or absolute file path.' },
-          line: { type: 'number', description: 'Target line number, starting at 1.' },
-          contextLines: { type: 'number', description: 'Number of surrounding context lines.' },
-        },
-        ['path', 'line']
-      ),
-      handler: async (args) => {
-        const { projectPath } = getRuntimeContext();
-        const fullPath = resolveProjectPath(projectPath, args.path);
-        if (!fs.existsSync(fullPath)) {
-          throw new Error(`File not found: ${args.path}`);
-        }
-        return buildSnippet(fullPath, args.line, Number.isFinite(args.contextLines) ? args.contextLines : 3);
-      },
-    },
-    {
-      name: 'write_file',
-      profile: 'full',
-      description: '[core] Write or overwrite a file in the Cocos project.',
-      inputSchema: createSchema(
-        {
-          path: { type: 'string', description: 'Project-relative or absolute file path.' },
-          content: { type: 'string', description: 'File content to write.' },
-        },
-        ['path', 'content']
-      ),
-      handler: async (args) => {
-        const { projectPath } = getRuntimeContext();
-        const fullPath = resolveProjectPath(projectPath, args.path);
-        fs.mkdirSync(path.dirname(fullPath), { recursive: true });
-        fs.writeFileSync(fullPath, args.content, 'utf8');
-        return `Wrote ${args.content.length} chars to ${args.path}\n${await refreshAssets(projectPath, fullPath)}`;
-      },
-    },
-    {
-      name: 'replace_in_file',
-      profile: 'full',
-      description: '[core] Replace text in a file, useful for script auto-fix loops.',
-      inputSchema: createSchema(
-        {
-          path: { type: 'string', description: 'Project-relative or absolute file path.' },
-          search: { type: 'string', description: 'Literal text to search for.' },
-          replace: { type: 'string', description: 'Replacement text.' },
-          replaceAll: { type: 'boolean', description: 'Replace every occurrence instead of only the first.' },
-        },
-        ['path', 'search', 'replace']
-      ),
-      handler: async (args) => {
-        const { projectPath } = getRuntimeContext();
-        const fullPath = resolveProjectPath(projectPath, args.path);
-        if (!fs.existsSync(fullPath)) {
-          throw new Error(`File not found: ${args.path}`);
-        }
-
-        const original = fs.readFileSync(fullPath, 'utf8');
-        if (!original.includes(args.search)) {
-          throw new Error(`Search text was not found in ${args.path}`);
-        }
-
-        const updated = args.replaceAll
-          ? replaceAllLiteral(original, args.search, args.replace)
-          : original.replace(args.search, args.replace);
-
-        fs.writeFileSync(fullPath, updated, 'utf8');
-        return `Updated ${args.path} (${args.replaceAll ? 'all matches' : 'first match'})\n${await refreshAssets(projectPath, fullPath)}`;
-      },
-    },
-    {
-      name: 'search_files',
-      profile: 'full',
-      description: '[core] Search project files by simple wildcard pattern.',
-      inputSchema: createSchema(
-        {
-          pattern: { type: 'string', description: "Wildcard file pattern such as '*.ts' or 'Player*'." },
-          directory: { type: 'string', description: 'Project-relative search root. Defaults to assets.' },
-          limit: { type: 'number', description: 'Maximum number of results to return.' },
-        },
-        ['pattern']
-      ),
-      handler: async (args) => {
-        const { projectPath } = getRuntimeContext();
-        const searchRoot = resolveProjectPath(projectPath, args.directory || 'assets');
-        if (!fs.existsSync(searchRoot)) {
-          throw new Error(`Directory not found: ${args.directory || 'assets'}`);
-        }
-
-        const limit = Number.isFinite(args.limit) ? Math.max(1, Math.min(500, args.limit)) : 100;
-        const results = searchFiles(searchRoot, args.pattern, limit).map((fullPath) =>
-          path.relative(projectPath, fullPath).replace(/\\/g, '/')
-        );
-        return {
-          count: results.length,
-          files: results,
-        };
-      },
-    },
-    {
-      name: 'list_directory',
-      profile: 'full',
-      description: '[core] List files and directories inside a project directory.',
-      inputSchema: createSchema(
-        {
-          path: { type: 'string', description: 'Project-relative or absolute directory path.' },
-        },
-        ['path']
-      ),
-      handler: async (args) => {
-        const { projectPath } = getRuntimeContext();
-        const targetPath = resolveProjectPath(projectPath, args.path);
-        if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
-          throw new Error(`Directory not found: ${args.path}`);
-        }
-
-        const entries = fs
-          .readdirSync(targetPath, { withFileTypes: true })
-          .filter((entry) => !entry.name.startsWith('.'))
-          .map((entry) => ({
-            name: entry.name,
-            type: entry.isDirectory() ? 'directory' : 'file',
-          }));
-        return {
-          path: args.path,
-          entries,
-        };
-      },
-    },
-    {
-      name: 'exists',
-      profile: 'full',
-      description: '[core] Check whether a project file or directory exists.',
-      inputSchema: createSchema(
-        {
-          path: { type: 'string', description: 'Project-relative or absolute path.' },
-        },
-        ['path']
-      ),
-      handler: async (args) => {
-        const { projectPath } = getRuntimeContext();
-        const targetPath = resolveProjectPath(projectPath, args.path);
-        return {
-          path: args.path,
-          exists: fs.existsSync(targetPath),
-          isFile: fs.existsSync(targetPath) ? fs.statSync(targetPath).isFile() : false,
-          isDirectory: fs.existsSync(targetPath) ? fs.statSync(targetPath).isDirectory() : false,
-        };
-      },
-    },
-    {
-      name: 'refresh_assets',
-      profile: 'full',
-      description: '[core] Best-effort asset database refresh for a file or the assets root.',
-      inputSchema: createSchema(
-        {
-          path: { type: 'string', description: 'Optional project-relative file path to refresh.' },
-        },
-        []
-      ),
-      handler: async (args) => {
-        const { projectPath } = getRuntimeContext();
-        const targetPath = resolveProjectPath(projectPath, args.path || 'assets');
-        return await refreshAssets(projectPath, targetPath);
-      },
-    },
     {
       name: 'run_script_diagnostics',
       profile: 'core',

lib/tools/files.js

@@ -0,0 +1,303 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { resolveProjectPath } = require('../path-safety');
+
+/**
+ * Build a focused, line-numbered snippet around one file line.
+ * @param {string} filePath Absolute file path.
+ * @param {number} lineNumber One-based target line number.
+ * @param {number} contextLines Surrounding lines to include.
+ * @returns {string}
+ */
+function buildSnippet(filePath, lineNumber, contextLines = 3) {
+  const lines = fs.readFileSync(filePath, 'utf8').split(/\r?\n/);
+  const start = Math.max(1, Number(lineNumber || 1) - Math.max(0, contextLines));
+  const end = Math.min(lines.length, Number(lineNumber || 1) + Math.max(0, contextLines));
+  const snippet = [];
+  for (let line = start; line <= end; line += 1) {
+    const marker = line === Number(lineNumber || 1) ? '>' : ' ';
+    snippet.push(`${marker} ${String(line).padStart(4, ' ')} | ${lines[line - 1]}`);
+  }
+  return snippet.join('\n');
+}
+
+function matchesPattern(fileName, pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*');
+  return new RegExp(`^${escaped}$`, 'i').test(fileName);
+}
+
+function searchFiles(rootDir, pattern, limit) {
+  const results = [];
+  if (!fs.existsSync(rootDir)) {
+    return results;
+  }
+
+  const stack = [rootDir];
+  while (stack.length && results.length < limit) {
+    const current = stack.pop();
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name === '.git' || entry.name === 'node_modules' || entry.name === 'temp' || entry.name === 'library') {
+        continue;
+      }
+
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+        continue;
+      }
+
+      if (matchesPattern(entry.name, pattern)) {
+        results.push(fullPath);
+        if (results.length >= limit) {
+          break;
+        }
+      }
+    }
+  }
+
+  return results;
+}
+
+function replaceAllLiteral(content, search, replacement) {
+  if (!search) {
+    throw new Error('search text is required.');
+  }
+  return content.split(search).join(replacement);
+}
+
+/**
+ * Best-effort refresh for Cocos asset database after external file edits.
+ * @param {string} projectPath Active Cocos project root.
+ * @param {string} targetPath Absolute file or directory path.
+ * @returns {Promise<string>}
+ */
+async function refreshAssets(projectPath, targetPath) {
+  if (!global.Editor || !Editor.Message || typeof Editor.Message.request !== 'function') {
+    return 'Asset refresh API is unavailable; Cocos Creator should pick up file changes automatically.';
+  }
+
+  const relative = path.relative(path.join(projectPath, 'assets'), targetPath).replace(/\\/g, '/');
+  if (!relative.startsWith('..')) {
+    const dbUrl = `db://assets/${relative}`;
+    try {
+      await Editor.Message.request('asset-db', 'refresh-asset', dbUrl);
+      return `Refreshed asset database for ${dbUrl}`;
+    } catch (error) {
+      try {
+        await Editor.Message.request('asset-db', 'refresh-asset', 'db://assets');
+        return `Refreshed asset database after writing ${dbUrl}`;
+      } catch (innerError) {
+        return `File written, but asset refresh failed: ${innerError.message}`;
+      }
+    }
+  }
+
+  return 'File written outside assets directory; no asset-db refresh was needed.';
+}
+
+/**
+ * File-system tools. Kept separate from the registry so path safety and asset
+ * refresh behavior can be tested and evolved independently.
+ */
+function createFileTools({ createSchema, getRuntimeContext }) {
+  return [
+    {
+      name: 'read_file',
+      profile: 'full',
+      description: '[core] Read a file from the Cocos project.',
+      inputSchema: createSchema(
+        {
+          path: { type: 'string', description: 'Project-relative or absolute file path.' },
+        },
+        ['path']
+      ),
+      handler: async (args) => {
+        const { projectPath } = getRuntimeContext();
+        const fullPath = resolveProjectPath(projectPath, args.path);
+        if (!fs.existsSync(fullPath)) {
+          throw new Error(`File not found: ${args.path}`);
+        }
+        const content = fs.readFileSync(fullPath, 'utf8');
+        return content.length > 12000 ? `${content.slice(0, 12000)}\n... (truncated)` : content;
+      },
+    },
+    {
+      name: 'get_file_snippet',
+      profile: 'full',
+      description: '[core] Read a focused snippet around a file line number.',
+      inputSchema: createSchema(
+        {
+          path: { type: 'string', description: 'Project-relative or absolute file path.' },
+          line: { type: 'number', description: 'Target line number, starting at 1.' },
+          contextLines: { type: 'number', description: 'Number of surrounding context lines.' },
+        },
+        ['path', 'line']
+      ),
+      handler: async (args) => {
+        const { projectPath } = getRuntimeContext();
+        const fullPath = resolveProjectPath(projectPath, args.path);
+        if (!fs.existsSync(fullPath)) {
+          throw new Error(`File not found: ${args.path}`);
+        }
+        return buildSnippet(fullPath, args.line, Number.isFinite(args.contextLines) ? args.contextLines : 3);
+      },
+    },
+    {
+      name: 'write_file',
+      profile: 'full',
+      description: '[core] Write or overwrite a file in the Cocos project.',
+      inputSchema: createSchema(
+        {
+          path: { type: 'string', description: 'Project-relative or absolute file path.' },
+          content: { type: 'string', description: 'File content to write.' },
+        },
+        ['path', 'content']
+      ),
+      handler: async (args) => {
+        const { projectPath } = getRuntimeContext();
+        const fullPath = resolveProjectPath(projectPath, args.path);
+        fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+        fs.writeFileSync(fullPath, args.content, 'utf8');
+        return `Wrote ${args.content.length} chars to ${args.path}\n${await refreshAssets(projectPath, fullPath)}`;
+      },
+    },
+    {
+      name: 'replace_in_file',
+      profile: 'full',
+      description: '[core] Replace text in a file, useful for script auto-fix loops.',
+      inputSchema: createSchema(
+        {
+          path: { type: 'string', description: 'Project-relative or absolute file path.' },
+          search: { type: 'string', description: 'Literal text to search for.' },
+          replace: { type: 'string', description: 'Replacement text.' },
+          replaceAll: { type: 'boolean', description: 'Replace every occurrence instead of only the first.' },
+        },
+        ['path', 'search', 'replace']
+      ),
+      handler: async (args) => {
+        const { projectPath } = getRuntimeContext();
+        const fullPath = resolveProjectPath(projectPath, args.path);
+        if (!fs.existsSync(fullPath)) {
+          throw new Error(`File not found: ${args.path}`);
+        }
+
+        const original = fs.readFileSync(fullPath, 'utf8');
+        if (!original.includes(args.search)) {
+          throw new Error(`Search text was not found in ${args.path}`);
+        }
+
+        const updated = args.replaceAll
+          ? replaceAllLiteral(original, args.search, args.replace)
+          : original.replace(args.search, args.replace);
+
+        fs.writeFileSync(fullPath, updated, 'utf8');
+        return `Updated ${args.path} (${args.replaceAll ? 'all matches' : 'first match'})\n${await refreshAssets(projectPath, fullPath)}`;
+      },
+    },
+    {
+      name: 'search_files',
+      profile: 'full',
+      description: '[core] Search project files by simple wildcard pattern.',
+      inputSchema: createSchema(
+        {
+          pattern: { type: 'string', description: "Wildcard file pattern such as '*.ts' or 'Player*'." },
+          directory: { type: 'string', description: 'Project-relative search root. Defaults to assets.' },
+          limit: { type: 'number', description: 'Maximum number of results to return.' },
+        },
+        ['pattern']
+      ),
+      handler: async (args) => {
+        const { projectPath } = getRuntimeContext();
+        const searchRoot = resolveProjectPath(projectPath, args.directory || 'assets');
+        if (!fs.existsSync(searchRoot)) {
+          throw new Error(`Directory not found: ${args.directory || 'assets'}`);
+        }
+
+        const limit = Number.isFinite(args.limit) ? Math.max(1, Math.min(500, args.limit)) : 100;
+        const results = searchFiles(searchRoot, args.pattern, limit).map((fullPath) =>
+          path.relative(projectPath, fullPath).replace(/\\/g, '/')
+        );
+        return {
+          count: results.length,
+          files: results,
+        };
+      },
+    },
+    {
+      name: 'list_directory',
+      profile: 'full',
+      description: '[core] List files and directories inside a project directory.',
+      inputSchema: createSchema(
+        {
+          path: { type: 'string', description: 'Project-relative or absolute directory path.' },
+        },
+        ['path']
+      ),
+      handler: async (args) => {
+        const { projectPath } = getRuntimeContext();
+        const targetPath = resolveProjectPath(projectPath, args.path);
+        if (!fs.existsSync(targetPath) || !fs.statSync(targetPath).isDirectory()) {
+          throw new Error(`Directory not found: ${args.path}`);
+        }
+
+        const entries = fs
+          .readdirSync(targetPath, { withFileTypes: true })
+          .filter((entry) => !entry.name.startsWith('.'))
+          .map((entry) => ({
+            name: entry.name,
+            type: entry.isDirectory() ? 'directory' : 'file',
+          }));
+        return {
+          path: args.path,
+          entries,
+        };
+      },
+    },
+    {
+      name: 'exists',
+      profile: 'full',
+      description: '[core] Check whether a project file or directory exists.',
+      inputSchema: createSchema(
+        {
+          path: { type: 'string', description: 'Project-relative or absolute path.' },
+        },
+        ['path']
+      ),
+      handler: async (args) => {
+        const { projectPath } = getRuntimeContext();
+        const targetPath = resolveProjectPath(projectPath, args.path);
+        return {
+          path: args.path,
+          exists: fs.existsSync(targetPath),
+          isFile: fs.existsSync(targetPath) ? fs.statSync(targetPath).isFile() : false,
+          isDirectory: fs.existsSync(targetPath) ? fs.statSync(targetPath).isDirectory() : false,
+        };
+      },
+    },
+    {
+      name: 'refresh_assets',
+      profile: 'full',
+      description: '[core] Best-effort asset database refresh for a file or the assets root.',
+      inputSchema: createSchema(
+        {
+          path: { type: 'string', description: 'Optional project-relative file path to refresh.' },
+        },
+        []
+      ),
+      handler: async (args) => {
+        const { projectPath } = getRuntimeContext();
+        const targetPath = resolveProjectPath(projectPath, args.path || 'assets');
+        return await refreshAssets(projectPath, targetPath);
+      },
+    },
+  ];
+}
+
+module.exports = {
+  buildSnippet,
+  createFileTools,
+  refreshAssets,
+};

package.json

@@ -1,17 +1,63 @@
 {
   "name": "funplay-cocos-mcp",
   "package_version": 2,
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "Embedded MCP server for Cocos Creator with scene script execution, project resources, prompts, and file/scene tools.",
   "author": "Funplay",
   "license": "MIT",
   "main": "browser.js",
+  "bin": {
+    "funplay-cocos-mcp": "bin/funplay-cocos-mcp.js"
+  },
+  "mcpName": "io.github.FunplayAI/funplay-cocos-mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/FunplayAI/funplay-cocos-mcp.git"
+  },
+  "homepage": "https://github.com/FunplayAI/funplay-cocos-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/FunplayAI/funplay-cocos-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "cocos",
+    "cocos-creator",
+    "funplay",
+    "model-context-protocol",
+    "ai"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "docs/",
+    "lib/",
+    "panel/",
+    "browser.js",
+    "scene.js",
+    "server.json",
+    "README.md",
+    "README_CN.md",
+    "CHANGELOG.md",
+    "CONTRIBUTING.md",
+    "LICENSE",
+    "RELEASE_WORKFLOW.md",
+    "RELEASE_CHECKLIST.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
-    "check": "node --check browser.js && node --check scene.js && node --check panel/index.js && node --check lib/assets.js && node --check lib/client-config.js && node --check lib/config.js && node --check lib/diagnostics.js && node --check lib/electron-tools.js && node --check lib/input.js && node --check lib/interaction-log.js && node --check lib/logs.js && node --check lib/path-safety.js && node --check lib/prefabs.js && node --check lib/project-instructions.js && node --check lib/prompts.js && node --check lib/resources.js && node --check lib/runtime-log.js && node --check lib/screenshots.js && node --check lib/server.js && node --check lib/tool-registry.js && node --check lib/update-checker.js && node --check lib/utils.js && node --check scripts/release.js",
+    "check": "node --check browser.js && node --check scene.js && node --check panel/index.js && node --check bin/funplay-cocos-mcp.js && node --check lib/assets.js && node --check lib/client-config.js && node --check lib/config.js && node --check lib/diagnostics.js && node --check lib/electron-tools.js && node --check lib/input.js && node --check lib/interaction-log.js && node --check lib/logs.js && node --check lib/path-safety.js && node --check lib/prefabs.js && node --check lib/project-instructions.js && node --check lib/prompts.js && node --check lib/resources.js && node --check lib/runtime-log.js && node --check lib/screenshots.js && node --check lib/server.js && node --check lib/tool-registry.js && node --check lib/tools/files.js && node --check lib/update-checker.js && node --check lib/utils.js && node --check scripts/generate-tool-docs.js && node --check scripts/release.js",
     "test": "node --test",
-    "release:check": "node scripts/release.js check",
+    "docs:generate": "node scripts/generate-tool-docs.js",
+    "docs:check": "node scripts/generate-tool-docs.js --check",
+    "pack:dry-run": "npm pack --dry-run",
+    "registry:validate": "mcp-publisher validate server.json",
+    "release:check": "node scripts/release.js check && npm run docs:check",
     "release:package": "node scripts/release.js package",
-    "release:verify": "npm run check && npm test && npm run release:check && npm run release:package"
+    "release:verify": "npm run check && npm test && npm run release:check && npm run pack:dry-run && npm run release:package"
   },
   "panels": {
     "default": {

panel/index.js

@@ -34,6 +34,8 @@ module.exports = Editor.Panel.define({
           </label>
           <ui-button id="restartBtn">Restart</ui-button>
           <ui-button id="copyUrlBtn">Copy URL</ui-button>
+          <ui-button id="copyHealthCurlBtn">Copy Health Curl</ui-button>
+          <ui-button id="copyToolsCurlBtn">Copy Tools Curl</ui-button>
           <ui-button id="checkUpdatesBtn">Check Updates</ui-button>
         </div>
         <div class="grid">
@@ -70,6 +72,20 @@ module.exports = Editor.Panel.define({
         </div>
       </section>
 
+      <section class="card">
+        <h2>Activity</h2>
+        <div class="activity-grid">
+          <div class="activity-column">
+            <h3>Recent Calls</h3>
+            <div id="recentCalls" class="mini-list muted"></div>
+          </div>
+          <div class="activity-column">
+            <h3>Log Preview</h3>
+            <div id="recentLogs" class="mini-list muted"></div>
+          </div>
+        </div>
+      </section>
+
       <section class="card">
         <h2>MCP Client Config</h2>
         <div class="row">
@@ -114,6 +130,12 @@ module.exports = Editor.Panel.define({
       margin: 0 0 10px 0;
       font-size: 15px;
     }
+    h3 {
+      margin: 0 0 6px 0;
+      font-size: 12px;
+      font-weight: 600;
+      color: var(--color-normal-contrast-weak);
+    }
     p {
       margin: 4px 0 0 0;
       color: var(--color-normal-contrast-weakest);
@@ -199,6 +221,46 @@ module.exports = Editor.Panel.define({
       white-space: pre-wrap;
       word-break: break-all;
     }
+    .activity-grid {
+      display: grid;
+      grid-template-columns: repeat(2, minmax(180px, 1fr));
+      gap: 10px;
+    }
+    .mini-list {
+      min-height: 74px;
+      max-height: 158px;
+      overflow: auto;
+      box-sizing: border-box;
+      border: 1px solid var(--color-normal-border);
+      border-radius: 6px;
+      padding: 8px;
+      background: rgba(0,0,0,0.12);
+      line-height: 1.35;
+    }
+    .mini-item {
+      padding: 0 0 8px 0;
+      margin-bottom: 8px;
+      border-bottom: 1px solid rgba(255,255,255,0.08);
+    }
+    .mini-item:last-child {
+      margin-bottom: 0;
+      padding-bottom: 0;
+      border-bottom: none;
+    }
+    .mini-title {
+      color: var(--color-normal-contrast);
+      font-weight: 600;
+      word-break: break-word;
+    }
+    .mini-meta {
+      margin-top: 2px;
+      color: var(--color-normal-contrast-weakest);
+      font-size: 11px;
+    }
+    .mini-body {
+      margin-top: 2px;
+      word-break: break-word;
+    }
     details {
       display: block;
     }
@@ -232,6 +294,11 @@ module.exports = Editor.Panel.define({
     .primary {
       border-color: #4aa3ff;
     }
+    @media (max-width: 620px) {
+      .activity-grid {
+        grid-template-columns: 1fr;
+      }
+    }
   `,
   $: {
     root: '.mcp-root',
@@ -244,6 +311,8 @@ module.exports = Editor.Panel.define({
     sessionsInput: '#sessionsInput',
     restartBtn: '#restartBtn',
     copyUrlBtn: '#copyUrlBtn',
+    copyHealthCurlBtn: '#copyHealthCurlBtn',
+    copyToolsCurlBtn: '#copyToolsCurlBtn',
     checkUpdatesBtn: '#checkUpdatesBtn',
     updateStatus: '#updateStatus',
     toolSummary: '#toolSummary',
@@ -258,6 +327,8 @@ module.exports = Editor.Panel.define({
     configureClientBtn: '#configureClientBtn',
     clientTargetStatus: '#clientTargetStatus',
     clientConfigText: '#clientConfigText',
+    recentCalls: '#recentCalls',
+    recentLogs: '#recentLogs',
     output: '#output',
   },
   methods: {
@@ -295,9 +366,8 @@ module.exports = Editor.Panel.define({
       this.$.disabledToolsInput.value = this.formatList(config.disabledTools);
       this.renderUpdateStatus();
       this.renderToolSummary();
-
-      this.$.clientConfigText.value = state.clientConfig ? state.clientConfig.codex : '';
       this.renderClientTargets();
+      this.renderActivity();
     },
     formatList(value) {
       return Array.isArray(value) ? value.join('\n') : '';
@@ -329,6 +399,75 @@ module.exports = Editor.Panel.define({
       this.$.toolSummary.textContent =
         `Enabled ${enabled.length}/${catalog.length} tools  |  Categories: ${categories.join(', ')}`;
     },
+    renderActivity() {
+      const state = this.state || {};
+      this.renderMiniList(
+        this.$.recentCalls,
+        state.recentInteractions || [],
+        (entry) => ({
+          title: `${String(entry.status || '').toUpperCase()} ${entry.toolName || 'tool'}`,
+          meta: this.formatTimestamp(entry.timestamp),
+          body: entry.summary || '',
+        }),
+        'No recent MCP calls.'
+      );
+      this.renderMiniList(
+        this.$.recentLogs,
+        state.recentRuntimeLogs || [],
+        (entry) => ({
+          title: `${String(entry.level || 'info').toUpperCase()} ${entry.message || ''}`,
+          meta: this.formatTimestamp(entry.timestamp),
+          body: entry.details ? stringify(entry.details) : '',
+        }),
+        'No runtime logs yet.'
+      );
+    },
+    renderMiniList(container, entries, formatEntry, emptyText) {
+      container.innerHTML = '';
+      if (!entries.length) {
+        container.textContent = emptyText;
+        return;
+      }
+
+      const fragment = document.createDocumentFragment();
+      entries.slice(0, 6).forEach((entry) => {
+        const formatted = formatEntry(entry);
+        const item = document.createElement('div');
+        item.className = 'mini-item';
+
+        const title = document.createElement('div');
+        title.className = 'mini-title';
+        title.textContent = formatted.title;
+        item.appendChild(title);
+
+        if (formatted.meta) {
+          const meta = document.createElement('div');
+          meta.className = 'mini-meta';
+          meta.textContent = formatted.meta;
+          item.appendChild(meta);
+        }
+
+        if (formatted.body) {
+          const body = document.createElement('div');
+          body.className = 'mini-body';
+          body.textContent = formatted.body;
+          item.appendChild(body);
+        }
+
+        fragment.appendChild(item);
+      });
+      container.appendChild(fragment);
+    },
+    formatTimestamp(value) {
+      if (!value) {
+        return '';
+      }
+      const date = new Date(value);
+      if (Number.isNaN(date.getTime())) {
+        return String(value);
+      }
+      return date.toLocaleTimeString();
+    },
     renderClientTargets() {
       const targets = (this.state && this.state.clientTargets) || [];
       const preferred = this.state && this.state.config ? this.state.config.lastClientTargetId : '';
@@ -349,10 +488,30 @@ module.exports = Editor.Panel.define({
         return;
       }
       this.$.clientTargetStatus.textContent = `${target.configured ? 'Configured' : 'Not configured'}: ${target.configPath}`;
+      const previews = this.state && this.state.clientConfig && Array.isArray(this.state.clientConfig.targets)
+        ? this.state.clientConfig.targets
+        : [];
+      const preview = previews.find((item) => item.id === target.id);
+      this.$.clientConfigText.value = preview && preview.preview
+        ? preview.preview
+        : (this.state && this.state.clientConfig ? this.state.clientConfig.codex : '');
     },
     showOutput(value) {
       this.$.output.textContent = stringify(value);
     },
+    copyText(text, successMessage) {
+      if (!text) {
+        this.showOutput('Nothing to copy.');
+        return;
+      }
+      navigator.clipboard.writeText(text)
+        .then(() => this.showOutput(successMessage))
+        .catch(() => this.showOutput(text));
+    },
+    getCurlCommand(key) {
+      const curl = this.state && this.state.clientConfig && this.state.clientConfig.curl;
+      return curl && curl[key] ? curl[key] : '';
+    },
     async persistConfig(options = {}) {
       const { showOutput = false } = options;
       try {
@@ -415,9 +574,13 @@ module.exports = Editor.Panel.define({
     this.$.copyUrlBtn.addEventListener('click', () => {
       const status = this.state && this.state.status;
       const text = status && status.url ? status.url : '';
-      navigator.clipboard.writeText(text)
+      this.copyText(text, 'Copied URL to clipboard.');
-        .then(() => this.showOutput('Copied URL to clipboard.'))
+    });
-        .catch(() => this.showOutput(text));
+    this.$.copyHealthCurlBtn.addEventListener('click', () => {
+      this.copyText(this.getCurlCommand('health'), 'Copied health curl command.');
+    });
+    this.$.copyToolsCurlBtn.addEventListener('click', () => {
+      this.copyText(this.getCurlCommand('tools'), 'Copied tools curl command.');
     });
     this.$.checkUpdatesBtn.addEventListener('click', () => this.runAction(() => request('check-updates')));
     this.$.enabledInput.addEventListener('change', () => this.handleEnableToggle());

scripts/generate-tool-docs.js

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { createToolRegistry } = require('../lib/tool-registry');
+
+const ROOT = path.resolve(__dirname, '..');
+const OUTPUT_PATH = path.join(ROOT, 'docs', 'TOOLS.md');
+
+function createRegistry(profile) {
+  return createToolRegistry({
+    getRuntimeContext: () => ({
+      config: { toolProfile: profile },
+      projectPath: '/tmp/funplay-cocos-docs-project',
+      version: '0.0.0-docs',
+    }),
+    interactionLog: { add() {} },
+    runtimeLog: { add() {}, list: () => [], clear: () => 0 },
+    sceneBridge: { call: async () => ({ ok: true }) },
+    editorExecutor: async () => ({ ok: true }),
+  });
+}
+
+function buildToolModel() {
+  const fullRegistry = createRegistry('full');
+  const coreNames = new Set(createRegistry('core').listTools().map((tool) => tool.name));
+  const fullNames = new Set(fullRegistry.listTools().map((tool) => tool.name));
+  const catalog = fullRegistry.listToolCatalog()
+    .map((tool) => ({
+      name: tool.name,
+      category: tool.category || 'other',
+      profile: tool.profile || 'full',
+      enabledInCore: coreNames.has(tool.name),
+      enabledInFull: fullNames.has(tool.name),
+      readOnly: Boolean(tool.annotations && tool.annotations.readOnlyHint),
+      destructive: Boolean(tool.annotations && tool.annotations.destructiveHint),
+      description: normalizeDescription(tool.description),
+    }))
+    .sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
+
+  return {
+    coreCount: coreNames.size,
+    fullCount: fullNames.size,
+    catalog,
+  };
+}
+
+function normalizeDescription(description) {
+  return String(description || '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+function buildMarkdown(model) {
+  const categories = groupBy(model.catalog, (tool) => tool.category);
+  const lines = [
+    '# Tool Reference',
+    '',
+    '<!-- This file is generated by `npm run docs:generate`. Do not edit by hand. -->',
+    '',
+    `Generated from \`lib/tool-registry.js\`. The default \`core\` profile exposes ${model.coreCount} tools; the \`full\` profile exposes ${model.fullCount} tools.`,
+    '',
+    '## Profile Summary',
+    '',
+    '| Profile | Tool Count | Purpose |',
+    '|---|---:|---|',
+    `| \`core\` | ${model.coreCount} | Focused default surface for common editor automation. |`,
+    `| \`full\` | ${model.fullCount} | All built-in tools, including destructive and low-level helpers. |`,
+    '',
+    '## Core Tools',
+    '',
+    model.catalog
+      .filter((tool) => tool.enabledInCore)
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .map((tool) => `\`${tool.name}\``)
+      .join(', '),
+    '',
+    '## Tools By Category',
+    '',
+  ];
+
+  for (const category of Object.keys(categories).sort()) {
+    const tools = categories[category];
+    lines.push(`### ${titleCase(category)}`);
+    lines.push('');
+    lines.push('| Tool | Profiles | Access | Description |');
+    lines.push('|---|---|---|---|');
+    for (const tool of tools) {
+      lines.push(`| \`${tool.name}\` | ${profileLabel(tool)} | ${accessLabel(tool)} | ${escapeTableCell(tool.description)} |`);
+    }
+    lines.push('');
+  }
+
+  return `${lines.join('\n').replace(/\n{3,}/g, '\n\n')}\n`;
+}
+
+function profileLabel(tool) {
+  return tool.enabledInCore ? '`core`, `full`' : '`full`';
+}
+
+function accessLabel(tool) {
+  if (tool.readOnly) {
+    return 'read-only';
+  }
+  if (tool.destructive) {
+    return 'mutating';
+  }
+  return 'stateful';
+}
+
+function titleCase(value) {
+  return String(value)
+    .split(/[-_\s]+/)
+    .filter(Boolean)
+    .map((part) => `${part.charAt(0).toUpperCase()}${part.slice(1)}`)
+    .join(' ');
+}
+
+function escapeTableCell(value) {
+  return String(value || '')
+    .replace(/\|/g, '\\|')
+    .replace(/\n/g, '<br>');
+}
+
+function groupBy(values, getKey) {
+  return values.reduce((groups, value) => {
+    const key = getKey(value);
+    if (!groups[key]) {
+      groups[key] = [];
+    }
+    groups[key].push(value);
+    return groups;
+  }, {});
+}
+
+function writeDocs(markdown) {
+  const directory = path.dirname(OUTPUT_PATH);
+  if (!fs.existsSync(directory)) {
+    fs.mkdirSync(directory, { recursive: true });
+  }
+  fs.writeFileSync(OUTPUT_PATH, markdown, 'utf8');
+}
+
+function checkDocs(markdown) {
+  const existing = fs.existsSync(OUTPUT_PATH) ? fs.readFileSync(OUTPUT_PATH, 'utf8') : '';
+  if (existing !== markdown) {
+    console.error('docs/TOOLS.md is out of date. Run `npm run docs:generate`.');
+    process.exitCode = 1;
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const markdown = buildMarkdown(buildToolModel());
+  if (args.includes('--check')) {
+    checkDocs(markdown);
+    return;
+  }
+  writeDocs(markdown);
+  console.log(`Wrote ${path.relative(ROOT, OUTPUT_PATH)}`);
+}
+
+main();

scripts/release.js

@@ -17,11 +17,14 @@ const REQUIRED_REPO_FILES = [
   'package.json',
   'README.md',
   'README_CN.md',
+  'docs/TOOLS.md',
   'RELEASE_WORKFLOW.md',
   'RELEASE_CHECKLIST.md',
   'CHANGELOG.md',
   'CONTRIBUTING.md',
   'LICENSE',
+  'server.json',
+  'bin/funplay-cocos-mcp.js',
   'browser.js',
   'scene.js',
   'panel/index.js',
@@ -33,9 +36,12 @@ const PACKAGE_INCLUDES = [
   'package.json',
   'README.md',
   'README_CN.md',
+  'docs',
   'CHANGELOG.md',
   'CONTRIBUTING.md',
   'LICENSE',
+  'server.json',
+  'bin',
   'browser.js',
   'scene.js',
   'panel',
@@ -150,10 +156,40 @@ function checkRelease(options = {}) {
     errors.push('package.json main must point to an existing file.');
   }
 
+  if (!packageJson.bin || packageJson.bin['funplay-cocos-mcp'] !== 'bin/funplay-cocos-mcp.js') {
+    errors.push('package.json bin.funplay-cocos-mcp must point to bin/funplay-cocos-mcp.js.');
+  }
+
   if (!/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(version)) {
     errors.push(`package.json version must be semver-like, got: ${version}`);
   }
 
+  const serverJson = readJson(path.join(ROOT, 'server.json'), errors);
+  if (serverJson) {
+    if (serverJson.name !== packageJson.mcpName) {
+      errors.push('server.json name must match package.json mcpName.');
+    }
+    if (serverJson.version !== version) {
+      errors.push(`server.json version ${serverJson.version} must match package.json version ${version}.`);
+    }
+    const npmPackage = Array.isArray(serverJson.packages)
+      ? serverJson.packages.find((entry) => entry && entry.registryType === 'npm')
+      : null;
+    if (!npmPackage) {
+      errors.push('server.json must include an npm package entry.');
+    } else {
+      if (npmPackage.identifier !== packageJson.name) {
+        errors.push(`server.json npm identifier ${npmPackage.identifier} must match package.json name ${packageJson.name}.`);
+      }
+      if (npmPackage.version !== version) {
+        errors.push(`server.json npm package version ${npmPackage.version} must match package.json version ${version}.`);
+      }
+      if (!npmPackage.transport || npmPackage.transport.type !== 'stdio') {
+        errors.push('server.json npm package transport must be stdio.');
+      }
+    }
+  }
+
   for (const relative of REQUIRED_REPO_FILES) {
     if (!fs.existsSync(path.join(ROOT, relative))) {
       errors.push(`Missing required repository file: ${relative}`);

server.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.FunplayAI/funplay-cocos-mcp",
+  "title": "Funplay Cocos MCP",
+  "description": "stdio bridge for the local Cocos Creator Editor MCP server from FunplayAI/funplay-cocos-mcp.",
+  "repository": {
+    "url": "https://github.com/FunplayAI/funplay-cocos-mcp",
+    "source": "github"
+  },
+  "version": "0.3.3",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "funplay-cocos-mcp",
+      "version": "0.3.3",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "FUNPLAY_COCOS_MCP_URL",
+          "description": "Optional local Cocos MCP HTTP endpoint. Defaults to http://127.0.0.1:8765/.",
+          "format": "string",
+          "isRequired": false,
+          "isSecret": false
+        },
+        {
+          "name": "FUNPLAY_COCOS_MCP_TIMEOUT_SECONDS",
+          "description": "Optional HTTP timeout per request in seconds. Defaults to 120.",
+          "format": "string",
+          "isRequired": false,
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}

test/server.test.js

@@ -66,6 +66,33 @@ function httpJson(port, payload, headers = {}) {
   });
 }
 
+function httpGet(port, path = '/', headers = {}) {
+  return new Promise((resolve, reject) => {
+    const request = http.request(
+      {
+        host: '127.0.0.1',
+        port,
+        method: 'GET',
+        path,
+        headers,
+      },
+      (response) => {
+        const chunks = [];
+        response.on('data', (chunk) => chunks.push(chunk));
+        response.on('end', () => {
+          resolve({
+            statusCode: response.statusCode,
+            headers: response.headers,
+            body: Buffer.concat(chunks).toString('utf8'),
+          });
+        });
+      }
+    );
+    request.on('error', reject);
+    request.end();
+  });
+}
+
 test('initialize negotiates the current MCP protocol version by default', async () => {
   const server = createServer();
   const response = await server.handleRpcRequest({
@@ -222,6 +249,43 @@ test('HTTP notifications return 202 Accepted with no body', async () => {
   }
 });
 
+test('HTTP GET /tools returns debug tool metadata and curl examples', async () => {
+  const server = createServer({
+    listTools: () => [
+      {
+        name: 'get_project_info',
+        description: 'Return project info.',
+        inputSchema: { type: 'object', properties: {} },
+      },
+    ],
+    listToolCatalog: () => [
+      {
+        name: 'get_project_info',
+        description: 'Return project info.',
+        category: 'project',
+        profile: 'core',
+        enabled: true,
+      },
+    ],
+  }, { port: 0 });
+  await server.start();
+  try {
+    const response = await httpGet(server.getPort(), '/tools?catalog=1');
+    const payload = JSON.parse(response.body);
+
+    assert.equal(response.statusCode, 200);
+    assert.equal(payload.ok, true);
+    assert.equal(payload.name, 'test-server');
+    assert.equal(payload.version, '0.0.0-test');
+    assert.equal(payload.count, 1);
+    assert.equal(payload.tools[0].category, 'project');
+    assert.match(payload.examples.health, /curl http:\/\/127\.0\.0\.1:\d+\/health/);
+    assert.match(payload.examples.tools, /curl http:\/\/127\.0\.0\.1:\d+\/tools/);
+  } finally {
+    await server.stop();
+  }
+});
+
 test('HTTP initialize can return an optional session id when sessions are enabled', async () => {
   const server = createServer({}, { port: 0, enableSessions: true });
   await server.start();

test/stdio-proxy.test.js

@@ -0,0 +1,176 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const childProcess = require('node:child_process');
+const http = require('node:http');
+const path = require('node:path');
+const test = require('node:test');
+
+const ROOT = path.resolve(__dirname, '..');
+const WRAPPER = path.join(ROOT, 'bin', 'funplay-cocos-mcp.js');
+const PACKAGE = require('../package.json');
+
+function writeFramed(stream, value) {
+  const payload = Buffer.from(JSON.stringify(value), 'utf8');
+  stream.write(`Content-Length: ${payload.length}\r\n\r\n`);
+  stream.write(payload);
+}
+
+function createFramedReader(stream) {
+  let buffer = Buffer.alloc(0);
+  const waiters = [];
+
+  function readFromBuffer() {
+    const marker = buffer.indexOf('\r\n\r\n');
+    if (marker < 0) {
+      return null;
+    }
+
+    const header = buffer.slice(0, marker).toString('ascii');
+    const match = /^content-length:\s*(\d+)$/im.exec(header);
+    if (!match) {
+      throw new Error(`Missing Content-Length header: ${header}`);
+    }
+
+    const length = Number.parseInt(match[1], 10);
+    const start = marker + 4;
+    const end = start + length;
+    if (buffer.length < end) {
+      return null;
+    }
+
+    const payload = buffer.slice(start, end).toString('utf8');
+    buffer = buffer.slice(end);
+    return JSON.parse(payload);
+  }
+
+  function pump() {
+    while (waiters.length > 0) {
+      const value = readFromBuffer();
+      if (value === null) {
+        return;
+      }
+      waiters.shift().resolve(value);
+    }
+  }
+
+  stream.on('data', (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    pump();
+  });
+  stream.on('error', (error) => {
+    while (waiters.length > 0) {
+      waiters.shift().reject(error);
+    }
+  });
+
+  return function readNext() {
+    const value = readFromBuffer();
+    if (value !== null) {
+      return Promise.resolve(value);
+    }
+    return new Promise((resolve, reject) => {
+      waiters.push({ resolve, reject });
+    });
+  };
+}
+
+function createHttpProxyTarget(handler) {
+  const server = http.createServer(handler);
+  return new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      resolve({
+        server,
+        url: `http://127.0.0.1:${server.address().port}/`
+      });
+    });
+  });
+}
+
+function readBody(request) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    request.on('data', (chunk) => chunks.push(chunk));
+    request.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    request.on('error', reject);
+  });
+}
+
+function waitForExit(child) {
+  return new Promise((resolve, reject) => {
+    child.once('error', reject);
+    child.once('exit', (code) => resolve(code));
+  });
+}
+
+test('stdio wrapper prints package version', () => {
+  const result = childProcess.spawnSync(process.execPath, [WRAPPER, '--version'], {
+    cwd: ROOT,
+    encoding: 'utf8'
+  });
+
+  assert.equal(result.status, 0);
+  assert.match(result.stderr, new RegExp(`funplay-cocos-mcp ${PACKAGE.version}`));
+});
+
+test('stdio wrapper proxies framed JSON-RPC to the Cocos HTTP endpoint', async () => {
+  const requests = [];
+  const target = await createHttpProxyTarget(async (request, response) => {
+    const body = await readBody(request);
+    requests.push({
+      headers: request.headers,
+      body: JSON.parse(body)
+    });
+
+    response.setHeader('Content-Type', 'application/json');
+    if (requests.length === 1) {
+      response.setHeader('Mcp-Session-Id', 'session-1');
+    }
+    response.end(JSON.stringify({
+      jsonrpc: '2.0',
+      id: requests.length,
+      result: { ok: true, index: requests.length }
+    }));
+  });
+
+  const child = childProcess.spawn(process.execPath, [WRAPPER, '--url', target.url], {
+    cwd: ROOT,
+    stdio: ['pipe', 'pipe', 'pipe']
+  });
+  const readNext = createFramedReader(child.stdout);
+
+  try {
+    writeFramed(child.stdin, {
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'initialize',
+      params: {}
+    });
+    assert.deepEqual(await readNext(), {
+      jsonrpc: '2.0',
+      id: 1,
+      result: { ok: true, index: 1 }
+    });
+
+    writeFramed(child.stdin, {
+      jsonrpc: '2.0',
+      id: 2,
+      method: 'tools/list'
+    });
+    assert.deepEqual(await readNext(), {
+      jsonrpc: '2.0',
+      id: 2,
+      result: { ok: true, index: 2 }
+    });
+
+    assert.equal(requests.length, 2);
+    assert.equal(requests[0].headers.accept, 'application/json, text/event-stream');
+    assert.equal(requests[1].headers['mcp-session-id'], 'session-1');
+    assert.equal(requests[1].body.method, 'tools/list');
+  } finally {
+    child.stdin.end();
+    await waitForExit(child);
+    await new Promise((resolve) => target.server.close(resolve));
+  }
+});

test/tools-files.test.js

@@ -0,0 +1,83 @@
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const test = require('node:test');
+const { buildSnippet, createFileTools } = require('../lib/tools/files');
+
+function createSchema(properties, required) {
+  return { type: 'object', properties, required };
+}
+
+function createTools(projectPath) {
+  return createFileTools({
+    createSchema,
+    getRuntimeContext: () => ({ projectPath }),
+  });
+}
+
+function getTool(tools, name) {
+  const tool = tools.find((item) => item.name === name);
+  assert.ok(tool, `Expected ${name} to exist`);
+  return tool;
+}
+
+test('buildSnippet returns focused line-numbered context', () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'funplay-cocos-files-'));
+  try {
+    const filePath = path.join(root, 'sample.ts');
+    fs.writeFileSync(filePath, ['alpha', 'beta', 'gamma', 'delta'].join('\n'), 'utf8');
+
+    const snippet = buildSnippet(filePath, 2, 1);
+
+    assert.match(snippet, / 1 \| alpha/);
+    assert.match(snippet, />\s+2 \| beta/);
+    assert.match(snippet, / 3 \| gamma/);
+    assert.doesNotMatch(snippet, /delta/);
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('file tools write, read, replace, search, list, and check project files', async () => {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'funplay-cocos-files-'));
+  try {
+    fs.mkdirSync(path.join(root, 'assets'), { recursive: true });
+    const tools = createTools(root);
+
+    const writeResult = await getTool(tools, 'write_file').handler({
+      path: 'assets/player.ts',
+      content: 'const name = "Hero";\nconst clone = "Hero";\n',
+    });
+    assert.match(writeResult, /Wrote \d+ chars/);
+
+    const readResult = await getTool(tools, 'read_file').handler({ path: 'assets/player.ts' });
+    assert.match(readResult, /const name = "Hero"/);
+
+    await getTool(tools, 'replace_in_file').handler({
+      path: 'assets/player.ts',
+      search: 'Hero',
+      replace: 'Player',
+      replaceAll: true,
+    });
+    assert.equal(fs.readFileSync(path.join(root, 'assets', 'player.ts'), 'utf8').includes('Hero'), false);
+
+    const searchResult = await getTool(tools, 'search_files').handler({ pattern: '*.ts', directory: 'assets' });
+    assert.deepEqual(searchResult.files, ['assets/player.ts']);
+
+    const listResult = await getTool(tools, 'list_directory').handler({ path: 'assets' });
+    assert.deepEqual(listResult.entries, [{ name: 'player.ts', type: 'file' }]);
+
+    const existsResult = await getTool(tools, 'exists').handler({ path: 'assets/player.ts' });
+    assert.deepEqual(existsResult, {
+      path: 'assets/player.ts',
+      exists: true,
+      isFile: true,
+      isDirectory: false,
+    });
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});