Work Journal MCP Server

Ein gehosteter MCP-Server, der es jedem Teammitglied ermöglicht, sein Simplified HR Work Journal über Claude zu lesen – die eigenen Einträge immer und die Einträge von Kollegen, soweit die bestehenden Work-Journal-Berechtigungen dies bereits erlauben.

Nur lesend. Kein Tool hier kann einen Eintrag erstellen, ändern oder löschen.

Verbinden, von jedem Claude-Client aus

Ein Ablauf, egal welchen Client Sie verwenden: Fügen Sie den Server per URL hinzu und melden Sie sich dann im sich öffnenden Browserfenster an.

Claude Desktop oder claude.ai – Einstellungen → Connectors → Benutzerdefinierten Connector hinzufügen →

https://wj-mcp.dev.besimplified.net/mcp

Claude Code

claude mcp add work-journal --transport http https://wj-mcp.dev.besimplified.net/mcp

In beiden Fällen öffnet sich ein Browserfenster. Melden Sie sich mit Ihrer Simplified-HR-E-Mail-Adresse und Ihrem Passwort an. In der Entwicklungsumgebung geben Sie auch Ihren Workspace ein, z. B. development-hr.dev.besimplified.net.

Wenn dies ein Gerät ist, das der Kontodienst noch nicht gesehen hat, erhalten Sie einen Verifizierungscode per E-Mail oder SMS. Geben Sie ihn einmal ein; Sie werden vom selben Client aus nicht erneut danach gefragt.

Ihr Passwort erreicht Claude nie, und dieser Server speichert es nie.

Stattdessen beim Kontodienst anmelden

WJ_LOGIN_MODE=redirect ersetzt das obige Formular. /authorize sendet den Browser zur Anmeldeseite des Kontodienstes für die Umgebung, das Mitglied meldet sich dort an, und der Kontodienst führt es mit einem kurzlebigen Übergabe-Token zu /identifier zurück, das dieser Server gegen die Sitzung eintauscht. Zwei Dinge folgen daraus: Es wird kein Passwort in eine Seite eingegeben, die dieser Server rendert, und das Mitglied ist gleichzeitig in den BeSimplified-Web-Apps angemeldet, weil die Sitzung diejenige ist, die der Kontodienst auf seiner eigenen Herkunft ausgestellt hat.

Es ist standardmäßig deaktiviert, weil es Voraussetzungen hat, die der Formularmodus nicht hat:

• Ein app_registrations-Datensatz im Kontodienst, der den Host dieses Servers als verifizierte fqdn oder als workspace benennt, in jeder Organisation, deren Mitglieder ihn nutzen. Die Anmeldeseite entnimmt den Host aus dem referrer, den sie erhält, und schlägt ihn nach; ohne Datensatz antwortet sie mit valid_workspace: false und führt den Browser zurück zur HR-App statt hierher. Dies ist ein Datensatz in der eigenen Datenbank des Kontodienstes – dort ändert sich kein Code.

• WJ_PUBLIC_BASE_URL als https ohne Port. Der Kontodienst baut den Callback als https://<host>/identifier allein aus dem Hostnamen auf, sodass ein Port oder ein Klartext-Schema ihn nicht empfangen kann. Der Server weigert sich andernfalls zu starten, anstatt eine Anmeldung zu bedienen, die beginnen und nie enden kann.

• Lesezugriff auf den Sitzungsspeicher des Kontodienstes, WJ_REDIS_HOST und WJ_ACC_CACHE_PREFIX. Das Übergabe-Token benennt einen Schlüssel dort; ohne ihn gibt es nichts, wofür das Token eingetauscht werden könnte.

Der Callback-Host wird in beiden Modi gegen eine Zulassungsliste geprüft. Hier ist das wichtiger: Sobald sich das Mitglied beim Kontodienst authentifiziert, erhält derjenige, der redirect_uri benannt hat, den Autorisierungscode, und PKCE hilft nicht gegen einen Angreifer, der den Ablauf gestartet hat.

Related MCP server: zulip-mcp

Tools

work_journal_get_entries

Einträge mit vollständiger Aufgabendetail für ein Datum oder einen Bereich von bis zu 31 Tagen.

Fragen Sie: „Zeig mir meine EOD-Einträge für letzte Woche"

work_journal_get_day

Ein Datum vollständig: jede Aufgabe mit Notizen und Anhängen, benachrichtigte Empfänger, ETA und Einreichungszeit.

Fragen Sie: „Was habe ich am 4. August protokolliert?"

work_journal_get_summary

Zählungen nach Typ und Status über einen beliebigen Zeitraum, ohne Tagesdetail. Verwenden Sie dies für alles, was länger als 31 Tage ist.

Fragen Sie: „Wie viele EOW-Berichte habe ich dieses Jahr verpasst?"

work_journal_find_member

Findet einen Kollegen anhand eines Teils seines Namens oder seiner E-Mail-Adresse und gibt seine Mitglieds-ID zurück, zur Verwendung als member bei den obigen Tools.

Fragen Sie: „Finde Rahuls Mitglieds-ID"

work_journal_get_team_report

Eine Zeile pro Mitglied mit eingereichten, ausstehenden und verpassten Zählungen für einen Zeitraum.

Fragen Sie: „Wer hat letzte Woche sein EOD verpasst?"

