# DEVUP AI · MCP Sales Analytics Lab

![Ask your store: local MCP sales analytics with DEVUP AI](assets/01-cover.png)

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](article.md) · [Open the standalone article](article-preview.html) · [Inspect the captured output](examples/demo.json)

## Run without an API key

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

```bash
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.

## Reproduced results

![Actual local MCP results from the synthetic dataset](assets/03-results.png)

| Window | Total DZD | Delivered orders | Units |
| --- | ---: | ---: | ---: |
| October 1–7, 2026 | 9,000.00 | 2 | 4 |
| October 8–14, 2026 | 17,000.00 | 3 | 7 |

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

![Agent host, DEVUP AI API, local MCP server and read-only database](assets/02-architecture.png)

| Tool | Inputs | Output |
| --- | --- | --- |
| `describe_dataset` | Empty object | Coverage, synthetic status, metric definition |
| `sales_summary` | `start`, `end` | Exact monetary strings, orders, units, average |
| `compare_periods` | `previous`, `current` windows | Both summaries, absolute and percentage change |
| `top_products` | `start`, `end`, `limit` from 1–10 | Products ordered by delivered merchandise value |

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 definition and date conventions](assets/04-metric-contract.png)

- 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:

```bash
npm run live
```

Or supply a question:

```bash
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

| File | Responsibility |
| --- | --- |
| `src/contracts.mts` | Strict schemas, calendar dates, integer formatting |
| `src/setup.mts` | Validated synthetic fixture → SQLite |
| `src/analytics.mts` | Predefined read-only queries |
| `src/server.mts` | Four MCP tool registrations over stdio |
| `src/client.mts` | Explicit child environment and local MCP client |
| `src/demo.mts` | Deterministic integration demonstration |
| `src/live-agent.mts` | Real agent SDK and DEVUP AI configuration |
| `tests/analytics.test.mts` | Calculations and invalid inputs |
| `tests/mcp.test.mts` | Actual child-process MCP calls and SDK adapter |
| `tests/sdk.test.mts` | Real agent loop with mocked model HTTP |

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](assets/README.md). Code and original figures: [MIT](LICENSE).