DEVUP AI · MCP Sales Analytics Lab

Ask a store question, retrieve explicit aggregates, and explain the results through an optional DEVUP AI agent. This TypeScript lab includes a real local MCP server, a synthetic SQLite dataset, and a reproducible demonstration that needs no API key.

38 tests passed · Node.js 24.19.0 · Four local tools · Read-only analytics

Read the full tutorial · Open the standalone article · Inspect the captured output

Run without an API key

Use Node.js 24.19.0 and npm. Open a terminal in the project root:

npm ci
npm test
npm run typecheck
npm run setup
npm run demo

Read out/demo.json. The demo starts a real MCP child process, lists tools and retrieves aggregates. It makes no model requests. Setup creates data/store.sqlite once and refuses to overwrite it. For subsequent runs, skip setup. To reset your synthetic dataset, remove only that generated file and run setup again.

examples/demo.json is the captured local run. The full English tutorial is article.md; article-preview.html embeds its four images for convenient reading.

Related MCP server: pizza-analytics

Reproduced results

Change: 8,000.00 DZD / 88.89%. The current-window leaders by value are Desk lamp (7,500.00), Office chair (5,000.00), and Notebook set (4,500.00). These are synthetic fixture results, not business performance or a model benchmark.

Architecture

The fixed queries bind their inputs. There is no model-accessible SQL, shell, filesystem or write tool. The server opens SQLite with readOnly: true and enables query-only mode. Tool annotations describe behavior; local implementation enforces the available operations.

The demonstration and live host choose the child executable, arguments and dataset locally. For isolated integration tests, the server entry point also accepts an administrator-supplied database filepath as its first positional argument. That argument is not exposed through MCP.

Metric contract

• Metric: delivered_merchandise_total, calculated as quantity × unit price for orders with snapshot status delivered.

• Currency: DZD, stored as integer centimes; 100 centimes per DZD.

• Windows: start inclusive, end exclusive; calendar order dates, without inferred timestamp conversion.

• Coverage: [2026-10-01, 2026-10-15). Requests outside coverage fail.

• Comparisons: equal-length disjoint windows, previous before current. A zero baseline produces a null percentage.

• Cancelled and returned orders are excluded. Taxes, shipping, discounts, partial refunds, cash collection and profit are not modeled.

• The synthetic importer bounds input size and integer magnitudes. Do not replace it with an unbounded production import without revisiting aggregation limits and dataset metadata.

Optional live agent

Copy .env.example to .env, set your private DEVUP key and the exact current model ID supporting tool calling through Responses, then run:

npm run live

Or supply a question:

npm run live -- "Compare October 1–7, 2026 with October 8–14, 2026 and rank the top 3 products by value in the second window."

Live runs consume API balance. The SDK uses https://api.devupai.com/v1, disables trace export, requests store: false, disables retries, caps output at 2,000 tokens per model response, and bounds the run to six turns with a 90-second abort signal. These are work limits, not a guaranteed spend ceiling or a complete retention policy.

The local server receives no API key. In live mode, questions and aggregate outputs, including product names, are sent through the DEVUP AI API. The SQLite file remains local. No key is included. This exact live endpoint/model combination is unverified here.

Files and validation

Validated locally with Node.js 24.19.0: 38 tests passed, TypeScript checks passed, and the no-key demo completed. Model HTTP in the SDK test is mocked. This validates wiring and deterministic analytics, not live model quality. Review VALIDATION.md for scope.

This is a local single-dataset teaching project. A production or public HTTP service needs authenticated tenant context, enforced row scoping, database provenance/freshness, richer accounting definitions and deployment controls.

Publish the tutorial

Use article.md, not this README, as the article body. Follow PUBLISHING.md to upload figures and replace local companion links once you create the new repository. No future GitHub or DEV.to URL has been invented.

Original SVG sources and PNG exports are included in assets/. See asset provenance. Code and original figures: MIT.