Ecommerce Investigation Agent

A read-only ecommerce investigation prototype: query sales, inventory, promotions and advertising for an exact SKU, inspect source evidence, and produce constrained action drafts.

The business module can run independently as a CLI or stdio MCP server. A bundled investigation Skill supports integration with CraftAgents; the desktop application and model runtime are upstream dependencies and are not included here. Developed with AI assistance as a learning project.

Quick start

Tested with Bun 1.3.8. After cloning, enter the repository and run:

bun install --frozen-lockfile
bun run typecheck
bun test
bun run demo
bun run preview

Open http://127.0.0.1:4317/ to view eight cases. artifacts/report.html is also a self-contained generated report. The CLI and HTML demo do not call a model.

bun run investigate CUP-BLUE-500
bun run mcp

The MCP process speaks protocol on stdio; use a compatible client for model-driven investigation. See MCP setup.

Related MCP server: Acmezone Data MCP

Demonstrated case

All data is synthetic, fixed at 2026-10-12. The recent window is October 5–11, compared with September 28–October 4.

Stockout and sales decline overlap. Lower advertising conversion may share that explanation; these observations do not prove causality or establish that an ad creative caused the decline. Sample metrics are not business improvements achieved by this software.

Nine read-only tools

Reliability and verification

• Zod input contracts, exact SKU matching and equal complete windows.

• Evidence contains source, refresh date, window, row IDs and original rows.

• Missing, stale or conflicting data is exposed; unavailable metrics are null.

• Fixed-workflow call budget, timeout, cancellation and ordered JSONL events.

• Margin-constrained promotion suggestions and unexecuted action drafts.

• Eight synthetic SKU cases and 24 business/real-stdio-MCP tests. This is not an LLM accuracy benchmark.

See architecture and limitations, verification, and sample report.

Repository layout

src/             Domain, data queries, analysis, runtime, MCP and reports
tests/           Business cases, failure paths and real MCP integration
data/            Reproducible synthetic dataset
craft/           Source guide and investigation Skill
integrations/    Portable CraftAgents source and permission templates
examples/        Generated synthetic report examples
docs/            Architecture, setup and verification

Upstream and scope

This project originated as a business extension in a CraftAgents 0.11.4 checkout. It reuses the client's model execution, Skill loading, source discovery and permission checks when integrated. It does not claim to implement the upstream Agent platform.

Upstream: craft-ai-agents/craft-agents-oss. The upstream license and notice are retained in LICENSE and NOTICE.

No real shop or ad account is connected. No production outcome, autonomous business write, scheduled monitoring, RAG or independent LLM reviewer is claimed. Local accounts, credentials, conversations, course materials and monorepo build artifacts are not part of this repository.