Skip to main content
Glama

ProductSafetyEngine

TypeScript Node.js Vitest License: MIT

High-Performance B2B Data Engine & Model Context Protocol (MCP) Server für EU-Produktsicherheits- und Rückrufdaten (Safety Gate / RAPEX & REACH Chemical Recall Screening).


Inhaltsverzeichnis

  1. Überblick & Kontext

  2. Gesamtarchitektur

  3. Package- & Workspace-Übersicht

  4. Kernfunktionen

  5. Schnellstart & Lokales Setup

  6. MCP Server Konfiguration

  7. Apify Actor & Pay-Per-Event (PPE)

  8. Testing & Qualitätssicherung

  9. Compliance & Rechtliches


Related MCP server: deeprecall-mcp

Überblick & Kontext

Mit Inkrafttreten der europäischen Verordnung über die allgemeine Produktsicherheit (GPSR – EU 2023/988) und der Marktüberwachungsverordnung (EU 2019/1020) stehen Online-Händler, Importeure, Marktplätze und Fulfilment-Dienstleister unter strikter Sorgfaltspflicht: Produkte mit bekannten Sicherheitsmängeln, Produktrückrufen oder verbotenen chemischen Inhaltsstoffen (REACH/SVHC) dürfen im EU-Binnenmarkt weder vertrieben noch gelagert werden.

ProductSafetyEngine schließt die Brücke zwischen behördlichen Rohdaten-Veröffentlichungen der Europäischen Kommission und modernen B2B-Systemen sowie autonomen KI-Agenten:

  • Automatisiertes Ingestion-System: Parst, bereinigt und normalisiert offizielle Safety-Gate-Meldungen (RAPEX).

  • Strikte GTIN/EAN-Validierung: Prüft EAN-8, EAN-13, UPC-A und UPC-E mittels Modulo-10-Algorithmus.

  • Hybride Storage-Architektur: Schnelle In-Memory-Verarbeitung oder persistente Speicherung via node:sqlite.

  • Model Context Protocol (MCP): 5 spezialisierte Agenten-Tools mit integriertem Prompt-Injection-Schutz und HTTP 402 Vorbereitung (Stripe Machine Payments Protocol).

  • Apify Actor Integration: Cloud-native Bereitstellung mit granularem Pay-Per-Event (PPE) Abrechnungsmodell.


Gesamtarchitektur

                          ┌────────────────────────────────────────┐
                          │  EU Safety Gate (RAPEX) / REACH Data   │
                          │        (Official XML / JSON)           │
                          └───────────────────┬────────────────────┘
                                              │
                                              ▼
                                 ┌─────────────────────────┐
                                 │    packages/fetcher     │
                                 │  • Rate-Limiter (1 r/s) │
                                 │  • ETag / Caching       │
                                 │  • robots.txt TDM Guard │
                                 └────────────┬────────────┘
                                              │
                                              ▼
                                 ┌─────────────────────────┐
                                 │      packages/core      │
                                 │  • Fast XML Parser      │
                                 │  • Zod AlertRecordSchema│
                                 │  • Modulo-10 GTIN Check │
                                 │  • SQLite & Memory DB   │
                                 └──────┬───────────┬──────┘
                                        │           │
                     ┌──────────────────┴───┐   ┌───┴──────────────────┐
                     ▼                      │   │                      ▼
         ┌───────────────────────┐          │   │          ┌───────────────────────┐
         │      apps/actor       │          │   │          │       apps/mcp        │
         │  • Apify Actor CLI    │          │   │          │  • Stdio MCP Protocol │
         │  • Input/Dataset Zod  │          │   │          │  • Prompt-Sanitizer   │
         │  • Pay-Per-Event (PPE)│          │   │          │  • 5 Specialized Tools│
         │    Accounting Engine  │          │   │          │  • HTTP 402 Gate (MPP)│
         └───────────────────────┘          │   │          └───────────────────────┘
                     │                      │   │                      │
                     ▼                      │   │                      ▼
         ┌───────────────────────┐          │   │          ┌───────────────────────┐
         │      Apify Store      │          │   │          │ Claude / Cursor /     │
         │    REST / Webhooks    │          │   │          │ AI Agent Workflows    │
         └───────────────────────┘          │   │          └───────────────────────┘

Package- & Workspace-Übersicht

