Nostr MCP Server

Nostr MCP Server

Ein Model Context Protocol (MCP)-Server, der LLMs wie Claude Nostr-Funktionen bereitstellt.

https://github.com/user-attachments/assets/1d2d47d0-c61b-44e2-85be-5985d2a81c64

Merkmale

Dieser Server implementiert mehrere Tools für die Interaktion mit dem Nostr-Netzwerk:

1. getProfile : Ruft die Profilinformationen eines Benutzers per öffentlichem Schlüssel ab
2. getKind1Notes : Ruft Textnotizen (Art 1) ab, die von einem Benutzer verfasst wurden
3. getLongFormNotes : Ruft Langforminhalte (Art 30023) ab, die von einem Benutzer verfasst wurden
4. getReceivedZaps : Ruft die von einem Benutzer empfangenen Zaps ab, einschließlich detaillierter Zahlungsinformationen
5. getSentZaps : Ruft von einem Benutzer gesendete Zaps ab, einschließlich detaillierter Zahlungsinformationen
6. getAllZaps : Ruft sowohl gesendete als auch empfangene Zaps für einen Benutzer ab, deutlich gekennzeichnet mit Richtung und Summen
7. searchNips : Suche durch Nostr Implementation Possibilities (NIPs) mit Relevanzbewertung
8. sendAnonymousZap : Bereiten Sie einen anonymen Zap für ein Profil oder Ereignis vor und generieren Sie eine Lightning-Rechnung zur Zahlung.

Alle Tools unterstützen sowohl öffentliche Hex-Schlüssel als auch das npub-Format vollständig und bieten eine benutzerfreundliche Anzeige der Nostr-Kennungen.

Installation

Verbindung zu Claude für Desktop herstellen

1. Stellen Sie sicher, dass Sie Claude für Desktop installiert und auf die neueste Version aktualisiert haben.
2. Konfigurieren Sie Claude für Desktop, indem Sie die Konfigurationsdatei bearbeiten oder erstellen:Für macOS:
   vim ~/Library/Application\ Support/Claude/claude_desktop_config.json
   Für Windows:
   notepad %AppData%\Claude\claude_desktop_config.json
3. Fügen Sie den Nostr-Server zu Ihrer Konfiguration hinzu:
   { "mcpServers": { "nostr": { "command": "node", "args": [ "/ABSOLUTE/PATH/TO/nostr-mcp-server/build/index.js" ] } } }
   Ersetzen Sie /ABSOLUTE/PATH/TO/ unbedingt durch den tatsächlichen Pfad zu Ihrem Projekt.
4. Starten Sie Claude für Desktop neu.

Verbindung zum Cursor herstellen

1. Stellen Sie sicher, dass Sie Cursor installiert und auf die neueste Version aktualisiert haben.
2. Konfigurieren Sie Cursor, indem Sie die Konfigurationsdatei erstellen oder bearbeiten:Für macOS:
   vim ~/.cursor/config.json
   Für Windows:
   notepad %USERPROFILE%\.cursor\config.json
3. Fügen Sie den Nostr-Server zu Ihrer Konfiguration hinzu:
   { "mcpServers": { "nostr": { "command": "node", "args": [ "/ABSOLUTE/PATH/TO/nostr-mcp-server/build/index.js" ] } } }
   Ersetzen Sie /ABSOLUTE/PATH/TO/ unbedingt durch den tatsächlichen Pfad zu Ihrem Projekt.
4. Cursor neu starten.

Verwendung in Claude

Nach der Konfiguration können Sie Claude bitten, die Nostr-Tools zu verwenden, indem Sie Anfragen wie die folgenden stellen:

• „Zeigen Sie mir die Profilinformationen für npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8“
• „Was sind die letzten Beiträge von npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8?“
• „Zeigen Sie mir die Langform-Artikel von npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8“
• „Wie viele Zaps hat npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8 empfangen?“
• „Zeigen Sie mir die Zaps, die von npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8 gesendet wurden.“
• „Zeige mir alle Zaps (sowohl gesendete als auch empfangene) für npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8“
• „Suche nach NIPs zu Zaps“
• „Welche NIPs beziehen sich auf Langforminhalte?“
• „Zeigen Sie mir NIP-23 mit vollständigem Inhalt“
• „Senden Sie einen anonymen Zap von 100 Sats an npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8“
• „Senden Sie 1000 Sats an note1abcdef … mit dem Kommentar ‚Toller Beitrag!‘“

