Synchronity

---

Synchronity is commerce infrastructure for AI assistants. It connects to the hosted Synchronity gateway at https://api.synchronity.app — there is nothing to self-host.

This repository contains the public, MIT-licensed pieces:

Part	What it is
packages/mcp	The MCP server — exposes shopping tools to Claude, Cursor, and any MCP client
packages/sdk	Typed gateway client used by the MCP server
desktop-extension	Claude Desktop extension (.mcpb) source — a zero-dependency bridge to the gateway
plugins/synchronity	Cross-assistant plugin (Claude Code + Codex) — install via the marketplace below
woocommerce	The Synchronity WooCommerce plugin — makes a store agent-ready

Releases attach prebuilt artifacts: the synchronity.mcpb desktop extension and the WooCommerce plugin zip. See Releases.

For shoppers — connect your AI assistant

Claude Desktop (easiest)

1. Download synchronity.mcpb from the latest release (or from api.synchronity.app/setup/download).
2. Open it with Claude Desktop and click Install.
3. Ask Claude to shop — e.g. "Search Synchronity for a wireless keyboard."

Claude Code (plugin marketplace)

/plugin marketplace add themewireco/synchronity
/plugin install synchronity@synchronity

Then just shop — "find me a birthday cake from my stores". The plugin bundles the synchronity-commerce skill and runs the MCP server locally via npx, so there is nothing to clone or build.

Codex

Add the Synchronity plugin from this repo (plugins/synchronity). Codex reads .codex-plugin/plugin.json and connects to the hosted MCP at https://api.synchronity.app/mcp, with the same synchronity-commerce skill.

Any MCP client (manual)

npm install && npm run build

{
  "mcpServers": {
    "synchronity": {
      "command": "node",
      "args": ["/absolute/path/to/synchronity/packages/mcp/dist/index.js"],
      "env": { "GATEWAY_URL": "https://api.synchronity.app" }
    }
  }
}

GATEWAY_URL defaults to https://api.synchronity.app. Sensitive actions (checkout, payment) require buyer approval — the assistant walks you through a one-time approval step.

What the assistant can do

Product search & details (with inline images), compare across stores, reviews, cart management, shipping, checkout, card/mobile-money payment, order tracking, and human-in-the-loop approval for sensitive actions.

For merchants — make your WooCommerce store agent-ready

1. Download the WooCommerce plugin zip from the latest release.
2. In WordPress: Plugins → Add New → Upload Plugin, choose the zip, Install and Activate.
3. Open WooCommerce → Synchronity, copy your connector key, and register your store with Synchronity.

Your store keeps its own catalog, currency, shipping, and orders — Synchronity routes agent requests to it through the gateway.

Build the artifacts yourself

npm run build         # build the MCP server + client
npm run build:mcpb    # -> synchronity.mcpb (Claude Desktop extension)
npm run build:plugin  # -> synchronity-woocommerce-v<version>.zip

Configuration

Env var	Default	Purpose
GATEWAY_URL	https://api.synchronity.app	Synchronity gateway base URL
DEFAULT_SITE_ID	—	Optional default store to scope tools to
DEBUG	false	Verbose logging to stderr

Reviewing & testing

New here or reviewing the connector? Follow the end-to-end walkthrough: docs/reviewer-testing.md.

Privacy & support

• Privacy Policy: PRIVACY.md · at synchronity.app/privacy-policy
• Support: hello@themewire.co

License

MIT © Themewire — see LICENSE.