Develop a plugin

A plugin package contains a manifest, a file inventory, implementation files, and user documentation. Start with a unique publisher namespace and a version that follows the plugin specification.

1. Declare all capabilities and their host, port, and secret-slot constraints in capabilities.
2. Validate the configuration fields your plugin uses and ignore unrelated fields.
3. Produce reproducible package contents and file digests.
4. Exclude credentials, personal paths, build caches, and runtime data.
5. Test success, failure, permission denial, and invalid packages.

Development tools and packaging

@gamex/plugin-tools provides the gamex-plugin CLI and requires Node.js 22.13.0 or later. Its source is in plugins/tools in the Registry repository. Build it from the repository and distribute it as a local npm archive.

After installing dependencies at the gamex-registry root, run:

npm --prefix plugins run build
npm --prefix plugins run test

Run npm pack in plugins/tools, then install the resulting tool archive in your plugin project:

npm install --no-save /path/to/gamex-plugin-tools-<version>.tgz
npx --no-install gamex-plugin pack ./files --output /tmp/my-plugin.gxplugin
npx --no-install gamex-plugin validate /tmp/my-plugin.gxplugin

Replace the path and version with the generated result. Output must be outside the input directory and cannot overwrite an existing archive. The packager generates META-INF/gamex.files.json; exclude development tools, dependency directories, and runtime data from the package.

Icons and workspace views

metadata.icon is used by the marketplace and installed plugin list. contributions.panels[].icon is used by workspace tabs. Set them independently; panel icons do not inherit the metadata icon. Use package-relative paths and PNG or WebP images, each up to 512 KiB. Panels without an icon use the puzzle icon.

Declare views in contributions.panels and include panel-ui/v1 in requires.features:

{
  "icon": "panel-icon.png",
  "id": "server-tools",
  "path": "ui/panel.mjs",
  "style": "ui/panel.css",
  "title": "Server tools"
}

Bundle React, ReactDOM, and other dependencies into browser ESM. Export mount(container, context) and return a synchronous cleanup function. The host does not provide HTML or an iframe. Prefix CSS classes for your plugin.

Context interface	Purpose
installationId, workspaceId	Current plugin installation and workspace
toast.error/success/info/warning(message)	Display host notifications
request(path, options)	Call same-origin Panel APIs with the current user's permissions and return response data
callTool(serverId, toolName, arguments)	Call ordinary MCP tools from this plugin
authentication(serverId, action)	Read or manage shared account connections using status/start/cancel/disconnect

Visited views stay mounted while their tab is hidden; hiding is not an unmount. When a workspace or release change unloads the view, clean up React roots, subscriptions, timers, and dialogs. The host cancels Context requests and removes notifications belonging to that view.

Configuration and conversation scope

Ordinary configuration must be an object, with a schema using the host's supported JSON Schema subset. additionalProperties: false removes undeclared fields; without a schema, the host normalizes configuration to {}. Supported property defaults are applied during normalization, but validate the final configuration rather than relying on complete default expansion through arbitrary branches or references. Use separate Secret slots for credentials.

MCP agentScope defaults to workspace and can be set to panel; a server appears only in the matching conversation type. Skills needing files, Shell, or installation must run in a workspace conversation. A Panel conversation can select or create a workspace and use workspace_handoff to create a shared workspace conversation. Transfer only a self-contained task summary the user intends to share.

For packaged helpers, plugin_skills_read returns paths and SHA-256 digests under packageFiles. Use plugin_file_import with area=package to copy a verified file into the Workspace with normal write authorization and approval. Importing a script does not execute it; existing files are preserved.

Runtime and data isolation

• Local MCP programs run as the Panel service account without an operating system sandbox. hosts and ports constrain remote MCP endpoints, not a local program's own host or network access.
• Ordinary configuration can enter skill context and PLUGIN_CONFIG; keep credentials out of it. Panel encrypts installation Secrets and injects them according to declarations and grants.
• Store authentication files in PLUGIN_DATA/.private. Do not return them through tool results, public data, or view assets. Persistent data is isolated by installation, not automatically by user or workspace.
• React views are trusted same-origin modules without an iframe sandbox. request uses the current user's permissions; MCP and account operations also check the current release and access settings.
• Direct view actions do not enter the AI approval queue. Ordinary MCP tools used by AI count as reads only when declaring annotations.readOnlyHint: true. Workspace secret writes always require human approval.

External chat events

Declare panel-events/v1 and mcp/v1, request panel.mcp.connect and panel.thread.control, and configure distinct receive, send, and optional poll tools on a workspace MCP server. These internal tools are unavailable to AI discovery and view callTool calls. The host manages binding confirmation, permissions, approvals, and task execution; the plugin verifies provider messages and handles delivery.

Outbound approval and question interactions include their request ID, positive revision, and authorized actor keys. Preserve the revision when tracking controls and deduplicate sends by delivery ID. Polling can include optional source names for display.

See the Panel event protocol for callback, polling, persistence, and binding APIs.

Submit a release

1. Sign in to GameX Registry with an account allowed to publish.
2. Upload the validated .gxplugin package, check its name, version, and permissions, then submit it for review.
3. Check the result on the publisher page. Review status refreshes automatically while the page is visible.

Approved versions cannot be overwritten; later changes require a new version number. Find development specifications and examples in the Registry repository's plugins/docs/ directory, and local tools in plugins/tools/.