Serveur MCP Commerce Agent Protocol
Commit 13 nov. 2026Enrichit les catalogues e-commerce avec des attributs structurés et un score de préparation aux agents pour rendre les produits recherchables et achetables par les agents de shopping IA.
Aussi connu sous teocomyn/commerce-agent-protocol
- Étoiles
- 1
- Outils
- —
- Téléchargements, 30 jours
- —
- Dernière version
- —
- Dernier commit
- 13 nov. 2026
- Licence
- Apache-2.0
Qu'est-ce que Commerce Agent Protocol MCP ?
Enrichit les catalogues e-commerce avec des attributs structurés et un score de préparation aux agents pour rendre les produits recherchables et achetables par les agents de shopping IA.
Résumé généré à partir du README du projet
À propos du MCP server Commerce Agent Protocol
Commerce Agent Protocol aide les marchands à préparer leurs catalogues produits pour les agents de shopping IA. Il transforme les données de base de la boutique en attributs hautement structurés et typés, tels que les matériaux, les dimensions et les certifications. Ce processus garantit que les produits sont facilement recherchables et classables par des outils d'IA comme ChatGPT, Gemini et Perplexity. Le système prend actuellement en charge Shopify via OAuth et la synchronisation en masse.
Les développeurs peuvent déployer cela en tant que MCP server local utilisant stdio pour Claude Desktop ou Cursor, ou le connecter à des clients distants via HTTP. La configuration nécessite un environnement local avec Node, pnpm, Docker, Postgres avec pgvector et Redis. Vous aurez également besoin d'une clé API OpenAI pour le processus d'enrichissement et d'identifiants Shopify spécifiques pour synchroniser une boutique.
Une fonctionnalité clé est le score de préparation aux agents, qui utilise l'outil computeGeoScore pour évaluer dans quelle mesure un catalogue répond aux exigences des agents de shopping. Le serveur fournit des outils tels que commerce_search et commerce_compare pour permettre aux agents d'interagir efficacement avec les données produits enrichies.
Ce que vous pouvez faire avec
- 1Enrichir les données produitsTransformez les metafields bruts des marchands en attributs structurés et typés grâce à un enrichissement piloté par LLM.
- 2Évaluer la qualité du catalogueDéterminez dans quelle mesure un catalogue de produits est prêt pour les agents de shopping IA à l'aide d'un score de préparation spécifique.
Extrait du README du projet. Chaque cas d'utilisation est vérifié par rapport à une citation du document.
Configuration
CAP_MERCHANT_ID
| Nom | Description | Type |
|---|---|---|
| CAP_MERCHANT_ID | — |
Vérifications automatisées
Exécuté le 15 nov. 2026Rapport complet →Pas encore vérifié. Un serveur nécessite un score de 80, aucune faille sérieuse et suffisamment de données pour que nous puissions effectuer les vérifications. Fonctionnement des vérifications · Ce qu'il faut corriger pour gagner des points
- Dépôt source lié et accessibleteocomyn/commerce-agent-protocol is public and reachablegithub.com/teocomyn/commerce-agent-protocol ↗Réussi
- Le nom du package correspond au dépôt sourceNon vérifié
- Provenance du build (attestation Sigstore)Non vérifié
- Licence open source (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Réussi
- Commit ou version publiée au cours de l'année écouléeLast commit or release 2026-11-13github.com/teocomyn/commerce-agent-protocol ↗Réussi
- OpenSSF ScorecardNon vérifié
- Nom du package non proche d'un package populaireNon vérifié
- Aucun avis critique dans le package ou ses dépendancesNon vérifié
- Aucune instruction cachée destinée au modèle0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersRéussi
- Les outils destructifs sont étiquetésNon vérifié
- Le point de terminaison distant répond à la poignée de main MCPNon vérifié
README
Voir sur GitHubWhy CAP?
Today, when an AI shopping agent reads a store, it gets what the storefront exposes: a title, a price, a few lines of description. Agents need thirty or more structured attributes to rank and recommend a product; most catalogs expose three to eight. The checkout rails now exist (Google and Shopify's UCP, Shopify Catalog, ChatGPT and Gemini shopping). The data they read is still poor.
CAP measures and fixes that. It ingests a merchant's catalog, enriches each product into typed attributes, scores how ready it is for agents and exposes the result the way an agent reads it, so the merchant sees and fixes what the rails see. The reference implementation is free (Apache-2.0); Shopify is the only supported platform today.
Until v0.2 CAP tried to be the checkout protocol between agents and merchants. Shopify now ships a UCP MCP per store and Google, OpenAI and Stripe own the rails, so CAP feeds them instead of competing with them. See ADR-0001.
What CAP gives you
| Pillar | What it does |
|---|---|
| 1. Catalog ingestion and structured enrichment | Shopify OAuth, bulk sync and webhooks feed a raw catalog; GPT structured output turns each product into typed attributes (materials, dimensions, certifications from merchant metafields, shipping, returns) with vector embeddings. |
| 2. Agent Readiness Score | computeGeoScore rates each product and catalog on what shopping agents need to read, rank and transact it. Published weights, per-attribute fixes and calibration on real catalogs are the next milestone (ADR-0001). |
| 3. Agent-facing read surface | /v1/search (semantic, vector) and /v1/compare (matrix) over REST and MCP (commerce_search, commerce_compare, same code and errors on both), used to check how an agent sees the catalog. /v1/checkout/initiate and commerce_checkout stay for compatibility and are no longer the product promise. |
This repository contains the reference implementation (this monorepo) and the original cap-spec/ JSON schema, kept as CAP's catalog format rather than as a standard for others to implement.
Architecture
Shopify ──► OAuth ──► Catalog sync (BullMQ)
│
▼
Postgres + pgvector ──► /v1/search (vector + filters)
│ /v1/compare
│ /v1/checkout/initiate (Cart API)
│
└─► MCP stdio and HTTP /mcp (commerce_search / compare / checkout)
│
▼
Claude · ChatGPT · Perplexity · Operator
Diagrams: cap_system_architecture_overview.svg · cap_data_flow_product_to_agent.svg
Quick start
Requirements: Node ≥ 22.12, pnpm ≥ 9, Docker.
# 1. Local Postgres (with pgvector) + Redis
docker compose up -d
# 2. Environment
cp .env.example .env
# Fill in at minimum: DATABASE_URL, REDIS_URL, OPENAI_API_KEY, ENCRYPTION_KEY,
# and SHOPIFY_* if you connect a store. Replace every `change_me` value: processes refuse to
# start with example secrets. Generate secrets with:
openssl rand -hex 32 # ENCRYPTION_KEY, CAP_OPERATIONS_TOKEN, DASHBOARD_SESSION_SECRET
# 3. Install + DB schema
pnpm install
pnpm db:generate
pnpm db:migrate # uses prisma migrate deploy
# 4. Run API + dashboard
pnpm dev
API on http://localhost:3000, dashboard on http://localhost:3001.
Workers (catalog sync + LLM enrichment) run as separate processes:
pnpm --filter=@cap/api dev:worker:enrichment
pnpm --filter=@cap/api dev:worker:catalog
Try the API:
# Live OpenAPI spec
curl http://localhost:3000/openapi.json | jq
# Search (after creating a CAP API key in the dashboard)
curl -X POST http://localhost:3000/v1/search \
-H "X-CAP-Key: cap_live_..." \
-H "Content-Type: application/json" \
-d '{"query":"white eco-friendly sneakers under 120","limit":3}'
Send an Idempotency-Key header on POST /v1/checkout/initiate: a retried request with the same key and body returns the first outcome (checkout or error) instead of creating a second Shopify cart. Keys are never released; to try again after a failure, use a new key.
Connect a remote MCP client (Streamable HTTP, any client that can send a custom header). The same tools are served at /mcp of a running API; the API key decides the merchant, as on the REST endpoints. Against the local API:
claude mcp add --transport http cap http://localhost:3000/mcp \
--header "Authorization: Bearer cap_live_..."
In Cursor's mcp.json: {"mcpServers": {"cap": {"url": "http://localhost:3000/mcp", "headers": {"Authorization": "Bearer cap_live_..."}}}}. Web connectors that require OAuth (for example Claude.ai custom connectors) are not supported, and no hosted endpoint exists today.
Run as a local MCP server (stdio, for Claude Desktop / Cursor):
CAP_MERCHANT_ID=<merchant-uuid> pnpm --silent -C apps/api mcp
stdout carries only JSON-RPC frames; logs go to stderr. Keep --silent and -C (not --filter), otherwise pnpm prints its script banner on stdout and breaks the MCP stream. The stdio server reads the database directly with ENCRYPTION_KEY, so run it only on a machine you trust with those credentials.
Repository layout
| Path | What lives here |
|---|---|
apps/api |
Hono API — OAuth, webhooks, search/compare/checkout, MCP server |
apps/dashboard |
Next.js 15 dashboard — merchant overview, products, API keys, human accounts and roles |
packages/db |
Prisma schema + migrations + client |
packages/shared |
Zod schemas, GEO score, utilities shared across packages |
cap-spec/ |
The CAP protocol specification (versioned, language-agnostic) |
.github/ |
Issue / PR templates, CI workflow, CODEOWNERS |
Status
CAP is alpha (v0.2.0-alpha, 2026-11-01). The ingestion, enrichment, scoring, search and checkout code runs end-to-end in tests and locally; nothing is deployed besides this site and no real merchant store has been connected yet. The project is pivoting to an agent-readiness score and catalog-quality tooling (ADR-0001); the /v1/checkout/initiate endpoint, the remote MCP server and cap-spec/ remain in the tree but are no longer the product promise. Breaking changes are expected before v1.0.
See the CHANGELOG for the full release history.
The deployable units are the API, the dashboard, the catalog worker and the enrichment worker, as separate services; none of them is deployed today (only this site is). See the dashboard authentication guide, staging runbook, Shopify E2E runbook, operations runbook, production deployment runbook, render.staging.yaml, and render.yaml.
Contributing
We welcome contributions of all sizes — from typo fixes to new platform adapters (WooCommerce, Salesforce Commerce, custom carts).
- Read the Contribution guide
- Check open issues labeled
good first issue - For protocol changes, open a Spec Proposal
By participating, you agree to abide by our Code of Conduct.
To report a security vulnerability, see SECURITY.md.
Community
- Discussions — GitHub Discussions
- Issues — GitHub Issues
- Security — private vulnerability report, see SECURITY.md
License
CAP is licensed under the Apache License 2.0 — including an explicit patent grant. The protocol itself is free to implement, fork, or embed.
Questions sur Commerce Agent Protocol MCP
Quelles plateformes sont prises en charge par CAP ?
Actuellement, Shopify est la seule plateforme prise en charge.
Comment CAP améliore-t-il les catalogues produits pour l'IA ?
Il ingère les catalogues, enrichit les produits en attributs typés via GPT et fournit un Agent Readiness Score pour mesurer la capacité des agents à classer et à effectuer des transactions sur les produits.