Developer Documentation

k-sync API & MCP Reference

Automate ecommerce migrations from AI assistants, agents, and CI/CD pipelines. k-sync exposes a full Model Context Protocol (MCP) server.

Quick Start

1. Get an API token

Go to Settings → API Tokens and create a token with the ks_ prefix.

2. Configure your MCP client

json

{
  "mcpServers": {
    "k-sync": {
      "url": "https://sync.krokanti.com/api/mcp",
      "headers": {
        "Authorization": "Bearer ks_your_token_here"
      }
    }
  }
}

3. Use it in your AI assistant

Ask Claude or any MCP-compatible assistant: "List my k-sync projects" or "Start a migration for project X to my Shopify store."

Authentication

All API requests require a Bearer token. Tokens are prefixed with ks_ and can be created in your account settings.

http

POST /api/mcp
Authorization: Bearer ks_your_token_here
Content-Type: application/json

The MCP endpoint also accepts NextAuth session cookies for browser-based tooling.

MCP Tools

These tools are available when k-sync is connected as an MCP server.

Projects

list_projects

List all your migration projects.

Returns: Array of projects with id, name, status, sourceType, productCount, createdAt

create_project

Create a new migration project.

Parameters

name·stringrequiredProject name

description·stringOptional description

sourceType·"woocommerce" | "csv"Default: "woocommerce"

Returns: Created project object with id

get_project_stats

Get product pipeline stats for a project (imported/mapped/validated/pushed/error counts).

Parameters

projectId·stringrequiredProject ID

Returns: Stats object: {total, imported, mapped, validated, pushed, error, skipped}

Connections

list_connections

List all your platform connections (WooCommerce and Shopify stores).

Returns: Array of connections with id, platform, storeName, storeUrl, status

Products

list_products

List products in a project with optional filtering.

Parameters

projectId·stringrequiredProject ID

limit·numberMax results (default 20, max 100)

Returns: Array of products with id, title, sku, price, status, validationErrors

import_products

Trigger a product import from a WooCommerce connection into a project.

Parameters

projectId·stringrequiredProject ID

connectionId·stringrequiredWooCommerce connection ID

Returns: {jobId} — poll with get_import_status

get_import_status

Poll the status of an import job.

Parameters

jobId·stringrequiredImport job ID from import_products

Returns: {status, processedPages, totalPages, productCount, error}

Mapping & Validation

apply_mappings

Apply field mappings to convert normalized product data to Shopify format.

Parameters

projectId·stringrequiredProject ID

Returns: {count} — number of products mapped

validate_products

Validate all mapped products against Shopify requirements.

Parameters

projectId·stringrequiredProject ID

Returns: {total, validated, withErrors}

Migration

start_migration

Start pushing validated products to Shopify.

Parameters

projectId·stringrequiredProject ID

connectionId·stringrequiredShopify connection ID (target)

Returns: {migrationId} — poll with get_migration_status

get_migration_status

Poll the status of a migration run.

Parameters

projectId·stringrequiredProject ID

migrationId·stringrequiredMigration run ID

Returns: {status, totalProducts, processedProducts, successCount, errorCount}

SEO & Data Quality

get_seo_audit

Run an SEO audit on all products in a project. Returns title/description coverage stats and products needing attention.

Parameters

projectId·stringrequiredProject ID

Returns: {totalProducts, withSeoTitle, withSeoDescription, missingBoth, missingTitle, missingDescription, averageTitleLength, averageDescriptionLength}

check_image_health

Check all product image URLs for accessibility. Returns broken/missing image counts.

Parameters

projectId·stringrequiredProject ID

Returns: {totalProducts, totalImages, checkedImages, brokenImages, missingImages, healthScore}

fix_handles

Auto-fix duplicate or missing URL handles across all products in a project.

Parameters

projectId·stringrequiredProject ID

dryRun·booleanPreview changes without applying (default: false)

Returns: {fixed, skipped, preview (in dry run mode)}

Bulk Operations

apply_price_rules

Apply price transformation rules to all products (multiply, add fixed amount, round, set minimum/maximum).

Parameters

projectId·stringrequiredProject ID

operation·"multiply" | "add" | "round" | "min" | "max"requiredOperation type

value·numberrequiredOperand value

dryRun·booleanPreview without applying

Returns: {affectedProducts, preview (dry run)} or {updated} on apply

manage_tags

Rename, delete, or normalize tags across all products in a project.

Parameters

projectId·stringrequiredProject ID

action·"rename" | "delete" | "normalize"requiredAction to perform

tag·stringSource tag (required for rename/delete)

newTag·stringReplacement tag (required for rename)

Returns: {affectedProducts, action, tag, newTag}

manage_vendors

Rename vendors or bulk-assign a vendor to products missing one.

Parameters

projectId·stringrequiredProject ID

action·"rename" | "fill-missing"requiredAction type

vendor·stringSource vendor (required for rename)

newVendor·stringReplacement vendor (required for rename or fill-missing)

Returns: {affectedProducts, action}

Example: Full Migration via MCP

This is the typical sequence for a complete WooCommerce → Shopify migration:

1list_connectionsFind WooCommerce + Shopify connection IDs

2create_projectname: "My Store Migration"

3import_productsPass projectId + WooCommerce connectionId

4get_import_statusPoll until status = 'completed'

5apply_mappingsConvert WooCommerce fields → Shopify format

6validate_productsCheck for errors before push

7start_migrationPass projectId + Shopify connectionId

8get_migration_statusPoll until status = 'completed'

Rate Limits

Free

10 req/min

Starter

60 req/min

Pro

300 req/min