@shoppexio/mcp-commerce-server 0.2.0 → 0.4.0

package/README.md

@@ -1,103 +1,3 @@
 # @shoppexio/mcp-commerce-server
 
-Model Context Protocol server for Shoppex commerce operations.
-
-Connect Claude Desktop, Claude Code, Cursor, Windsurf, or Codex to your Shoppex store. Read products, orders, customers, and analytics, create payment links, manage coupons, and create or update products — directly from chat.
-
-## Install
-
-```bash
-npm install -g @shoppexio/mcp-commerce-server
-```
-
-Or run without installing:
-
-```bash
-npx -y @shoppexio/mcp-commerce-server
-```
-
-## Claude Desktop
-
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
-
-```json
-{
-  "mcpServers": {
-    "shoppex-commerce": {
-      "command": "npx",
-      "args": ["-y", "@shoppexio/mcp-commerce-server"],
-      "env": {
-        "SHOPPEX_SHOP_API_KEY": "shx_your_dev_api_key"
-      }
-    }
-  }
-}
-```
-
-Restart Claude Desktop. Tools accept a `shop_api_key` argument on each call; the env var is available for clients that forward env to tool arguments.
-
-## Cursor / Windsurf / Other
-
-Any MCP client with stdio transport works. Set the same env var and point to `shoppex-mcp-commerce-server` as the command.
-
-## Tools (12)
-
-### Read
-
-| Tool | Purpose |
-|------|---------|
-| `products.list` | Search or list products |
-| `products.get` | Fetch one product by id or uniqid |
-| `orders.list` | List recent orders, optionally filtered |
-| `orders.get` | Fetch one order with line items |
-| `customers.get` | Fetch a customer by id or email |
-| `coupons.list` | List active coupons |
-| `analytics.revenue` | Revenue totals for a date range |
-
-### Write
-
-| Tool | Purpose |
-|------|---------|
-| `products.create` | Create a product (service, serials, dynamic, file) |
-| `products.update` | Update a product's price, title, gateways, stock, visibility |
-| `coupons.create` | Create a coupon (percentage or fixed discount) |
-| `coupons.update` | Update an existing coupon |
-| `payment_links.create` | Create a payment link |
-
-## Required Scopes
-
-Your Shoppex Dev API key needs the scopes matching the tools you use (e.g. `products.read`, `products.write`, `orders.read`, `coupons.write`, `analytics.read`, `payment_links.write`).
-
-Create one at [dashboard.shoppex.io/developer/api](https://dashboard.shoppex.io/developer/api).
-
-## Environment Variables
-
-| Variable | Required | Default |
-|----------|----------|---------|
-| `SHOPPEX_SHOP_API_KEY` | passed per call, or set here | — |
-| `SHOPPEX_API_BASE_URL` | no | `https://api.shoppex.io` |
-| `SHOPPEX_DEV_API_TIMEOUT_MS` | no | `10000` |
-
-## Example Prompts
-
-Once connected in Claude Desktop:
-
-- "Create a Discord Nitro 3-month product for $14.99 paid in crypto."
-- "Show me this month's top 10 customers by revenue."
-- "Generate a 20% off coupon for my Discord members, valid until end of month."
-- "Update the price of product `prd_abc123` to $12.99."
-- "Make a payment link for a $50 USDT one-time purchase."
-
-## Companion
-
-Pair with [`@shoppexio/mcp-theme-server`](https://www.npmjs.com/package/@shoppexio/mcp-theme-server) for storefront theme operations.
-
-## Docs
-
-- [Developer API Reference](https://docs.shoppex.io/api-reference/introduction)
-- [Quickstart](https://docs.shoppex.io/api-reference/quickstart)
-- [Authentication](https://docs.shoppex.io/api-reference/authentication)
-
-## License
-
-Proprietary. © Shoppex.
+Shoppex MCP server that exposes commerce tools over the Shoppex Dev API.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoppexio/mcp-commerce-server",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Shoppex MCP server for commerce operations over the Dev API",
   "type": "module",
   "repository": {

package/src/server.mjs

@@ -257,13 +257,29 @@ export class ShoppexCommerceDevApiClient {
 }
 
 const BaseToolSchema = {
-  shop_api_key: z.string().trim().min(1),
+  shop_api_key: z.string().trim().min(1).optional(),
   api_base_url: z.string().trim().url().optional(),
 };
 
+function resolveShopApiKey(explicitValue) {
+  if (typeof explicitValue === 'string' && explicitValue.trim()) {
+    return explicitValue.trim();
+  }
+  const fromEnv = process.env.SHOPPEX_SHOP_API_KEY?.trim()
+    || process.env.SHOPPEX_API_KEY?.trim()
+    || process.env.SHOP_API_KEY?.trim();
+  if (!fromEnv) {
+    throw new ShoppexCommerceDevApiError(
+      'Missing Shoppex shop API key. Set SHOPPEX_SHOP_API_KEY in the MCP server env, or pass shop_api_key to the tool.',
+      { code: 'auth_error', retryable: false },
+    );
+  }
+  return fromEnv;
+}
+
 function createClient(args) {
   return new ShoppexCommerceDevApiClient({
-    shopApiKey: args.shop_api_key,
+    shopApiKey: resolveShopApiKey(args.shop_api_key),
     apiBaseUrl: args.api_base_url,
   });
 }
@@ -271,7 +287,7 @@ function createClient(args) {
 export function createCommerceToolCatalog() {
   return [
     {
-      name: 'products.list',
+      name: 'products_list',
       description: 'Search or list products for one Shoppex shop.',
       inputSchema: {
         ...BaseToolSchema,
@@ -286,7 +302,7 @@ export function createCommerceToolCatalog() {
       }),
     },
     {
-      name: 'products.get',
+      name: 'products_get',
       description: 'Fetch one product by Shoppex product id or uniqid.',
       inputSchema: {
         ...BaseToolSchema,
@@ -295,7 +311,7 @@ export function createCommerceToolCatalog() {
       execute: async (args) => createClient(args).productsGet(args.product_id),
     },
     {
-      name: 'orders.list',
+      name: 'orders_list',
       description: 'List recent orders. Optionally filter by status or customer email.',
       inputSchema: {
         ...BaseToolSchema,
@@ -310,7 +326,7 @@ export function createCommerceToolCatalog() {
       }),
     },
     {
-      name: 'orders.get',
+      name: 'orders_get',
       description: 'Fetch one order with line items by id or uniqid.',
       inputSchema: {
         ...BaseToolSchema,
@@ -319,7 +335,7 @@ export function createCommerceToolCatalog() {
       execute: async (args) => createClient(args).ordersGet(args.order_id),
     },
     {
-      name: 'customers.get',
+      name: 'customers_get',
       description: 'Fetch one customer by Shoppex customer id or email.',
       inputSchema: {
         ...BaseToolSchema,
@@ -332,7 +348,7 @@ export function createCommerceToolCatalog() {
       }),
     },
     {
-      name: 'payment_links.create',
+      name: 'payment_links_create',
       description: 'Create a Shoppex payment link.',
       inputSchema: {
         ...BaseToolSchema,
@@ -369,7 +385,7 @@ export function createCommerceToolCatalog() {
       }),
     },
     {
-      name: 'analytics.revenue',
+      name: 'analytics_revenue',
       description: 'Fetch revenue totals for a date range.',
       inputSchema: {
         ...BaseToolSchema,
@@ -384,7 +400,7 @@ export function createCommerceToolCatalog() {
       }),
     },
     {
-      name: 'coupons.list',
+      name: 'coupons_list',
       description: 'List active coupons for a shop.',
       inputSchema: {
         ...BaseToolSchema,
@@ -395,7 +411,7 @@ export function createCommerceToolCatalog() {
       }),
     },
     {
-      name: 'coupons.create',
+      name: 'coupons_create',
       description: 'Create a coupon in Shoppex.',
       inputSchema: {
         ...BaseToolSchema,
@@ -422,8 +438,8 @@ export function createCommerceToolCatalog() {
       }),
     },
     {
-      name: 'coupons.update',
-      description: 'Update an existing coupon by uniqid. Only provided fields are changed.',
+      name: 'coupons_update',
+      description: 'Update an existing coupon by uniqid. Only provided fields change.',
       inputSchema: {
         ...BaseToolSchema,
         coupon_id: z.string().trim().min(1),
@@ -450,8 +466,8 @@ export function createCommerceToolCatalog() {
       },
     },
     {
-      name: 'products.create',
-      description: 'Create a product. Defaults to a simple digital/service product. For key-based products pass type="SERIALS" and provide the serials array.',
+      name: 'products_create',
+      description: 'Create a product. Defaults to a simple digital/service product. For key-based products pass type="SERIALS" and a serials array.',
       inputSchema: {
         ...BaseToolSchema,
         title: z.string().trim().min(1).max(128),
@@ -488,8 +504,8 @@ export function createCommerceToolCatalog() {
       },
     },
     {
-      name: 'products.update',
-      description: 'Update an existing product by uniqid. Only provided fields are changed.',
+      name: 'products_update',
+      description: 'Update an existing product by uniqid. Only provided fields change.',
       inputSchema: {
         ...BaseToolSchema,
         product_id: z.string().trim().min(1),
@@ -522,8 +538,13 @@ export function createCommerceToolCatalog() {
   ];
 }
 
+function normalizeToolName(name) {
+  return typeof name === 'string' ? name.replace(/\./g, '_') : name;
+}
+
 export async function executeCommerceTool(toolName, args) {
-  const tool = createCommerceToolCatalog().find((entry) => entry.name === toolName);
+  const normalized = normalizeToolName(toolName);
+  const tool = createCommerceToolCatalog().find((entry) => entry.name === normalized);
   if (!tool) {
     throw new Error(`Unknown tool: ${toolName}`);
   }