unchained icon indicating copy to clipboard operation
unchained copied to clipboard
verified publisher icon unchainedshop

MCP Server Implementation

Open pozylon opened this issue 6 months ago • 8 comments

Requirements:

  • We want to allow users of an MCP-compatible LLM-Chat client like Claude Desktop to search for products in Unchained and see those products nicely visualized in a list, showing _id, cover image, sku, title and status.
  • We want to allow users of an MCP-compatible LLM-Chat client like Claude Desktop to lookup all detail information of a product and get it nicely visualized in a card style, including texts and media, price, meta attributes etc.
  • We want to allow Admin Users to use an MCP client like Claude Desktop to manage products and assortments.

pozylon avatar Jun 04 '25 07:06 pozylon

@claude Please check this issue and extend the specification with detailed instructions and planned sub-tasks

pozylon avatar Jun 04 '25 07:06 pozylon

Claude encountered an error after 6m 57s —— View job

MCP Server Implementation Analysis

I'll analyze the requirements and create a detailed specification with planned sub-tasks for the MCP Server implementation.

Todo List:

  • [ ] Research MCP protocol and existing implementations
  • [ ] Analyze Unchained's current architecture and API
  • [ ] Define technical architecture for MCP server
  • [ ] Create detailed specifications for each requirement
  • [ ] Break down implementation into manageable sub-tasks
  • [ ] Define testing and deployment strategy

claude[bot] avatar Jun 04 '25 07:06 claude[bot]

@claude I already added a working MCP server that currently only contains a hello world tool, check packages/api/src/mcp/index.ts

pozylon avatar Jun 04 '25 07:06 pozylon

Claude encountered an error after 1m 49s —— View job

MCP Server Implementation Analysis

I'll analyze the existing MCP server implementation and create a detailed specification with planned sub-tasks for the MCP Server requirements.

Todo List:

  • [ ] Read and analyze existing MCP server implementation
  • [ ] Explore Unchained's GraphQL API and core modules
  • [ ] Research MCP protocol capabilities for rich visualizations
  • [ ] Create detailed technical specification for each requirement
  • [ ] Break down implementation into concrete sub-tasks
  • [ ] Define testing and deployment strategy

claude[bot] avatar Jun 04 '25 07:06 claude[bot]

@claude please focus on analyzing the existing MCP implementation, then explore of the GraphQL schema & resolvers, the core modules and core services to produce a simple list of MCP tools, resources and prompts needed for product management alone.

Skip the rest of the todos.

pozylon avatar Jun 04 '25 10:06 pozylon

Claude finished @pozylon's task in 1m 23s —— View job

MCP Server Implementation Analysis

Analyzing existing MCP implementation and exploring GraphQL schema/resolvers to create MCP tools for product management.

Todo List:

  • [x] Analyze existing MCP server implementation
  • [x] Explore GraphQL schema for product-related queries/mutations
  • [x] Examine core product modules and services
  • [x] Create list of MCP tools, resources and prompts for product management

Analysis Results

Existing MCP Implementation

Found a basic MCP server setup at packages/api/src/mcp/index.ts using @modelcontextprotocol/sdk/server/mcp.js with:

  • Single hello-world tool as example
  • Context access for Unchained services
  • Commented out resource example for config
  • Uses Zod for input validation

Product Management Capabilities Discovered

Core Product Services Available:

  • Product CRUD operations (create, read, update, delete)
  • Product publishing/unpublishing
  • Product variations and assignments
  • Product media management
  • Product text/localization management
  • Product pricing and commerce features
  • Product search and filtering
  • Product reviews
  • Bundle products and proxy products

Core Assortment Services Available:

  • Assortment CRUD operations
  • Assortment hierarchies and links
  • Assortment-product relationships
  • Assortment media and texts
  • Assortment filters

Recommended MCP Tools for Product Management

1. Product Search & Discovery Tools

