Minecraft ComputerCraft ME API — Backend

TypeScript backend that collects Minecraft ME system data pushed by a ComputerCraft computer and exposes it over HTTPS (REST) and WSS (live websocket feed).

This is the TypeScript rewrite of the original Rust/Axum + SQLite backend.

Stack

Fastify 5 — HTTP + WebSocket server. Chosen over Express/Nest because it has first-class WebSocket, JSON-schema validation and OpenAPI support built in, which keeps the project small for this scope.
PostgreSQL — runs in Docker via docker-compose.
@fastify/swagger + @fastify/swagger-ui — OpenAPI docs at /api/docs.
TypeBox — schemas used both for request validation and OpenAPI generation.
selfsigned — generates a self-signed TLS certificate on first start.

Data model

Two tables, mirroring the original design:

Table	Purpose
`me_system_live`	current contents — one row per item (`name` unique)
`me_system_history`	historic snapshots — references `me_system_live.id`

The mod of each item (the namespace before the : in minecraft:iron_ingot) is derived on ingest and stored on the live row so it can be filtered cheaply.

Quick start (Docker)

cp .env.example .env
docker compose up --build

This starts PostgreSQL and the backend. A self-signed certificate is generated into ./certs automatically.

Quick start (local dev)

cp .env.example .env          # adjust DATABASE_URL to your local Postgres
npm install
npm run dev

Accept the self-signed certificate

Because the certificate is self-signed, browsers reject it until trusted. Open https://localhost:3000/api/docs once and accept the warning — this also makes fetch and wss:// calls from the frontend work.

Endpoints

Method	Path	Description
`POST`	`/api/me-system/update`	Ingest a full snapshot (called by ComputerCraft)
`GET`	`/api/me-system/live`	Current contents — `search`, `mod`, `sort`, `order`
`GET`	`/api/me-system/mods`	Aggregated per-mod overview
`GET`	`/api/me-system/history`	History points for one item — `name`, `limit`
`GET`	`/api/health`	Health and runtime metrics
`WS`	`/api/ws/live`	Live data feed (see below)
`GET`	`/api/docs`	OpenAPI / Swagger UI

WebSocket protocol — `/api/ws/live`

On connect the server sends a snapshot message.
The client may send { "type": "setFilters", "filters": { "search": "iron", "mod": "minecraft", "sort": "amount", "order": "desc" } }.
The server replies with a fresh snapshot and keeps the filter for every later update message — so filters persist across data updates.
On every ingest the server pushes an update message to each client, with that client's filter already applied.

Message shape:

{ "type": "snapshot|update", "items": [...], "mods": [...], "filters": {...} }

Configuration

See .env.example. Key variables: PORT, DATABASE_URL, HISTORY_INTERVAL_SECONDS, TLS_ENABLED, CORS_ORIGIN.

ComputerCraft uploader

An example uploader script is provided in computercraft/me_uploader.lua. See the comment at the top of that file regarding the self-signed certificate.

Scripts

Command	Description
`npm run dev`	Watch-mode dev server (`tsx`)
`npm run build`	Compile TypeScript to `dist/`
`npm start`	Run the compiled server
`npm run typecheck`	Type-check without emitting

4.0 KiB Raw Blame History