Das Projekt ist als npm Workspace-Monorepo organisiert:

Pfad

Typ

Name

Zweck

packages/core

Bibliothek

@productsafetyengine/core

Parsen von Safety-Gate XML, Zod-Schemas, EAN-Validierung, Speicher-Engines (node:sqlite, Memory).

packages/fetcher

Bibliothek

@productsafetyengine/fetcher

HTTP-Client mit Rate-Limiting, Exponential Backoff, ETag-Handling und robots.txt TDM-Prüfung.

apps/actor

Anwendung

@productsafetyengine/actor

Apify Actor für Batch-Überprüfungen im Apify Store mit Pay-Per-Event (PPE) Abrechnung.

apps/mcp

Anwendung

@productsafetyengine/mcp

Offizieller MCP-Server (stdio) für LLM-Agenten (Claude, Cursor, Antigravity) mit Security-Sanitizer.


Kernfunktionen

1. packages/core

  • XML-Parsing: Robuste Extraktion von Attributen, CDATA-Blöcken und Namespaces aus offiziellen RAPEX-Dateien.

  • Typisiertes Zod-Schema (AlertRecordSchema):

    • alert_number, case_number, publication_date, category, product, brand, model

    • ean_barcodes: Bereinigte Liste von EANs ohne Steuerzeichen und Trennstriche

    • risk_type, danger_description, measures, notifying_country, country_of_origin, risk_level

  • GTIN/EAN-Validierung (isValidEan): Exakte Modulo-10-Prüfziffernberechnung für EAN-8, EAN-13, UPC-A und UPC-E.

  • Storage-Interface (IAlertStorage):

    • MemoryAlertStorage: In-Memory-Map für höchste Durchsatzraten und Tests.

    • SqliteAlertStorage: Persistente Speicherung auf Basis von Node 22 nativem node:sqlite.

2. packages/fetcher

  • Gentle Crawling: Fest verdrahtetes Rate-Limiting (max. 1 Request pro Sekunde).

  • Bandbreitenschonend: ETag- und If-None-Match-Unterstützung (304 Not Modified).

  • Legal Compliance: Automatischer Vorab-Check auf robots.txt-Ausschlüsse und TDM-Vorbehalte gemäß § 44b UrhG.

3. apps/actor

  • Apify Actor Spezifikation: Vollständige Konfiguration via .actor/actor.json, .actor/input_schema.json und dataset_schema.json.

  • Pay-Per-Event Engine (ppe.ts): Präzise Erfassung und Abrechnung pro Ereignis (ean-checked, alert-returned, query-executed, weekly-monitored).

4. apps/mcp

  • Offizieller MCP Stdio Transport: Basiert auf @modelcontextprotocol/sdk.

  • Sicherheits-Sanitizer: Filtert Prompt-Injections, Steuerzeichen und gefährliche Escape-Sequenzen.

  • Die 5 Agenten-Tools:

    1. check_ean_safety: EAN-Prüfung gegen die Datenbank mit ZWINGENDEM Sicherheits-Disclaimer bei 0 Treffern.

    2. screen_children_products: Gezielte Erkennung von Spielzeug-, Baby- und Kindergefahren (Erstickung, PFAS/Phthalate, Magnete).

    3. search_product_recalls: Freitext- und Kategoriesuche nach Marke, Modell und Gefahrenart.

    4. get_chemical_restrictions: Gezielte Filterung nach chemischen Gefahren (REACH, Phthalate, Blei, Cadmium, SVHC).

    5. monitor_weekly_alerts: Abfrage der neuesten wöchentlichen Sicherheitsberichte.

  • PaymentGate (payment.ts): Vorbereitetes Interface für HTTP 402 / Stripe Machine Payments Protocol (MPP).


Schnellstart & Lokales Setup

Voraussetzungen

  • Node.js: >= 22.0.0

  • npm: >= 10.0.0

Installation

# Repository klonen
git clone https://github.com/thartmannsgruber-ai/ProductSafetyEngine.git
cd ProductSafetyEngine

# Abhängigkeiten im Monorepo installieren
npm install

Build & Typecheck

# TypeScript-Prüfung über alle Workspaces
npm run typecheck

Tests ausführen

# Alle Tests (100% offline gegen Fixtures) ausführen
npm test

# Nur Core-Tests ausführen
npm test -w packages/core

