nod-mcp-server

So werden KI-Agenten mit Unternehmen interagieren — nicht durch Scraping, sondern durch das Lesen strukturierter Manifeste. Dieser Referenz-MCP-Server bringt jedem MCP-kompatiblen Client (Claude Desktop, Agent-Frameworks, IDEs) bei, das nod.json-Manifest eines Unternehmens unter https://{domain}/.well-known/nod.json zu lesen und echte Fragen darüber zu beantworten, was das Unternehmen tun kann: Essen bestellen, Termine buchen, Produkte suchen, Preise prüfen und mehr.

Er stellt zwei Tools bereit — lookup_nod und check_capability — und bündelt vier Demo-Manifeste, die lokal gehostet werden, sodass die Demo sofort ohne externe Abhängigkeiten funktioniert.

Installation

git clone <this repo> nod-mcp-server
cd nod-mcp-server
npm install
npm run build

Erfordert Node.js 20+.

Ausführen des Demo-Manifest-Servers

Da bisher kaum echte Websites nod.json veröffentlichen, bündelt dieses Repository vier Beispiel-Manifeste (Restaurant, E-Commerce, SaaS, Gesundheitswesen) und stellt sie lokal bereit.

npm run demo:manifests

Sie sollten Folgendes sehen:

NOD demo manifest server listening on http://localhost:3456
  http://localhost:3456/demo-restaurant.localhost/nod.json
  http://localhost:3456/demo-shop.localhost/nod.json
  http://localhost:3456/demo-saas.localhost/nod.json
  http://localhost:3456/demo-health.localhost/nod.json

Lassen Sie dieses Terminal während der Demo geöffnet. Der MCP-Server leitet automatisch jede *.localhost-Domain an diesen Server weiter.

Konfiguration von Claude Desktop

Öffnen (oder erstellen) Sie ~/Library/Application Support/Claude/claude_desktop_config.json unter macOS (oder %APPDATA%\Claude\claude_desktop_config.json unter Windows) und fügen Sie Folgendes hinzu:

{
  "mcpServers": {
    "nod": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/nod-mcp-server/dist/index.js"]
    }
  }
}

Ersetzen Sie /ABSOLUTE/PATH/TO/nod-mcp-server durch den vollständigen Pfad zu diesem Checkout (z. B. /Users/you/projects/nod-mcp-server). Starten Sie Claude Desktop neu. Sie sollten nun den nod-Server in Claudes Tool-Auswahl mit zwei Tools sehen: lookup_nod und check_capability.

60-Sekunden-Demo-Skript

Wenn der Demo-Manifest-Server in einem Terminal läuft und Claude Desktop konfiguriert ist, fügen Sie diese Prompts nacheinander in Claude ein.

1. "Look up the NOD manifest for demo-restaurant.localhost"

Claude ruft lookup_nod({ domain: "demo-restaurant.localhost" }) auf und gibt etwa Folgendes zurück:

# Pike Place Noodle House  (restaurant)
Hand-pulled noodles, dumplings, and regional Chinese classics...

- URL: https://demo-restaurant.localhost
- Manifest: http://localhost:3456/demo-restaurant.localhost/nod.json

## Declared capabilities
  - purchase
  - booking
  - view_menu
  - order_food
  - book_table

## Supported actions
  - purchase → https://demo-restaurant.localhost/api/orders [auth: api_key]
  - booking  → https://demo-restaurant.localhost/api/reservations [auth: api_key]
  - search   → https://demo-restaurant.localhost/api/menu/search [auth: none]

2. "Can I order food from demo-restaurant.localhost?"

Claude ruft check_capability({ domain: "demo-restaurant.localhost", action: "order_food" }) auf:

YES — demo-restaurant.localhost supports "order_food".
Manifest declares "order_food" under discovery.mcp_server.capabilities.

Endpoint: POST https://demo-restaurant.localhost/api/orders
Authentication: api_key
Matched via: discovery.mcp_server.capabilities

Constraints:
{ "require_human_confirmation": { "purchases_above": 150, ... },
  "rate_limits": { "transactions": { "requests": 10, "period": "minute" } },
  "allow_automated_purchases": true }

3. "What actions does demo-shop.localhost support?"

Claude ruft lookup_nod({ domain: "demo-shop.localhost" }) auf und fasst zusammen: Produktsuche, Preisgestaltung, Bestandsprüfungen und OAuth2-geschützte Bestellaufgabe — mit einer Schwelle für menschliche Bestätigung bei 500 $ und einer 60-tägigen Rückgaberichtlinie.

Bonus-Prompts

• "Book an appointment at demo-health.localhost — what does that flow require?" → gibt den Buchungs-Endpunkt, erforderliche Felder (patient_name, DOB, reason, provider_id, preferred_date), OAuth2-Scopes und die Stornierungsrichtlinie zurück.

• "Does demo-saas.localhost allow automated purchases?" → gibt NEIN mit der URL für menschliche Unterstützung zurück, da das Manifest allow_automated_purchases: false setzt.

Tool-Referenz

lookup_nod

Ruft https://{domain}/.well-known/nod.json ab, mit Fallback auf https://{domain}/nod.json. Gibt eine strukturierte Zusammenfassung zurück: Unternehmensidentität, erklärte Fähigkeiten, unterstützte Aktionen (mit Endpunkten + Authentifizierung), API-Endpunkte und Kontaktmethoden. Gibt bei Fehler eine klare Meldung "no manifest found" zurück.

check_capability

Ruft das Manifest ab und prüft die Aktion gegen transactions.capabilities, discovery.mcp_server.capabilities, support.contact.mcp_server.capabilities und die strukturellen Endpunkte (transactions.purchase, discovery.search, information.pricing usw.). Gibt ein Ja/Nein-Urteil, die Endpunkt-URL, die Authentifizierungsmethode und Richtlinienbeschränkungen (Ratenbegrenzungen, Schwellenwerte für menschliche Bestätigung) zurück.

Wie das *.localhost-Routing funktioniert

Wenn der MCP-Server eine Domain erhält, die auf .localhost endet, ruft er diese von http://localhost:3456/{domain}/nod.json ab, anstatt von der normalen Well-Known-URL. Dies macht die Demo in sich geschlossen — Sie können Claude auf demo-restaurant.localhost verweisen und echte Ergebnisse erhalten, ohne DNS- oder HTTPS-Einrichtung.

Umgebungsvariablen:

• NOD_LOCAL_PORT — Port, auf dem der Demo-Manifest-Server lauscht (Standard 3456)

• NOD_LOCAL_MANIFEST_SERVER — Basis-URL, die der MCP-Server für .localhost-Lookups verwendet (Standard http://localhost:3456)

• NOD_FORCE_LOCAL=1 — leitet jede Domain durch den lokalen Manifest-Server (nützlich für Mitwirkende, die neue Beispiel-Manifeste testen)

Wie geht es weiter?

Veröffentlichen Sie ein nod.json für Ihr eigenes Unternehmen unter Verwendung der NOD-Protokollspezifikation unter opennod.ai/protocol. Ein minimales, gültiges Manifest zu schreiben dauert etwa 30 Minuten — und sobald es unter https://yourdomain.com/.well-known/nod.json live ist, kann jeder Agent, der diesen MCP-Server (oder einen anderen NOD-fähigen Client) verwendet, Ihr Unternehmen entdecken und auf dessen Fähigkeiten zugreifen.

Lizenz

MIT