zai-coding-gateway 0.1.0__tar.gz

zai_coding_gateway-0.1.0/.gitignore

@@ -0,0 +1,60 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtualenv
+.venv/
+venv/
+ENV/
+env/
+
+# Pytest
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# IDE / Editor
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Cursor
+.cursor/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env (секреты не коммитить)
+.env
+.env.local
+.env.*.local
+pypi_credentials.env
+
+# MCP config с ключами (пример — в репо, свой — нет)
+mcp.json
+
+# Логи сессий solve_in_workspace (не коммитить)
+workspace_sessions_logs/

zai_coding_gateway-0.1.0/PKG-INFO

@@ -0,0 +1,176 @@
+Metadata-Version: 2.4
+Name: zai-coding-gateway
+Version: 0.1.0
+Summary: MCP-сервер для решения задач в рабочем пространстве через Z.AI Coding Plan (solve_in_workspace, apply_changes)
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.11
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: respx>=0.20.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ZAI Coding Gateway
+
+MCP-сервер для решения задач в рабочем пространстве через **Z.AI Coding Plan** endpoint (`api.z.ai/api/coding/paas/v4`). Предоставляет инструменты `solve_in_workspace`, `apply_changes`, `confirm_session_done` для любых MCP-клиентов (Cursor, Anigravity, Claude Code, Cline и др.). Один и тот же сервер можно добавить в любую IDE — поведение не зависит от того, откуда вы его запускаете.
+
+## Требования
+
+- Python 3.11+
+- Ключ Z.AI и подписка Coding Plan
+
+## Установка
+
+```bash
+pip install -e .
+# или с тестами:
+pip install -e ".[dev]"
+```
+
+## Настройка
+
+Все настройки задаются **переменными окружения**. Ключ и модель **не хранятся в коде** — их задаёт пользователь в настройках MCP-клиента (например, в Cursor в `mcp.json` в секции `env`).
+
+| Переменная     | Назначение                                      |
+|----------------|--------------------------------------------------|
+| `ZAI_API_KEY`  | Ключ Z.AI (обязательный)                        |
+| `ZAI_WORK_MODEL` | Необязательно. Модель для генерации кода, рефакторинга и основного цикла сессии. По умолчанию **glm-4.7** (контекст 200K). |
+| `ZAI_FAST_MODEL` | Необязательно. Модель для консолидации и суммаризации внутри сессии. По умолчанию **glm-4.5-air** (контекст 128K, быстрая). |
+| `ZAI_BASE_URL` | По умолчанию `https://api.z.ai/api/coding/paas/v4` |
+| `ZAI_PROJECT_ROOT` | Корень открытого проекта для solve_in_workspace (пути file_paths и сессия). **Чтобы из любой IDE всё работало «как по маслу»**, задайте эту переменную в конфиге MCP так, чтобы она указывала на папку открытого в IDE проекта. Многие IDE при старте MCP подставляют в env переменные вроде `${workspaceFolder}` / `${projectPath}` — тогда один конфиг подходит для Cursor, Anigravity и др. Без неё сервер пробует MCP `roots/list` (многие клиенты пока не поддерживают) или поиск вверх от cwd по маркерам; при неудаче — явная ошибка с просьбой задать ZAI_PROJECT_ROOT. |
+| `ZAI_SESSION_LOGS_DIR` | Опционально. Каталог для логов сессий solve_in_workspace. По умолчанию логи пишутся в проект gateway (для разработчиков). Если нужно получать логи в свой проект — укажите абсолютный путь к каталогу (например `${workspaceFolder}/workspace_sessions_logs`). |
+
+## Работа из любой IDE
+
+MCP запускается вашей IDE при открытии проекта. Чтобы пути file_paths/file_path и сессия solve_in_workspace относились к открытому проекту (а не к случайному cwd), в настройках MCP укажите **ZAI_PROJECT_ROOT** в `env`. Тогда не важно, в какой IDE вы работаете (Cursor, Anigravity, другая):
+
+- Если IDE при запуске MCP подставляет в env путь к открытому проекту (например через переменную вроде `${workspaceFolder}`, `${workspaceRoot}`, `%projectPath%` и т.п.) — используйте её для `ZAI_PROJECT_ROOT`. Один и тот же конфиг будет работать во всех проектах и во всех таких IDE.
+- Если такой подстановки нет — укажите в конфиге абсолютный путь к корню проекта; для другого проекта можно завести отдельный конфиг или переопределить env в настройках проекта/workspace.
+
+Идея: **корень проекта задаёт тот, кто запускает MCP (IDE)**, через env — тогда серверу не нужно угадывать, и поведение едино во всех средах.
+
+## Подключение в Cursor
+
+1. Скопируйте пример конфигурации:
+   ```bash
+   cp mcp.json.example mcp.json
+   ```
+2. Откройте `mcp.json` и в секции `env` подставьте свой `ZAI_API_KEY`.
+3. Добавьте содержимое `mcp.json` в настройки MCP Cursor (например, в `~/.cursor/mcp.json` или в настройках проекта в разделе MCP Servers). **При использовании в другом проекте** укажите в `env` путь к корню этого проекта: `"ZAI_PROJECT_ROOT": "/путь/к/проекту"` (Cursor пока не передаёт workspace через MCP roots/list). Формат:
+   ```json
+   {
+     "mcpServers": {
+       "zai-coding-gateway": {
+         "command": "/путь/к/.venv/bin/python",
+         "args": ["-m", "zai_coding_gateway.main", "--stdio"],
+         "env": {
+           "ZAI_API_KEY": "ваш-ключ",
+           "ZAI_PROJECT_ROOT": "/путь/к/корню/проекта"
+         }
+       }
+     }
+   }
+   ```
+4. Убедитесь, что в PATH доступен тот же Python, в окружении которого установлен пакет (`pip install -e .`). Либо укажите полный путь к `python` в `command`.
+
+## Модели (work / fast)
+
+- Для основного цикла сессии в **solve_in_workspace** (need_more/done/use_tools) используется **work-модель** (по умолчанию **glm-4.7**, контекст 200K).
+- Для внутренней консолидации и суммаризации истории в **solve_in_workspace** используется **fast-модель** (по умолчанию **glm-4.5-air**, контекст 128K).
+- Выбор модели в вызовах MCP недоступен; при необходимости заменить дефолты задайте **ZAI_WORK_MODEL** и/или **ZAI_FAST_MODEL** в env.
+
+## Запуск
+
+Сервер запускается MCP-клиентом по stdio (Cursor сам стартует процесс по `mcp.json`). Ручной запуск для отладки:
+
+```bash
+export ZAI_API_KEY="ваш-ключ"
+python -m zai_coding_gateway.main --stdio
+```
+
+## Инструменты
+
+Порядок использования: **solve_in_workspace** → **apply_changes** → при необходимости **confirm_session_done**.
+
+### solve_in_workspace
+
+Точка входа: запускает сессию рабочего пространства. Модель получает полный контекст, может запрашивать файлы (need_more), использовать list_dir/grep/glob/read, вернуть отчёт и suggested_changes (в т.ч. предложения по новым файлам). Создание файлов в проекте — только через apply_changes после утверждения архитектором.
+
+**Вход:** `instruction` (строка — формулировка задачи), `todos` (список строк), `file_paths` (список путей относительно корня проекта, обязательный начальный контекст), `max_steps` (число, по умолчанию 10).
+
+**Выход:** `session_id` (строка), `report` (строка), `suggested_changes` (список объектов: каждый с полем `path` и полем `diff` или `content`), `files_used` (список путей).
+
+Лимит: 5 раундов инструментов за сессию. Логи: `workspace_sessions_logs/<session_id>.log` или каталог из `ZAI_SESSION_LOGS_DIR`.
+
+### apply_changes
+
+Применяет утверждённые изменения к проекту. Вызывать после solve_in_workspace, когда принято решение по suggested_changes.
+
+**Вход:** `session_id` (из ответа solve_in_workspace), `changes` (список объектов: каждый `{path: путь к файлу, content: новое содержимое}` или `{path, diff: unified diff или полный текст}`), `confirm_after` (bool, по умолчанию True — после применения очистить сессию). Пути должны входить в сессию.
+
+**Выход:** `session_id`, `applied` (список применённых путей), `cleaned` (bool).
+
+### confirm_session_done
+
+Очищает темп-каталог сессии после принятия решения (после apply_changes или при отказе от изменений).
+
+**Вход:** `session_id`. **Выход:** `session_id`, `cleaned` (true).
+
+## Режим «архитектор + разработчик»
+
+Один поток работы: сформулируйте задачу в **instruction** и **todos**, укажите **file_paths** (начальный контекст — существующие файлы). Запустите **solve_in_workspace** — модель получит контекст, при необходимости запросит ещё файлы или использует list_dir/grep/glob/read, затем вернёт отчёт и suggested_changes (в т.ч. предложения по новым файлам). Все изменения применяются только после вашего утверждения через **apply_changes** (или откажитесь и при необходимости вызовите **confirm_session_done**). Точечное чтение и запись файлов архитектор выполняет средствами IDE.
+
+## Тесты
+
+```bash
+pytest tests/ -v
+```
+
+Тесты используют мок Z.AI API (реальный ключ не нужен). E2E-тесты с реальным API помечены маркером `e2e` и выполняются только при заданном `ZAI_API_KEY`:
+
+```bash
+ZAI_API_KEY=ваш-ключ pytest tests/ -v -m e2e
+# или
+ZAI_API_KEY=ваш-ключ ./scripts/e2e_smoke.sh
+```
+
+**Боевой E2E** (`tests/test_e2e_battle.py`): тестовый проект в `tests/e2e_fixtures/battle_project/`. Тесты проверяют доступ к файлам проекта и solve_in_workspace (структура ответа). Запуск с ключом: `ZAI_API_KEY=... pytest tests/test_e2e_battle.py -v -m e2e`.
+
+В CI по умолчанию e2e не запускают.
+
+## Как проверить, что списывается Coding Plan (а не общий биллинг)
+
+1. **При старте MCP** в stderr выводится строка вида:  
+   `zai-coding-gateway: endpoint = https://api.z.ai/api/coding/paas/v4 (Coding Plan)`  
+   Если в скобках **Coding Plan** — запросы идут на подписку Coding Plan. Если **общий paas (не Coding Plan)** — используется общий endpoint (без `/coding/` в пути), и списание может идти с общего биллинга.
+
+2. **По умолчанию** (без `ZAI_BASE_URL`) используется `https://api.z.ai/api/coding/paas/v4` — это Coding Plan. Не задавайте `ZAI_BASE_URL`, если хотите использовать только Coding Plan.
+
+3. **Проверка в кабинете Z.AI** — в [использовании/биллинге](https://z.ai) посмотрите, по какому продукту идёт списание (Coding Plan vs общий API).
+
+4. **Кто решает, откуда списывать** — итоговая привязка к Coding Plan или к общему биллингу определяется политикой Z.AI (как правило, по вызываемому endpoint и/или по привязке API-ключа к продукту). Мы со своей стороны гарантируем только то, что запросы уходят на выбранный URL (по умолчанию Coding Plan); ключ вы задаёте в конфиге MCP. При сомнениях — уточните в документации или поддержке Z.AI.
+
+## Диагностика 401 (token expired or incorrect)
+
+Если E2E или вызовы из Cursor возвращают `401 - token expired or incorrect`:
+
+1. **Формат ключа** — Z.AI ожидает ключ вида `{id}.{secret}` и заголовок `Authorization: Bearer <ключ>`. Сервер уже отправляет ключ в этом формате; проверьте, что в `ZAI_API_KEY` нет лишних пробелов и кавычек.
+2. **Подписка Coding Plan** — endpoint `api.z.ai/api/coding/paas/v4` доступен только при активной подписке [GLM Coding Plan](https://docs.z.ai/devpack/overview). Убедитесь, что ключ создан для аккаунта с этой подпиской.
+3. **Проверка ключа на общем endpoint** — временно задайте `ZAI_BASE_URL=https://api.z.ai/api/paas/v4` и запустите E2E. Если с общим endpoint запрос проходит, а с Coding — 401, значит ключ или аккаунт не привязаны к Coding Plan.
+4. **Перевыпуск ключа** — в [управлении API-ключами](https://z.ai/manage-apikey/apikey-list) проверьте, что ключ активен; при необходимости создайте новый и подставьте в `ZAI_API_KEY`.
+
+## Транспорт и развёртывание
+
+Текущий режим — **stdio** (клиент запускает процесс). Развёртывание на удалённом сервере (StreamableHTTP) планируется в следующей итерации.
+
+## Лицензия
+
+MIT.

zai_coding_gateway-0.1.0/README.md

@@ -0,0 +1,156 @@
+# ZAI Coding Gateway
+
+MCP-сервер для решения задач в рабочем пространстве через **Z.AI Coding Plan** endpoint (`api.z.ai/api/coding/paas/v4`). Предоставляет инструменты `solve_in_workspace`, `apply_changes`, `confirm_session_done` для любых MCP-клиентов (Cursor, Anigravity, Claude Code, Cline и др.). Один и тот же сервер можно добавить в любую IDE — поведение не зависит от того, откуда вы его запускаете.
+
+## Требования
+
+- Python 3.11+
+- Ключ Z.AI и подписка Coding Plan
+
+## Установка
+
+```bash
+pip install -e .
+# или с тестами:
+pip install -e ".[dev]"
+```
+
+## Настройка
+
+Все настройки задаются **переменными окружения**. Ключ и модель **не хранятся в коде** — их задаёт пользователь в настройках MCP-клиента (например, в Cursor в `mcp.json` в секции `env`).
+
+| Переменная     | Назначение                                      |
+|----------------|--------------------------------------------------|
+| `ZAI_API_KEY`  | Ключ Z.AI (обязательный)                        |
+| `ZAI_WORK_MODEL` | Необязательно. Модель для генерации кода, рефакторинга и основного цикла сессии. По умолчанию **glm-4.7** (контекст 200K). |
+| `ZAI_FAST_MODEL` | Необязательно. Модель для консолидации и суммаризации внутри сессии. По умолчанию **glm-4.5-air** (контекст 128K, быстрая). |
+| `ZAI_BASE_URL` | По умолчанию `https://api.z.ai/api/coding/paas/v4` |
+| `ZAI_PROJECT_ROOT` | Корень открытого проекта для solve_in_workspace (пути file_paths и сессия). **Чтобы из любой IDE всё работало «как по маслу»**, задайте эту переменную в конфиге MCP так, чтобы она указывала на папку открытого в IDE проекта. Многие IDE при старте MCP подставляют в env переменные вроде `${workspaceFolder}` / `${projectPath}` — тогда один конфиг подходит для Cursor, Anigravity и др. Без неё сервер пробует MCP `roots/list` (многие клиенты пока не поддерживают) или поиск вверх от cwd по маркерам; при неудаче — явная ошибка с просьбой задать ZAI_PROJECT_ROOT. |
+| `ZAI_SESSION_LOGS_DIR` | Опционально. Каталог для логов сессий solve_in_workspace. По умолчанию логи пишутся в проект gateway (для разработчиков). Если нужно получать логи в свой проект — укажите абсолютный путь к каталогу (например `${workspaceFolder}/workspace_sessions_logs`). |
+
+## Работа из любой IDE
+
+MCP запускается вашей IDE при открытии проекта. Чтобы пути file_paths/file_path и сессия solve_in_workspace относились к открытому проекту (а не к случайному cwd), в настройках MCP укажите **ZAI_PROJECT_ROOT** в `env`. Тогда не важно, в какой IDE вы работаете (Cursor, Anigravity, другая):
+
+- Если IDE при запуске MCP подставляет в env путь к открытому проекту (например через переменную вроде `${workspaceFolder}`, `${workspaceRoot}`, `%projectPath%` и т.п.) — используйте её для `ZAI_PROJECT_ROOT`. Один и тот же конфиг будет работать во всех проектах и во всех таких IDE.
+- Если такой подстановки нет — укажите в конфиге абсолютный путь к корню проекта; для другого проекта можно завести отдельный конфиг или переопределить env в настройках проекта/workspace.
+
+Идея: **корень проекта задаёт тот, кто запускает MCP (IDE)**, через env — тогда серверу не нужно угадывать, и поведение едино во всех средах.
+
+## Подключение в Cursor
+
+1. Скопируйте пример конфигурации:
+   ```bash
+   cp mcp.json.example mcp.json
+   ```
+2. Откройте `mcp.json` и в секции `env` подставьте свой `ZAI_API_KEY`.
+3. Добавьте содержимое `mcp.json` в настройки MCP Cursor (например, в `~/.cursor/mcp.json` или в настройках проекта в разделе MCP Servers). **При использовании в другом проекте** укажите в `env` путь к корню этого проекта: `"ZAI_PROJECT_ROOT": "/путь/к/проекту"` (Cursor пока не передаёт workspace через MCP roots/list). Формат:
+   ```json
+   {
+     "mcpServers": {
+       "zai-coding-gateway": {
+         "command": "/путь/к/.venv/bin/python",
+         "args": ["-m", "zai_coding_gateway.main", "--stdio"],
+         "env": {
+           "ZAI_API_KEY": "ваш-ключ",
+           "ZAI_PROJECT_ROOT": "/путь/к/корню/проекта"
+         }
+       }
+     }
+   }
+   ```
+4. Убедитесь, что в PATH доступен тот же Python, в окружении которого установлен пакет (`pip install -e .`). Либо укажите полный путь к `python` в `command`.
+
+## Модели (work / fast)
+
+- Для основного цикла сессии в **solve_in_workspace** (need_more/done/use_tools) используется **work-модель** (по умолчанию **glm-4.7**, контекст 200K).
+- Для внутренней консолидации и суммаризации истории в **solve_in_workspace** используется **fast-модель** (по умолчанию **glm-4.5-air**, контекст 128K).
+- Выбор модели в вызовах MCP недоступен; при необходимости заменить дефолты задайте **ZAI_WORK_MODEL** и/или **ZAI_FAST_MODEL** в env.
+
+## Запуск
+
+Сервер запускается MCP-клиентом по stdio (Cursor сам стартует процесс по `mcp.json`). Ручной запуск для отладки:
+
+```bash
+export ZAI_API_KEY="ваш-ключ"
+python -m zai_coding_gateway.main --stdio
+```
+
+## Инструменты
+
+Порядок использования: **solve_in_workspace** → **apply_changes** → при необходимости **confirm_session_done**.
+
+### solve_in_workspace
+
+Точка входа: запускает сессию рабочего пространства. Модель получает полный контекст, может запрашивать файлы (need_more), использовать list_dir/grep/glob/read, вернуть отчёт и suggested_changes (в т.ч. предложения по новым файлам). Создание файлов в проекте — только через apply_changes после утверждения архитектором.
+
+**Вход:** `instruction` (строка — формулировка задачи), `todos` (список строк), `file_paths` (список путей относительно корня проекта, обязательный начальный контекст), `max_steps` (число, по умолчанию 10).
+
+**Выход:** `session_id` (строка), `report` (строка), `suggested_changes` (список объектов: каждый с полем `path` и полем `diff` или `content`), `files_used` (список путей).
+
+Лимит: 5 раундов инструментов за сессию. Логи: `workspace_sessions_logs/<session_id>.log` или каталог из `ZAI_SESSION_LOGS_DIR`.
+
+### apply_changes
+
+Применяет утверждённые изменения к проекту. Вызывать после solve_in_workspace, когда принято решение по suggested_changes.
+
+**Вход:** `session_id` (из ответа solve_in_workspace), `changes` (список объектов: каждый `{path: путь к файлу, content: новое содержимое}` или `{path, diff: unified diff или полный текст}`), `confirm_after` (bool, по умолчанию True — после применения очистить сессию). Пути должны входить в сессию.
+
+**Выход:** `session_id`, `applied` (список применённых путей), `cleaned` (bool).
+
+### confirm_session_done
+
+Очищает темп-каталог сессии после принятия решения (после apply_changes или при отказе от изменений).
+
+**Вход:** `session_id`. **Выход:** `session_id`, `cleaned` (true).
+
+## Режим «архитектор + разработчик»
+
+Один поток работы: сформулируйте задачу в **instruction** и **todos**, укажите **file_paths** (начальный контекст — существующие файлы). Запустите **solve_in_workspace** — модель получит контекст, при необходимости запросит ещё файлы или использует list_dir/grep/glob/read, затем вернёт отчёт и suggested_changes (в т.ч. предложения по новым файлам). Все изменения применяются только после вашего утверждения через **apply_changes** (или откажитесь и при необходимости вызовите **confirm_session_done**). Точечное чтение и запись файлов архитектор выполняет средствами IDE.
+
+## Тесты
+
+```bash
+pytest tests/ -v
+```
+
+Тесты используют мок Z.AI API (реальный ключ не нужен). E2E-тесты с реальным API помечены маркером `e2e` и выполняются только при заданном `ZAI_API_KEY`:
+
+```bash
+ZAI_API_KEY=ваш-ключ pytest tests/ -v -m e2e
+# или
+ZAI_API_KEY=ваш-ключ ./scripts/e2e_smoke.sh
+```
+
+**Боевой E2E** (`tests/test_e2e_battle.py`): тестовый проект в `tests/e2e_fixtures/battle_project/`. Тесты проверяют доступ к файлам проекта и solve_in_workspace (структура ответа). Запуск с ключом: `ZAI_API_KEY=... pytest tests/test_e2e_battle.py -v -m e2e`.
+
+В CI по умолчанию e2e не запускают.
+
+## Как проверить, что списывается Coding Plan (а не общий биллинг)
+
+1. **При старте MCP** в stderr выводится строка вида:  
+   `zai-coding-gateway: endpoint = https://api.z.ai/api/coding/paas/v4 (Coding Plan)`  
+   Если в скобках **Coding Plan** — запросы идут на подписку Coding Plan. Если **общий paas (не Coding Plan)** — используется общий endpoint (без `/coding/` в пути), и списание может идти с общего биллинга.
+
+2. **По умолчанию** (без `ZAI_BASE_URL`) используется `https://api.z.ai/api/coding/paas/v4` — это Coding Plan. Не задавайте `ZAI_BASE_URL`, если хотите использовать только Coding Plan.
+
+3. **Проверка в кабинете Z.AI** — в [использовании/биллинге](https://z.ai) посмотрите, по какому продукту идёт списание (Coding Plan vs общий API).
+
+4. **Кто решает, откуда списывать** — итоговая привязка к Coding Plan или к общему биллингу определяется политикой Z.AI (как правило, по вызываемому endpoint и/или по привязке API-ключа к продукту). Мы со своей стороны гарантируем только то, что запросы уходят на выбранный URL (по умолчанию Coding Plan); ключ вы задаёте в конфиге MCP. При сомнениях — уточните в документации или поддержке Z.AI.
+
+## Диагностика 401 (token expired or incorrect)
+
+Если E2E или вызовы из Cursor возвращают `401 - token expired or incorrect`:
+
+1. **Формат ключа** — Z.AI ожидает ключ вида `{id}.{secret}` и заголовок `Authorization: Bearer <ключ>`. Сервер уже отправляет ключ в этом формате; проверьте, что в `ZAI_API_KEY` нет лишних пробелов и кавычек.
+2. **Подписка Coding Plan** — endpoint `api.z.ai/api/coding/paas/v4` доступен только при активной подписке [GLM Coding Plan](https://docs.z.ai/devpack/overview). Убедитесь, что ключ создан для аккаунта с этой подпиской.
+3. **Проверка ключа на общем endpoint** — временно задайте `ZAI_BASE_URL=https://api.z.ai/api/paas/v4` и запустите E2E. Если с общим endpoint запрос проходит, а с Coding — 401, значит ключ или аккаунт не привязаны к Coding Plan.
+4. **Перевыпуск ключа** — в [управлении API-ключами](https://z.ai/manage-apikey/apikey-list) проверьте, что ключ активен; при необходимости создайте новый и подставьте в `ZAI_API_KEY`.
+
+## Транспорт и развёртывание
+
+Текущий режим — **stdio** (клиент запускает процесс). Развёртывание на удалённом сервере (StreamableHTTP) планируется в следующей итерации.
+
+## Лицензия
+
+MIT.

zai_coding_gateway-0.1.0/mcp.json.example

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "zai-coding-gateway": {
+      "command": "python",
+      "args": ["-m", "zai_coding_gateway.main", "--stdio"],
+      "env": {
+        "ZAI_API_KEY": "<подставьте свой ключ Z.AI>",
+        "ZAI_PROJECT_ROOT": "<рекомендуется: путь к корню открытого проекта; во многих IDE можно использовать переменную типа ${workspaceFolder}>"
+      }
+    }
+  }
+}

zai_coding_gateway-0.1.0/pypi_credentials.env.example

@@ -0,0 +1,10 @@
+# Учётные данные для загрузки пакета на PyPI.
+# PyPI больше НЕ принимает пароль от аккаунта — только API token!
+# 1. Создайте токен: https://pypi.org/manage/account/token/ → Add API token
+# 2. Скопируйте этот файл: cp pypi_credentials.env.example pypi_credentials.env
+# 3. Вставьте токен в TWINE_PASSWORD (целиком, вид pypi-AgEIcHlwaS5vcmc...)
+# Логин всегда __token__ (два подчёркивания с обеих сторон), не ваш username.
+# Файл pypi_credentials.env в .gitignore, в репозиторий не попадёт.
+
+TWINE_USERNAME=__token__
+TWINE_PASSWORD=pypi-ВСТАВЬТЕ_СЮДА_ВАШ_API_ТОКЕН_С_PYPI_ORG

zai_coding_gateway-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "zai-coding-gateway"
+version = "0.1.0"
+description = "MCP-сервер для решения задач в рабочем пространстве через Z.AI Coding Plan (solve_in_workspace, apply_changes)"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = []
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development",
+]
+dependencies = [
+    "mcp>=1.0.0",
+    "openai>=1.0.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "respx>=0.20.0",
+]
+
+[project.scripts]
+zai-coding-gateway = "zai_coding_gateway.main:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/zai_coding_gateway"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+pythonpath = ["src"]
+markers = [
+    "e2e: end-to-end test with real Z.AI API (run only when ZAI_API_KEY is set)",
+]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true

zai_coding_gateway-0.1.0/scripts/e2e_smoke.sh

@@ -0,0 +1,13 @@
+#!/usr/bin/env bash
+# E2E smoke: запуск e2e-тестов только при заданном ZAI_API_KEY.
+# В CI по умолчанию не запускать (нет ключа).
+
+set -e
+cd "$(dirname "$0")/.."
+
+if [ -z "${ZAI_API_KEY}" ]; then
+  echo "ZAI_API_KEY не задан — e2e пропущены."
+  exit 0
+fi
+
+.venv/bin/python -m pytest tests/ -v -m e2e 2>&1

zai_coding_gateway-0.1.0/scripts/upload_to_pypi.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Сборка пакета и загрузка на PyPI.
+# Нужен файл pypi_credentials.env с TWINE_USERNAME=__token__ и TWINE_PASSWORD=<API token с pypi.org>.
+set -e
+cd "$(dirname "$0")/.."
+if [ ! -f pypi_credentials.env ]; then
+  echo "Создайте pypi_credentials.env (см. pypi_credentials.env.example)."
+  exit 1
+fi
+set -a
+source pypi_credentials.env
+set +a
+if [ -z "$TWINE_PASSWORD" ]; then
+  echo "В pypi_credentials.env задайте TWINE_PASSWORD (API token с https://pypi.org/manage/account/token/)."
+  exit 1
+fi
+if [ "$TWINE_USERNAME" != "__token__" ]; then
+  echo "Для API token TWINE_USERNAME должен быть __token__. Сейчас: $TWINE_USERNAME"
+  exit 1
+fi
+echo "Сборка пакета..."
+python -m build
+echo "Загрузка на PyPI..."
+twine upload dist/*
+echo "Готово."

zai_coding_gateway-0.1.0/src/zai_coding_gateway/__init__.py

@@ -0,0 +1,3 @@
+"""ZAI Coding Gateway — MCP-сервер для решения задач в рабочем пространстве через Z.AI Coding Plan."""
+
+__version__ = "0.1.0"

zai_coding_gateway-0.1.0/src/zai_coding_gateway/client.py

@@ -0,0 +1,93 @@
+"""Обёртка над OpenAI-клиентом для Z.AI Coding Plan endpoint."""
+
+import os
+from typing import Any
+
+from openai import OpenAI
+
+from zai_coding_gateway.errors import QuotaExceededError
+
+
+def _is_quota_error(exc: Exception) -> bool:
+    """Определяет по исключению, что это исчерпание квоты (429 / quota / rate limit)."""
+    status = getattr(exc, "status_code", None)
+    if status == 429:
+        return True
+    msg = str(exc).lower()
+    if "429" in msg or "quota" in msg or "rate limit" in msg or "rate_limit" in msg:
+        return True
+    return False
+
+DEFAULT_BASE_URL = "https://api.z.ai/api/coding/paas/v4"
+DEFAULT_WORK_MODEL = "glm-4.7"
+DEFAULT_FAST_MODEL = "glm-4.5-air"
+
+
+def _get_env(key: str, default: str | None = None) -> str | None:
+    return os.environ.get(key) or default
+
+
+def get_effective_base_url() -> str:
+    """Возвращает URL, который будет использоваться для запросов (из env или дефолт). Для проверки биллинга."""
+    return (_get_env("ZAI_BASE_URL") or DEFAULT_BASE_URL).rstrip("/") + "/"
+
+
+def get_work_model() -> str:
+    """Модель для основного цикла сессии solve_in_workspace. По умолчанию glm-4.7."""
+    v = (_get_env("ZAI_WORK_MODEL") or "").strip()
+    return v or DEFAULT_WORK_MODEL
+
+
+def get_fast_model() -> str:
+    """Модель для консолидации и суммаризации в solve_in_workspace. По умолчанию glm-4.5-air."""
+    v = (_get_env("ZAI_FAST_MODEL") or "").strip()
+    return v or DEFAULT_FAST_MODEL
+
+
+def create_client() -> OpenAI:
+    """Создаёт OpenAI-клиент с base_url и api_key из ENV. Ключ только из окружения."""
+    api_key = _get_env("ZAI_API_KEY")
+    if not api_key:
+        raise ValueError("ZAI_API_KEY не задан. Укажите ключ в env (например в mcp.json).")
+    base_url = get_effective_base_url()
+    return OpenAI(api_key=api_key, base_url=base_url)
+
+
+def chat_completions(
+    client: OpenAI,
+    messages: list[dict[str, Any]],
+    model: str,
+    response_format: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """
+    Вызов chat/completions. При исчерпании квоты выбрасывает QuotaExceededError.
+    model: передавать get_work_model() или get_fast_model() в зависимости от сценария.
+    """
+    kwargs: dict[str, Any] = {"model": model, "messages": messages, "stream": False}
+    if response_format is not None:
+        kwargs["response_format"] = response_format
+    try:
+        resp = client.chat.completions.create(**kwargs)
+    except QuotaExceededError:
+        raise
+    except Exception as e:  # noqa: BLE001
+        if _is_quota_error(e):
+            raise QuotaExceededError("QuotaExceeded: wait for refresh cycle") from e
+        raise
+    return _completion_to_dict(resp)
+
+
+def _completion_to_dict(resp: Any) -> dict[str, Any]:
+    """Преобразует объект Completion в dict для единообразного разбора."""
+    return {
+        "choices": [
+            {
+                "message": {
+                    "content": c.message.content,
+                    "role": getattr(c.message, "role", "assistant"),
+                }
+            }
+            for c in (resp.choices or [])
+        ],
+        "usage": getattr(resp, "usage", None),
+    }