# Nur MCP-Tests ausführen
npm test -w apps/mcp

MCP Server Konfiguration

Der MCP-Server kommuniziert über stdio und kann direkt in MCP-Clients (z. B. Claude Desktop, Cursor oder Antigravity) eingebunden werden.

Einbindung in Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "product-safety": {
      "command": "node",
      "args": [
        "/absolute/path/to/ProductSafetyEngine/apps/mcp/dist/index.js"
      ],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Entwicklungsmodus via tsx

npx tsx apps/mcp/src/index.ts

Apify Actor & Pay-Per-Event (PPE)

Der Actor in apps/actor ist für den Apify Store optimiert und bietet ein hochkompetitives Einstiegspreismodell von $1.90 / 1.000 Results ($0.0019 pro geliefertem Datensatz). Er ermöglicht es Nutzern, eigene Produktlisten oder EAN-Kataloge im Batch-Verfahren gegen alle EU-Rückrufe zu prüfen.

Abrechnung erfolgt verbrauchsgenau pro Event:

  • Einstiegspreismodell: $1.90 / 1.000 Results ($0.0019 pro Resultat)

  • ean-checked: $0.005 pro geprüfter EAN

  • alert-returned: $0.0019 pro zurückgegebenem Alert ($1.90 / 1.000 Results)

  • query-executed: $0.002 pro Suchanfrage

  • weekly-monitored: $0.020 pro Wochenbericht

  • Webhooks & Bulk CSV Ingestion: Kostenlos ($0.00) – keine zusätzlichen Abrechnungsevents

Details siehe PRICING.md.

Check Amazon ASINs & product URLs

Überprüfung von Amazon ASINs und Produkt-Detailseiten-URLs gegen offizielle EU Safety Gate Rückrufe und GPSR-Mängel.

JSON-Beispiel-Input:

{
  "asins": [
    "0306406152",
    "B08N5WRWNW"
  ],
  "amazonUrls": [
    "https://www.amazon.de/dp/0306406152",
    "https://www.amazon.co.uk/Motorcycle-Helmet-Bluetooth/dp/B08H93ZRK9"
  ],
  "childProductsOnly": false,
  "maxItems": 50
}

Die Auflösung erfolgt über drei konforme Mechanismen:

  1. ISBN-10 zu EAN-13 Konvertierung: Mathematische Prüfziffernberechnung für Buch-ASINs (resolution_method: "isbn10_conversion").

  2. Katalog-Mapping: Zuordnung über mitgelieferte ASIN/EAN-Paare aus Bulk-CSV-Dateien (resolution_method: "csv_mapping").

  3. URL-Slug-Keywords: Extraktion von Produkttiteln aus Amazon-URLs für Volltextsuchen im Safety-Gate-Index (resolution_method: "url_slug_keywords", gekennzeichnet mit match_confidence: "keyword").

NOTE

Ehrlicher Hinweis zu den Grenzen der ASIN-Auflösung (Zero Scraping):
ProductSafetyEngine agiert strikt datenschutz- und plattformkonform und betreibt kein Scraping von Amazon-Webseiten oder das Umgehen von Bot-Schutzmaßnahmen. Nicht auflösbare B0-ASINs (ohne ISBN-10-Muster, ohne CSV-Katalog-EAN und ohne sprechende URL-Slugs) werden im RUN_SUMMARY und BATCH_REPORT als nicht aufgelöst (unresolved) transparent ausgewiesen. Für nicht auflösbare Kennungen fallen keine PPE-Kosten ($0.00) an.


Bulk CSV screening (up to 10,000 SKUs)

Automatisiertes Screening ganzer Lieferanten- und Marktplatzkataloge mit bis zu 10.000 SKUs oder 5 MB Dateigröße pro Run.

CSV-Beispiel (apps/actor/.actor/examples/bulk-sample.csv):

sku,ean,asin,name,url
SKU-1001,5054298241091,,Wooden Building Blocks,https://www.amazon.de/dp/B08N5WRWNW
SKU-1002,4006381333931,,Magnetic Drawing Board,
SKU-1003,,0306406152,Science Experiment Manual,https://www.amazon.co.uk/dp/0306406152
SKU-1004,4099979071513,B08H93ZRK9,Baby Teething Ring,https://www.amazon.de/Baby-Teething-Ring/dp/B08H93ZRK9
SKU-1005,5901234123457,,Plush Animal Toy,

JSON-Beispiel-Input (Remote URL oder Direkt-Inhalt):

{
  "csvUrl": "https://example.com/catalogs/inventory_2026.csv",
  "childProductsOnly": false,
  "maxItems": 50,
  "webhookUrl": "https://api.yourdomain.com/webhooks/safety-alerts",
  "webhookFormat": "generic"
}

Highlights:

  • Automatische Erkennung gängiger Header (sku, ean, asin, url, name) und Trennzeichen (,, ;, \t).

  • Direkte Unterstützung von Google-Sheets-Freigabelinks (automatische Konvertierung nach /export?format=csv).

  • Duplikaterkennung: Mehrfach vorkommende EANs werden dedupliziert und nur ein einziges Mal abgerechnet.

  • SSRF-Schutz: Remote-URLs werden auf HTTPS validiert und private IP-Bereiche, Localhost sowie Cloud-Metadaten-Endpunkte blockiert.


Webhook alerts (Slack, Discord, Make, Zapier, ERP)

Echtzeit-Push-Benachrichtigungen bei Gefahren- und Produktrückruftreffern für automatisierte Workflows in Slack, Discord, Make, Zapier oder In-House-ERP-Systemen.

JSON-Beispiel-Input:

{
  "eans": ["5054298241091", "4006381333931"],
  "webhookUrl": "https://api.yourdomain.com/webhooks/safety-alerts",
  "webhookFormat": "generic",
  "webhookSecret": "whsec_live_9a8b7c6d5e4f3a2b1c0d",
  "webhookOnlyOnMatch": true
}

Unterstützte Formate:

  • generic: Vollständiges JSON-Schema pse.alert.v1 mit Trefferdetails und EU-Safety-Gate-Referenzen.

  • slack: Fertig gerenderte Slack Block-Kit-Payloads (max. 50 Blöcke).

  • discord: Reichhaltige Embed-Karten für Discord-Webhooks (max. 10 Embeds).

Signaturprüfung (Node.js Snippet): Zur Verifikation der Echtheit wird der Header X-Hub-Signature-256 mit HMAC-SHA256 validiert:

import crypto from 'node:crypto';

/**
 * Signaturprüfung für eingehende ProductSafetyEngine Webhooks
 * @param {string} rawBody - Ungeparster Roh-Request-Body als String
 * @param {string} signatureHeader - Wert des Headers 'X-Hub-Signature-256'
 * @param {string} secret - Konfiguriertes Webhook-Secret
 * @returns {boolean} True wenn die Signatur valide und authentisch ist
 */
export function verifyWebhookSignature(rawBody, signatureHeader, secret) {
  if (!signatureHeader || !signatureHeader.startsWith('sha256=') || !secret) {
    return false;
  }

  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf-8')
    .digest('hex');

  const signatureBuffer = Buffer.from(signatureHeader, 'utf-8');
  const expectedBuffer = Buffer.from(expectedSignature, 'utf-8');

  if (signatureBuffer.length !== expectedBuffer.length) {
    return false;
  }

  return crypto.timingSafeEqual(signatureBuffer, expectedBuffer);
}

Kostenhinweis: Webhooks und CSV-Parsing sind 100 % kostenlos ($0.00). Es fallen keine zusätzlichen Abrechnungsevents an.


Testing & Qualitätssicherung

  • Strict Offline Rule: Sämtliche Tests laufen strikt offline gegen die mitgelieferte Original-Fixture fixtures/safety_gate_2026_45.xml.

  • Keine externen Netzwerkaufrufe: Der HTTP-Fetcher wird in allen Test-Suiten vollständig über Mocks isoliert.

  • 100% Typabdeckung: Strict TypeScript (strict: true, noImplicitAny: true).


Compliance & Rechtliches

Die Nutzung von behördlichen Daten der Europäischen Union unterliegt den Regelungen des EU-Beschlusses 2011/833/EU über die Weiterverwendung von Kommissionsdokumenten.

Ausführliche rechtliche Hinweise, Haftungsausschlüsse und Quellenangaben finden Sie in COMPLIANCE.md.


Lizenz

MIT License. Copyright (c) 2026 Thomas Hartmannsgruber. Weitere Details siehe LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers