Repository navigation
Releases
Workspace Operator 2.2.5 - cached clients, durable staged operations, typed errors
Workspace Operator 2.2.5
Performance and durability, plus a cleaner contract for tool errors. The MCP tool list and every schema are unchanged — no client configuration or prompt needs to change.
Faster calls: one Google client per configuration
Every handler used to call get_creds(config) and build(api, version, ...) on each invocation, so the token file was read again and the discovery document parsed again for every tool call and every bulk worker. Clients are now cached per (configuration, api, version) and the credentials are read once and refreshed on expiry.
The cache belongs to the configuration object, so a second server with different settings (another token, scopes or profile) never inherits the first one's clients.
Staged Apps Script operations survive a restart
script_write → prepare, then execute or cancel, kept its state in memory: a restart, a second process or a container recreate lost the prepared operation. Prepared updates now live as JSON files under operation_dir (default data/operations), written atomically with owner-only permissions because they contain script source, and carrying an expiry:
operation_ttl/MCP_OPERATION_TTL— seconds a prepared operation stays executable (default 600);operation_dir/MCP_OPERATION_DIR— where they are kept; the Docker template uses/home/app/data/operations;- the directory is now in the protected paths, so
drive_write(action="upload")refuses to upload it; - an executed operation is removed atomically, so two concurrent
executecalls cannot both apply the same update, and a failed update puts the operation back for a retry.
Tool errors: explicit signals instead of guessing from the text
The router treated any handler reply beginning with "Error" as a failure. A legitimate answer such as "Errors found: 0" was therefore reported with isError, and a handler had no way to say "this text is not an error". Handlers can now raise ToolError("...") or return ToolResult(text, is_error=...), and the legacy string convention is matched strictly (^Error(?=:|\s|$)).
Visible change: text that merely starts with the word "Error" (for example "Errors found: 0", or "ERROR: …" in capitals) is now a normal result. Every real handler error message keeps the old shape and is still reported as an error.
Compose: choose the profile in .env
docker-compose.yml now passes MCP_TOOL_PROFILE through (default core), so a deployment can select full, read-write or read-only in .env without editing the tracked config.docker.yaml. The shipped default stays conservative.
Under the hood
448 tests, coverage 58.6% (floor raised to 56%), CI green on Linux and Windows for Python 3.10/3.12/3.13.
Workspace Operator 2.2.5 (русский)
Производительность и надёжность, плюс более чистой контракт ошибок инструментов. Список инструментов и все схемы не изменились — настраивать клиентов и промпты заново не нужно.
Быстрее: один Google-клиент на конфигурацию
Каждый хендлер вызывал get_creds(config) и build(api, version, ...) при каждом обращении: файл токена перечитывался, а документ discovery парсился заново на каждый вызов инструмента и на каждый поток bulk. Теперь клиенты кэшируются по (конфигурация, api, версия), а учётные данные читаются один раз и обновляются по истечении.
Кэш привязан к объекту конфигурации, поэтому второй сервер с другими настройками (другой токен, скоупы или профиль) не получит клиентов первого.
Подготовленные операции Apps Script переживают перезапуск
script_write → prepare, затем execute или cancel: состояние жило в памяти, и перезапуск, второй процесс или пересоздание контейнера теряли подготовленную операцию. Теперь подготовленные изменения лежат JSON-файлами в operation_dir (по умолчанию data/operations), пишутся атомарно с правами владельца (внутри исходники скрипта) и имеют срок жизни:
operation_ttl/MCP_OPERATION_TTL— сколько секунд операция остаётся выполнимой (по умолчанию 600);operation_dir/MCP_OPERATION_DIR— где она хранится; в Docker-шаблоне это/home/app/data/operations;- каталог добавлен в защищённые пути, поэтому
drive_write(action="upload")его не выгрузит; - выполненная операция удаляется атомарно, поэтому два одновременных
executeне применят одно и то же изменение дважды, а неудачное обновление возвращает операцию для повторной попытки.
Ошибки инструментов: явные сигналы вместо догадок по тексту
Роутер считал ошибкой любой ответ хендлера, начинающийся с «Error». Поэтому нормальный ответ вроде «Errors found: 0» помечался как isError, а хендлер не мог сказать «этот текст — не ошибка». Теперь хендлер может возбудить ToolError("...") или вернуть ToolResult(text, is_error=...), а прежняя строковая конвенция проверяется строго (^Error(?=:|\s|$)).
Заметное изменение: текст, который лишь начинается со слова «Error» (например «Errors found: 0» или «ERROR: …» заглавными), теперь считается обычным результатом. Все настоящие сообщения об ошибках хендлеров сохранили прежний вид и по-прежнему помечаются как ошибки.
Compose: профиль выбирается в .env
docker-compose.yml теперь передаёт MCP_TOOL_PROFILE (по умолчанию core), поэтому деплой может выбрать full, read-write или read-only в .env, не редактируя отслеживаемый config.docker.yaml. Значение по умолчанию осталось консервативным.
Внутри
448 тестов, покрытие 58,6% (порог поднят до 56%), CI зелёный на Linux и Windows для Python 3.10/3.12/3.13.
Workspace Operator 2.2.4 - security hardening and internal refactor
Workspace Operator 2.2.4
First PyPI/GHCR release since 2.1.2. Versions 2.2.0 to 2.2.3 were internal steps and were not published, so these notes cover everything since 2.1.2.
The MCP surface is unchanged: the tools, their order and JSON schemas, annotations, prompts, resources and server instructions are identical to 2.1.2 in all four profiles (compared programmatically). What changes is security behaviour, listed first because some of it needs action.
⚠️ Read before upgrading
- Docker: the image now binds
127.0.0.1by default. A plaindocker run -p 8765:8765 IMAGEno longer answers. Add--http --host 0.0.0.0 --allow-network --insecureand keep the-p 127.0.0.1:8765:8765mapping (docker-compose does this already). - HTTP token: the server refuses to start over HTTP with a placeholder (
change_me, …) or a token shorter than 24 characters. Generate one:python -c "import secrets; print(secrets.token_urlsafe(32))"and prefer theMCP_AUTH_TOKENenvironment variable overconfig.yaml. - Approval links: the agent no longer receives a browser link. Run
workspace-operator approvals link <id>to get it (it carries a per-approval secret). Old links without?k=return 404. drive_write(action="upload")refuses OAuth secrets,.env*, keys and~/.google,~/.ssh,~/.aws, and files outsideupload_rootswhen you set it (MCP_UPLOAD_ROOTS).
Security fixes
- Path traversal: a mail attachment named
..\..\xcould be written outside the target folder. Names from remote data are now reduced to a plain file name. - An agent that knew an approval id and the server URL could approve its own request over HTTP. Approvals now need a secret the agent never sees, an Origin/Host check and strict headers.
token.jsonis refreshed under a file lock, written atomically and readable by the owner only.workspace-operator doctornow flags a token stored inconfig.yaml, stray credentials (token.json.bak-*,service-account.json) and files readable by other users.
Fixes
- Bulk jobs lost results on cancel: items already running when a job was cancelled changed Google data but were not recorded, so
bulk_undoskipped them and resume repeated them. They are recorded now. handlers.__all__listed a name that does not exist; the server.json package version lagged one release.
Under the hood
server.pywent from 3,740 to 325 lines: tool definitions are JSON data (workspace_operator/definitions/), the handler table isdispatch.py, the call path isToolRouter, prompts and resources have their own modules. Each step was pinned by characterisation tests taken from the old code.- CI (Linux and Windows, Python 3.10/3.12/3.13, ruff, mypy, bandit, pip-audit) now gates both publish workflows. mypy: 152 errors to 0. 421 tests (one skipped on Linux/macOS by design), coverage 56%.
- New contributor guide ("Adding a tool or action") in both READMEs.
Full list: docs/VERSIONS.md.
Workspace Operator 2.2.4 (русский)
Первый релиз в PyPI/GHCR после 2.1.2. Версии 2.2.0–2.2.3 были внутренними этапами и не публиковались, поэтому заметки охватывают всё с 2.1.2.
MCP-поверхность не изменилась: инструменты, их порядок и JSON-схемы, аннотации, промпты, ресурсы и инструкции сервера идентичны 2.1.2 во всех четырёх профилях (сравнивалось программно). Меняется поведение безопасности; оно вынесено вперёд, потому что часть изменений требует действий.
⚠️ Прочитайте перед обновлением
- Docker: образ по умолчанию слушает
127.0.0.1. Обычныйdocker run -p 8765:8765 IMAGEбольше не отвечает. Добавьте--http --host 0.0.0.0 --allow-network --insecureи оставьте проброс-p 127.0.0.1:8765:8765(docker-compose это уже делает). - Токен HTTP: сервер не запустится по HTTP с заглушкой (
change_me, …) или токеном короче 24 символов. Сгенерируйте:python -c "import secrets; print(secrets.token_urlsafe(32))", лучше в переменнойMCP_AUTH_TOKEN, а не вconfig.yaml. - Ссылки одобрений: агент больше не получает ссылку для браузера. Получите её командой
workspace-operator approvals link <id>(в ней секрет конкретного одобрения). Старые ссылки без?k=дают 404. drive_write(action="upload")отклоняет секреты OAuth,.env*, ключи и~/.google,~/.ssh,~/.aws, а также файлы внеupload_roots, если он задан (MCP_UPLOAD_ROOTS).
Исправления безопасности
- Path traversal: вложение письма с именем
..\..\xмогло записаться за пределы целевой папки. Имена из удалённых данных теперь сводятся к простому имени файла. - Агент, знающий id одобрения и адрес сервера, мог одобрить свой запрос по HTTP. Теперь нужны секрет, которого агент не видит, проверка Origin/Host и строгие заголовки.
token.jsonобновляется под файловой блокировкой, пишется атомарно и доступен только владельцу.workspace-operator doctorтеперь находит токен вconfig.yaml, лишние учётные данные (token.json.bak-*,service-account.json) и файлы, доступные другим пользователям.
Исправления
- Bulk-задачи теряли результаты при отмене: элементы, уже запущенные к моменту отмены, меняли данные в Google, но не записывались, поэтому
bulk_undoих пропускал, а возобновление повторяло. Теперь они записываются. - В
handlers.__all__было несуществующее имя; версия пакета в server.json отставала на один релиз.
Внутри
server.py: 3740 → 325 строк. Определения инструментов теперь JSON-данные (workspace_operator/definitions/), таблица handler'ов вdispatch.py, путь вызова вToolRouter, у промптов и ресурсов свои модули. Каждый шаг закреплён тестами, снятыми со старого кода.- CI (Linux и Windows, Python 3.10/3.12/3.13, ruff, mypy, bandit, pip-audit) теперь блокирует оба workflow публикации. mypy: 152 ошибки → 0. 421 тест (один пропускается на Linux/macOS намеренно), покрытие 56%.
- Руководство для контрибьюторов («Как добавить инструмент или действие») в обоих README.
Полный список: docs/VERSIONS.md.
Workspace Operator 2.1.2
Browser approval fallback.
- Native in-chat elicitation remains the primary path on clients that support it.
- Clients without elicitation (including current DSH) now get a clickable local approval link in the tool result.
/approvals/{id}serves an Approve/Deny page; no terminal needed.- Added
approval_url/MCP_APPROVAL_URL, HTTP page tests and docs. - 308 tests green.
Workspace Operator 2.1.1
In-chat approval release.
- Destructive calls now ask for approval directly in the chat when the MCP client supports elicitation (
elicitation/create). - Accept runs the action once; decline/cancel changes nothing.
- If the client does not support elicitation, the server falls back to the existing
approval_id+ local CLI flow. - The session remains stable in both paths; failures fall back cleanly.
- 305 tests, including accepted/declined elicitation paths.
Workspace Operator 2.1.0
Human-in-the-loop safety release.
- Destructive tools now return a normal
APPROVAL_REQUIREDresult with anapproval_id; they do not execute. - A human approves the exact call locally:
workspace-operator approvals approve <id>(or denies it). - The agent retries the same call with
approval_id; approval is one-time, TTL-bound and hash-bound to tool/action/arguments. - Pending, expired, denied, reused and changed-argument cases return clear results without crashing the MCP session.
- New
workspace-operator approvals list/show/approve/denycommands;approval_dirandapproval_ttlconfig. - 303 tests green.
Workspace Operator 2.0.6
Documentation accuracy release. No code or OAuth changes.
- Removed the stale
sheet_briefprompt row from both READMEs. - Added exact tests: README tool table, English prompt table, Russian prompt table.
- Tool descriptions/actions, prompts, resources and templates rechecked against code.
- Counts corrected to 293 tests.
Workspace Operator 2.0.5
Documentation accuracy release. No code or OAuth changes.
- README/RU now mention all four profiles and both HTTP profile endpoints.
- Added
MCP_SCOPE_ROUTINGandMCP_ALLOW_PUBLIC_SHARINGto the operations table. - Corrected local-file capabilities: upload/export only, no download, no pptx.
- Completed both documentation tables (profiles, migration, versions).
- Updated SECURITY/TROUBLESHOOTING/LEARN to current tool names and Trash semantics.
- 290 tests green.
Workspace Operator 2.0.4
Documentation release. No code or OAuth changes.
- README/RU now state 39 consolidated tools (20 in the default
coreprofile) at the top. - Added a complete scope → tools matrix to
docs/PROFILES.mdand its Russian copy. - Documented minimal scope sets, missing-token behaviour, routing-off caveats and missing-tool troubleshooting.
AUTH_SETUPlinks to the matrix.- 290 tests green.
Workspace Operator 2.0.3
Documentation consolidation release. No tool or OAuth changes.
- Removed duplicate troubleshooting lines in README/RU.
- Replaced 38 per-version release/spec files with one
docs/VERSIONS.md. - Corrected prompt count to 7 and test count to 290.
- Updated PUBLISHING, IDE_SETUP, DISTRIBUTION, LAUNCH_PACKAGE, SCREENSHOTS and LEARN.
- Added PROFILES and MIGRATION links to both README documentation tables.
- 290 tests green.
Workspace Operator 2.0.2
Workspace Operator 2.0.2
Code cleanup release. No new tools and no new OAuth scopes.
Removed dead code
- Deleted
handlers/slides.py,handlers/comments.py,handlers/deck.py,
handlers/report.py,handlers/template.py. - Removed their imports, exports, tool definitions and dispatch branches.
- Removed obsolete handler functions:
find_files,drive_download,
create_event,calendar_find_free_slots,doc_export_pdf,
doc_fill_template,drive_empty_trash,drive_transfer_ownership,
drive_create_shortcut,batch_delete_emails. - Removed Slides conversion/export from
drive_upload/drive_export. - Removed the remaining Slides domain handling from the bulk engine.
- Removed
sheet_briefprompt because it depended on the removed report handler;
prompt count is now 7. - Removed stale 1.x live scripts from
tests/; the executable suite is the
290-test unit/in-memory suite.
Preserved
- 39 consolidated tools;
core= 20,read-only= 17,read-write= 30,
full= 39. - Hidden 1.x aliases from 2.0.1.
- Scope routing, profile endpoints, no permanent Drive deletion, public sharing
disabled by default. - Removed capabilities return the migration error instead of an
unknown tool.
Verification
- 290 tests, all green.
- CLI catalog:
core20,full39. - Live read/write check on a synthetic Google Doc; removed after the test.
- HTTP endpoints
/mcp,/mcp/read,/mcp/read-write,/mcp/full.