Implementation proposal
ARCHIVE
Archived research / exploratory draft. Not the current implementation contract. Read REST 1.0 and the current concept.
Accepted architecture · 1 October 2026, option 2
Agentfy hosts the harness; Store Deputy API exposes the single MCP; the OpenCart module exposes a protected REST/JSON API. Store Deputy governs connections, actor/shopper context, permissions, approvals and audit without building another harness. Connect → login/register → secure pairing → automatic agent provisioning in Agentfy with Store Deputy MCP → return to the module. App contains teams, agents, account, billing and per-agent chat.
This replaces the earlier same-day direct-module-MCP design. Existing code and prototypes below do not implement the new integration. Shopper sessions and the real OpenCart cart have separate scoped bindings; cookies stay in the shop. See the accepted central MCP decision for boundaries, delivery stages and remaining contract work.
Target design, not existing Store Deputy architecture. None of the catalog, approval or job design below is built. What exists today — accounts, teams and connecting a store, on a developer's machine only — is described in Architecture. Agentfy source was inspected for possible reuse; no integration or end-to-end capability was verified.
Build a small commerce execution layer on Agentfy, with a versioned OpenCart connector and a deterministic job runner. Use the model to understand intent and explain exceptions; use ordinary code to validate and apply changes.
Proposed responsibility map
| Component | Responsibility | Boundary |
|---|---|---|
| Merchant workspace | Today, chat, review table, job receipt and connection controls | Never directly authorizes a platform mutation solely from model output |
| Agentfy platform | Candidate reuse for conversations, agent/tool execution, team secrets and scheduling | Reuse after contract/integration tests; do not recreate the platform here or move its code speculatively |
| Commerce domain | Store scope, identifier mappings, price semantics, proposals, approvals and outcomes | Owns the commercial meaning of a job |
| Execution service | Durable states, idempotency, conditional writes, retry/reconciliation and cancellation | Enforces authorized operations regardless of model instructions |
| OpenCart extension/connector | Authenticated, narrowly scoped operations against supported shop behavior | Preserves platform hooks and checks; does not expose arbitrary SQL or arbitrary admin execution |
| Operation ledger | Per-item intent, attempt, approval, verification and recovery evidence | Must be durable before writes begin |
Target flow: owner intent → structured proposal → policy validation → owner approval → connector execution → authoritative read-back → receipt. The model is not in charge of accounting for partial commits.
What the platform inspection supports
Agentfy contains an AgentMcpServer schema under agent/app, including team ownership, declared secret names, egress grants and cached tool discovery. Its runtime documentation describes task queue, worker and event responsibilities. These are reuse candidates found in source, not evidence that store-specific approvals, tenant separation, cancellation or commercial audit are complete.
The implementation spike must exercise a tool call with a dedicated test shop, revoked credentials, wrong-tenant access, timeouts and a background job resumed after worker loss. A schema or README cannot substitute for those tests. The app bundle of connector, skills and required credential names remains a packaging proposal.
OpenCart integration strategy
Prefer a small installed extension with a dedicated revocable credential and fixed operation schemas. Pin one release family using recruited stores, rather than promising “OpenCart compatible” across all versions and extensions. Inspect that version's actual APIs and hooks before choosing the implementation path. OpenCart's extension guide documents the extension mechanism; it does not prove a complete catalog-write API for our scope.
The shop-side contract is drafted as Bridge Protocol v1: one signed protocol, a small bridge per platform, and a capability manifest.
Proposed tools are store.describe, catalog.find, stock.read, order.status, price.prepare, price.apply and operation.get. These are proposed contract names, not existing endpoints. price.apply accepts a server-issued approved-job reference; it must not accept a fresh arbitrary price instruction from the model.
Use platform-supported data access and events. Do not automate admin-panel clicking as the default write mechanism and do not write raw SQL from an LLM. If a shop has custom price logic, options, customer-group pricing or a shared multi-store catalog, advertise the exact supported subset and block unsupported mutations.
Data contracts to settle first
StoreConnection: platform/version, supported capabilities, scope, currency, timezone, credential reference and last sync status.CatalogMapping: supplier identifier, shop product/option identifier, mapping provenance and ambiguity state. Never trust SKU uniqueness without checking it.ChangeProposal: immutable inputs, exact before/after values, decimal precision, tax/currency semantics, policy version and exclusions.Approval: actor, proposal hash/version, operation scope and expiry.JobItem: operation key, expected old state, attempt status, remote receipt, verified state and conflict reason.
Treat variant identifiers, tax-inclusive/exclusive amounts, customer groups, special-price dates and rounding as domain requirements. If inventory is owned by an ERP, a store read may not be the authoritative stock count. State which source and timestamp an answer represents.
Fit with CleanSlice
Consulted the CleanSlice MCP's dependency-flow guidance for this proposal. Group capabilities by business feature, with domain services depending on gateway interfaces and adapters mapping external records into domain types. Proposed feature areas are connection, catalog, proposal, approval and job. Final repository placement and code boundaries must be agreed during the platform spike; no new backend scaffold is implied by this document. The slices that exist today are described in API.
A future WooCommerce adapter must be checked against its current native MCP documentation: it is a developer preview, uses the WordPress MCP adapter, and documents the older Woo-specific endpoint as deprecated. Marketplace-plugin documentation can differ from core documentation; do not copy authentication assumptions across adapters.
Tests before real writes
Use controlled stores with fixtures covering duplicate/missing SKUs, locale-specific decimals, currencies, promotions, concurrent manual edits and extension behavior. Exercise crash-before-send, crash-after-send, duplicate delivery, expired approval, revoked access, cross-tenant access and malicious instructions inside a supplier file. Verify actual state changes, not just mocked tool success.
The pilot must include a demonstrated reconciliation and compensation flow. Deployment, model/provider choice, hosting location and retention are still decisions to make, not prerequisites to invent in documentation. See the roadmap.