Skip to content
Back to search

agentic-ebay-store

Autonomous eBay store ops: ERP MCP server wrapped in FastMCP, driven by durable Prefect flows with human-in-the-loop approval gates

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jeremiahcarreon--agentic-ebay-store/badge.svg)](/listings/jeremiahcarreon--agentic-ebay-store)

HTML

<a href="/listings/jeremiahcarreon--agentic-ebay-store"><img src="/api/listings/jeremiahcarreon--agentic-ebay-store/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 491 lines
  1. # agentic-ebay-store
  2. [![CI](https://github.com/jeremiahcarreon/agentic-ebay-store/actions/workflows/ci.yml/badge.svg)](https://github.com/jeremiahcarreon/agentic-ebay-store/actions/workflows/ci.yml)
  3. An eBay store run by an AI agent, built on **Prefect** and **FastMCP**.
  4. An existing production ERP MCP server ([Intunex](#connecting-the-real-intunex-erp), a Laravel
  5. MCP endpoint) is wrapped with a FastMCP proxy and combined with an eBay store MCP server into
  6. one gateway. A tool-using agent runs every part of the store (inventory, fulfilment, buyer
  7. messages, returns, reputation, pricing, promotions, listings and store health) through
  8. **durable Prefect flows**. Anything that touches buyers, money or listings goes through a
  9. deterministic **policy engine**. Above the autonomy threshold it also goes through a
  10. **human approval gate**, which suspends the run until someone decides.
  11. ---
  12. ## Contents
  13. 1. [In plain English](#in-plain-english)
  14. 2. [How it works](#how-it-works)
  15. 3. [What the agent does, flow by flow](#what-the-agent-does-flow-by-flow)
  16. 4. [Guardrails: policy, approvals, memory, audit](#guardrails-policy-approvals-memory-audit)
  17. 5. [Durability and reliability](#durability-and-reliability)
  18. 6. [The agent](#the-agent)
  19. 7. [The MCP gateway](#the-mcp-gateway)
  20. 8. [Interfaces: where people see and control it](#interfaces-where-people-see-and-control-it)
  21. 9. [Try it](#try-it)
  22. 10. [CLI reference](#cli-reference)
  23. 11. [Configuration](#configuration)
  24. 12. [Connecting the real Intunex ERP](#connecting-the-real-intunex-erp)
  25. 13. [eBay backends and current limits](#ebay-backends-and-current-limits)
  26. 14. [Roadmap](#roadmap)
  27. 15. [Project layout and development](#project-layout-and-development)
  28. ---
  29. ## In plain English
  30. Running an eBay store is a lot of small, repetitive jobs that never stop. You answer "where
  31. is my order?", copy tracking numbers into eBay, keep stock counts right so you don't oversell,
  32. deal with returns, reply to bad feedback, nudge prices and write listings. Most of these jobs
  33. need facts from the business system, such as what is actually in the warehouse, whether the
  34. order shipped and what the part fits.
  35. This project is a digital store assistant that does those jobs around the clock. It looks up
  36. the real facts in the business system first. Then it **suggests** what to do. Safe, routine
  37. changes (for example "eBay says 2 in stock, the warehouse says 14") happen automatically.
  38. Anything a customer will read, or anything that costs money, waits for a person to tap
  39. **approve**. Everything it does is written down so you can check its work later.
  40. ## How it works
  41. ```mermaid
  42. flowchart LR
  43. T[Schedules / events / autopilot] --> F
  44. subgraph F[Prefect flow run]
  45. direction LR
  46. R[read tasks<br/>persisted] --> P[agent plan<br/>persisted + cached]
  47. P --> Pol[policy engine<br/>LOW · MEDIUM · HIGH · BLOCKED]
  48. Pol --> G{approval gate<br/>suspend / resume}
  49. G -->|approved or within autonomy| X[execute<br/>idempotent, retried]
  50. end
  51. R -->|read-only| GW
  52. P -->|read-only + propose_action| GW
  53. X -->|write-enabled| GW
  54. subgraph GW[FastMCP gateway · audit + write-guard middleware]
  55. E1[erp_* · FastMCP proxy]
  56. E2[ebay_* · eBay store server]
  57. end
  58. E1 --> I[(Intunex ERP<br/>Laravel MCP /mcp/erp)]
  59. E2 --> S[(eBay simulator<br/>or Sell REST APIs)]
  60. G -. artifact + event + form .- H((Reviewer))
  61. ```
  62. Every flow follows the same five steps:
  63. 1. **Gather facts.** Read-only tasks call the gateway, for example "list paid eBay orders"
  64. and "find each one in the ERP". The results are persisted, so a resumed run sees exactly
  65. what the reviewer saw.
  66. 2. **Plan.** The agent gets the facts and an objective. It can call any *read* tool to
  67. investigate further, and it returns **proposals**. A proposal is a specific write tool,
  68. its exact arguments, a one-line rationale and the evidence it relied on.
  69. 3. **Assess.** The policy engine gives every proposal a risk level using fixed, tested
  70. rules. The agent never sets its own risk.
  71. 4. **Gate.** Blocked proposals are dropped. Proposals within the autonomy level go straight
  72. through. The rest wait for a person.
  73. 5. **Execute.** Approved proposals run through a separate write-enabled gateway. Each run is
  74. retried on network errors and recorded so it can never run twice. A results table is
  75. published to the Prefect UI.
  76. ## What the agent does, flow by flow
  77. Each domain is its own Prefect flow and deployment, with its own schedule, history and logs.
  78. ### `inventory-sync`: stock counts never drift (every 15 min)
  79. - **Reads:** active eBay listings, then ERP `check_stock` for all their SKUs in one call. ERP
  80. `available_to_sell` is already net of other customers' reservations, backorders and
  81. exchange holds.
  82. - **Proposes:** `ebay_update_quantity` wherever eBay and the ERP disagree. Listed quantity is
  83. capped at 25 to limit exposure if a sync is ever missed.
  84. - **Risk:** LOW when the number came from the ERP, so it runs automatically. Zeroing a best
  85. seller (10+ sold in 30 days) is MEDIUM, because it drops the listing out of search.
  86. ### `fulfillment-sync`: tracking gets to eBay (every 30 min)
  87. - **Reads:** paid, unshipped eBay orders. Each one is looked up in the ERP by eBay order id,
  88. and only exact matches count.
  89. - **Proposes:** `ebay_mark_shipped` with the ERP's carrier and tracking number when the ERP
  90. shows the order shipped. Orders with no ERP match are logged and nothing is made up.
  91. - **Risk:** LOW when the tracking came from the ERP. Any tracking number that can't be traced
  92. to the ERP is HIGH, because fake tracking damages seller metrics.
  93. ### `buyer-messages`: every question answered from real data (every 10 min, and on demand)
  94. - **Reads:** unanswered buyer messages. For each one it finds the ERP order (by order id, or
  95. by buyer username) and works out the SKU from the text or the listing. Then it pulls the
  96. product's specs, fitment and staff knowledge notes, plus stock and incoming purchase
  97. orders. It also reads how staff edited earlier drafts (`get_reply_feedback`), so replies
  98. match the house voice.
  99. - **Proposes:** `ebay_send_buyer_message` for each message. When something can't be
  100. confirmed, such as an uncertain fitment, it proposes `erp_ask_product_expert` and sends a
  101. holding reply instead of guessing.
  102. - **Examples:** "Where is my order?" gets the carrier and tracking number. "Does RAD-259 fit
  103. my 1966 Mustang?" gets the catalogued fitment, plus the restock date from the incoming PO
  104. if the part is out of stock.
  105. - **Risk:** MEDIUM (customer-facing), so it needs approval by default. Promising a refund,
  106. replacement or compensation is HIGH. Mentioning cost, margin or wholesale is BLOCKED.
  107. - **Event trigger:** when `store-health` reports unanswered messages, this deployment starts
  108. immediately instead of waiting for its schedule.
  109. ### `returns-desk`: returns decided with evidence (hourly)
  110. - **Reads:** open return requests, the eBay order (for its age) and the ERP order (for
  111. fulfilment stage and tracking).
  112. - **Proposes:** accept seller-fault returns (damaged, defective, not as described, wrong
  113. item) and then refund. Other returns are accepted inside the 30-day window. A decline is
  114. proposed only with a stated reason.
  115. - **Risk:** accepting is MEDIUM and declining is HIGH (case escalations hurt the defect
  116. rate). Refunds over $75 (configurable) are HIGH. A refund can only run after its return is
  117. accepted, so rejecting the acceptance also stops the refund.
  118. ### `reputation`: feedback handled (daily 09:00)
  119. - **Proposes:** positive feedback for buyers on delivered orders that don't have any yet
  120. (LOW). Also one calm, factual public reply to each unanswered negative feedback, which
  121. mentions the accepted return if there is one and promises nothing more (HIGH, because eBay
  122. allows exactly one permanent reply).
  123. ### `pricing`: small, defensible price moves (daily 06:00)
  124. - **Reads:** price, stock and 30-day views, watchers and sales for each active listing, plus
  125. the ERP list price and dealer tier prices. SKUs already in a promotion are skipped.
  126. - **Rules (used when no LLM is available):**
  127. - Less than 7 days of stock left at the current sales rate: **+5%**.
  128. - Watchers are at least 2% of views but conversion is under 1.5%: **−4%**, to turn
  129. watchers into buyers.
  130. - More than 10% above the ERP list price: **back to list**.
  131. - Out-of-stock listings are left alone, and prices are rounded to .95.
  132. - **Price floor:** the *highest* dealer tier price. Retail on eBay must never undercut what
  133. dealers pay, and anything below the floor is BLOCKED.
  134. - **Risk:** moves of 5% or less are LOW, up to 15% are MEDIUM, and anything larger is HIGH.
  135. ### `promotions`: clear slow stock (Mondays 07:00)
  136. - **Proposes:** at most one markdown sale that groups slow movers (more than 180 days of
  137. stock and at least 10 units), 10% off for 14 days. Items that already have a promotion are
  138. skipped, so re-runs do nothing.
  139. - **Risk:** markdowns up to 15% are MEDIUM, deeper ones are HIGH. The store itself rejects
  140. anything outside eBay's 5–80% range.
  141. ### `listing-builder`: drafts become complete listings (daily 06:30)
  142. - **Reads:** draft listings, plus each part's ERP product record (specs, fitment, knowledge
  143. notes) and its stock.
  144. - **Proposes:** `ebay_upsert_listing` with a keyword-rich title of 80 characters or less, an
  145. HTML description (specs, every fitting vehicle, staff notes), item specifics, the ERP list
  146. price and a stock-capped quantity. It then proposes `ebay_publish_listing`. Parts that are
  147. out of stock are skipped.
  148. - **Risk:** publishing is HIGH, so a person approves every new live listing. Approved
  149. publishes run in a **transaction**: if publishing fails, the listing is restored exactly as
  150. it was.
  151. ### `store-health`: the scoreboard (hourly)
  152. - Publishes the store KPIs as Prefect artifacts: active listings, stock-outs, orders waiting
  153. to ship, unanswered messages, open returns, feedback score, 30-day sales and conversion.
  154. - Emits an `ebay.store.kpi.breached` event for each KPI outside its threshold:
  155. - unanswered messages > 0
  156. - orders waiting to ship > 5
  157. - out-of-stock listings > 0
  158. - open returns > 2
  159. - feedback score < 98%
  160. Automations can page someone or start a fix flow from these events.
  161. ### `store-autopilot`: everything, in order (on demand)
  162. - Runs inventory → fulfilment → messages → returns → reputation → pricing → promotions →
  163. listings → health.
  164. - Each domain is isolated, so one failure is recorded and the rest still run.
  165. - With `use_deployments=True` it starts each domain's *deployment* instead. Every domain can
  166. then wait at its own gate without holding anything up.
  167. ## Guardrails: policy, approvals, memory, audit
  168. ### Risk levels
  169. | Level | Meaning | Default handling |
  170. |---|---|---|
  171. | LOW | Mechanical, ERP-backed, reversible | Executes automatically |
  172. | MEDIUM | Customer-facing or commercial, within policy | Waits for a person (or automatic if autonomy is raised to MEDIUM) |
  173. | HIGH | Money out, permanent or public, or big moves | Always waits for a person |
  174. | BLOCKED | Against policy | Never executes; recorded |
  175. ### Policy rules (`src/ebay_agent/policy.py`)
  176. | Action | Rule |
  177. |---|---|
  178. | Update quantity | LOW if from ERP; MEDIUM if not, or if zeroing a best seller |
  179. | Update price | LOW ≤5%, MEDIUM ≤15%, HIGH >15%, **BLOCKED below dealer floor** |
  180. | Mark shipped | LOW with ERP tracking, else HIGH |
  181. | Send buyer message | MEDIUM; HIGH if it promises refund/replacement/compensation; **BLOCKED if it mentions cost/margin/wholesale** |
  182. | Accept / decline return | MEDIUM / HIGH |
  183. | Issue refund | MEDIUM up to $75, else HIGH |
  184. | Upsert listing | MEDIUM; **BLOCKED if title > 80 chars** |
  185. | Publish / end listing | HIGH |
  186. | Leave buyer feedback | LOW |
  187. | Respond to feedback | HIGH (permanent and public) |
  188. | Markdown promotion | MEDIUM ≤15%, else HIGH |
  189. | ERP draft reply / ask product expert | LOW (a person reviews these in the ERP anyway) |
  190. | Anything unrecognised | HIGH |
  191. All thresholds can be set with environment variables (`EBAY_AGENT_POLICY__*`).
  192. ### Approval gates (`src/ebay_agent/workflow/approvals.py`)
  193. When proposals need a person, the gate:
  194. 1. Publishes an **"Approval needed" artifact**: a table of every pending proposal with its
  195. id, risk badge, exact action, rationale and evidence.
  196. 2. Emits `ebay.agent.approval.requested`, which a Prefect Automation can route to Slack,
  197. email or SMS.
  198. 3. **Suspends** the run (inside a deployment) or pauses it (ad-hoc run) and waits for a
  199. **ReviewDecision** form: *approve all*, or a list of approved ids, plus reviewer name and
  200. a note. Anything not approved is rejected.
  201. 4. Emits `ebay.agent.approval.decided` and records the decision.
  202. If nobody answers within 24 hours (configurable), the gate rejects everything.
  203. `EBAY_AGENT_APPROVAL_MODE=auto` lets policy decide alone (demos). `deny` rejects
  204. everything that needs a person, so only LOW-risk changes run.
  205. ### Reviewer memory (`src/ebay_agent/workflow/decisions.py`)
  206. Every decision is appended to `decisions.jsonl`, and the agent learns from it in two ways:
  207. - Recent decisions and reviewer notes for the domain are added to its context, for example
  208. *"check transmission type before confirming fitment"*.
  209. - A change a person rejected in the last 7 days is **not proposed again**, so a 10-minute
  210. schedule doesn't keep showing the reviewer the same thing.
  211. ### Audit trail
  212. - `audit.jsonl` holds every gateway tool call: time, session (agent / executor /
  213. external), tool, arguments, success or failure, and latency.
  214. - Prefect keeps every flow run, task run, log line, artifact and event.
  215. ## Durability and reliability
  216. | Concern | Mechanism |
  217. |---|---|
  218. | Waiting hours for a human without holding a server | Deployment runs **suspend** at the gate. Resuming re-runs the flow and every finished step loads its saved result. |
  219. | Resuming must not re-ask the model and get a different answer | The plan task is persisted and cached per flow run, and the reads are too. A resumed run reaches the **same** gate key and receives the submitted decision. |
  220. | Nothing executes twice | Proposal ids are content hashes, and execution is cached per *flow run + proposal id*. Simulator writes are idempotent. |
  221. | Half-done listing changes | Prefect **transaction** with an `on_rollback` hook that restores the pre-change listing. |
  222. | Flaky networks / API hiccups | Reads retry 1s/5s/15s and writes retry 2s/10s/30s, with jitter. Business errors (for example "order not paid") fail fast without retrying. |
  223. | eBay rate limits | Global concurrency limit `ebay-store-writes` across all runs and workers. Each deployment also has `concurrency_limit=1`. |
  224. | One area failing | The autopilot isolates each domain flow. |
  225. This was verified against a live Prefect server. A served `buyer-messages` run suspended at
  226. its gate and released its process. After approval it resumed with every ERP read and the
  227. agent plan in state `Cached`, the gate returned the decision, and each reply was sent
  228. exactly once:
  229. ```
  230. Flow run 'curly-oryx' - Suspending flow run, execution will be rescheduled when this flow run is resumed.
  231. ... reviewer approves ...
  232. Task run 'read erp_find_order' - Finished in state Cached(type=COMPLETED)
  233. Task run 'plan messages' - Finished in state Cached(type=COMPLETED)
  234. Flow run 'curly-oryx' - Gate 'Buyer messages': 2 approved, 0 rejected by jeremiah
  235. Task run 'execute ebay_send_buyer_message' - Executed ebay_send_buyer_message(reply_to_message_id='MSG-1001', ...)
  236. Flow run 'curly-oryx' - Finished in state Completed()
  237. ```
  238. ## The agent
  239. Two interchangeable planners produce the same kind of proposals, and both are governed the
  240. same way.
  241. - **LLM planner** (`agent/llm.py`) is used when Anthropic credentials are available. It runs
  242. a Messages API tool-use loop with adaptive thinking and configurable effort. It is offered
  243. **only the read tools** on the gateway plus `propose_action`, which only accepts the write
  244. tools allowed for that task. Its system prompt sets the rules: look things up before
  245. acting, never guess stock, ship dates, tracking or fitment, never mention cost or margin,
  246. never promise refunds, and ask the product expert when unsure. Refusals, `pause_turn` and
  247. turn limits are handled, and oversized tool results are trimmed.
  248. - **Rule-based planners** (`@heuristic` functions in each flow) are used when there is no
  249. LLM, for example in CI, offline demos or a provider outage. The whole store still runs.
  250. Every plan publishes an artifact listing what the agent looked at and what it proposed.
  251. ## The MCP gateway
  252. One FastMCP server with two namespaces and 33 tools:
  253. - **`erp_*`** comes from the Intunex ERP through a FastMCP proxy: `find_order`, `get_order`,
  254. `check_stock`, `get_pricing`, `lookup_product`, `find_fitment`, `suggest_fan_pairing`,
  255. `search_product_knowledge`, `get_ebay_context`, `get_reply_feedback`, `draft_ebay_reply`,
  256. `ask_product_expert`.
  257. - **`ebay_*`** is the store server.
  258. - Reads: `list_listings`, `get_listing`, `list_orders`, `get_order`,
  259. `list_buyer_messages`, `list_returns`, `list_feedback`, `list_promotions`,
  260. `store_metrics`.
  261. - Writes: `upsert_listing`, `publish_listing`, `end_listing`, `update_price`,
  262. `update_quantity`, `mark_shipped`, `send_buyer_message`, `decide_return`,
  263. `issue_refund`, `leave_buyer_feedback`, `respond_to_feedback`,
  264. `create_markdown_promotion`.
  265. - Resource: `ebay://store/metrics`.
  266. Every tool is tagged `read` or `write` and carries MCP annotations (`readOnlyHint`,
  267. `destructiveHint`). The **write guard** middleware refuses writes on a read-only gateway.
  268. Upstream tools that don't declare themselves read-only are treated as writes.
  269. ## Interfaces: where people see and control it
  270. | Interface | Who | What for |
  271. |---|---|---|
  272. | **Prefect UI** (`:4200`, or Prefect Cloud) | Owner, reviewers | Dashboard of every run, schedule, log and artifact. Approval requests appear as paused or suspended runs with a review table and form. KPI tables from `store-health`. |
  273. | **`ebay-agent` CLI** | Operators | Run flows, list pending approvals, approve or reject, check KPIs. |
  274. | **MCP gateway** (stdio or HTTP `/mcp`) | Any MCP-capable chat app or agent | Ask questions about the store in a chat window. It is read-only by default. |
  275. No chat window is needed: the flows run on their own schedules. A dedicated store-owner web
  276. dashboard is on the [roadmap](#roadmap).
  277. ## Try it
  278. Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).
  279. ```bash
  280. git clone https://github.com/jeremiahcarreon/agentic-ebay-store && cd agentic-ebay-store
  281. uv sync
  282. ```
  283. **1. Watch it run the whole store (auto-approved, about 25 seconds):**
  284. ```bash
  285. uv run ebay-agent seed --reset
  286. uv run ebay-agent status # KPIs before
  287. uv run ebay-agent run autopilot --simulate --approval auto
  288. uv run ebay-agent status # KPIs after
  289. ```
  290. **2. Be the human in the loop:**
  291. ```bash
  292. uv run prefect server start # terminal 1 → http://127.0.0.1:4200
  293. uv run ebay-agent seed --reset && uv run ebay-agent serve # terminal 2
  294. uv run prefect deployment run buyer-messages/buyer-messages # terminal 3
  295. uv run ebay-agent pending # shows the suspended run
  296. ```
  297. Open the run in the UI, read **Approval needed**, then resume it with the form. You can also
  298. use the terminal:
  299. ```bash
  300. uv run ebay-agent approve <flow-run-id> --ids <proposal-id> --reviewer you --note "looks good"
  301. ```
  302. **3. Cautious mode (only LOW-risk changes run; everything else is listed and rejected):**
  303. ```bash
  304. uv run ebay-agent run pricing --approval deny
  305. ```
  306. **4. Use the real AI planner:** set `ANTHROPIC_API_KEY`, then repeat any of the steps above.
  307. **5. Chat with the store from an MCP client:** add `uv run ebay-agent mcp` (stdio) to your
  308. client, or run `docker compose up` and point it at `http://localhost:8765/mcp`.
  309. ## CLI reference
  310. | Command | What it does |
  311. |---|---|
  312. | `ebay-agent run <flow> [--approval prefect\|auto\|deny] [--simulate]` | Run one flow now. Flows: `autopilot`, `inventory`, `fulfillment`, `messages`, `returns`, `reputation`, `pricing`, `promotions`, `listings`, `health`. |
  313. | `ebay-agent serve` | Serve every deployment (schedules, triggers, durable gates). |
  314. | `ebay-agent mcp [--transport stdio\|http] [--allow-writes]` | Serve the gateway. Read-only unless `--allow-writes` is passed. |
  315. | `ebay-agent seed [--reset]` | Create or reset the simulator store. |
  316. | `ebay-agent simulate [--seed N]` | Inject buyer activity (orders, questions). |
  317. | `ebay-agent status` | Print store KPIs. |
  318. | `ebay-agent pending` | List runs waiting for approval. |
  319. | `ebay-agent approve <run> --all \| --ids a,b [--reviewer] [--note]` | Approve and resume. |
  320. | `ebay-agent reject <run> [--reviewer] [--note]` | Reject everything pending and resume. |
  321. ## Configuration
  322. All settings are environment variables (prefix `EBAY_AGENT_`, nested with `__`). Every one
  323. is optional, and the defaults run fully offline.
  324. | Variable | Default | Meaning |
  325. |---|---|---|
  326. | `EBAY_AGENT_ERP_BACKEND` | `mock` | `mock` or `remote` (real Intunex endpoint) |
  327. | `EBAY_AGENT_INTUNEX_MCP_URL` | `http://localhost/mcp/erp` | Intunex MCP endpoint |
  328. | `EBAY_AGENT_INTUNEX_TOKEN` | – | Sanctum token, sent as `Authorization: Bearer` |
  329. | `EBAY_AGENT_EBAY_BACKEND` | `simulator` | `simulator`, `sandbox` or `production` |
  330. | `EBAY_AGENT_EBAY_CLIENT_ID` / `_CLIENT_SECRET` / `_REFRESH_TOKEN` | – | eBay OAuth (REST backends) |
  331. | `ANTHROPIC_API_KEY` | – | Turns on the LLM planner; without it the rule-based planners run |
  332. | `EBAY_AGENT_ANTHROPIC_MODEL` | `claude-opus-5-5` | Planner model |
  333. | `EBAY_AGENT_AGENT_EFFORT` | `medium` | Planner effort (`low` … `max`) |
  334. | `EBAY_AGENT_USE_LLM` | `true` | Set to `false` to force the rule-based planners |
  335. | `EBAY_AGENT_APPROVAL_MODE` | `prefect` | `prefect` (human), `auto` (policy only), `deny` (LOW-risk only) |
  336. | `EBAY_AGENT_APPROVAL_TIMEOUT_SECONDS` | `86400` | Unanswered gates reject after this |
  337. | `EBAY_AGENT_POLICY__AUTO_APPROVE_UP_TO` | `1` (LOW) | Autonomy level: `2` also runs MEDIUM automatically |
  338. | `EBAY_AGENT_POLICY__MAX_AUTO_REFUND` | `75` | Refunds above this are HIGH |
  339. | `EBAY_AGENT_POLICY__SMALL_PRICE_CHANGE_PCT` / `__LARGE_PRICE_CHANGE_PCT` | `5` / `15` | Pricing risk bands |
  340. | `EBAY_AGENT_POLICY__MAX_AUTO_MARKDOWN_PCT` | `15` | Deeper markdowns are HIGH |
  341. | `EBAY_AGENT_DATA_DIR` | `.data` | Simulator state, `audit.jsonl`, `decisions.jsonl` |
  342. ## Connecting the real Intunex ERP
  343. Intunex exposes its ERP to AI assistants as a Laravel MCP server. It has twelve tools,
  344. Sanctum auth and per-tool permission checks, and its writes are drafts a person approves.
  345. None of it is re-implemented here:
  346. ```python
  347. upstream = Client(settings.intunex_mcp_url, auth=token) # Authorization: Bearer <token>
  348. erp = create_proxy(upstream, name="Intunex ERP") # a local FastMCP server
  349. gateway.mount(erp, namespace="erp") # erp_find_order, erp_check_stock, ...
  350. ```
  351. To connect it, set `EBAY_AGENT_ERP_BACKEND=remote`, the URL and a token. Laravel MCP's
  352. `#[IsReadOnly]` becomes `readOnlyHint`, which the gateway uses to classify upstream tools.
  353. The bundled mock reproduces the same tool names, arguments and response shapes, so
  354. everything runs without ERP access.
  355. ## eBay backends and current limits
  356. - **Simulator (default):** a JSON-persisted store with realistic seed data. It enforces
  357. eBay's rules (publish needs a title and price, markdowns must be 5–80%, one feedback
  358. response, refunds only after acceptance) and makes writes idempotent.
  359. - **Sell REST APIs** (`EbayRestStore`):
  360. - OAuth refresh with token caching.
  361. - Inventory API (items, offers, publish/withdraw, bulk price/quantity).
  362. - Fulfillment API (orders, shipping fulfilments).
  363. - Post-Order API (returns, decisions, refunds).
  364. - Marketing API (markdowns).
  365. So far it has been tested against recorded wire shapes, not a live sandbox account.
  366. - **Not yet implemented:** buyer messaging and feedback exist only in eBay's XML **Trading
  367. API**. Those methods raise an error naming the Trading call to implement. Store metrics
  368. are derived from listings and orders rather than the Analytics API.
  369. ## Roadmap
  370. 1. **Live wiring:** eBay sandbox account and Trading API messaging/feedback, live Intunex
  371. token, eBay notification webhooks (new order or message → run the flow immediately).
  372. 2. **Quality scoring:** a fast, cheap "judge" model grades every proposal and every executed
  373. reply (accuracy against ERP facts, tone, policy compliance, helpfulness), stores the
  374. score next to the reviewer's decision, and tracks approval rate and edit rate per domain
  375. over time.
  376. 3. **Earned autonomy:** when a domain's quality score and approval rate stay high for N
  377. weeks, raise its autonomy level automatically (for example, routine "where's my order"
  378. replies stop needing approval).
  379. 4. **Store-owner dashboard:** a simple login page with today's work, an approval inbox with
  380. one-tap approve/edit/reject from a phone, KPIs and quality trends. It would sit on the
  381. Prefect API.
  382. 5. **Multi-store / multi-tenant:** one deployment per seller account, with their own
  383. credentials and policy settings.
  384. 6. **True dry-run mode:** plan and gate everything but execute nothing, for onboarding a new store.
  385. 7. **Smarter pricing:** competitor and sold-listing data, and price tests with measured
  386. results.
  387. ## Project layout and development
  388. ```
  389. src/ebay_agent/
  390. config.py typed settings (pydantic-settings)
  391. policy.py Proposal, RiskAssessment, PolicyEngine
  392. ebay/ domain models, EbayStore port, simulator, Sell REST client
  393. mcp/
  394. ebay_server.py eBay store as a FastMCP server (tagged + annotated tools)
  395. intunex.py FastMCP proxy to the Intunex ERP MCP endpoint
  396. intunex_mock.py offline ERP with the identical tool surface
  397. gateway.py composed gateway + audit and write-guard middleware
  398. agent/ LLM planner, rule-based planners, persisted `plan` task
  399. workflow/ gateway client, approval gates, governed execution, decision memory
  400. flows/ one flow per store domain + autopilot + health
  401. deployments.py schedules, triggers, concurrency limits
  402. cli.py `ebay-agent` command
  403. tests/ unit tests + end-to-end flow runs on a throwaway Prefect server
  404. ```
  405. ```bash
  406. uv run pytest -q # 61 tests, fully offline
  407. uv run ruff check src tests && uv run ruff format --check src tests
  408. uv run mypy src
  409. docker compose up --build # Prefect UI :4200, agent, gateway :8765/mcp
  410. ```
  411. MIT licensed.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.