esa MCP Server

esa MCP Server

日本語 | English

Offizieller Model Context Protocol (MCP) Server für esa.io – STDIO-Transportversion.

Übersicht

Dieser MCP-Server ermöglicht die nahtlose Integration zwischen KI-Assistenten und esa.io, einer kollaborativen Dokumentationsplattform. Er erlaubt KI-Assistenten, esa-Dokumente direkt über das Model Context Protocol zu lesen, zu erstellen, zu aktualisieren und zu verwalten.

Verfügbare Werkzeuge

Teamverwaltung

• esa_get_teams – Zugängliche esa-Teams des Benutzers abrufen
• esa_get_team_stats – Teamstatistiken abrufen (Mitglieder, Beiträge, Kommentare, Sterne, Beobachter, aktive Benutzer)
• esa_get_team_tags – Alle in Teamposts verwendeten Tags mit Anzahl abrufen
• esa_get_team_members – Teammitglieder mit Rollen und Profilinformationen abrufen

Beitragsverwaltung

• esa_search_posts – Nach Beiträgen in esa.io suchen
• esa_get_post – Einen bestimmten Beitrag anhand der Beitragsnummer abrufen (enthält backlinks_count und body_md_stats mit Zeichen- und Zeilenanzahl des Textkörpers)
• esa_get_post_backlinks – Beiträge auflisten, die auf einen bestimmten Beitrag verweisen, mit Seitenumbruch
• esa_create_post – Einen neuen Beitrag mit Tags, Kategorie und WIP-Status erstellen
• esa_update_post – Vorhandenen Beitrag aktualisieren (Titel, Inhalt, Tags, Kategorie, WIP-Status)
• esa_append_post – Inhalt am Ende des Beitragstextes anhängen (aktueller Text muss nicht abgerufen werden; wird als neue Revision gespeichert)
• esa_prepend_post – Inhalt am Anfang des Beitragstextes voranstellen (aktueller Text muss nicht abgerufen werden; wird als neue Revision gespeichert)

Beitragsaktionen

• esa_archive_post – Einen Beitrag archivieren, indem er in die Kategorie „Archived/“ verschoben wird
• esa_ship_post – Einen Beitrag abschließen (als abgeschlossen markieren, indem wip auf false gesetzt wird)
• esa_duplicate_post – Einen Beitrag duplizieren (einen neuen WIP-Beitrag mit demselben Titel und Text erstellen; teamübergreifende Duplizierung wird ebenfalls unterstützt)

Kommentarverwaltung

• esa_get_comment – Einen bestimmten Kommentar anhand der ID abrufen
• esa_create_comment – Einen neuen Kommentar zu einem Beitrag erstellen
• esa_update_comment – Einen vorhandenen Kommentar aktualisieren
• esa_delete_comment – Einen Kommentar löschen
• esa_get_post_comments – Kommentare für einen bestimmten Beitrag mit Seitenumbruch abrufen
• esa_get_team_comments – Teamkommentare mit Seitenumbruch abrufen

Kategorieverwaltung

• esa_get_categories – Kategorien und Unterkategorien für einen bestimmten Pfad abrufen
• esa_get_top_categories – Alle Hauptkategorien für ein Team abrufen
• esa_get_all_category_paths – Alle Kategoriepfade in einem Team abrufen (mit Beitragsanzahl, unterstützt Filterung)
  • Ideal zum Verständnis der Kategoriestruktur, für Organisationsplanung und Bereinigung
  • Filterbeispiele: prefix: "dev" für entwicklungsbezogene, match: "api" für API-bezogene Kategorien

Anhänge

• esa_get_attachment – Eine Anhangsdatei aus esa-Beiträgen und -Kommentaren abrufen
  • Gibt base64-kodierte Daten für unterstützte Bilder (JPEG, PNG, GIF, WebP) unter 30 MB zurück
  • Gibt signierte URLs (5 Minuten gültig) für andere Dateitypen, größere Bilder oder wenn forceSignedUrl angegeben ist, zurück

Hilfe & Dokumentation

• esa_get_search_options_help – Dokumentation zur esa-Suchsyntax abrufen
• esa_get_markdown_syntax_help – Dokumentation zur esa-Markdown-Syntax abrufen
• esa_search_help – esa-Dokumentation nach Funktionen und Terminologie durchsuchen

Verfügbare Ressourcen

• esa_recent_posts – Kürzlich aktualisierte Beiträge aus dem esa-Team abrufen
  • Vorlage: esa://teams/{teamName}/posts/recent
  • Rückgabe: JSON-Liste der zuletzt aktualisierten Beiträge

Verfügbare Prompts

• esa_summarize_post – Einen esa-Beitragsinhalt zusammenfassen
  • Eingabe: Teamname und Beitragsnummer
  • Ausgabe: Strukturierte Zusammenfassung des Beitragsinhalts

MCP-Client-Konfiguration

Zur Konfigurationsdatei Ihres MCP-Clients hinzufügen:

Erforderliche Umgebungsvariablen

• ESA_ACCESS_TOKEN: Zugriffstoken
  • Erforderliche Bereiche: read write oder admin:comment read:post write:post read:category read:tag read:attachment read:team read:member
  • PAT v2 wird empfohlen.
• LANG: Sprache für die Benutzeroberfläche

Claude Desktop Beispiel

Zu claude_desktop_config.json hinzufügen:

Option 1: Docker (Empfohlen)

{
  "mcpServers": {
    "esa": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "ESA_ACCESS_TOKEN",
        "-e",
        "LANG",
        "ghcr.io/esaio/esa-mcp-server"
      ],
      "env": {
        "ESA_ACCESS_TOKEN": "your_personal_access_token",
        "LANG": "en"
      }
    }
  }
}

Option 2: npx

{
  "mcpServers": {
    "esa": {
      "command": "/Users/your-username/.nodenv/shims/npx",
      "args": ["@esaio/esa-mcp-server"],
      "env": {
        "ESA_ACCESS_TOKEN": "your_personal_access_token",
        "LANG": "en"
      }
    }
  }
}

Hinweis: Ersetzen Sie /path/to/your/node durch die Ausgabe des Befehls which node.

Registry

Dieses Paket liefert registry.json im Paketstammverzeichnis aus und legt registrierte Werkzeuge, Ressourcen und Prompts offen. Es kann programmatisch genutzt werden, ohne den Server zu starten:

import registry from "@esaio/esa-mcp-server/registry.json" with { type: "json" };

Schema:

{
  "tools": [{ "name": "esa_get_teams" }, "..."],
  "resources": [
    { "name": "esa_recent_posts", "uriTemplate": "esa://teams/{teamName}/posts/recent" }
  ],
  "prompts": [{ "name": "esa_summarize_post" }]
}

Die Datei wird durch npm run build:registry neu generiert, und eine CI-Prüfung stellt sicher, dass sie mit dem registrierten Satz synchron bleibt.

Links

• esa.io – Die kollaborative Dokumentationsplattform
• Model Context Protocol – Mehr über MCP erfahren
• API-Dokumentation – esa.io API-Referenz
• Claude Desktop – KI-Assistent mit MCP-Unterstützung

Support

• 📧 Support: Feedback-Formular
• 🐛 Probleme: GitHub Issues
• 📖 Hilfe: esa Docs

---

Mit ❤️ vom esa-Team erstellt