Der Server übernimmt automatisch die Konvertierung zwischen npub- und Hex-Formaten, sodass Sie beide Formate in Ihren Abfragen verwenden können. Die Ergebnisse werden mit benutzerfreundlichen npub-Kennungen angezeigt.

Erweiterte Nutzung

Sie können für jede Abfrage benutzerdefinierte Relays angeben:

• „Zeigen Sie mir das Profil für npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8 mit Relay wss://relay.damus.io“

Sie können auch die Anzahl der abzurufenden Notizen oder Zaps angeben:

• „Zeige mir die letzten 20 Notizen von npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8“

Bei anonymen Zaps können Sie optionale Kommentare einfügen und den Zieltyp angeben:

• „Senden Sie einen anonymen Zap von 500 Sats an note1abcdef … mit dem Kommentar ‚Toller Beitrag!‘“
• „Senden Sie 1000 Sats anonym an nevent1qys … mit dem Relay wss://relay.damus.io“

Für Zap-Abfragen können Sie zusätzliche Validierung und Debugging aktivieren:

• „Zeigen Sie mir alle Zaps für npub1qny3tkh0acurzla8x3zy4nhrjz5zd8ne6dvrjehx9n9hr3lnj08qwuzwc8 mit aktivierter Validierung und Debug“

Bei NIP-Suchen können Sie die Anzahl der Ergebnisse steuern und den vollständigen Inhalt einschließen:

• „Suche nach NIPs zu Zaps mit vollständigem Inhalt“
• „Zeigen Sie mir die Top 5 NIPs zum Thema Relais“
• „Welche NIPs beziehen sich auf die Verschlüsselung? Zeigen Sie mir 15 Ergebnisse.“

Einschränkungen

• Der Server verfügt standardmäßig über ein Timeout von 8 Sekunden für Abfragen, um ein Hängenbleiben zu verhindern.
• Es werden nur öffentliche Schlüssel im Hex-Format oder im npub-Format unterstützt
• Standardmäßig wird nur eine Teilmenge der Relais verwendet

Implementierungsdetails

• Native Unterstützung für das npub-Format mit NIP-19-Kodierung/Dekodierung
• NIP-57-konforme Zap-Empfangserkennung mit Richtungserkennung (gesendet/empfangen/selbst)
• Erweitertes Bolt11-Rechnungs-Parsing mit Zahlungsbetragsextraktion
• Intelligentes Caching-System für verbesserte Leistung bei großen Zap-Volumina
• Berechnung der Gesamtsättigung für gesendete/empfangene/selbst erstellte Zaps mit Nettosaldo
• Optionale NIP-57-Validierung zur Gewährleistung der Integrität von Zap-Belegen
• Anonymer Zap-Support mit Lightning-Rechnungserstellung
• Unterstützung für Zapping-Profile, Ereignisse (Notiz-IDs) und ersetzbare Ereignisse (naddr)
• Jeder Tool-Aufruf stellt eine neue Verbindung zu den Relais her und gewährleistet so einen zuverlässigen Datenabruf

Anonyme Zaps

Mit dem Tool sendAnonymousZap können Benutzer Zaps senden, ohne ihre Nostr-Identität preiszugeben. Wichtige Punkte zu anonymen Zaps:

• Der Zap scheint von einem anonymen Benutzer in der Brieftasche des Empfängers zu stammen
• Der Zap folgt dem NIP-57-Protokoll, jedoch ohne Absendersignatur
• Der Empfänger kann die Zahlung und alle enthaltenen Nachrichten weiterhin erhalten.
• Sie können Profile (mit npub/hex pubkey), bestimmte Ereignisse (mit note/nevent/hex ID) oder ersetzbare Ereignisse (mit naddr) zappen.
• Der Server generiert eine Lightning-Rechnung zur Zahlung, die Sie in Ihr Lightning-Wallet kopieren können

Beispiele:

Der Server validiert LNURL-Dienste vollständig gemäß den Spezifikationen LNURL-pay (LUD-06) und Lightning Address (LUD-16) und stellt so die Kompatibilität mit verschiedenen Wallet-Implementierungen sicher.

Fehlerbehebung

