EasyGerber agent integration

This package connects coding agents to EasyGerber's hosted board-design tools. Its public files contain workflow instructions, connection metadata, icons, and a small installer. Board layout, routing, and scoring run on EasyGerber's servers.

Version 0.3.0 makes a deliberate breaking change before 1.0: the saved-layout blocker check is named check_board_layout, replacing score_board with no compatibility alias. The response still reports blocking issues without numeric scores. This version requires the matching service contract; the package and service must be upgraded together.

Source is available in the public integration repository. The npm installer and portable directory package have separate release and client-validation processes.

Codex in VS Code or the terminal

Requires Node.js 22 or newer and Codex. To install version 0.3.0:

npx @easygerber/agent-plugin@0.3.0 setup --dry-run
npx @easygerber/agent-plugin@0.3.0 setup
npx @easygerber/agent-plugin@0.3.0 doctor

Setup installs ~/.agents/skills/easygerber and adds a small managed MCP table to $CODEX_HOME/config.toml (default ~/.codex/config.toml). It preserves existing TOML text and other servers. An ownership receipt lives in ~/.easygerber/agent-plugin/codex-install.json. No project files or firmware are changed. Codex is the default and only installer target; optional --client codex makes that choice explicit. All commands support unattended use, and --yes is accepted for scripts.

Restart the Codex chat/IDE after setup, then ask: “Use EasyGerber to create a small board as a guest. Show me the preview and export the manufacturing files.” The agent checks the available tools and starts a guest session without an EasyGerber account through https://www.easygerber.com/api/mcp.

For your saved account boards or organization work, connect EasyGerber from MCP settings. If Codex CLI is installed, run:

codex mcp login easygerber

The client opens the account authorization flow and stores its credentials. The managed MCP configuration requests boards:read, boards:write, boards:generate, boards:export, and offline_access, so account consent covers board workflows and renewable access. Organization permissions, account limits, and the user's consent still control account access. The installer never asks for, reads, or stores access tokens or guest capabilities. doctor checks local configuration and skill integrity; it does not prove that authentication, guest mode, or the live service works.

Try: “Use EasyGerber to create a board from the pin assignments in this firmware.” The agent reads relevant local code, selects published parts, and sends board requirements through the MCP service. Account scopes are boards:read, boards:write, boards:generate, and boards:export; organization permissions, quotas, and billing still apply.

Try before signing up

Guest access is live on EasyGerber's production MCP service and uses the published component catalog. The agent can create one board per session with unlimited edits, layouts, checks, previews, and manufacturing ZIP or .egb exports before signup. The board and session have no automatic expiry. Normal request-rate, board-complexity, and shared compute protections still apply. The service returns limits: { boards: 1 }; expiresAt: null means no scheduled expiration. The board limit applies to a session, not a verified person.

The agent keeps the guest capability in its tool context. Keep its private viewer link to return to the board; anyone with that link can access the guest design. Neither the raw token nor that link belongs in firmware repositories, public issues, or diagnostic logs. The viewer removes the token fragment and uses a private browser session. Guest access depends on keeping that capability or link; creating another session cannot recover a lost one. Download links expire after fifteen minutes, and export objects become eligible for cleanup twenty-four hours after creation. These artifact limits do not expire the guest board.

For account ownership, account-based recovery, and additional boards under your normal plan, open the private viewer, sign in or create an account, and choose Keep board. This copies the saved design into your personal account with a new board ID and ends guest access. Your agent can also claim it after normal account authorization. Continue with the returned account board ID. Reuse the original guest session; do not create extra sessions to bypass the board limit or service protections. An expired account connection must be reauthorized; it does not silently become a guest connection.

ChatGPT and native Codex plugins

The portable root manifest and mcp.json support review for OpenAI's plugin directory. They declare mixed public and OAuth access: guests can discover tools without account authorization, and account operations use a registered public OAuth client with PKCE and normal consent. Its client ID is public metadata, not a credential. This does not alter the npm installer's automatic Codex registration. Guest discovery and optional account authorization need separate checks in each client; package validation does not establish directory approval or native-client acceptance. The tested native Codex build does not load the portable OpenAI MCP extension, so use the standalone installation above for Codex, including its IDE extension. Native Codex plugin support requires a separately validated compatible package. Avoid installing duplicate integrations in the same client.

