Imported from ArifZx/cocos-extension-mcp (AGENTS.md). Install upstream with npx skills add ArifZx/cocos-extension-mcp. Copyright stays with the author.

AGENTS.md

Purpose

This repository is a TypeScript MCP server for Cocos Creator extension tooling. The server exposes Cocos-aware tools that generate, inspect, and validate editor extension artifacts.

Commands

• npm run build compiles the server with TypeScript and is the default validation command.
• npm run dev runs the stdio MCP server from source via tsx.
• npm run start runs the compiled server from dist/.
• npm test currently aliases to npm run build.

Source Layout

• src/index.ts is the stdio MCP entrypoint and tool registration surface.
• src/cocos-extension.ts contains the Cocos-specific schema and generation or validation logic.
• dist/ is generated output. Prefer editing src/ only.

Working Rules

• Keep the project ESM-compatible. Imports should target the emitted .js path style used by NodeNext.
• Prefer small domain helpers in src/cocos-extension.ts and keep src/index.ts focused on MCP registration.
• When adding a new MCP tool, return both content and structuredContent when the result is structured.
• Validate changes with npm run build immediately after editing TypeScript files.

Cocos Extension Model

Tool behavior should follow the Cocos Creator 3.8 editor extension architecture documented here:

• Manual book index: https://docs.cocos.com/creator/3.8/manual/en/editor/extension/readme.html
• Basic index: https://docs.cocos.com/creator/3.8/manual/en/editor/extension/basic.html
• Extension infrastructure: https://docs.cocos.com/creator/3.8/manual/en/editor/extension/package.html
• Extension definition: https://docs.cocos.com/creator/3.8/manual/en/editor/extension/define.html
• Message system: https://docs.cocos.com/creator/3.8/manual/en/editor/extension/messages.html
• Configuration system: https://docs.cocos.com/creator/3.8/manual/en/editor/extension/profile.html
• Panel system: https://docs.cocos.com/creator/3.8/manual/en/editor/extension/panel.html
• UI components: https://docs.cocos.com/creator/3.8/manual/en/editor/extension/ui.html

Use these rules when implementing or validating Cocos-related outputs:

• Treat the manual book index as the navigation hub for extension docs. Use it first when you need to discover the right child page for menus, panels, communication, installation, or contributions.

• package.json is the primary contract for an extension: package_version, version, name, main, panels, contributions, and scripts are the main control points.

• Cocos extensions are multi-process. Extension main runs separately from panel processes, so panel interactions should be modeled around Editor.Message and Editor.Panel instead of shared in-memory assumptions.

• Normal message names should use lowercase kebab-case, and broadcast messages should follow the packageName:actionName pattern.

• Panel definitions belong in package.json > panels; panel implementation usually lives under src/panels/<name>/index.ts and compiles to dist/panels/<name>.

• i18n-facing strings should prefer i18n: keys when they represent user-visible labels in manifest-like data.

• Persistent settings should align with contributions.profile for editor or project configuration instead of ad hoc config shapes.

Scope Guidance

• Keep this repo focused on generating and validating extension artifacts, not on running Cocos Creator itself.
• If a behavior depends on undocumented Cocos internals, prefer emitting a conservative scaffold plus a warning rather than inventing unsupported fields.newline