teletype-mcp-server 0.1.0 → 0.1.1

package/docs/ru/CONTRIBUTING.md

@@ -23,6 +23,8 @@
 1. Откройте доступ к `https://github.com/Teletype-App/teletype-mcp-server` и проверьте адрес репозитория в `package.json` и `server.json`.
 2. Запустите `https://mcp.teletype.app/mcp` по HTTPS. Выполните `TELETYPE_API_TOKEN=... npm run hosted:smoke` с токеном проекта, чтобы проверить MCP-подключение и чтение через Teletype Public API. Команда не печатает данные проекта или токен.
 3. Убедитесь, что имя `teletype-mcp-server` свободно в npm, и настройте Trusted Publisher. Поле `mcpName` в `package.json` должно совпадать с именем в `server.json`.
-4. Обновите версии пакета и записи для реестра вместе. Выполните `npm run check`, `npm run package:smoke`, `npm run mcp:conformance`, `npm run bundle:mcpb` и `GITHUB_REF_NAME=v<версия> npm run release:verify`. Проверьте `server.json` официальной командой `mcp-publisher validate`.
+4. Обновите версии пакета и записи для реестра вместе. Выполните `npm run check`, `npm run package:smoke`, `npm run mcp:conformance`, `npm run bundle:mcpb` и `GITHUB_REF_NAME=v<версия> npm run release:verify`. Проверьте `server.json` по официальной схеме из его поля `$schema`.
 
-Когда процесс выпуска опубликует npm-пакет, Docker-образ и файл `.mcpb`, проверьте их публичные адреса. Затем авторизуйтесь в [MCP Registry](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/quickstart.mdx) и выполните `mcp-publisher publish server.json`. Реестр требует, чтобы указанная версия npm-пакета и удалённый адрес уже работали. Публикация в реестре выполняется отдельным шагом.
+После публикации npm процесс выпуска вызывает `publish-registry.yml`. Он сверяет тег, ждёт появления npm-версии и публикует `server.json` через [GitHub OIDC](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/github-actions.mdx). Отдельный секрет для Registry не нужен. При ошибке запустите **Publish MCP Registry** вручную с существующим тегом релиза. После выпуска проверьте адреса npm, Registry, Docker и `.mcpb`. Удалённый MCP-эндпоинт должен уже работать.
+
+Обновляйте версии манифеста LobeHub, расширения Gemini, трёх манифестов плагина, маркетплейсов Claude и Cursor, MCPB и закреплённых npm-запусков вместе с версией пакета. `release:verify` проверяет их согласованность. При изменении инструментов, ресурсов или промптов обновляйте массивы возможностей в манифесте LobeHub.

package/docs/ru/OAUTH.md

