[verified] Harden Etsy MCP validation and scheduled token refresh

2026-11-07 21:54:33 +00:00
parent 960189d14b
commit c8c5822166
13 changed files with 455 additions and 89 deletions
@@ -43,13 +43,23 @@ First-party stdio MCP for HL3D agents. It uses the stored HickLab3D shop connect
 php artisan etsy:mcp
 ```

-Register it from this repo's `.mcp.json` as server name `etsy` (`php` + `artisan etsy:mcp`). Example for an HL3D Hermes profile after this server exists:
+Register the local `.mcp.json` only where PHP is installed and the working directory is this app. On the Hermes host, use the existing web container instead (after deployment):

 ```sh
-hermes -p hl3d_teamlead mcp add etsy --command php --args artisan etsy:mcp
+hermes -p hl3d_teamlead mcp add etsy --command ssh --args -T H-NODE-05 'docker exec -i -u www-data -w /var/www/HickLab3D nginx-ui-php php artisan etsy:mcp --no-ansi'
 ```

-Run the command from the dashboard app root so it inherits `.env`. After deploy, an admin must reconnect Etsy in the dashboard so the token includes `listings_r listings_w transactions_r transactions_w shops_r`. New listings are created as drafts; publishing requires `etsy_publish_listing` with `confirm=true`.
+This uses the managed live environment without placing credentials in MCP config and does not require host PHP. Configure positive tool allow-lists through supported `hermes config set` commands before exposing tools to agents: teamlead/designer should get read/status tools only; marketing may additionally create drafts. Do not expose publishing, shipment or inventory-write tools without separately authorising those operations. Disable MCP sampling for this server. Start a fresh profile session or reload MCP after configuration.
+
+An admin must reconnect Etsy in the dashboard if status reports unknown or missing scopes (`listings_r listings_w transactions_r transactions_w shops_r`). Never request operator passwords or MFA codes. New listings are drafts; `confirm=true` is a technical publish guard, not operator authorisation. Publishing, activating, renewing or repricing live listings, inventory changes and shipping still require explicit approval for the specific action in the current conversation.
+
+## Artisan scheduler
+
+The Settings page lets admins tune registered jobs or run them immediately. Defaults: `integrations:refresh` and `alerts:scan` every 30 seconds, `etsy:sync` every 15 minutes, and `etsy:refresh-token` checks every five minutes. Etsy is no longer force-refreshed by the bundled integration job. The refresh check rotates only within ten minutes of expiry; database row locking and a fresh read serialise rotating-token use across MCP, HTTP and scheduler processes. Lowering the token-check cadence or disabling it can leave an idle access token expired.
+
+Settings are atomically replaced under a shared file lock at `storage/app/dashboard-schedules.json`. Preserve storage and the Infisical-managed `.env` during deployments. Only H-NODE-05 owns the systemd scheduler timer; its container working directory must be `/var/www/HickLab3D`, matching the actual vhost and CI target. Subminute tasks keep `schedule:run` alive until the end of the minute, so do not install a duplicate cron or scheduler elsewhere.
+
+For local tests in the existing serviceengineering toolchain image, explicitly set `APP_ENV=testing`: the image exports `APP_ENV=local`, which otherwise wins over PHPUnit XML and correctly activates real CSRF enforcement. Never disable production CSRF to repair that test-environment mismatch.

 Etsy Open API v3 has no conversation inbox (`conversations_*` scopes do not exist). Receipt notes are exposed; sending a buyer-inbox reply is not.