convez.ai
MCP ServerIntegração & APIsIntermediário
Supplyline

Plytix MCP Server

Supplyline/plytix-mcp

MCP stateless para integração com Plytix PIM e automação de dados de produtos

Ver no GitHub
BomPluginScore · de 0 a 100

Servidor MCP stateless que conecta Claude e outros assistentes de IA diretamente à API Plytix PIM. Oferece 51 ferramentas para leitura e escrita de dados de produtos, ativos, categorias e relacionamentos, ideal para automação de e-commerce sem necessidade de persistência local.

Instalação

$npx convez-ai Supplyline/plytix-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
8
Forks
6
Acompanhando
0
Saúde
42%
Último commit
há 3 dias
Versão
—
Issues abertas
0
Contribuidores
3

Casos de uso

  • Automação de gestão de catálogo de produtos em tempo real
  • Assistentes de IA para busca e lookup inteligente de informações de produtos
  • Integrações de e-commerce com atualização de metadados e atributos
  • Deployment remoto em Cloudflare Workers para acesso mobile/web

Veredito

MCP server robusto e bem documentado para integração PIM, com suporte a deployment remoto e autenticação automática. Excelente para equipes de e-commerce que precisam de acesso programático ao Plytix sem overhead de persistência.

README

A tradução para o português deste README ainda está na fila.

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 with exponential backoff
  • Zero persistence — stateless, no database required
  • Remote server support — Deploy to Cloudflare Workers for mobile/web access

Installation

Prerequisites

  • Node.js 18+ (Node 20+ recommended)
  • 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
  1. Configure credentials:
cp .env.example .env
# Edit .env with your Plytix API credentials
  1. 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 46 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.

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

ToolDescription
products_lookupSmart lookup by any identifier (auto-detects ID, SKU, MPN, GTIN, label)
products_getGet single product by ID with full details and overwritten_attributes
products_get_fullGet one product with related family, variants, categories, and assets
products_searchAdvanced search with filters, pagination, and sorting
products_findSimple multi-criteria search (SKU, MPN, MNO, GTIN, label, fuzzy)
products_batch_exportCapped inline product snapshot by search, SKU, or product ID
products_batch_export_to_fileStdio-only JSONL/NDJSON product export under PLYTIX_MCP_EXPORT_DIR
products_createCreate a new product
products_updatePartial update to product fields/attributes
products_batch_updateApply a small guarded product-update batch
products_batch_update_manifestStdio-only guarded product updates from a local JSON manifest
products_assign_familyAssign or unassign a product family
products_set_attributeAtomic set of one attribute value
products_clear_attributeAtomic clear of one attribute value

Family Tools

ToolDescription
families_listList or search product families
families_getGet single family with linked attributes
families_createCreate a new product family
families_link_attributeLink one or more attributes to a family
families_unlink_attributeUnlink one or more attributes from a family
families_list_attributesList attributes directly linked to a family
families_list_all_attributesList direct and inherited family attributes

Attribute & Filter Tools

ToolDescription
attributes_listList all attributes (system + custom) with types and options
attributes_getGet full metadata for one attribute label
attributes_get_optionsGet allowed values for a selectable attribute
attributes_filtersDeprecated alias for product filter discovery
products_filtersGet product search filter metadata
assets_filtersGet asset search filter metadata
relationships_filtersGet relationship search filter metadata

Asset Tools

ToolDescription
assets_getGet one asset by ID
assets_searchSearch account assets
assets_updateUpdate asset metadata (filename, categories)
assets_listList assets (images, videos, documents) linked to a product
assets_linkLink an asset to a product
assets_unlinkUnlink an asset from a product

Category Tools

ToolDescription
categories_searchSearch existing categories
categories_listList categories associated with a product
categories_linkLink a category to a product
categories_unlinkUnlink a category from a product

Variant Tools

ToolDescription
variants_createCreate a variant under a parent product
variants_linkLink an existing product as a variant
variants_unlinkUnlink a variant from its parent without deleting it
variants_listList variants for a product
variants_resyncReset variant attributes to inherit parent values

Relationship Tools

ToolDescription
relationships_getGet a relationship definition by ID
relationships_searchSearch relationship definitions
relationships_link_productLink one related product row in a relationship
relationships_unlink_productUnlink one related product row in a relationship
relationships_set_quantityUpdate quantity for one related product row

Identifier Utilities (Stdio Only)

ToolDescription
identifier_detectDetect identifier type from raw value
identifier_normalizeNormalize identifier for matching
match_scoreScore identifier-product match confidence

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

VariableRequiredDefaultDescription
PLYTIX_API_KEY✅—Your Plytix API key
PLYTIX_API_PASSWORD✅—Your Plytix API password
PLYTIX_API_BASE❌https://pim.plytix.comPlytix API base URL
PLYTIX_AUTH_URL❌https://auth.plytix.com/auth/api/get-tokenAuth endpoint
PLYTIX_MPN_LABELS❌["attributes.mpn"]JSON array of MPN attribute labels
PLYTIX_MNO_LABELS❌["attributes.model_no"]JSON array of MNO attribute labels
PLYTIX_MCP_EXPORT_DIR❌—Required only for products_batch_export_to_file; limits file exports to this directory

Development

Scripts

CommandDescription
npm run devDevelopment server with hot reload (stdio)
npm run dev:workerDevelopment server for Cloudflare Workers
npm run buildBuild TypeScript to JavaScript
npm run deployDeploy to Cloudflare Workers
npm startStart production server (stdio)
npm testRun unit tests (vitest)
npm run test:watchRun tests in watch mode
npm run test:mcpTest MCP protocol handshake
npm run test:workerTest worker endpoints
npm run test:allBuild + unit + integration + MCP tests
npm run typecheckType check without building

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

Ver o original no GitHub

Bom para

Relacionados