Only OpenAI/Codex is targeted for the initial release. Release artifacts contain the portable OpenAI plugin and Codex installer.

Update and remove

Upgrading from 0.2.x requires both the updated service and version 0.3.0 of this package. Run npx @easygerber/agent-plugin@0.3.0 setup, then restart the Codex chat/IDE so it reloads the skill and discovers the current tools. Existing sessions may retain the old tool name; the updated service does not support those calls or provide an alias. For layout checks, the connection must advertise check_board_layout.

Run setup from the new package version to update unchanged managed files. Repeating the same setup is a no-op. A conflicting MCP entry or modified skill file causes setup to stop without replacing it. Keep the file, or move it aside yourself before retrying. Symlinked managed destinations are refused to avoid changing unexpected locations.

npx @easygerber/agent-plugin@0.3.0 uninstall --dry-run
npx @easygerber/agent-plugin@0.3.0 uninstall

Uninstall removes only unchanged files and the unchanged managed connection, preserving unrelated settings and modified files. It reports preserved paths and retains their ownership receipt. Revoke the account connection separately in Codex or EasyGerber; deleting local files does not revoke OAuth grants or invalidate an existing guest viewer link. Guest access ends after claim or revocation, not on an automatic timer. Retired guest data becomes eligible for cleanup twenty-four hours after claim or revocation; the claimed account copy stays available. Interrupted setup can resume from its receipt. If a stale installer lock remains, verify no installer process is running before removing the lock path reported by the CLI.

Network and data

The integration connects directly to https://www.easygerber.com/api/mcp; authorization uses the metadata and account flow advertised by that service. Tool requests can contain the board requirements, component selections, schematic edits, and board/organization identifiers needed for your task. Generated artifact links are returned by EasyGerber. The hosted service retains agent activity analytics for one year, including guest history after a board is claimed. The installer does not upload repositories, inspect environment files, run lifecycle hooks, or collect telemetry. Ordinary npm package retrieval is handled by npm.

See integration documentation and support, privacy policy, and terms.

Maintainer validation and release

The package contains the installer runtime, connection metadata, skills, and assets. The public repository also contains a GitHub Actions workflow and an installer smoke test. On pushes and pull requests, the workflow checks the packed installer on Linux, Windows, and macOS with Node.js 22 and 24. It tests temporary user profiles without connecting to EasyGerber or using account credentials. These checks cover installation behavior; they do not certify authentication or board operations in a particular agent client. See the Actions results for actual run status.

The production guest flow was verified on October 13, 2026 through direct MCP requests using both supported protocol versions and manual web-viewer checks. The checks covered board creation, editing, layout, previews, blocker checks through the then-current score_board interface, both export formats, and account claim with the old guest access revoked. This evidence predates the check_board_layout rename and does not validate it. It also does not establish acceptance in native ChatGPT, a plugin-loaded client, or a fresh installed Codex session against production.

The workflow and smoke test are excluded from the npm package and plugin ZIP. The broader regression suite and release tooling remain in EasyGerber's private development checkout. That tooling creates the OpenAI ZIP and public source from separate explicit file allowlists and verifies the resulting archive contents. The exported runtime uses only Node.js built-ins and the public smol-toml parser; it never imports EasyGerber's private packages.

Before publishing, confirm ownership of the npm scope, the official public integration repository, and the vendor publishing identities. Verify production sign-in and one complete create/revise/generate/export flow in supported clients. Inspect npm pack --dry-run --json from the public export. Publish only that sanitized package/repository; the product monorepo and its history stay private. Icons and listing copy in this package are editable release materials, not evidence of marketplace approval. Do not add npm install lifecycle hooks.

The MIT license covers this integration package, not the hosted service or private engines.