Typ-Aliasse

Der Abgleich ignoriert Groß-/Kleinschreibung und behandelt Leerzeichen, Bindestriche und Unterstriche als gleichwertig.

Wer wessen Journal sehen kann

Dieser Server erzwingt keine eigenen Berechtigungen. Jede Anfrage trägt Ihre eigene Simplified-HR-Sitzung, und die Work-Journal-API wendet genau die Berechtigungen an, die sie auch in der Weboberfläche anwendet:

• Instanzberechtigung – Sie können jedes Mitglied Ihres Unternehmens lesen

• Gruppenberechtigung – Sie können Mitglieder in Ihrem Berichtsunterbaum lesen

• Keine – Sie können nur Ihr eigenes Journal lesen, und jeder Versuch, auf ein anderes Mitglied zuzugreifen, wird abgelehnt

Zwei Dinge sollten Sie beim Lesen der Einträge eines Kollegen wissen: Die Anfrage kann rundweg abgelehnt werden, und eine Admin-Ansicht schließt Entwürfe, geplante und private Einträge aus. Ein fehlender Eintrag beweist daher nicht, dass nichts protokolliert wurde.

Grenzen

• work_journal_get_entries lehnt Bereiche länger als 31 Tage ab und verweist Sie auf work_journal_get_summary

• Pro Toolaufruf laufen höchstens 4 Anfragen gleichzeitig, sodass ein großer Bereich die API schonend behandelt

• Relative Daten wie „letzte Woche" werden von Claude vor dem Aufruf aufgelöst; die Tools akzeptieren nur YYYY-MM-DD

Lokal ausführen

npm install
cp .env.example .env      # then fill in the two secrets
WJ_ENV=dev \
WJ_PUBLIC_BASE_URL=http://localhost:8080 \
WJ_TOKEN_KEY=$(openssl rand -hex 32) \
WJ_FINGERPRINT_SECRET=$(openssl rand -hex 32) \
npm start

GET /healthz sollte {"status":"ok"} antworten. Das Ausführen von node src/index.js ohne Umgebung muss sofort beendet werden und jede fehlende Variable auflisten.

Umgebung

WJ_FINGERPRINT_SECRET muss auf jeder Aufgabe identisch sein und darf nicht beiläufig rotiert werden. Es leitet den stabilen Geräte-Fingerabdruck jedes Mitglieds ab; eine Änderung fordert das gesamte Team erneut mit einem Verifizierungscode heraus.

Bereitstellungshinweise

• Cookie-Stickiness auf /authorize ist nur eine Anforderung für WJ_LOGIN_MODE=form. Im redirect-Modus wird nichts im Prozessspeicher zwischen den beiden Schritten gehalten – die Autorisierungsanfrage kommt vom Kontodienst in einem verschlüsselten redirect_page-Token zurück – daher sind /authorize und /identifier beide zustandslos und benötigen keine Stickiness.

• Cookie-Stickiness ist nur auf /authorize erforderlich. Eine OTP-Übermittlung muss die Aufgabe erreichen, die den Login gestartet hat, da der laufende Login fünf Minuten lang im Speicher dieses Prozesses gehalten wird. /mcp und /token sind zustandslos und dürfen nicht sticky sein.

• Beide Geheimnisse gehören in den SSM Parameter Store als SecureString, referenziert aus dem secrets-Block der Task-Definition – niemals als Umgebungsvariablen-Literale. Erstellen Sie sie einmal pro Umgebung vor dem ersten Deployment; nichts anderes auf der Plattform verwendet das Präfix /hr/work-journal-mcp/, daher existieren sie noch nicht:

  aws ssm put-parameter --type SecureString --name /hr/work-journal-mcp/<env>/token_key           --value "$(openssl rand -hex 32)"
  aws ssm put-parameter --type SecureString --name /hr/work-journal-mcp/<env>/fingerprint_secret  --value "$(openssl rand -hex 32)"

  ecsTaskExecutionRole benötigt ssm:GetParameters und kms:Decrypt auf beiden, sonst schlägt die Aufgabe beim Start mit ResourceInitializationError fehl, bevor dieser Code überhaupt ausgeführt wird.

• Produktion lehnt das workspace-Login-Feld ab, das dev erfordert, daher verbirgt die Login-Seite es außerhalb von dev.

Sicherheit

• Passwörter werden niemals gespeichert, niemals protokolliert und niemals in irgendeiner Form an den Browser zurückgegeben. Sie existieren nur im Speicher, für die Sekunden, die ein Login dauert.

• Der Sitzungszustand reist in einem AES-256-GCM-verschlüsselten Umschlag, den nur dieser Server öffnen kann. Das Simplified HR JWT erreicht weder Claude noch das Modell.

• Zugriffs-, Aktualisierungs- und Autorisierungscode-Umschläge sind kryptographisch an ihre Art gebunden, sodass einer nicht als ein anderer ausgegeben werden kann.

• Login-Versuche werden pro E-Mail-Adresse ratenbegrenzt.

• Jeder Tool-Aufruf wird mit dem Aufrufer, dem Tool und dem Mitglied, dessen Journal gelesen wurde, protokolliert, sodass Mitgliederübergreifende Lesevorgänge prüfbar sind. Tokens und Eintragsinhalte werden niemals protokolliert.

Tests

npm test