Weeeking

Weeeking 🛡️

Русский · English

Weeek and conquer. MCP-сервер для Weeek с полным покрытием публичного API: 157 операций из официальной OpenAPI-спецификации. Один бинарник на Rust, без Node и внешних зависимостей в рантайме. Релизы — для семи платформ: Windows x64/arm64, Linux x64 (glibc/musl), Linux arm64, macOS arm64/x64.

Возможности

• 13 админ-групп с action — weeek_project, weeek_board, weeek_board_column, weeek_custom_fields, weeek_portfolio, weeek_tags, weeek_task (таймеры, записи времени, вложения, родитель…), weeek_funnels, weeek_funnel_statuses, weeek_deals, weeek_organizations, weeek_contacts, weeek_currencies.
• 12 curated-тулов для повседневной работы: weeek_context, weeek_search_tasks, weeek_get_task, weeek_list_comments, weeek_download_attachment + записи (weeek_create_task, weeek_update_task, weeek_move_task, weeek_complete_task, weeek_set_task_people, weeek_add_comment, weeek_delete_comment).
• READ_ONLY по умолчанию: изменяющие действия не регистрируются, пока не выставлено READ_ONLY=false.
• Ресурсы и промпты MCP: weeek://me и weeek://projects читаются клиентом без tool-call; промпты «Мои задачи на сегодня» и «Итоги недели» — готовые сценарии для агента.
• Эргономика LLM: compact=true убирает null и пустые значения (включая пустые элементы массивов) из тяжёлых ответов; fetchAll=true (+maxItems) собирает страницы задач и комментариев (страница по умолчанию 100, не более 50 страниц) с флагом truncated.
• Надёжность: ретраи 429 и 502/503/504 с Retry-After и экспоненциальным бэкоффом (429 — для любого метода, 502/503/504 и сетевые сбои — только для GET/HEAD; таймауты не повторяются); WEEEK_LOG=debug — HTTP-логи в stderr (метод, путь, статус, длительность; без токена).
• Кодогенератор спеки: tools/update_spec.py тянет OpenAPI с developers.weeek.net и генерирует src/spec_generated.rs — статические данные (&'static str), которые компилируются в бинарник; в рантайме нет ни JSON, ни парсинга, чанк спеки в репозитории не сохраняется.

Сборка

Требуется Rust 1.88+ (MSVC toolchain на Windows).

cargo build --release
# → target/release/weeeking.exe (Windows) / target/release/weeeking (Linux, macOS)

Релизы

Готовые бинарники — в GitHub Releases: архивы weeeking-<версия>-<платформа> и сырые бинарники для npm-обёртки; рядом — файлы .sha256, хэши также перечислены в описании релиза.

Платформа	Архив	Сырой бинарник
Windows x64	weeeking-<версия>-win-x64.zip	weeeking-<версия>-win-x64.exe
Windows arm64	weeeking-<версия>-win-arm64.zip	weeeking-<версия>-win-arm64.exe
Linux x64 (glibc)	weeeking-<версия>-linux-x64.tar.gz	weeeking-<версия>-linux-x64
Linux x64 (musl, static)	weeeking-<версия>-linux-musl-x64.tar.gz	weeeking-<версия>-linux-musl-x64
Linux arm64	weeeking-<версия>-linux-arm64.tar.gz	weeeking-<версия>-linux-arm64
macOS arm64	weeeking-<версия>-osx-arm64.tar.gz	weeeking-<версия>-osx-arm64
macOS x64	weeeking-<версия>-osx-x64.tar.gz	weeeking-<версия>-osx-x64

# проверка контрольной суммы
certutil -hashfile weeeking-<версия>-win-x64.zip SHA256          # Windows
sha256sum -c weeeking-<версия>-linux-x64.tar.gz.sha256           # Linux

Каждый файл релиза подписан GitHub-аттестацией (Sigstore) — проверяемое происхождение сборки:

gh attestation verify weeeking-<версия>-win-x64.exe -R OniVe/weeeking

npm（npx）

npx -y weeeking     # MCP-сервер по stdio; бинарник скачается и проверится по sha256

weeeking パッケージは薄いラッパーです。同じバージョンの GitHub Releases から、対象プラットフォーム用のネイティブバイナリ（Windows x64/arm64、Linux x64 gnu/musl、Linux arm64、macOS arm64/x64）を取得します。npm trusted publishing（OIDC、provenance 付き）を通じて公開されています。

サーバーは公式 MCP Registry にも io.github.OniVe/weeeking として公開されており、GitHub MCP ディレクトリや各種アグリゲーターから利用されています。

macOS では、ブラウザーからダウンロードしたバイナリに Gatekeeper の隔離属性が付くことがあります。解除するには xattr -d com.apple.quarantine <ファイル> を実行するか、npx または curl でインストールしてください。

環境変数

変数	デフォルト	説明
WEEEK_API_TOKEN	—	Weeek のトークン（ワークスペースの設定 → API）。設定しないと読み取り操作はできません。
READ_ONLY	true	false/0 にすると、変更操作（作成、編集、削除、CRM）が有効になります。
WEEEK_ALLOW_ACTIONS	—	操作のホワイトリスト（operationId または * マスク）。リストにない操作（読み取りを含む）はすべて禁止されます。WEEEK_PROFILE と併用できません。
WEEEK_DENY_ACTIONS	—	操作のブラックリスト（delete-* などのマスクも指定可能）。対象の操作は呼び出されず、表示もされません。ホワイトリストやプロファイルより優先されます。
WEEEK_PROFILE	—	アクセスプロファイル。executor は読み取りに加え、タスクとコメントの作成を許可します。
WEEEK_LANG	ru	ユーザー向けテキストの言語（ru/en）：ヘルプ、ツールの説明、プロンプト、エラー。
WEEEK_BASE_URL	https://api.weeek.net/public/v1	必要に応じて独自のプロキシ／ホストを指定します。
WEEEK_TIMEOUT_MS	30000	リクエストのタイムアウト。
WEEEK_MAX_RESPONSE_CHARS	60000	大きなレスポンスを切り詰める文字数。
WEEEK_DISABLE_KEYCHAIN	—	1 にすると、システムのキーチェーンからトークンを読み込みません。
WEEEK_KEYCHAIN_ACCOUNT	api-token	システムキーチェーンのエントリー名（複数アカウント用）。
WEEEK_MAX_ATTACHMENT_BYTES	67108864（64 MiB）	添付ファイルのダウンロード上限（巨大なレスポンスへの対策）。
WEEEK_RETRY_MAX	2	429、502/503/504、ネットワーク障害時の追加試行回数（0～5）。タイムアウト時は再試行しません。
WEEEK_RETRY_BASE_MS	300	指数バックオフの基準値（上限 5 秒。Retry-After を考慮し、上限は 30 秒）。
WEEEK_RPS	—	クライアント側の毎秒リクエスト数上限（トークンバケット方式、再試行を含む）。未設定または ≤0 の場合は無効です。0 < RPS < 0.001 の場合、起動エラーになります。
WEEEK_RPS_BURST	ceil(RPS)、最小値 1	バースト時のトークン容量。
WEEEK_LOG	—	debug にすると、詳細な HTTP ログを stderr に出力します（メソッド、パス、ステータス、ミリ秒。トークンは記録されません）。

トークンの取得元

1. 環境変数の WEEEK_API_TOKEN（または WEEEK_TOKEN）。常にこちらが優先されます。
2. システムキーチェーンの weeek-mcp サービスにある、WEEEK_KEYCHAIN_ACCOUNT という名前のエントリー（デフォルトは api-token）。Windows Credential Manager（target api-token.weeek-mcp）、macOS Keychain、Linux Secret Service（D-Bus 経由の GNOME Keyring/KWallet）が対象です。weeeking store-token コマンドで保存します。値がログに記録されることはありません。
3. どちらも空の場合、サーバーは起動しますが、呼び出しはヒントとともに isError を返します。

システムキーチェーンはすべてのプラットフォームで使用できますが、D-Bus のないヘッドレス Linux では利用できません。その場合は、環境変数 WEEEK_API_TOKEN または WEEEK_TOKEN を設定してください。

Несколько аккаунтов Weeek

Личность действий (автор комментариев, задач) определяется токеном: API всегда действует от владельца токена. Для второго пользователя нужен его собственный токен (создаётся в Настройках workspace → API; доступ к разделу есть у супер-админов и админов).

# 1) Сохранить токен второго аккаунта (ввод скрыт, в argv токен не попадает)
weeeking store-token --account api-token-anna

# 2) Запуск сервера под этим аккаунтом
$env:WEEEK_KEYCHAIN_ACCOUNT = "api-token-anna"; weeeking   # PowerShell (Windows)
WEEEK_KEYCHAIN_ACCOUNT=api-token-anna weeeking             # bash/zsh (macOS, Linux)

Пример второго инстанса в конфиге OpenCode (нативная форма V2):

"mcp": {
  "servers": {
    "weeek-anna": {
      "type": "local",
      "command": ["C:\\путь\\weeeking.exe"],
      "environment": {
        "WEEEK_KEYCHAIN_ACCOUNT": "api-token-anna",
        "READ_ONLY": "false"
      }
    }
  }
}

Агент сможет выбирать, от кого действовать: тулы weeek-anna_* пишут от Анны, weeek_* — от основного аккаунта. Удалить запись из хранилища: Windows — cmdkey /delete:api-token-anna.weeek-mcp; macOS — security delete-generic-password -s weeek-mcp -a api-token-anna; Linux — средствами вашего хранилища (GNOME Keyring / KWallet).

На headless-Linux без D-Bus системного хранилища нет: мультиаккаунт — отдельный инстанс сервера с собственным WEEEK_API_TOKEN в окружении.

CLI

weeeking                                запустить MCP-сервер (stdio)
weeeking store-token [--account <имя>]  сохранить токен в системное хранилище
weeeking --help                         справка

Ограничение операций

READ_ONLY — грубый переключатель: false открывает весь изменяющий API. Тоньше доступ настраивается фильтром операций (по operationId из OpenAPI):

• WEEEK_DENY_ACTIONS — чёрный список: перечисленные операции (или маски: delete-*) не вызываются и не показываются в описаниях инструментов;
• WEEEK_ALLOW_ACTIONS — абсолютный белый список: всё, что не перечислено (включая чтения), запрещено; несовместим с WEEEK_PROFILE;
• WEEEK_PROFILE=executor — готовый узкий профиль: чтения плюс create-task и create-task-comment (создание задачи и комментария; без изменений и удалений).

Семантика: READ_ONLY=true сильнее списков и профиля (они игнорируются с предупреждением); WEEEK_DENY_ACTIONS сильнее WEEEK_ALLOW_ACTIONS и профиля. Fail-closed: пустое значение WEEEK_ALLOW_ACTIONS/WEEEK_DENY_ACTIONS и маска, не совпавшая ни с одной операцией OpenAPI, останавливают сервер с ошибкой при старте; под READ_ONLY=true такие настройки игнорируются, но о проблеме сообщается предупреждением. Списки разделяются запятыми и/или пробелами; * в маске — любая подстрока.

Запрещённые действия не рекламируются в tools/list (действие исчезает из action-enum, инструмент — из списка) и отклоняются при вызове с типизированной ошибкой. Ресурсы, промпты и серверная инструкция тоже следуют политике: если контекст (weeek_context и ресурсы weeek://me, weeek://projects) недоступен, он не рекламируется и не читается, а промпты, опирающиеся на скрытые инструменты, пропадают из prompts/list.

# Запретить все удаления, остальное оставить:
READ_ONLY=false WEEEK_DENY_ACTIONS="delete-*" weeeking

# Узкий исполнитель: чтения, создание задач и комментариев:
READ_ONLY=false WEEEK_PROFILE=executor weeeking

# Явный белый список (абсолютный — чтения тоже перечисляются):
READ_ONLY=false WEEEK_ALLOW_ACTIONS="get-tasks,get-task,get-task-comments,create-task,create-task-comment" weeeking

Соответствие curated-инструментов операциям OpenAPI:

Инструмент	Операции
weeek_context	get-profile, get-workspace, get-workspace-members, get-tags, get-projects (+get-boards, get-board-columns при аргументах projectId/boardId)
weeek_search_tasks	get-tasks
weeek_get_task	get-task, get-task-comments
weeek_list_comments	get-task-comments
weeek_download_attachment	get-attachment
weeek_create_task	create-task
weeek_update_task	update-task
weeek_move_task	change-task-board, change-task-board-column
weeek_complete_task	complete-task, uncomplete-task
weeek_set_task_people	add-assignees-to-task, remove-assignees-from-task, add-watchers-to-task, remove-watchers-from-task
weeek_add_comment	create-task-comment
weeek_delete_comment	delete-task-comment

Инструмент доступен, только если разрешены все его операции (у weeek_context дополнительные выборки get-boards/get-board-columns проверяются отдельно — при передаче projectId/boardId). Админ-группы (weeek_project, weeek_task, …) фильтруют action-список: доступные операции перечислены в описании инструмента.

Сосуществование потребителей

Weeek не публикует лимиты запросов, и они, по-видимому, общие на workspace. Когда рядом работают несколько потребителей (инстансы weeeking, сервис-синхронизатор, скрипты), бюджет можно сгладить:

• WEEEK_RPS — клиентский лимит запросов в секунду для этого инстанса (token bucket): действует на все HTTP-запросы, включая повторные попытки; Retry-After не отменяется — пауза берётся не меньше предписанной API;
• WEEEK_RPS_BURST — допуск всплеска в токенах: по умолчанию «секунда запаса» (ceil(RPS), минимум 1) — короткая пачка укладывается в секунду без лишнего пейсинга; если при малом RPS параллельные выборки не должны тормозить, задайте burst вручную;
• по умолчанию throttle выключен; пустое или ≤0 значение — тоже выключен (baseline не меняется); значения меньше 0.001 отклоняются на старте (иначе один запрос ждал бы тысячи секунд).

Общий бюджет на несколько инстансов: разделите WEEEK_RPS между ними вручную или поставьте перед API общий throttle-прокси и укажите его в WEEEK_BASE_URL — тогда лимит соблюдается суммарно.

# Строгий режим для сервиса-синхронизатора: 1 запрос/с без всплеска
READ_ONLY=false WEEEK_RPS=1 WEEEK_RPS_BURST=1 weeeking

# Интерактивный инстанс: в среднем 4 запроса/с, всплеск до 8
WEEEK_RPS=4 WEEEK_RPS_BURST=8 weeeking

Подключение (OpenCode)

Нативная форма OpenCode V2 — серверы живут в mcp.servers:

"mcp": {
  "servers": {
    "weeek": {
      "type": "local",
      "command": ["C:\\путь\\weeeking.exe"],   // на любой ОС: ["npx", "-y", "weeeking"]
      "environment": { "READ_ONLY": "false" }
    }
  }
}

Добавить из CLI: opencode mcp add weeek -- npx -y weeeking (с --global — для всех проектов). Отключить сервер, не удаляя из конфига: "disabled": true (нативная V2-форма; V1-форма "mcp": { "weeek": { … } } с enabled тоже поддерживается).

Любой другой MCP-клиент: команда — путь к бинарнику (или npx -y weeeking), транспорт — stdio.

Обновление спецификации

pip install quickjs            # зависимость кодогенератора (один раз)
python tools/update_spec.py    # developers.weeek.net → src/spec_generated.rs (кодогенерация)
cargo fmt && cargo build --release

Разработка

cargo fmt
cargo clippy --all-targets
cargo test                   # unit + mock-сюита (HTTP против эмулятора) + smoke

Приёмочный smoke против живого API (перед релизом; read-only по умолчанию):

python tools/live_smoke.py
python tools/live_smoke.py --write-test <PROJECT_ID>   # + цикл мутаций в sandbox-проекте

Пересборка при работающем OpenCode (exe залочен запущенным MCP-сервером):

python tools\rebuild.py

Ограничения API Weeek (важно агенту)

• Описание задачи задаётся только при создании — позже не изменить.
• tags в weeek_update_task заменяет весь список — сначала прочитайте задачу.
• Комментарии можно создать и удалить, но не отредактировать.

Участие

Проект открыт для вклада и вопросов: баг-репорты, идеи и вопросы — в issues (для типовых случаев есть шаблоны).

• Как собрать проект, какие проверки обязательны и что нужно для PR — в CONTRIBUTING.md.
• Участвуя в проекте, вы соглашаетесь с Кодексом поведения.

Мейнтейнер — @OniVe.

Безопасность

Об уязвимостях сообщайте приватно — см. SECURITY.md. Токены не попадают в логи; не прикладывайте их к issue и PR.

Лицензия

MIT — см. LICENSE.