Plytix PIM 产品数据 MCP 服务器

Plytix MCP Server

A lightweight, stateless Model Context Protocol (MCP) server that provides AI assistants with live access to Plytix PIM (Product Information Management) data. This server enables AI tools like Claude Desktop, Claude mobile app, and other MCP clients to search, look up, and retrieve product information directly from the Plytix API.

Note: This is a stateless, live API tool for read and write operations. For sync, caching, or ETL workflows, pair it with a separate persistence layer of your choosing.

Features

• 51 MCP tools via stdio and 46 via the remote worker
• Smart product lookup with automatic identifier detection (SKU, MPN, GTIN, label)
• Family & inheritance tracking with overwritten_attributes support
• Schema discovery for attributes and search filters
• Automatic authentication with token refresh
• Rate limit handling — proactive pacing to the account's advertised window plus jittered 429/5xx backoff
• Zero persistence — stateless, no database required
• Remote server support — Deploy to Cloudflare Workers for mobile/web access

Installation

Prerequisites

• Node.js 20+
• Plytix PIM account with API access

Setup

1. Clone and install:

git clone https://github.com/Supplyline/plytix-mcp.git
cd plytix-mcp
npm install

2. Configure credentials:

cp .env.example .env
# Edit .env with your Plytix API credentials

3. Build the project:

npm run build

Usage

With Claude Desktop

Add to your Claude Desktop MCP configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "plytix": {
      "command": "node",
      "args": ["/path/to/plytix-mcp/dist/index.js"],
      "env": {
        "PLYTIX_API_KEY": "your_api_key_here",
        "PLYTIX_API_PASSWORD": "your_api_password_here"
      }
    }
  }
}

Standalone

npm start          # Production mode
npm run dev        # Development with hot reload

Remote Server (Cloudflare Workers)

Deploy as a remote MCP server for access from Claude mobile app, web clients, or shared team access.

Quick Deploy

# Install dependencies (includes wrangler)
npm install

# Login to Cloudflare
wrangler login

# Deploy to Cloudflare Workers
npm run deploy

Using the Remote Server

Once deployed, connect from any MCP client using the deployed URL and your Plytix credentials:

# With Claude Desktop (using mcp-remote)
npx mcp-remote https://plytix-mcp.your-subdomain.workers.dev/mcp \
  --header "X-Plytix-API-Key: YOUR_API_KEY" \
  --header "X-Plytix-API-Password: YOUR_API_PASSWORD"

The remote worker exposes 56 tools. It intentionally omits local-only utilities and filesystem tools: identifier_detect, identifier_normalize, match_score, products_batch_update_manifest, and products_batch_export_to_file.

Protocol versions

The worker is dual-era: it serves both the stateless 2026-07-28 revision and the older handshake-based revisions on the same endpoint, choosing per request.

A client newer than this server receives -32022 with the supported list and can renegotiate down. The 2026-07-28 transport dropped the standalone GET stream and DELETE teardown, so both now answer 405; Mcp-Session-Id is ignored rather than echoed.

The stdio server still speaks the legacy handshake — it delegates the protocol to @modelcontextprotocol/sdk, which has not yet shipped 2026-07-28.

Local Development

npm run dev:worker         # Start local worker at localhost:8787
npm run test:worker        # Test the worker endpoints

For detailed setup instructions, see docs/remote-setup.md.

Available Tools

Product Tools

Family Tools

Attribute & Filter Tools

Asset Tools

Category Tools

Variant Tools

Relationship Tools

Identifier Utilities (Stdio Only)

The remote worker exposes every tool above except the three identifier utilities in the final section and the two stdio-only filesystem tools: products_batch_update_manifest and products_batch_export_to_file.

Smart Lookup System

The products_lookup tool automatically detects identifier types and uses staged search strategies:

Detection priority:

