catalog-mcp

Ein MCP-Server, der jedes JSON-Katalog in ein Abfragetool für KI-Agenten verwandelt.

Richten Sie ihn auf eine Katalog-URL oder -Datei – einen Bestandsfeed, eine Produktliste, die catalog.json, die feedmerge veröffentlicht – und jeder MCP-Client (Claude Desktop, Claude Code, alles, was das Protokoll spricht) erhält strukturierte Filter-, Gruppierungs-, Ranking- und Schemaerkennung über Ihre Datensätze.

Node 18+. Zwei Laufzeitabhängigkeiten: das MCP-SDK und zod.

Warum

Agenten sind schlecht mit großen JSON-Dateien und gut mit Werkzeugen. Geben Sie einem Agenten einen 2 MB großen Katalog und er wird Datensätze abschneiden, überfliegen oder halluzinieren; geben Sie ihm catalog_query mit einer Filtergrammatik und er antwortet „günstigster Datensatz unter $30k mit diesen zwei Eigenschaften“ jedes Mal korrekt, indem er nur die Datensätze liest, die passen.

Dieses Repository ist die verallgemeinerte Version eines MCP-Servers, den ich in Produktion betreibe: ein Verkaufsflächen-KI-Assistent fragt einen Live-Bestandskatalog über genau diese Werkzeuge ab (gleiche Filtersemantik, gleiche Null-Preis-Regel, gleicher TTL-Cache) hunderte Male am Tag. Die Pipeline, zu der es gehört:

vendor feed  ->  feedmerge  ->  catalog.json  ->  catalog-mcp  ->  any agent
             (guarded sync)   (versioned)      (query tools)

Ich betreibe dies gegen meinen eigenen öffentlichen Bestandsfeed; das folgende Beispiel verwendet einen neutralen Katalog, damit das Repository eigenständig ist.

Schnellstart

git clone https://github.com/stevyf93II/catalog-mcp.git
cd catalog-mcp
npm install
npm test                                          # engine, loader, and stdio end-to-end tests

# serve the example catalog
node src/server.js --file examples/telescopes.json --key sku

Binden Sie es in Claude Desktop ein (claude_desktop_config.json):

{
  "mcpServers": {
    "my-catalog": {
      "command": "node",
      "args": ["/path/to/catalog-mcp/src/server.js"],
      "env": {
        "CATALOG_URL": "https://example.com/catalog.json",
        "CATALOG_KEY": "sku"
      }
    }
  }
}

Fragen Sie dann den Agenten Dinge wie „welche Typen sind im Katalog und was kostet jeder am unteren Ende?“ und sehen Sie zu, wie er catalog_schema, catalog_count_by und catalog_top selbstständig zusammensetzt.

Werkzeuge

Alle Werkzeuge sind schreibgeschützt und idempotent und geben dies in ihren MCP-Anmerkungen an.

Die Filtergrammatik

Eine kleine Spezifikation, verwendet von query, count_by und top:

{
  "eq":       { "type": "reflector", "goto": true },
  "min":      { "aperture_mm": 150 },
  "max":      { "price": 1000 },
  "has":      { "features": ["Parabolic Mirror", "Cooling Fan"] },
  "contains": { "name": "dobsonian" }
}

• eq – strenge Gleichheit für jeden Wert, einschließlich Booleans und null.

• min / max – numerische Grenzen. Ein Datensatz ohne reelle Zahl in einem begrenzten Feld wird ausgeschlossen. Diese Regel ist tragend: Im Produktionskatalog bedeutet ein fehlender Preis „Preis auf Anfrage“, und „zeige Einheiten unter $30k“ darf niemals eine Einheit mit unbekanntem Preis anzeigen.

• has – Array-Mitgliedschaft; jeder aufgeführte Wert muss vorhanden sein.

• contains – Groß-/Kleinschreibung-unabhängige Teilzeichenkette in einem Zeichenkettenfeld; Feld "*" durchsucht jedes Zeichenkettenfeld im Datensatz.

Bedingungen werden UND-verknüpft. Ein unbekannter Schlüssel der obersten Ebene ist ein Fehler, der die gültigen Schlüssel nennt, denn ein stillschweigend ignorierter Filter ist, wie ein Agent zuversichtlich falsche Antworten meldet.

Sortieren schiebt Datensätze, denen das Sortierfeld fehlt, in beiden Richtungen ans Ende – „nach Preis sortieren“ zeigt zuerst Datensätze mit Preis, nicht eine Wand von Nullen.

Konfiguration

Wenn CATALOG_RECORDS_PATH nicht gesetzt ist, verwendet der Lader das Dokumentstammverzeichnis, wenn es ein Array ist, oder das einzige Array der obersten Ebene von Objekten, wenn es genau eines gibt ({ "meta": ..., "items": [...] } funktioniert einfach). Wenn das Dokument mehrdeutig ist, lehnt es ab und nennt die Kandidatenschlüssel.

Bei einem fehlgeschlagenen Refresh bedient der Server die letzten guten Daten anstatt einen Fehler zu werfen – ein Agent mitten in einer Aufgabe ist mit fünf Minuten alten Datensätzen besser dran als mit einer Ausnahme – und catalog_stats meldet das Cache-Alter, sodass Veralten nie verborgen bleibt.

Nicht-Ziele

• Keine Datenbank. Der Katalog ist schreibgeschützt und lebt im Speicher; wenn Ihre Daten nicht bequem in eine JSON-Datei passen, benötigen Sie einen echten Speicher.

• Keine Schreibvorgänge. Nichts hier verändert den Katalog – das ist die Aufgabe der Synchronisationspipeline (siehe feedmerge).

• Keine Abfragesprache. Fünf Filtersschlüssel decken ab, was Agenten tatsächlich fragen; alles Ausgefallenere gehört in den Code, nicht in ein Werkzeugschema.

Lizenz

MIT