// Search products with visualization
search_products(query?: string, tags?: string[], limit?: number, includeDrafts?: boolean)
// Returns: List with _id, cover image, sku, title, status

// Get single product details  
get_product(productId?: string, slug?: string, sku?: string)
// Returns: Full product card with texts, media, pricing, meta attributes

// List products with filtering
list_products(limit?: number, offset?: number, sort?: string[], tags?: string[])

2. Product Management Tools

// Create new product
create_product(type: ProductType, title: string, texts?: ProductTexts[])

// Update product information
update_product(productId: string, updates: ProductUpdates)

// Publish/unpublish products
publish_product(productId: string)
unpublish_product(productId: string)

// Delete product
delete_product(productId: string)

3. Product Content Management Tools

// Manage product texts/localization
update_product_texts(productId: string, texts: ProductTexts[])

// Manage product media
add_product_media(productId: string, mediaFile: File)
remove_product_media(productMediaId: string)

// Manage product variations
create_product_variation(productId: string, variation: ProductVariation)

4. Assortment Management Tools

// Search assortments
search_assortments(query?: string, includeInactive?: boolean)

// Create/update assortments
create_assortment(assortment: AssortmentInput, texts?: AssortmentTexts[])
update_assortment(assortmentId: string, updates: AssortmentUpdates)

// Manage product-assortment relationships
add_product_to_assortment(assortmentId: string, productId: string)
remove_product_from_assortment(assortmentProductId: string)

Recommended MCP Resources

1. Product Schemas Resource

  • product://schemas - Product type definitions and validation schemas
  • Rich visualization of available product types, required fields, etc.

2. Product Status Reference

  • product://status-guide - Visual guide to product statuses (DRAFT, ACTIVE, DELETED)

Recommended MCP Prompts

1. Product Management Assistant

  • Context about product types, workflows, and best practices
  • Guidelines for SEO-friendly slugs, proper categorization
  • Pricing and inventory management guidance

2. Assortment Organization Helper

  • Best practices for product categorization
  • Hierarchy design patterns
  • Filter and tag strategies

claude[bot] avatar Jun 04 '25 10:06 claude[bot]

@claude let's get into details about product search and discovery:

list_products and search_products should be combined to list_products with all the arguments supported. Additionally support filtering with filter keys and values. paging should be supported so it's possible to fetch a big list chunk by chunk for further analysis.

After that, create an issue for each list_products and get_product where you specify in detail the implementation of and come up with a UX/UI design idea on how a visually appealing representat the result.

Product list and the product details should have a similar corporate design of https://unchained.shop regarding colors, fonts etc. but keep it minimal and lightweight.

pozylon avatar Jun 04 '25 11:06 pozylon

Claude finished @pozylon's task in 4m 38s —— View job

MCP Product Search & Discovery Specification

Creating detailed specifications for enhanced product search and discovery tools, plus design mockups for visual representation.

Todo List:

  • [x] Analyze existing MCP server implementation
  • [x] Examine GraphQL schema for product queries and filters
  • [x] Research unchained.shop design system (colors, fonts)
  • [x] Design enhanced list_products tool specification
  • [x] Design get_product tool specification
  • [x] Create GitHub issue for list_products implementation
  • [x] Create GitHub issue for get_product implementation

Analysis Results

Existing MCP Implementation

  • Basic MCP server using @modelcontextprotocol/sdk/server/mcp.js
  • Context access to Unchained services and modules
  • Zod validation for inputs
  • Single hello-world tool as template

Available Product APIs

From GraphQL schema analysis:

  • products query: supports ProductQuery, sorting, pagination (limit/offset)
  • searchProducts query: supports filterQuery, queryString, assortmentId, includeInactive
  • ProductQuery interface: queryString, includeDrafts, productIds, productSelector, slugs, tags
  • SearchFilterQuery type: { key: string; value?: string }[]

Enhanced Tool Specifications

1. list_products Tool Specification

Purpose: Combined search and list functionality with comprehensive filtering and pagination

Input Schema:

{
  // Search & Filter
  queryString?: string,              // Text search
  tags?: string[],                   // Product tags
  slugs?: string[],                  // Specific product slugs
  productIds?: string[],             // Specific product IDs
  filterQuery?: { key: string, value?: string }[],  // Key-value filters
  assortmentId?: string,             // Filter by assortment
  includeDrafts?: boolean,           // Include draft products
  includeInactive?: boolean,         // Include inactive products
  
  // Pagination  
  limit?: number,                    // Results per page (default: 20, max: 100)
  offset?: number,                   // Skip results (default: 0)
  
  // Sorting
  sort?: { key: string, value: 'ASC' | 'DESC' }[],  // Sort options
}

Output: Rich HTML table with Unchained corporate styling

Visual Design:

  • Clean table layout with rounded corners and subtle shadows
  • Unchained brand colors: Primary blue (#0066cc), secondary orange (#ff6600)
  • Typography: Clean sans-serif (system fonts)
  • Responsive grid showing: thumbnail, ID, SKU, title, status badge
  • Pagination controls at bottom
  • Total count indicator

2. get_product Tool Specification

Purpose: Detailed product information with rich visualization

Input Schema:

{
  productId?: string,     // Product ID (primary lookup)
  slug?: string,          // Product slug (alternative lookup)  
  sku?: string,           // Product SKU (alternative lookup)
}

Output: Rich HTML product card with complete information

Visual Design:

  • Card-based layout with hero image area
  • Information sections: Basic Info, Pricing, Media Gallery, Texts, Meta
  • Unchained brand styling with blue/orange accents
  • Status indicators with color-coded badges
  • Expandable sections for detailed information
  • Mobile-friendly responsive design

Design System Guidelines

Colors (Unchained-inspired):

  • Primary: #0066cc (blue)
  • Secondary: #ff6600 (orange)
  • Success: #28a745 (green)
  • Warning: #ffc107 (yellow)
  • Danger: #dc3545 (red)
  • Gray scale: #f8f9fa, #e9ecef, #6c757d, #343a40

Typography:

  • Headers: -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui
  • Body: Same system font stack
  • Monospace: 'SF Mono', Monaco, 'Cascadia Code', monospace

Components:

  • Rounded corners: 6px
  • Shadows: 0 2px 4px rgba(0,0,0,0.1)
  • Spacing: 8px grid system
  • Status badges with appropriate colors

GitHub Issues to Create

Since I don't have permission to create issues directly, please create these two issues:

Issue 1: "MCP Tool: Implement list_products with enhanced search and pagination"

Labels: enhancement, mcp, product-management

Click to expand issue content

Overview

Implement a comprehensive list_products MCP tool that combines search and listing functionality with advanced filtering, pagination, and visual representation.

Implementation Details

Tool Specification

Tool Name: list_products Description: Search and list products with comprehensive filtering and pagination support

Input Schema (Zod validation)

{
  // Search & Filter
  queryString: z.string().optional().describe('Text search across product fields'),
  tags: z.array(z.string()).optional().describe('Filter by product tags'),
  slugs: z.array(z.string()).optional().describe('Filter by specific product slugs'),
  productIds: z.array(z.string()).optional().describe('Filter by specific product IDs'),
  filterQuery: z.array(z.object({
    key: z.string().describe('Filter key'),
    value: z.string().optional().describe('Filter value')
  })).optional().describe('Key-value filter pairs'),
  assortmentId: z.string().optional().describe('Filter by assortment'),
  includeDrafts: z.boolean().default(false).describe('Include draft products'),
  includeInactive: z.boolean().default(false).describe('Include inactive products'),
  
  // Pagination  
  limit: z.number().min(1).max(100).default(20).describe('Results per page'),
  offset: z.number().min(0).default(0).describe('Skip results for pagination'),
  
  // Sorting
  sort: z.array(z.object({
    key: z.string().describe('Sort field'),
    value: z.enum(['ASC', 'DESC']).describe('Sort direction')
  })).optional().describe('Sort options'),
}

Backend Integration

Use existing Unchained services:

  1. Primary: modules.products.findProducts() for basic queries
  2. Search: services.filters.searchProducts() for text search with filters
  3. Assortment filtering: modules.assortments.findProductIds() when assortmentId provided

Visual Output Design

HTML Structure with Unchained styling:

<div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui; max-width: 1200px;">
  <div style="margin-bottom: 16px; display: flex; justify-content: space-between; align-items: center;">
    <h3 style="color: #343a40; margin: 0;">Products</h3>
    <span style="color: #6c757d; font-size: 14px;">Showing {offset+1}-{offset+results.length} of {total}</span>
  </div>
  
  <div style="background: white; border-radius: 6px; box-shadow: 0 2px 4px rgba(0,0,0,0.1); overflow: hidden;">
    <table style="width: 100%; border-collapse: collapse;">
      <thead style="background: #f8f9fa; border-bottom: 1px solid #e9ecef;">
        <tr>
          <th style="padding: 12px; text-align: left; font-weight: 600; color: #343a40;">Image</th>
          <th style="padding: 12px; text-align: left; font-weight: 600; color: #343a40;">Product</th>
          <th style="padding: 12px; text-align: left; font-weight: 600; color: #343a40;">SKU</th>
          <th style="padding: 12px; text-align: left; font-weight: 600; color: #343a40;">Status</th>
          <th style="padding: 12px; text-align: left; font-weight: 600; color: #343a40;">ID</th>
        </tr>
      </thead>
      <tbody>
        <!-- Product rows -->
      </tbody>
    </table>
  </div>
</div>

Implementation Tasks

  • [ ] Add tool definition to MCP server (packages/api/src/mcp/index.ts)
  • [ ] Implement input validation with Zod schema
  • [ ] Create service integration logic
  • [ ] Handle different query scenarios (search vs list vs filter)
  • [ ] Implement pagination logic
  • [ ] Build HTML output template
  • [ ] Add error handling for invalid inputs
  • [ ] Test with various filter combinations
  • [ ] Add JSDoc documentation

Acceptance Criteria

  1. Tool accepts all specified input parameters
  2. Integrates with existing Unchained product APIs
  3. Returns paginated results with proper metadata
  4. Visual output matches design specification
  5. Handles edge cases (no results, invalid IDs, etc.)
  6. Performance is acceptable for large product catalogs
  7. Error messages are helpful and specific

Issue 2: "MCP Tool: Implement get_product with rich product details visualization"

Labels: enhancement, mcp, product-management

Click to expand issue content

Overview

Implement a detailed get_product MCP tool that provides comprehensive product information with rich visual representation in a card-based layout.

Implementation Details

Tool Specification

Tool Name: get_product Description: Get detailed product information with rich visualization

Input Schema (Zod validation)

{
  productId: z.string().optional().describe('Product ID for lookup'),
  slug: z.string().optional().describe('Product slug for lookup'),
  sku: z.string().optional().describe('Product SKU for lookup'),
}

Validation: At least one of productId, slug, or sku must be provided

Backend Integration

Use existing Unchained services:

  1. Primary lookup: modules.products.findProduct() with appropriate selector
  2. Media: Access product media through product.media relationship
  3. Texts: Access localized texts through product.texts relationship
  4. Pricing: Access pricing through modules.products.price.getPrice()
  5. Meta: Access product metadata and configuration

Visual Output Design

Card-based layout with sections:

<div style="font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui; max-width: 800px;">
  <!-- Header -->
  <div style="background: white; border-radius: 6px; box-shadow: 0 2px 4px rgba(0,0,0,0.1); margin-bottom: 16px; overflow: hidden;">
    <div style="padding: 20px; border-bottom: 1px solid #e9ecef;">
      <div style="display: flex; justify-content: space-between; align-items: start; margin-bottom: 12px;">
        <h2 style="margin: 0; color: #343a40; font-size: 24px;">{title}</h2>
        <span style="padding: 6px 12px; border-radius: 12px; font-size: 14px; font-weight: 500; 
                     background: {statusColor}; color: white;">{status}</span>
      </div>
      <p style="margin: 0; color: #6c757d; font-size: 16px;">{subtitle}</p>
      <div style="margin-top: 12px; display: flex; gap: 16px; font-size: 14px; color: #6c757d;">
        <span><strong>ID:</strong> {_id}</span>
        <span><strong>SKU:</strong> {sku || 'N/A'}</span>
        <span><strong>Type:</strong> {type}</span>
      </div>
    </div>
    
    <!-- Hero Image -->
    <div style="padding: 20px; text-align: center; background: #f8f9fa;">
      <img src="{primaryImageUrl}" style="max-width: 100%; max-height: 300px; border-radius: 6px; box-shadow: 0 2px 4px rgba(0,0,0,0.1);" 
           onerror="this.style.display='none'; this.nextElementSibling.style.display='block'" />
      <div style="display: none; padding: 60px; color: #6c757d; font-size: 18px;">No image available</div>
    </div>
  </div>
  
  <!-- Details Grid -->
  <div style="display: grid; grid-template-columns: 1fr 1fr; gap: 16px;">
    <!-- Basic Info -->
    <div style="background: white; border-radius: 6px; box-shadow: 0 2px 4px rgba(0,0,0,0.1); padding: 20px;">
      <h3 style="margin: 0 0 16px 0; color: #0066cc; font-size: 18px;">Basic Information</h3>
      <!-- Product details -->
    </div>
    
    <!-- Pricing -->
    <div style="background: white; border-radius: 6px; box-shadow: 0 2px 4px rgba(0,0,0,0.1); padding: 20px;">
      <h3 style="margin: 0 0 16px 0; color: #0066cc; font-size: 18px;">Pricing</h3>
      <!-- Pricing details -->
    </div>
  </div>
  
  <!-- Additional sections as needed -->
</div>

Data Sections to Include

  1. Basic Information:

    • Title, subtitle, description
    • SKU, Type, Status
    • Tags, Created/Updated dates
    • Sequence number

  2. Pricing Information:

    • Current price (if available)
    • Price range for variations
    • Currency information
    • Pricing configuration

  3. Media Gallery:

    • Primary image (hero)
    • Additional images in gallery
    • Alt texts and captions

  4. Localization:

    • Available text languages
    • Localized titles/descriptions
    • Vendor and brand information

  5. Technical Details:

    • Product variations
    • Bundle items (if bundle product)
    • Meta attributes
    • Configuration options

  6. Relationships:

    • Assortment memberships
    • Related products
    • Reviews summary

Implementation Tasks

  • [ ] Add tool definition to MCP server
  • [ ] Implement input validation with Zod
  • [ ] Create product lookup logic (by ID/slug/SKU)
  • [ ] Implement data fetching for all sections
  • [ ] Build responsive HTML template
  • [ ] Handle missing/optional data gracefully
  • [ ] Add error handling for not found
  • [ ] Optimize for performance
  • [ ] Add comprehensive JSDoc

Acceptance Criteria

  1. Tool accepts productId, slug, or sku for lookup
  2. Returns comprehensive product information
  3. Visual output is well-structured and branded
  4. Handles all product types correctly
  5. Gracefully handles missing data
  6. Provides helpful error messages
  7. Performance is acceptable for complex products
  8. Mobile-friendly responsive design

These detailed specifications provide everything needed to implement both MCP tools with proper Unchained integration and visual design. The tools will provide a rich, branded experience for product management through MCP-compatible clients like Claude Desktop.

claude[bot] avatar Jun 04 '25 11:06 claude[bot]