1. MongoDB ObjectId (24-char hex) → id (confidence: 1.0)
2. GTIN (8/12/13/14 digits) → gtin (confidence: 0.95)
3. Contains spaces → label (confidence: 0.9)
4. Dashed alphanumeric → mpn (confidence: 0.8)
5. Alphanumeric with separators → sku (confidence: 0.7)

Search strategies (in order):

1. Direct ID lookup (if detected as ID)
2. Exact field matches (SKU, GTIN, MPN, MNO)
3. Text search across multiple fields
4. Broad LIKE search (last resort)

Example:

Input: "LMI-PD-123"
→ Detected as: sku (confidence: 0.7)
→ Tries: sku_eq, mpn fields, text_search, broad_like
→ Returns: best match with confidence score

Inheritance Tracking

Products return an overwritten_attributes array listing which attributes are explicitly set (not inherited from family). Use this with:

• product_family_id — The family this product belongs to
• families_get — Retrieve family-level default values
• Compare to determine inherited vs overwritten values

Configuration

Environment Variables

Delete safety gate

src/safety.ts provides a two-call gate for the destructive tools (products_delete, attributes_delete, categories_delete). A caller first invokes the tool with dry_run: true and gets back a preview of what would be removed plus a confirm_token; executing requires calling again with that token. Tokens are single-use, scoped to one tool and one target, and expire after 5 minutes. A per-process cap (PLYTIX_MCP_MAX_DELETES, default 3) bounds how much any one session can remove.

The execute call must repeat the side-effect options the preview was issued for (unlink_variants on a product, move_children_to on a category), and it is refused if the target's variants or children changed since the dry run. Plytix deletes a parent's variants and a category's whole subtree; those two options unlink the variants (they become standalone products) or move the direct children out first, so only the named item is removed. Plytix has no bulk product delete, so products_delete is one product per call.

What this does and does not protect against. The token goes back to the calling agent, not to a human — an autonomous agent can read it from the dry-run response and immediately call again. So the gate is a forced pause with a visible preview and a hard ceiling, not a human confirmation step. It stops a runaway loop from clearing a catalog; it does not stop an agent that has decided to delete something.

Genuine human confirmation needs the MCP elicitInput capability, where the server asks the client to prompt the user. A future revision can elicit when the client advertises that capability and fall back to this token flow otherwise.

Development

Scripts

Architecture

src/
  index.ts              # MCP server entry point (stdio transport)
  worker.ts             # Cloudflare Worker entry point (HTTP transport)
  client.ts             # Plytix API client with auth & rate limiting
  worker-client.ts      # Worker-compatible client (BYOK credentials)
  worker-lookup.ts      # Worker-compatible smart lookup
  types.ts              # TypeScript types
  lookup/
    identifier.ts       # Identifier type detection
    lookup.ts           # Smart lookup with staged search
  tools/
    products.ts         # Product tools (lookup, get, search, find, write ops)
    families.ts         # Family tools (list, get, create, attribute membership)
    attributes.ts       # Attribute metadata + filter discovery tools
    product-attributes.ts # Atomic product attribute write tools
    assets.ts           # Asset get/search/update + product asset link tools
    categories.ts       # Category search + product category link tools
    variants.ts         # Variant lifecycle tools
    relationships.ts    # Relationship discovery + product relationship write tools
  extensions/           # Optional deployment-specific customizations
wrangler.toml           # Cloudflare Workers configuration
docs/
  remote-setup.md       # Remote server setup guide

Design Principles

This MCP server is intentionally stateless and lightweight:

• No database — All queries go directly to Plytix API
• No sync/caching layer — Fresh data on every request
• No background jobs — Request/response only
• Ephemeral in-memory cache — Brief (60s) request deduplication, cleared on restart

For ETL, sync, or persistent caching needs, pair this server with a separate persistence layer.

License

MIT License — see LICENSE file for details.

Support

• Issues: GitHub Issues
• Plytix API: Plytix Documentation
• MCP Protocol: Model Context Protocol