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