Getting started

Get the A-Market backend running locally in a few minutes. For the architecture behind it, see Architecture; for the day-to-day commands, the Cheatsheet.

Requirements

• Node ≥ 24.16 and npm ≥ 11.16 (see engines in package.json).
• Docker + Docker Compose — for the full local stack (Postgres + Keycloak).
• Optional: jq for pretty-printing JSON in the examples.

Install

git clone https://github.com/ggcaponetto/redline.git
cd redline
npm install
npm run build      # tsc --build across the workspace

This is an npm-workspaces monorepo (ESM throughout) with three workspaces: packages/shared (domain schemas), apps/mcp-server (the backend), and apps/webapp (the SPA).

Run it — pick a mode

1. stdio (no auth, no database)

The fastest inner loop: an in-memory store, a fixed local principal, no Keycloak.

npm run dev:stdio -w @redline/mcp-server

Point a local MCP client (e.g. the MCP Inspector) at the process, or use it for development.

2. HTTP with full OAuth (Postgres + Keycloak)

The realistic setup: the Streamable-HTTP MCP endpoint + the REST API, behind Keycloak.

cp .env.example .env
docker compose up --build postgres keycloak mcp-server

• MCP endpoint: http://localhost:3000/mcp
• REST API: http://localhost:3000/v1
• Keycloak: http://localhost:8080 (test user dealer / dealer)
• Health: http://localhost:3000/healthz

3. The webapp

npm run dev -w @redline/webapp   # Vite dev server on :5173
# or run the HTTP server + webapp together:
npm run dev

Make your first call

# public read — no token
curl -s 'http://localhost:3000/v1/listings?limit=5' | jq

# get a token, then create a listing
TOKEN=$(curl -s http://localhost:8080/realms/redline/protocol/openid-connect/token \
  -d grant_type=password -d client_id=redline-mcp-client \
  -d username=dealer -d password=dealer \
  -d 'scope=openid listings:read listings:write' | jq -r .access_token)

curl -s -X POST http://localhost:3000/v1/listings \
  -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \
  -d '{"type":"car","make":"VW","model":"Golf","year":2020,"priceCents":1899000,"currency":"EUR","mileageKm":78500,"fuelType":"diesel","transmission":"manual","condition":"used"}' | jq

Verify the whole OAuth path end to end:

node scripts/auth-smoke.mjs http://localhost:3000 http://auth.localhost:8080

Next

• Cheatsheet — every command you'll use day to day.
• Features → code — what the platform does and where it lives.
• Testing — the test & hardening suite.
• MCP tools · REST API · Data models.