goalslot-mcp

Сервер MCP для GoalSlot. Он предоставляет ИИ-ассистенту инструменты для целей, задач, шаблона еженедельного расписания, учёта времени, общего таймера, отчётов, заметок и журнала — применительно к вашему собственному аккаунту GoalSlot.

Работает через stdio, так что любой MCP-хост может его запустить. В комплекте четыре навыка, которые учат модель правильно пользоваться инструментами.

Установка

Сначала нужно войти в goalslot CLI, потому что этот сервер читает учётные данные, которые записывает 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. %APPDATA%\goalslot\credentials.json на Windows.

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 — это обычные Bearer JWT с typ: "cli" и утверждением cid, указывающим на строку отзываемого токена, и все обычные маршруты API их принимают. Access-токены живут один час. При 401 этот сервер обновляет refresh-токен через POST /api/auth/cli/token/refresh, атомарно записывает новую пару на диск до её использования и один раз повторяет исходный запрос. Ротация выполняется в режиме single-flight: refresh-токены одноразовые, и повторное использование уже ротированного токена отзывает все учётные данные, так что два одновременных обновления привели бы к постоянному выходу.

Никакой токен, заголовок или строка Authorization никогда не записываются в логи, ни на каком уровне.

Если учётные данные отсутствуют или недействительны, каждый инструмент возвращает структурированную ошибку NOT_AUTHENTICATED или SESSION_EXPIRED, сообщающую модели, что вам нужно выполнить goalslot login. Он не попросит вас вставить токен.

Безголовый режим и CI

GOALSLOT_ACCESS_TOKEN полностью переопределяет файл. Если вы хотите, чтобы обновление работало, укажите также GOALSLOT_REFRESH_TOKEN; без него обновление отключено, и сессия завершается, когда истекает часовой access-токен. Для длительных процессов лучше задать GOALSLOT_CONFIG_DIR и позволить серверу управлять файлом.

Инструменты

Девять инструментов чтения и девять инструментов записи. Инструменты чтения безопасно вызывать свободно, они помечены readOnlyHint. Описание каждого инструмента записи начинается с WRITES., и ничто из представленного здесь не удаляет пользовательские данные.

Чтение

Запись

Намеренно не инструменты

Удаление целей, задач и записей времени; очистка всего расписания; публикация чего-либо публично или для другого человека; конечные точки чата с ИИ-коучем; биллинг и настройки аккаунта; импорт шаблонов. Уничтожение с каскадными эффектами и всё, что публикует личные данные, должно выполняться там, где печатает человек, а не там, где агент может вызывать это в цикле. Используйте приложение GoalSlot или CLI.

Соглашения, которые соблюдают инструменты

• Длительности — целые минуты, всегда называются durationMinutes, никогда не просто duration. Чтения также возвращают durationHours как число с плавающей точкой только для отображения. targetHours цели — единственное исключение.

• Даты — YYYY-MM-DD и отклоняются на границе, если содержат время. «Сегодня» вычисляется в вашем часовом поясе, а не из UTC-среза ISO.

• Расписание — повторяющийся еженедельный шаблон, а не события с датами. В описании каждого соответствующего инструмента это указано.

• dayOfWeek — с воскресенья (0 = воскресенье), что не совпадает с порядком с понедельника, используемым в еженедельных отчётах. Оба помечены в тексте, и каждый ответ содержит dayName.

• Недельные группы пересчитываются из дат записей, а не читаются из хранимого в API столбца dayOfWeek, который вычисляется в часовом поясе сервера API и может отличаться на единицу.

Ошибки

Сбои возвращаются как isError: true с одним 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.

Навыки

В комплекте четыре навыка в 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 и нет хранения токенов, поэтому любой, кто может получить доступ к порту, может читать и записывать в учетную запись. Он привязывается к loopback и должен там оставаться. Это не размещенный многопользовательский MCP-сервер, отслеживаемый в goal-slot-api#55; для этого нужен настоящий поток OAuth и хранение токенов для каждого пользователя, что является отдельной задачей.

stdio — поддерживаемый путь.

Разработка

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

TypeScript strict, ESM, Node 20 или новее. Тесты — vitest с заглушкой fetch; ничего в наборе не касается живого API. CI запускает проверку типов, тесты и сборку на Node 20 и 22 в Ubuntu и Windows.

Лицензия

MIT