goalslot-mcp

Ein MCP-Server für GoalSlot. Er gibt einem KI-Assistenten Werkzeuge für Ziele, Aufgaben, die wöchentliche Zeitplanvorlage, Zeiterfassung, den gemeinsamen Timer, Berichte, Notizen und das Journal – für dein eigenes GoalSlot-Konto.

Läuft über stdio, sodass jeder MCP-Host ihn starten kann. Enthält vier Skills, die einem Modell beibringen, die Werkzeuge gut zu nutzen.

Installation

Du musst zuerst die goalslot-CLI angemeldet haben, weil dieser Server die Anmeldedaten liest, die die CLI schreibt. Er führt selbst keinen Anmeldevorgang durch.

npm install -g goalslot-cli
goalslot login

Füge dann den MCP-Server zu Claude Code hinzu:

claude mcp add goalslot -- npx -y goalslot-mcp

Für Claude Desktop oder jeden Host, der eine JSON-Konfiguration akzeptiert:

{
  "mcpServers": {
    "goalslot": {
      "command": "npx",
      "args": ["-y", "goalslot-mcp"]
    }
  }
}

Prüfe, ob es funktioniert:

npx -y goalslot-mcp --list-tools

Dieses Paket ist noch nicht auf npm veröffentlicht. Bis dahin installiere es aus dem Quellcode: Klone das Repository, npm install && npm run build, und weise den Host auf node /path/to/goalslot-mcp/dist/cli.js an.

Related MCP server: GoHighLevel MCP Server

So funktioniert die Authentifizierung

Es gibt keinen Anmeldevorgang in diesem Server. stdio ist der Protokollkanal, daher kann ein Server nichts abfragen, und ein Modell um einen Token zu bitten wäre schlechter. Er liest eine Anmeldedatei, die bereits auf dem Rechner existiert.

Auflösungsreihenfolge:

1. GOALSLOT_ACCESS_TOKEN aus der Umgebung, falls gesetzt und nicht leer.

2. $GOALSLOT_CONFIG_DIR/credentials.json.

3. %APPDATA%\goalslot\credentials.json unter Windows.

4. $XDG_CONFIG_HOME/goalslot/credentials.json, sonst ~/.config/goalslot/credentials.json.

Die Datei wird von goalslot login geschrieben und mit der CLI geteilt. Ihre Struktur:

{
  "version": 1,
  "apiBaseUrl": "https://api.goalslot.io/api",
  "apiUrl": "https://api.goalslot.io/api",
  "accessToken": "<jwt>",
  "refreshToken": "gsl_rt_...",
  "accessTokenExpiresAt": "2026-08-25T12:00:00.000Z",
  "refreshTokenExpiresAt": "2026-11-23T00:00:00.000Z",
  "tokenId": "<uuid>",
  "scopes": ["full"],
  "user": { "id": "...", "email": "..." },
  "defaultTimezone": "Asia/Karachi",
  "weekStartsOn": 1
}

apiBaseUrl und apiUrl werden beide gelesen und beide mit demselben Wert geschrieben, sodass sich CLI und dieser Server nicht gegenseitig überschreiben können. Unbekannte Schlüssel überleben eine Neufassung.

CLI-Tokens sind gewöhnliche Bearer-JWTs mit typ: "cli" und einem cid-Anspruch, der die widerrufbare Token-Zeile benennt, und alle normalen API-Routen akzeptieren sie. Access-Tokens leben eine Stunde. Bei einem 401 rotiert dieser Server das Refresh-Token gegen POST /api/auth/cli/token/refresh, schreibt das neue Paar atomar auf die Festplatte bevor er es verwendet, und spielt die ursprüngliche Anfrage einmal erneut ab. Die Rotation ist single-flight: Refresh-Tokens sind nur einmal verwendbar, und das erneute Abspielen eines rotierten Tokens widerruft die gesamte Anmeldedatei, sodass zwei gleichzeitige Rotationen einen dauerhaften Logout bedeuten würden.

Kein Token, kein Header und keine Authorization-Zeile wird jemals in irgendein Log geschrieben, auf keiner Ebene.

Wenn die Anmeldedatei fehlt oder ungültig ist, gibt jedes Werkzeug ein strukturiertes NOT_AUTHENTICATED oder SESSION_EXPIRED zurück, das dem Modell sagt, du sollst goalslot login ausführen. Es wird dich nicht bitten, einen Token einzufügen.

Headless und CI

GOALSLOT_ACCESS_TOKEN überschreibt die Datei vollständig. Kombiniere es mit GOALSLOT_REFRESH_TOKEN, wenn die Rotation funktionieren soll; ohne dieses ist die Rotation deaktiviert und die Sitzung endet, wenn das einstündige Access-Token abläuft. Für etwas Langlebiges setze stattdessen GOALSLOT_CONFIG_DIR und lass den Server die Datei verwalten.

Werkzeuge

Neun Lese-Werkzeuge und neun Schreib-Werkzeuge. Lese-Werkzeuge sind sicher frei aufzurufen und mit readOnlyHint annotiert. Die Beschreibung jedes Schreib-Werkzeugs beginnt mit WRITES. und nichts, was hier exponiert ist, löscht Benutzerdaten.

