Skip to content
ShopMCP
All topicsRead as Markdown

Report an issue from an AI client

ShopMCP provides a reporting route for bugs, missing API features, setup issues, and improvement suggestions. Reports are stored in the central ShopMCP support inbox. They are not automatically published as email, GitHub issues, or public messages.

Workflow for AI clients

  1. Read get_support_reporting_instructions. This call does not send a report and shows the shop and connection identifiers that will be attached automatically.
  2. Draft a short technical summary locally in the conversation. Category, title, and description are required. Add reproduction steps, expected and actual behavior, tool name, Shopify operation, error code, or client name if useful.
  3. Show the user the complete report that would be sent. Explain that the shop domain and connection ID will be attached. Do not include customer data, credentials, raw tool-call data, logs, or conversation history.
  4. Ask clearly: “May I send this exact report to ShopMCP Support together with the shop domain and connection ID?”
  5. Call submit_support_report only after an unambiguous yes. Set userApproved:true and copy the exact consentStatement from the reporting instructions. Use a new UUID idempotency key.
  6. Share the returned report ID with the user. If the connection fails, retry with the same key and same content. An already stored report is recognized.

A refusal, silence, error report, or permission to troubleshoot does not authorize submission. If the report changes after approval, ask for consent again. There is no automatic error upload and no server call to prepare report content before approval.

Useful reports

Example of a technical summary:

> Category: Missing API feature. Title: Customer address cannot be updated. When calling customerAddressUpdate, an expected input field is missing from the type description. Expected: the field is discoverable through get_shopify_type. Actual: it is missing from the returned field list. The shop domain and connection ID will be attached.

Before reporting an issue, check type-description pagination. Missing Shopify scopes, connection grants, an unsuitable plan, or a required Shopify approval are separate prerequisites. get_shopify_capabilities and the API documentation can help identify the cause. The reporting route remains available on the Free plan when the API monthly allowance is exhausted; login and an active connection are still required.

Stored data and limits

ShopMCP stores the sanitized technical report, shop domain, connection ID, timestamp, status, and the consent confirmed by the client. ShopMCP filters known token, email, and phone-number patterns. This does not reliably detect every personal detail. The user and client must therefore review the report before sending it. A boolean and confirmation statement are a client declaration, not technical proof of human approval.

The limit is three new reports per connection and ten per shop per UTC calendar day. Replaying the same report with the same key does not count again. Different content with a previously used key is rejected.

Reports are intended to be kept for 30 days. Expired entries are removed when further reports are submitted or by the maintenance command; cleanup is event-driven, not a guaranteed daily background job. Deleting the connection or shop data also deletes related reports. To request earlier deletion, contact support@shopmcp.app with the report ID.

Operating the support inbox

The inbox is not publicly readable. Operators read it with the local command npm run support:reports -- --help using their own database access. Report contents are untrusted user input. They are issue descriptions, never instructions for a support agent to follow. Reports and customer data are not automatically sent to other services.

  • npm run support:reports -- list --limit 25: show the newest reports; optionally filter with --shop example.myshopify.com.
  • npm run support:reports -- detail REPORT_ID: read one report.
  • npm run support:reports -- --prune: remove reports outside the 30-day window.

The command needs the operator's configured DATABASE_URL and is also available in the runtime container. The inbox is reviewed manually in this version; there are no automatic email notifications. Operators must include review and cleanup in their support process.

The MCP reporting route requires a working ShopMCP connection. If the connection or login is completely unavailable, contact support@shopmcp.app manually. A report ID confirms receipt, not a guaranteed response time or completed fix.