goalslot-mcp

GoalSlot 用の MCP サーバーです。これは、自分の GoalSlot アカウントに対して、目標、タスク、週間スケジュールテンプレート、時間追跡、共有タイマー、レポート、メモ、ジャーナルのツールを AI アシスタントに提供します。

stdio 上で動作するため、任意の MCP ホストが起動できます。ツールをうまく使う方法をモデルに教える4つのスキルが同梱されています。

インストール

このサーバーは CLI が書き込んだ資格情報を読み取るため、先に goalslot CLI にサインインしておく必要があります。このサーバー自体がログインフローを実行することはありません。

npm install -g goalslot-cli
goalslot login

次に、MCP サーバーを Claude Code に追加します:

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

Claude Desktop や、JSON 設定を受け取る任意のホストの場合:

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

動作確認:

npx -y goalslot-mcp --list-tools

このパッケージはまだ npm に公開されていません。公開されるまでは、ソースからインストールしてください: リポジトリをクローンし、npm install && npm run build を実行してから、ホストを node /path/to/goalslot-mcp/dist/cli.js に指定します。

Related MCP server: GoHighLevel MCP Server

認証の仕組み

このサーバーにはログインフローはありません。stdio がプロトコルチャネルであるため、サーバーは何かをプロンプト表示できず、モデルにトークンを処理させるのはさらに悪いでしょう。マシン上に既に存在する資格情報を読み取ります。

解決順序:

1. 環境変数 GOALSLOT_ACCESS_TOKEN（設定されていて空でない場合）

2. $GOALSLOT_CONFIG_DIR/credentials.json

3. Windows では %APPDATA%\goalslot\credentials.json

4. $XDG_CONFIG_HOME/goalslot/credentials.json、それ以外の場合は ~/.config/goalslot/credentials.json

このファイルは goalslot login によって書き込まれ、CLI と共有されます。その形式は次のとおりです:

{
  "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 と apiUrl は両方とも読み取られ、同じ値で書き込まれるため、CLI とこのサーバーが互いに上書きすることはありません。未知のキーは書き換え後も保持されます。

CLI トークンは、typ: "cli" と、失効可能なトークン行を指定する cid クレームを持つ通常の Bearer JWT であり、通常の API ルートはすべてこれを受け入れます。アクセストークンの有効期限は1時間です。401 が返された場合、このサーバーは POST /api/auth/cli/token/refresh に対してリフレッシュトークンをローテーションし、新しいペアを 使用する前に アトミックにディスクに書き込み、元のリクエストを1回再試行します。ローテーションはシングルフライトです: リフレッシュトークンは一度きりであり、ローテーション済みのトークンを再試行すると資格情報全体が失効するため、同時に2つのリフレッシュが発生すると恒久的なログアウトになります。

トークン、ヘッダー、Authorization 行がログに書き込まれることは、どのレベルでも一切ありません。

資格情報が存在しないか無効な場合、すべてのツールは構造化された NOT_AUTHENTICATED または SESSION_EXPIRED を返し、モデルに goalslot login を実行するよう指示します。トークンを貼り付けるよう求めることはありません。

ヘッドレスと CI

GOALSLOT_ACCESS_TOKEN はファイルを完全に上書きします。リフレッシュを機能させたい場合は GOALSLOT_REFRESH_TOKEN と組み合わせてください。これがない場合、リフレッシュは無効になり、1時間のアクセストークンが期限切れになるとセッションは終了します。長期間の使用には、代わりに GOALSLOT_CONFIG_DIR を設定し、サーバーにファイルを管理させてください。

ツール

読み取りツールが9つ、書き込みツールが9つあります。読み取りツールは自由に呼び出しても安全で、readOnlyHint と注釈されています。各書き込みツールの説明は WRITES. で始まり、ここで公開されているものでユーザーデータを削除するものはありません。

読み取り

書き込み

意図的にツールにしないもの

目標、タスク、時間エントリの削除、スケジュール全体のクリア、公開または他の人との共有、AI コーチのチャットエンドポイント、請求とアカウント設定、テンプレートのインポート。連鎖的な影響を伴う破壊や個人データを公開するものは、エージェントがループで呼び出せる場所ではなく、人間が入力する場所に属します。GoalSlot アプリまたは CLI を使用してください。

ツールが強制する規約

• 期間は整数分 で、常に durationMinutes という名前で、裸の duration ではありません。読み取りでは表示専用に durationHours を浮動小数点数として返します。目標の targetHours は唯一の例外です。

• 日付は YYYY-MM-DD で、時刻が含まれる場合は境界で拒否されます。「今日」は UTC ISO スライスではなく、あなたのタイムゾーンで計算されます。

• スケジュールは繰り返しの週間テンプレート であり、日付付きのイベントではありません。関連するすべてのツールの説明にその旨が記載されています。

• dayOfWeek は日曜日始まり（0 = 日曜日）で、週次レポートが使用する月曜日始まりの順序とは異なります。両方ともインラインでラベル付けされ、すべてのレスポンスには dayName が含まれます。

• 週次バケットは、API サーバーのタイムゾーンで導出され、1日ずれる可能性がある API の保存済み dayOfWeek 列から読み取るのではなく、エントリの日付から再計算されます。

エラー

失敗は isError: true と1つの JSON オブジェクトとして返されます:

{
  "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 はモデル向けに命令形で書かれています。コード: 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。

スキル

4つのスキルが skills/ に同梱されています。これらはツールの説明では表現できない判断を担います: 呼び出しの順序、書き込み前に確認すべきこと、言うべきでないこと。

スキルフォルダにディレクトリをコピーして Claude Code にインストールします:

# 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

クローンからは、代わりにリポジトリの skills/* をコピーしてください。プロジェクトスコープでも機能します: リポジトリ内の .claude/skills/ に配置します。

設定

HTTP トランスポート

オプションで、フラグの後ろにあります:

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

同じツールレジストリを http://127.0.0.1:7801/mcp でストリーミング可能な HTTP トランスポート経由でステートレスに提供します。

これはシングルユーザーかつローカルのみです。すべてのリクエストはこのマシンのGoalSlot認証情報で処理されます。呼び出し元ごとの認証、OAuth、トークンの管理は一切ないため、ポートに到達できる人は誰でもアカウントを読み書きできます。ループバックにバインドされており、そのままにしておく必要があります。goal-slot-api#55で追跡されているホスト型マルチテナントMCPサーバーではありません。それには本格的なOAuthフローとユーザーごとのトークン保存が必要であり、それは別の作業です。

stdioがサポートされているパスです。

開発

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

TypeScript strict、ESM、Node 20以降。テストはスタブ化されたfetchを使用したvitestです。スイート内の何もライブAPIに触れません。CIはUbuntuとWindowsでNode 20と22に対して型チェック、テスト、ビルドを実行します。

ライセンス

MIT