Lesen

Schreiben

Bewusst keine Werkzeuge

Löschen von Zielen, Aufgaben und Zeiteinträgen; Löschen des gesamten Zeitplans; Teilen von etwas öffentlich oder mit einer anderen Person; die KI-Coach-Chat-Endpunkte; Abrechnung und Kontoeinstellungen; Vorlagenimporte. Zerstörung mit kaskadierenden Effekten und alles, das persönliche Daten veröffentlicht, gehört dorthin, wo ein Mensch es tippt, nicht dorthin, wo ein Agent es in einer Schleife aufrufen kann. Nutze die GoalSlot-App oder die CLI.

Konventionen, die die Werkzeuge durchsetzen

• Dauern sind ganze Minuten, immer benannt durationMinutes, nie ein nacktes duration. Lesevorgänge geben auch durationHours als Float nur zur Anzeige zurück. Das targetHours eines Ziels ist die einzige Ausnahme.

• Daten sind YYYY-MM-DD und werden an der Grenze abgelehnt, wenn sie eine Uhrzeit tragen. „Heute“ wird in deiner Zeitzone berechnet, nicht aus einem UTC-ISO-Ausschnitt.

• Der Zeitplan ist eine sich wiederholende Wochenvorlage, keine datierten Ereignisse. Jede relevante Werkzeugbeschreibung sagt das.

• dayOfWeek ist Sonntag-zuerst (0 = Sonntag), was nicht der Montag-zuerst-Reihenfolge der Wochenberichte entspricht. Beide sind inline beschriftet und jede Antwort trägt einen dayName.

• Wochen-Buckets werden aus Eintragsdatumsangaben neu berechnet, statt aus der gespeicherten dayOfWeek-Spalte der API gelesen, die in der Zeitzone des API-Servers abgeleitet wird und um eins danebenliegen kann.

Fehler

Fehler kommen als isError: true mit einem JSON-Objekt zurück:

{
  "error": {
    "code": "PLAN_LIMIT",
    "message": "You've reached your FREE plan limit for goals.",
    "httpStatus": 403,
    "retryable": false,
    "remedy": "The account is at its goal limit. Ask the user to pause a goal with update_goal (status PAUSED), delete one from the CLI, or upgrade. Do not retry.",
    "details": { "plan": "FREE", "limitType": "goals" }
  }
}

remedy ist im Imperativ geschrieben, für das Modell. Codes: NOT_AUTHENTICATED, SESSION_EXPIRED, PLAN_LIMIT, FORBIDDEN, SCHEDULE_CONFLICT, INVALID_INPUT, NOT_FOUND, RATE_LIMITED, UPSTREAM_ERROR, WRITE_BUDGET_EXCEEDED, READ_ONLY_MODE, TIMER_ALREADY_RUNNING, NO_TIMER_RUNNING.

Skills

Vier Skills sind in skills/ enthalten. Sie tragen das Urteilsvermögen, das die Werkzeugbeschreibungen nicht leisten können: in welcher Reihenfolge Dinge aufgerufen werden, was vor dem Schreiben bestätigt werden muss und was man nicht sagen sollte.

Installiere sie in Claude Code, indem du die Verzeichnisse in deinen Skills-Ordner kopierst:

# macOS and Linux
cp -r "$(npm root -g)/goalslot-mcp/skills/"* ~/.claude/skills/

# Windows PowerShell
Copy-Item "$(npm root -g)\goalslot-mcp\skills\*" "$env:USERPROFILE\.claude\skills\" -Recurse

Aus einem Klon kopiere stattdessen skills/* aus dem Repository. Projektbezogen funktioniert auch: Lege sie in .claude/skills/ innerhalb eines Repos ab.

Konfiguration

HTTP-Transport

Optional, hinter einem Flag:

npx -y goalslot-mcp --http --port 7801

Er bedient dieselbe Werkzeug-Registry unter http://127.0.0.1:7801/mcp über den streamable HTTP-Transport, zustandslos.

Dies ist nur für Einzelbenutzer und lokal. Jede Anfrage wird mit den GoalSlot-Anmeldedaten dieser Maschine bedient. Es gibt keine Authentifizierung pro Aufrufer, kein OAuth und keine Token-Verwahrung, sodass jeder, der den Port erreichen kann, das Konto lesen und schreiben kann. Es bindet an Loopback und sollte dort bleiben. Es ist nicht der gehostete Multi-Tenant-MCP-Server, der in goal-slot-api#55 verfolgt wird; dieser benötigt einen echten OAuth-Ablauf und eine benutzerspezifische Token-Speicherung, was eine andere Aufgabe ist.

stdio ist der unterstützte Pfad.

Entwicklung

npm install
npm run typecheck
npm test
npm run build
node dist/cli.js --list-tools

TypeScript strict, ESM, Node 20 oder neuer. Die Tests verwenden vitest mit einem gestubten fetch; nichts in der Suite berührt eine Live-API. CI führt Typecheck, Tests und Build auf Node 20 und 22 unter Ubuntu und Windows aus.

Lizenz

MIT