• Wenn bei Abfragen eine Zeitüberschreitung auftritt, versuchen Sie, den QUERY_TIMEOUT Wert im Quellcode zu erhöhen (derzeit 8 Sekunden).
• Wenn keine Daten gefunden werden, versuchen Sie, verschiedene Relais anzugeben, die die Daten möglicherweise haben
• Überprüfen Sie Claudes MCP-Protokolle auf detaillierte Fehlerinformationen

Standardrelais

Der Server verwendet standardmäßig die folgenden Relays:

• wss://relay.damus.io
• wss://relay.nostr.band
• wss://relay.primal.net
• wss://nos.lol
• wss://relay.current.fyi
• wss://nostr.bitcoiner.social

Entwicklung

So ändern oder erweitern Sie diesen Server:

1. Bearbeiten Sie die entsprechende Datei:
   • index.ts : Hauptserver und Tool-Registrierung
   • note/note-tools.ts : Profil- und Notizenfunktionalität ( Dokumentation )
   • zap/zap-tools.ts : Zap-bezogene Funktionalität ( Dokumentation )
   • nips/nips-tools.ts : Funktionen zum Suchen von NIPs ( Dokumentation )
   • utils/ : Gemeinsam genutzte Dienstprogrammfunktionen
     • constants.ts : Globale Konstanten und Relaiskonfigurationen
     • conversion.ts : Dienstprogramme zur Konvertierung des Pubkey-Formats
     • formatting.ts : Ausgabeformatierungshilfen
     • pool.ts : Nostr-Verbindungspoolverwaltung
     • ephemeral-relay.ts : In-Memory-Nostr-Relay zum Testen
2. Führen Sie zum Kompilieren npm run build aus
3. Starten Sie Claude für Desktop oder Cursor neu, um Ihre Änderungen zu übernehmen

Testen

Wir haben mit Jest eine umfassende Testsuite implementiert, um sowohl die grundlegende Funktionalität als auch die Integration mit dem Nostr-Protokoll zu testen:

Die Testsuite umfasst:

Unit-Tests

• basic.test.ts – Testet einfache Profilformatierung und Zap-Belegverarbeitung
• profile-notes-simple.test.ts – Testet Profil- und Notizdatenstrukturen
• zap-tools-simple.test.ts – Testet die Zap-Verarbeitung und die anonyme Zap-Vorbereitung

Integrationstests

• integration.test.ts – Testet die Interaktion mit einem flüchtigen Nostr-Relay, einschließlich:
  • Veröffentlichen von Profilereignissen
  • Erstellen und Abrufen von Textnotizen
  • Zap-Belege veröffentlichen
  • Ereignisse filtern
• websocket-integration.test.ts – Testet die WebSocket-Kommunikation mit einem Nostr-Relay:
  • Veröffentlichen von Ereignissen über WebSocket
  • Abonnieren von Ereignissen mit Filtern
  • Verwalten mehrerer Abonnements
  • Abonnements schließen
  • Überprüfen, ob Ereignisse mit ungültigen Signaturen abgelehnt werden

Alle Integrationstests nutzen unsere ephemeral-relay.ts -Implementierung – ein voll funktionsfähiges In-Memory-Nostr-Relay, das das Nostr-Protokoll unterstützt und die Signierung und Verifizierung kryptografischer Ereignisse ohne externe Netzwerkverbindungen ermöglicht. Dies bietet eine robuste Möglichkeit, den gesamten Nostr-Workflow in einer isolierten Umgebung zu testen.

Weitere Einzelheiten zur Testsuite finden Sie unter tests /README.md .

Codebasisorganisation

Die Codebasis ist in Module unterteilt:

• Core-Server-Setup in index.ts
• Spezialisierte Funktionen in dedizierten Verzeichnissen:
  • nips/ : NIPs-Such- und Caching-Funktionalität
  • note/ : Profil- und Notizenfunktion
  • zap/ : Zap-Handling und anonymes Zappen
• Allgemeine Dienstprogramme im Verzeichnis utils/

Diese modulare Struktur verbessert die Wartung des Codes, reduziert Duplikate und ermöglicht einfachere Funktionserweiterungen. Ausführliche Informationen zu den Funktionen und der Implementierung der einzelnen Module finden Sie in der jeweiligen Dokumentation.