Admin MCP Best Practices

{
  "merchant_id": 42,
  "channels": [
    {
      "id": 101,
      "name": "Flagship Webstore",
      "type": "webstore",
      "store": { "url": "https://example.com" }
    },
    {
      "id": 102,
      "name": "Downtown POS",
      "type": "pos",
      "store": {}
    }
  ]
}

Validation Error: The specified channel (ID: 102) is of type 'pos'. Theme tools require a 'webstore' channel.

Low Risk (Autonomous Execution Allowed)
├── Read tools: search_products, get_order, list_channels, get_theme_file
└── Low-impact mutations: add_order_note, tag_customer, create_draft_product

High Risk (Require Human Confirmation)
├── Catalog: delete_product, delete_variant, bulk_update_prices, unpublish_product
├── Orders & Finances: cancel_order, issue_refund, create_manual_charge
├── Storefront & Brand: update_theme_file, delete_theme_section, modify_store_settings
└── Inventory: adjust_inventory_level, finalize_stock_transfer

interface ActionProposal {
  tool: string;
  resourceId: string | number;
  action: "delete" | "update" | "refund" | "unpublish";
  summary: string;
  changes: Record<string, { current: unknown; proposed: unknown }>;
}
 
function formatConfirmationPrompt(proposal: ActionProposal): string {
  return [
    `Action proposal: ${proposal.action} ${proposal.tool}:`,
    `- Target: ${proposal.resourceId}`,
    `- Summary: ${proposal.summary}`,
    "- Changes:",
    ...Object.entries(proposal.changes).map(
      ([field, { current, proposed }]) => `  * ${field}: ${JSON.stringify(current)} -> ${JSON.stringify(proposed)}`
    ),
    "",
    "Proceed with this update? (yes/no)",
  ].join("\n");
}

{
  "status": "error",
  "response": {
    "message": "Resource revision mismatch. The resource has been modified since it was loaded.",
    "code": "revision_mismatch",
    "suggestions": {
      "current_revision": "a8f9c1b2",
      "action": "reload_resource"
    }
  }
}

interface ToolErrorPayload {
  status: "error";
  response: {
    message: string;
    code?: string;
    suggestions?: Record<string, unknown>;
  };
}
 
async function handleToolExecution(client: any, toolName: string, args: Record<string, unknown>) {
  const result = await client.callTool({ name: toolName, arguments: args });
 
  if (result.isError) {
    const rawText = result.content[0]?.text || "{}";
    let errorData: ToolErrorPayload;
 
    try {
      errorData = JSON.parse(rawText);
    } catch {
      throw new Error(`Tool execution failed: ${rawText}`);
    }
 
    const { code, message, suggestions } = errorData.response;
 
    // Handle stale revision concurrency
    if (code === "revision_mismatch") {
      console.warn("Revision mismatch detected. Refreshing resource...");
      // Re-fetch resource, update args with latest revision, and retry
      if (args.product_id) {
        const fresh = await client.callTool({
          name: "get_product",
          arguments: { product_id: args.product_id },
        });
        const freshData = JSON.parse(fresh.content[0].text);
        return await client.callTool({
          name: toolName,
          arguments: { ...args, revision: freshData.revision },
        });
      }
    }
 
    // Handle missing theme release
    if (code === "release_missing" && args.channel_id) {
      console.warn("Release missing. Looking up current active release...");
      const releases = await client.callTool({
        name: "list_theme_releases",
        arguments: { channel_id: args.channel_id },
      });
      const releaseList = JSON.parse(releases.content[0].text);
      const activeRelease = releaseList.find((r: any) => r.is_active);
      if (activeRelease) {
        return await client.callTool({
          name: toolName,
          arguments: { ...args, release_id: activeRelease.id },
        });
      }
    }
 
    throw new Error(`Unrecoverable tool error [${code}]: ${message}`);
  }
 
  return JSON.parse(result.content[0].text);
}

You are an authorized Finqu Commerce Admin Assistant. You operate the merchant's store using the Finqu Admin MCP
toolset.
 
Core Operational Rules:
 
1. Discovery First:
   - Call get_profile at the start of a conversation to identify the merchant and confirmed scopes.
   - Call list_channels before calling any tool that accepts channel_id. Store the webstore channel ID in context.
 
2. Precision & Verification:
   - Never guess resource IDs, SKUs, or variant IDs. Always use search_* or list_* tools first to locate the exact
     entity.
   - When updating prices, verify the currency from get_profile and specify exact decimal amounts.
 
3. Safety & Human Confirmation:
   - Always ask for merchant confirmation before making destructive or high-impact changes (e.g., deleting products,
     unpublishing items, modifying Liquid theme templates, altering order records).
   - Display the current value alongside the proposed new value when requesting confirmation.
 
4. Error Self-Correction:
   - If a tool returns an error payload with status="error", inspect the response.code and suggestions object.
   - If the code is revision_mismatch, re-fetch the item to obtain the new revision and re-apply changes.
   - If the code is release_missing, query list_theme_releases to find the current active theme release.