@@ -0,0 +1,54 @@
+[English](../OAUTH.md) | Русский
+
+# OAuth для собственного HTTP-сервера
+
+На публичном сервере `https://mcp.teletype.app/mcp` OAuth выключен. Для подключения нужен токен проекта в заголовке `X-Teletype-Api-Token`. Эта инструкция описывает включение OAuth на собственном сервере.
+
+OAuth включается отдельно и по умолчанию отключён. Он добавляет подключение через браузер поверх существующего токена проекта Teletype Public API. OAuth-провайдер внутри Teletype не нужен. Пользователь открывает страницу из MCP-клиента, вводит токен своего проекта и подтверждает доступ. Сервер проверяет токен через Teletype, затем выдаёт клиенту отдельные OAuth-токены.
+
+Страница подключения доступна на русском и английском. Сначала язык выбирается по настройкам браузера. Ручной выбор сохраняется в cookie. Переключение языка сохраняет введённый токен и разрешения. Ссылка «Где взять токен» открывает [настройки Public API Teletype](https://panel.teletype.app/settings/public-api) в новой вкладке.
+
+## Включение
+
+Нужен Node.js 22.13+ или 24.x. На Node.js 20 продолжают работать stdio и HTTP с токеном проекта в заголовке, но OAuth с SQLite недоступен.
+
+Задайте переменные в приватном окружении сервера:
+
+```dotenv
+OAUTH_ENABLED=true
+PUBLIC_BASE_URL=https://your-mcp-domain.example
+OAUTH_DB_PATH=/var/lib/teletype-mcp/oauth.sqlite
+OAUTH_ENCRYPTION_KEY=<64-character hex key>
+```
+
+Один раз создайте ключ командой `openssl rand -hex 32` и сохраните его в хранилище секретов. После перезапуска нужен тот же ключ. `PUBLIC_BASE_URL` должен содержать публичный HTTPS origin. HTTP допускается только на loopback для локальной разработки. Проксируйте `/mcp`, `/authorize`, `/oauth/consent`, `/oauth/assets/*`, `/token`, `/register`, `/revoke` и `/.well-known/*` на сервер.
+
+Каталог базы должен быть доступен на запись пользователю сервера и сохраняться между развёртываниями. Docker-образ готовит `/data` для пользователя `node`. Подключите named volume в `/data` и задайте `OAUTH_DB_PATH=/data/oauth.sqlite`. Для bind mount передайте каталог на хосте тому же пользователю. SQLite должна находиться на локальном диске. Такой вариант подходит для одного хоста. Репликам на разных машинах потребуется другая реализация общего хранилища.
+
+Подключение через `X-Teletype-Api-Token` продолжает работать. OAuth-клиенты передают `Authorization: Bearer <OAuth access token>`. Токен проекта Teletype не является OAuth bearer-токеном. В одном запросе нельзя использовать оба способа авторизации.
+
+## Права и сроки
+
+Клиент получает сведения о ресурсе через `/.well-known/oauth-protected-resource/mcp`, а о сервере авторизации через `/.well-known/oauth-authorization-server`. Регистрация, обмен кода с PKCE S256, обновление и отзыв токенов используют маршруты выше.
+
+| Scope | Доступ |
+| --- | --- |
+| `read` | Чтение данных проекта. Обязателен для каждого подключения |
+| `write` | Пишущие инструменты и отметка диалогов прочитанными. Выдаётся только после отдельного разрешения на странице подключения |
+| `offline_access` | Автоматическое продление доступа до отзыва подключения |
+
+Access-токен действует до часа. С `offline_access` клиент получает новые access-токены без повторного подключения пользователя. Само подключение не имеет фиксированного срока действия. Без `offline_access` оно заканчивается через час. Refresh-токен заменяется при каждом использовании. Повторное использование старого refresh-токена отзывает всё подключение. При обновлении можно уменьшить права, но нельзя добавить новые.
+
+Регистрация клиента сохраняется, пока у него есть подключения с продлением доступа. У секрета клиента нет отдельного срока действия. Без подключений с продлением регистрация действует 30 дней. Отзыв одного подключения не прерывает остальные подключения того же клиента.
+
+Общие ограничения read-only и toolsets действуют и для OAuth. Требование `confirm: true` у пишущих инструментов сохраняется. Права OAuth не заменяют разрешение пользователя на конкретное действие.
+
+## Хранение и восстановление
+
+SQLite хранит регистрации клиентов, ожидающие подтверждения, одноразовые коды, подключения и хеши токенов. Содержимое записей, включая токен проекта, зашифровано AES-256-GCM. Для access-токенов, кодов и браузерных секретов используются хеши SHA-256. У каждого подключения хранится только хеш текущего refresh-токена. Сервер подписывает идентификатор подключения внутри refresh-токена с помощью HMAC. Это позволяет распознавать повторное использование старых токенов без хранения всей их истории. Клиент получает OAuth-токены, исходный токен Teletype ему не передаётся.
+
+Погашение кода, замена refresh-токена и отзыв выполняются в коротких транзакциях. Просроченные записи не дают доступ и удаляются при записи в базу. Файл базы создаётся с правами только для владельца. SQLite-файлы исключены из Git и контекста Docker-сборки.
+
+Делайте копию базы при остановленном сервере, ключ храните отдельно. Для восстановления нужны оба файла и тот же публичный origin. Неверный ключ или другой origin не позволят серверу запуститься. Замена ключа не является механизмом ротации. Удаление базы сбросит все OAuth-подключения, пользователям придётся подключиться заново. Для отзыва одного подключения используйте действие отключения в клиенте, которое вызывает `/revoke`. Отзыв токена проекта в Teletype также блокирует дальнейшие операции Public API для всех подключений с этим токеном.
+
+Отозванное подключение удаляется сразу. Просроченные подключения удаляются при следующей записи в базу. Обработчики OAuth не пишут тела запросов и секреты в журнал. Настройте журнал обратного прокси так, чтобы он не сохранял тела форм и заголовки авторизации.

package/docs/ru/SECURITY.md

@@ -4,6 +4,8 @@
 
 Сообщайте об уязвимостях приватно на адрес [контакта Teletype по Public API](https://teletype.app/help/api/) [p@teletype.app](mailto:p@teletype.app). Не публикуйте их в issue. В сообщении укажите затронутые версии, шаги воспроизведения и возможные последствия.
 
-HTTP-транспорт требует `X-Teletype-Api-Token` в каждом MCP-запросе и передаёт его в Teletype. Отдельных пользователей и прав в MCP-сервере нет. Для удалённого доступа используйте HTTPS и считайте токен ключом ко всему проекту. Сервер проверяет наличие токена, а Teletype проверяет его действительность при вызове Public API.
+По умолчанию HTTP-транспорт требует `X-Teletype-Api-Token` в каждом MCP-запросе и передаёт его в Teletype. Для удалённого доступа используйте HTTPS и считайте токен ключом ко всему проекту. Teletype проверяет его действительность при вызове Public API.
+
+На публичном сервере OAuth выключен. При явном включении [OAuth](OAUTH.md) на собственном сервере он проверяет токен проекта при подключении, хранит его в зашифрованной записи SQLite и выдаёт клиенту отдельные bearer-токены с правами чтения и записи. Эти токены действуют только для ресурса `/mcp` данного сервера. OAuth без права записи блокирует изменения даже на сервере с включёнными пишущими инструментами. Ограничения сервера и явное подтверждение записей сохраняются. Повторное использование старого refresh-токена отзывает подключение. Храните базу и ключ шифрования приватно, резервные копии делайте отдельно.
 
 Загрузка локальных файлов через `attachment_path` доступна только в stdio-режиме.

package/examples/clients/goose-stdio.yaml

@@ -0,0 +1,13 @@
+extensions:
+  teletype:
+    name: teletype
+    type: stdio
+    enabled: true
+    cmd: npx
+    args:
+      - -y
+      - teletype-mcp-server
+      - --stdio
+    envs:
+      TELETYPE_API_TOKEN: your-teletype-public-api-token
+    timeout: 300

package/examples/clients/openclaw.json

@@ -0,0 +1,13 @@
+{
+  "mcp": {
+    "servers": {
+      "teletype": {
+        "url": "https://mcp.teletype.app/mcp",
+        "transport": "streamable-http",
+        "headers": {
+          "X-Teletype-Api-Token": "${TELETYPE_API_TOKEN}"
+        }
+      }
+    }
+  }
+}

package/gemini-extension.json

@@ -0,0 +1,22 @@
+{
+  "name": "teletype",
+  "version": "0.1.1",
+  "description": "Teletype customer support: triage conversations, read customer history, draft replies, and hand over shifts.",
+  "mcpServers": {
+    "teletype": {
+      "httpUrl": "https://mcp.teletype.app/mcp",
+      "headers": {
+        "X-Teletype-Api-Token": "${TELETYPE_API_TOKEN}"
+      }
+    }
+  },
+  "contextFileName": "plugin/skills/teletype-support/SKILL.md",
+  "settings": [
+    {
+      "name": "Teletype Public API token",
+      "description": "Project token from Teletype settings. The assistant can access this project's conversations and customer data.",
+      "envVar": "TELETYPE_API_TOKEN",
+      "sensitive": true
+    }
+  ]
+}