mcgl-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 exi66
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,197 @@
-# Temporary Holding Version
+# mcgl-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MCP-сервер для форума [Minecraft Galaxy](https://forum.minecraft-galaxy.ru/main/). API у форума нет, поэтому сервер ходит на него как браузер: HTML, формы, кука `PHPSESSID`.
+
+**Текущее состояние:** авторизация игрока и чтение общего форума. Действий от лица игрока пока нет.
+
+## Инструменты
+
+Все инструменты публичные: авторизация не нужна, работают в обоих режимах. В локальном режиме с кредами страницы читаются залогиненным.
+
+| Инструмент | Страница | Что возвращает |
+|---|---|---|
+| `forum_list_sections` | `/main/` | разделы 1..11 по категориям: описание, число тем и ответов, последнее сообщение |
+| `forum_latest_topics` | `/forum/0/{page}` | последние темы всех разделов, у каждой указан раздел |
+| `forum_list_topics` | `/forum/{id}/{page}` | темы раздела: закреплена, закрыта (зачёркнута), кто может отвечать (`all`/`vip`/`premium_platinum`/`moderators`), автор, ответы, число страниц, последнее сообщение |
+| `forum_get_topic` | `/topic/{id}/{page}` | без `page` — последние 15 постов темы; с `page` — страницы по 15 от начала (`pageSize` 1..50). Всего постов и страниц; в режиме «последние» и на 1-й странице ещё опрос, системные сообщения («перемещено из…») и кто читает сейчас |
+| `forum_get_post` | `/post/{id}` | один пост с номером в теме, его тема и страница `forum_get_topic`, на которой он находится |
+
+В инструментах страницы нумеруются с 1, в URL форума — с 0.
+
+**Пагинация тем.** Форум показывает на странице столько постов, сколько задано в настройках игрока (у гостя и игроков бывает 15…100). Агенту сто постов за раз дорого, поэтому `forum_get_topic` отдаёт свои страницы фиксированного размера поверх пагинации форума. Номера постов `#N` в теме сквозные, удалённые тоже нумеруются, так что страница `v` — это посты `#(v-1)*15+1 … #v*15`. Без `page` отдаются последние 15 постов: в больших темах обычно нужен конец. Если тема недавно встречалась в списке тем, там уже было число её страниц, и `ForumReader` открывает последнюю страницу форума одним запросом. Если тема с тех пор выросла на новую страницу, это видно по пагинации, и reader идёт обычным путём. Размер страницы форума `ForumReader` узнаёт по первой (или последней) странице темы и перепроверяет по номерам: если игрок поменял настройку, пересчитывает. Разобранные страницы форума кешируются на 60 секунд, чтобы листание темы не скачивало их заново.
+
+**Недоступность форума.** GET повторяется до 3 раз при сетевой ошибке, таймауте или 5xx, с паузами 1 и 2 секунды. POST не повторяется: повтор может создать дубль поста. После 2 подряд неудачных запросов срабатывает circuit breaker (`src/forum/health.ts`): 30 секунд запросы на форум не идут, инструменты сразу отвечают «форум не отвечает, повтори через N секунд». Затем проходит один пробный запрос. Состояние видно в `/health` HTTP-режима.
+
+Пост содержит номер, id, автора (ник, id, группа, статус, клан со званием, число ответов), дату, текст и рейтинг. Удалённый пост возвращается как `{deleted: true, number, id}`. Если аккаунт автора удалён или заблокирован (на форуме это `player$0`), у автора стоит `accountDeleted: true`.
+
+Текст поста получается из отрендеренного bbCode ([справка](https://forum.minecraft-galaxy.ru/wiki/201)):
+
+- `[quote: ник] … [/quote]`, `[spoiler: заголовок] … [/spoiler]`;
+- `[image: url]`, `[video: url]`, `[audio: url]`;
+- предметы — `[Золотой блок #41]`, с метадатой — `[Красная шерсть #35:14]`;
+- окна крафта, печи и наковальни — `[craft]`: сетка id предметов (`-` — пустой слот, `->` — результат, `x4` — количество) и легенда `124 = Ажурный камень`;
+- таблицы — ячейками через `|`, списки — с `- `;
+- ссылки — как `текст (url)`, редиректы форума раскрываются.
+
+Названия предметов берутся из эндпоинта подсказок форума `/object/{id}/2?d={meta}` (`src/forum/objects.ts`). Кеш живёт весь процесс. За один вызов инструмента делается не больше 25 новых запросов, остальные предметы остаются как `[item #id]`. Тот же эндпоинт отдаёт карточку игрока (тип 1) и сообщества (тип 3).
+
+### Экономия токенов
+
+- Описания инструментов и служебные маркеры в тексте — на английском и в ASCII. Контент форума остаётся как есть, на русском.
+- Ответы — компактный JSON без отступов.
+- Флаги `false` не отдаются (`pinned`, `closed`, `deleted`, `accountDeleted` есть только при `true`); об этом сказано в описаниях инструментов.
+
+Парсеры в `src/forum/parsers/` общие: списки тем и страницы тем одинаково свёрстаны во всём форуме, включая сообщества (`/htopic/N`, `/hpost/N`).
+
+## Режимы
+
+| Режим | Транспорт | Инструменты | Авторизация |
+|---|---|---|---|
+| Локальный | stdio | публичные + от лица игрока | логин и пароль игрока в env клиента |
+| Хост | Streamable HTTP, `POST /public/mcp` | только публичные | нет (пока) |
+
+## Авторизация на форуме
+
+1. `GET /guilogin/`: из формы `form[action="/login.php"]` берутся скрытые поля `form`, `ref`, `fcode`, `recap`.
+2. `POST /login.php` с этими полями плюс `login` и `pass`.
+   - Успех: 302 на `/main/`, в шапке появляется ник (`a.button[href="/profilemain/"] .text`).
+   - Неудача: 302 на `/guilogin/4?f=N` с плашкой `table.alert td.caption` («Введенный логин или пароль неверны! Попыток входа осталось: N…»).
+3. Гостевая страница определяется по кнопке «Войти» в шапке (`a.button[href="/guilogin/"]`). Форма ответа в теме видна и гостю, поэтому по ней судить о логине нельзя.
+
+Особенности форума:
+
+- **`fcode` обязателен.** Без него вход отклоняется и списывается попытка.
+- **reCAPTCHA v3 сервер не проверяет**, `recap` уходит пустым.
+- **У входов есть лимит попыток.** Поэтому после неудачного логина `PlayerSession` больше не пробует войти, пока процесс не перезапустят.
+- **Протухшая сессия переустанавливается сама.** Если страница пришла гостевой, бросается `SessionExpiredError`, сессия перелогинивается и повторяет операцию один раз.
+
+Проверка без MCP (креды из `.env`): `pnpm check:login`. Скрипт логинится, повторно использует сессию и имитирует её протухание. Каждый запуск тратит 2 входа.
+
+## Локальный режим
+
+Нужен Node.js 22+. Ставить отдельно ничего не надо: клиент сам запустит пакет через `npx`.
+
+**Claude Code:**
+
+```bash
+claude mcp add mcgl -e FORUM_LOGIN=ник -e FORUM_PASSWORD=пароль -- npx -y mcgl-mcp
+```
+
+**Claude Desktop, Cursor и другие** (`claude_desktop_config.json`, `.cursor/mcp.json` и т.п.):
+
+```json
+{
+  "mcpServers": {
+    "mcgl": {
+      "command": "npx",
+      "args": ["-y", "mcgl-mcp"],
+      "env": {
+        "FORUM_LOGIN": "ник",
+        "FORUM_PASSWORD": "пароль"
+      }
+    }
+  }
+}
+```
+
+`FORUM_LOGIN` и `FORUM_PASSWORD` необязательны: без них доступно только чтение.
+
+Если на Windows клиент не находит `npx`, укажи `"command": "cmd"` и `"args": ["/c", "npx", "-y", "mcgl-mcp"]`.
+
+С кредами сервер логинится сразу при старте. Результат («Authorized as …» или текст ошибки форума) виден в логах MCP-клиента.
+
+### Запуск из исходников
+
+```bash
+pnpm install
+pnpm build
+```
+
+В конфиге клиента: `"command": "node"`, `"args": ["<путь>/mcgl-mcp/dist/entry/stdio.js"]`.
+
+## Публикация в npm
+
+Публикует GitHub Actions ([.github/workflows/publish.yml](.github/workflows/publish.yml)) по тегу:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+- **Версия берётся из тега.** В `package.json` в репозитории лежит заглушка `0.0.0-dev`, менять её руками не нужно.
+- **Пререлизы** (`v1.0.0-beta.1`) публикуются с dist-tag `next`, поэтому `npx mcgl-mcp` продолжает ставить последнюю стабильную версию.
+- **Тег, который не является semver,** останавливает workflow с ошибкой.
+- **Пакет подписывается `--provenance`:** npm показывает, что он собран этим workflow из этого репозитория.
+
+Один раз нужно добавить секрет `NPM_TOKEN` в Settings → Secrets and variables → Actions. Токен создаётся на npmjs.com в разделе Access Tokens → Generate New Token → Granular, с правом публикации.
+
+Что попадёт в пакет: `npm pack --dry-run`. Идут только `dist/**/*.js` (без `dist/dev`), README и LICENSE.
+
+## Хост
+
+```bash
+cp .env.example .env
+docker compose up -d --build
+```
+
+Эндпоинт: `https://<домен>/public/mcp`, проверка здоровья: `/health`. `FORUM_LOGIN` и `FORUM_PASSWORD` HTTP-режим не читает.
+
+## Устройство
+
+```
+src/
+  entry/stdio.ts         локальный режим
+  entry/http.ts          публичный режим
+  dev/check-login.ts     ручная проверка авторизации
+  env.ts                 конфиг из переменных окружения
+  forum/
+    site.ts              URL форума
+    http.ts              fetch + куки + ручные редиректы + повторы GET
+    health.ts            circuit breaker: форум лежит → не ходим 30 с
+    cookie-jar.ts
+    rate-limiter.ts      минимальный интервал между запросами (общий на процесс)
+    player-session.ts    логин, проверка сессии, перелогин
+    reader.ts            чтение форума (гостем или через сессию игрока)
+    types.ts             формы данных, которые отдают инструменты
+    parsers/
+      common.ts          общие хелперы, признаки гостя, пользователи, пагинация
+      topic-list.ts      главная, /forum/0, /forum/N (и разделы сообществ)
+      topic.ts           тема и отдельный пост: посты, опрос, шапка
+      content.ts         HTML поста (bbCode) → текст
+      player.ts          форма логина
+  mcp/
+    define-tool.ts       definePublicTool / definePlayerTool
+    tools/index.ts       реестр инструментов
+    tools/public/read.ts инструменты чтения
+    server.ts            сборка McpServer
+```
+
+Добавление инструмента: объявить через `definePublicTool` или `definePlayerTool` и положить в массив в `mcp/tools/index.ts`. В player-инструментах обращения к форуму оборачиваются в `ctx.session.withAuth(...)`, а страницы получаются через `ctx.session.getAuthed(...)`.
+
+## Тесты
+
+```bash
+pnpm test              # все тесты, без сети (их же гоняет CI)
+pnpm test:watch
+pnpm test:live         # smoke-тесты на настоящем форуме, креды игрока из .env необязательны
+pnpm fixtures:update   # перекачать страницы форума в test/fixtures
+```
+
+| Папка | Что проверяется |
+|---|---|
+| `test/parsers/` | конвертер bbCode → текст на коротких HTML-фрагментах; парсеры страниц на фикстурах |
+| `test/forum/` | куки, редиректы, cp1251, лимитер; логин, перелогин, блокировка после неверного пароля; названия предметов (кеш, лимит запросов) |
+| `test/mcp/` | MCP целиком: клиент SDK ↔ сервер (`InMemoryTransport`) ↔ фейковый форум |
+| `test/live/` | только `pnpm test:live`: живая разметка всё ещё парсится |
+
+Тесты сети работают против фейкового форума: это локальный http-сервер внутри теста (`test/helpers/fake-forum.ts`). Он отдаёт страницы из `test/fixtures/`, поэтому проверяется настоящий `ForumHttp`, без моков `fetch`.
+
+Фикстуры — замороженные копии страниц форума, они лежат в git. Если форум поменял вёрстку, запусти `pnpm fixtures:update` и посмотри, какие тесты упали.
+
+CI ([.github/workflows/ci.yml](.github/workflows/ci.yml)) на push в `main` и на PR прогоняет typecheck, тесты, сборку и проверку состава пакета. Перед публикацией `prepublishOnly` прогоняет то же самое.
+
+`tsconfig.json` проверяет типы в `src`, тестах и скриптах, а `tsconfig.build.json` собирает только `src` в `dist`.
+
+## Лицензия
+
+[MIT](LICENSE)

package/dist/entry/http.js

@@ -0,0 +1,49 @@
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { loadForumEnv, loadHttpEnv } from "../env.js";
+import { ForumHttp } from "../forum/http.js";
+import { ForumReader } from "../forum/reader.js";
+import { RateLimiter } from "../forum/rate-limiter.js";
+import { createLogger } from "../logger.js";
+import { createMcpServer, SERVER_INFO } from "../mcp/server.js";
+const logger = createLogger("http");
+const forumEnv = loadForumEnv();
+const httpEnv = loadHttpEnv();
+// Общий анонимный клиент и общий лимитер: все запросы к форуму идут с IP хоста.
+const limiter = new RateLimiter(forumEnv.minIntervalMs);
+const forumHttp = new ForumHttp(forumEnv, limiter);
+const reader = new ForumReader(forumHttp);
+const app = createMcpExpressApp({ host: httpEnv.host, allowedHosts: httpEnv.allowedHosts });
+// Сам сервер жив (ok), форум — по данным circuit breaker (без лишних запросов к нему).
+app.get("/health", (_req, res) => {
+    res.json({ ok: true, ...SERVER_INFO, forum: forumHttp.health.status });
+});
+const MCP_PATH = "/public/mcp";
+app.post(MCP_PATH, async (req, res) => {
+    const server = createMcpServer({ reader });
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    res.on("close", () => {
+        void transport.close();
+        void server.close();
+    });
+    try {
+        await server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+    }
+    catch (error) {
+        logger.error("Error handling MCP request", error);
+        if (!res.headersSent) {
+            res.status(500).json({ jsonrpc: "2.0", error: { code: -32603, message: "Internal server error" }, id: null });
+        }
+    }
+});
+// Stateless-режим: ни GET (SSE-стрим), ни DELETE (закрытие сессии) не нужны.
+const methodNotAllowed = (_req, res) => {
+    res.status(405).json({ jsonrpc: "2.0", error: { code: -32000, message: "Method not allowed." }, id: null });
+};
+app.get(MCP_PATH, methodNotAllowed);
+app.delete(MCP_PATH, methodNotAllowed);
+app.listen(httpEnv.port, httpEnv.host, () => {
+    logger.info(`Listening on http://${httpEnv.host}:${httpEnv.port}${MCP_PATH} (forum: ${forumEnv.baseUrl})`);
+});
+//# sourceMappingURL=http.js.map

package/dist/entry/stdio.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * Локальный режим: MCP-клиент запускает процесс и общается через stdin/stdout.
+ * Креды игрока берутся из env (FORUM_LOGIN / FORUM_PASSWORD), которые пользователь
+ * сам прописывает в конфиге клиента. Без них доступны только публичные инструменты.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadForumEnv, loadPlayerCredentials } from "../env.js";
+import { ForumHttp } from "../forum/http.js";
+import { PlayerSession } from "../forum/player-session.js";
+import { ForumReader } from "../forum/reader.js";
+import { RateLimiter } from "../forum/rate-limiter.js";
+import { createLogger } from "../logger.js";
+import { createMcpServer } from "../mcp/server.js";
+const logger = createLogger("stdio");
+async function main() {
+    const forumEnv = loadForumEnv();
+    const credentials = loadPlayerCredentials();
+    const http = new ForumHttp(forumEnv, new RateLimiter(forumEnv.minIntervalMs));
+    if (!credentials) {
+        await createMcpServer({ reader: new ForumReader(http) }).connect(new StdioServerTransport());
+        logger.info("Started with public tools only (FORUM_LOGIN/FORUM_PASSWORD not set)");
+        return;
+    }
+    const session = new PlayerSession(http, credentials);
+    await createMcpServer({ reader: new ForumReader(http, session), session }).connect(new StdioServerTransport());
+    logger.info(`Started with player tools for login "${credentials.login}"`);
+    // Логинимся сразу, чтобы неверный пароль был виден в логах клиента при старте,
+    // а не при первом вызове инструмента. Процесс не падает: ошибку получит и инструмент.
+    session.whoami().then((username) => logger.info(`Authorized as ${username}`), (error) => logger.error(`Authorization failed: ${error instanceof Error ? error.message : String(error)}`));
+}
+main().catch((error) => {
+    logger.error("Fatal", error);
+    process.exit(1);
+});
+//# sourceMappingURL=stdio.js.map

package/dist/env.js

@@ -0,0 +1,57 @@
+import { DEFAULT_FORUM_URL } from "./forum/site.js";
+function str(name, fallback) {
+    const value = process.env[name]?.trim() || fallback;
+    if (value === undefined) {
+        throw new Error(`Missing required environment variable: ${name}`);
+    }
+    return value;
+}
+function optional(name) {
+    const value = process.env[name]?.trim();
+    return value ? value : undefined;
+}
+function int(name, fallback) {
+    const raw = optional(name);
+    if (raw === undefined)
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 0) {
+        throw new Error(`Environment variable ${name} must be a non-negative integer, got "${raw}"`);
+    }
+    return value;
+}
+/** Настройки доступа к форуму, общие для обоих режимов. */
+export function loadForumEnv() {
+    return {
+        baseUrl: str("FORUM_BASE_URL", DEFAULT_FORUM_URL).replace(/\/+$/, ""),
+        minIntervalMs: int("FORUM_MIN_INTERVAL_MS", 300),
+        timeoutMs: int("FORUM_TIMEOUT_MS", 15000),
+    };
+}
+/**
+ * Креды игрока для локального режима. Пользователь сам кладёт их в env
+ * в конфиге своего MCP-клиента. Если они не заданы, сервер стартует только
+ * с публичными инструментами.
+ */
+export function loadPlayerCredentials() {
+    const login = optional("FORUM_LOGIN");
+    const password = optional("FORUM_PASSWORD");
+    if (!login && !password)
+        return undefined;
+    if (!login || !password) {
+        throw new Error("FORUM_LOGIN and FORUM_PASSWORD must be set together");
+    }
+    return { login, password };
+}
+export function loadHttpEnv() {
+    const allowedHosts = optional("ALLOWED_HOSTS")
+        ?.split(",")
+        .map((h) => h.trim())
+        .filter(Boolean);
+    return {
+        host: str("HOST", "0.0.0.0"),
+        port: int("PORT", 3000),
+        allowedHosts: allowedHosts?.length ? allowedHosts : undefined,
+    };
+}
+//# sourceMappingURL=env.js.map

package/dist/forum/cookie-jar.js

@@ -0,0 +1,45 @@
+/**
+ * Простейшее хранилище кук на один хост форума. Path, domain и secure
+ * не учитываются: мы всегда ходим на один и тот же origin.
+ */
+export class CookieJar {
+    cookies = new Map();
+    /** Применяет заголовки Set-Cookie из ответа. */
+    absorb(headers) {
+        for (const raw of headers.getSetCookie()) {
+            const [pair, ...attrs] = raw.split(";");
+            const eq = pair.indexOf("=");
+            if (eq <= 0)
+                continue;
+            const name = pair.slice(0, eq).trim();
+            const value = pair.slice(eq + 1).trim();
+            const expired = attrs.some((a) => {
+                const [k, v = ""] = a.split("=").map((s) => s.trim());
+                const key = k.toLowerCase();
+                if (key === "max-age")
+                    return Number(v) <= 0;
+                if (key === "expires")
+                    return Date.parse(v) <= Date.now();
+                return false;
+            });
+            if (expired || value === "" || value === "deleted") {
+                this.cookies.delete(name);
+            }
+            else {
+                this.cookies.set(name, value);
+            }
+        }
+    }
+    header() {
+        if (this.cookies.size === 0)
+            return undefined;
+        return [...this.cookies].map(([k, v]) => `${k}=${v}`).join("; ");
+    }
+    has(name) {
+        return this.cookies.has(name);
+    }
+    clear() {
+        this.cookies.clear();
+    }
+}
+//# sourceMappingURL=cookie-jar.js.map

package/dist/forum/errors.js

@@ -0,0 +1,38 @@
+/** Ошибка, текст которой можно показать агенту как результат инструмента. */
+export class ForumError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ForumError";
+    }
+}
+/** Форум ответил страницей «войдите». Сессия будет переустановлена один раз. */
+export class SessionExpiredError extends ForumError {
+    constructor() {
+        super("Forum session expired");
+        this.name = "SessionExpiredError";
+    }
+}
+/** Логин не удался: неверные креды, бан, капча и т.п. */
+export class LoginFailedError extends ForumError {
+    constructor(reason) {
+        super(`Forum login failed: ${reason}`);
+        this.name = "LoginFailedError";
+    }
+}
+/** Разметка страницы не совпала с ожиданиями парсера. */
+export class ParseError extends ForumError {
+    constructor(what, url) {
+        super(`Could not parse ${what} at ${url}. The forum markup may have changed.`);
+        this.name = "ParseError";
+    }
+}
+/** Форум не отвечает (сработал ForumHealth): запросы временно не отправляются. */
+export class ForumUnavailableError extends ForumError {
+    retryInSec;
+    constructor(retryInSec) {
+        super(`The forum is not responding right now. Try again in ${retryInSec}s.`);
+        this.retryInSec = retryInSec;
+        this.name = "ForumUnavailableError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/forum/health.js

@@ -0,0 +1,60 @@
+import { createLogger } from "../logger.js";
+import { ForumUnavailableError } from "./errors.js";
+const logger = createLogger("forum-health");
+/**
+ * Circuit breaker для форума. Форум периодически лежит; без этого каждый вызов
+ * инструмента ждал бы таймауты всех повторов.
+ *
+ * - closed: запросы идут как обычно;
+ * - open: после `failureThreshold` неудачных запросов подряд форум считается
+ *   лежащим, запросы сразу получают ForumUnavailableError;
+ * - через `cooldownMs` пропускается один пробный запрос (half-open): успех
+ *   закрывает breaker, неудача снова открывает его на cooldown.
+ *
+ * Один экземпляр на процесс, общий для всех ForumHttp.
+ */
+export class ForumHealth {
+    failures = 0;
+    openUntil = 0;
+    probing = false;
+    threshold;
+    cooldownMs;
+    now;
+    constructor(options = {}) {
+        this.threshold = options.failureThreshold ?? 2;
+        this.cooldownMs = options.cooldownMs ?? 30_000;
+        this.now = options.now ?? Date.now;
+    }
+    /** Бросает ForumUnavailableError, если форум сейчас считается лежащим. */
+    check() {
+        if (this.failures < this.threshold)
+            return;
+        const wait = this.openUntil - this.now();
+        if (wait > 0 || this.probing) {
+            throw new ForumUnavailableError(Math.max(1, Math.ceil(Math.max(wait, 1000) / 1000)));
+        }
+        // Cooldown прошёл: пропускаем один пробный запрос.
+        this.probing = true;
+    }
+    success() {
+        if (this.failures >= this.threshold)
+            logger.info("Forum is back up");
+        this.failures = 0;
+        this.probing = false;
+    }
+    failure() {
+        this.failures++;
+        this.probing = false;
+        if (this.failures >= this.threshold) {
+            if (this.failures === this.threshold)
+                logger.warn(`Forum looks down, pausing requests for ${this.cooldownMs / 1000}s`);
+            this.openUntil = this.now() + this.cooldownMs;
+        }
+    }
+    get status() {
+        if (this.failures < this.threshold)
+            return { up: true };
+        return { up: false, retryInSec: Math.max(0, Math.ceil((this.openUntil - this.now()) / 1000)) };
+    }
+}
+//# sourceMappingURL=health.js.map

package/dist/forum/http.js

@@ -0,0 +1,136 @@
+import { createLogger } from "../logger.js";
+import { CookieJar } from "./cookie-jar.js";
+import { ForumError } from "./errors.js";
+import { ForumHealth } from "./health.js";
+const logger = createLogger("forum-http");
+const USER_AGENT = "mcgl-mcp/0.1 (+MCP forum tools)";
+const MAX_REDIRECTS = 5;
+/** Ответ, после которого GET имеет смысл повторить. */
+class RetryableError extends ForumError {
+}
+/**
+ * HTTP-клиент к форуму: свой CookieJar, общий RateLimiter, ручные редиректы
+ * (чтобы не терять Set-Cookie из 302 после логина), повторы и circuit breaker.
+ *
+ * - GET при сетевой ошибке, таймауте или 5xx повторяется (по умолчанию 3 попытки).
+ * - POST не повторяется: при обрыве неизвестно, дошёл ли запрос, а повтор
+ *   отправки поста создал бы дубль.
+ * - Если форум лежит (ForumHealth), запрос сразу падает с ForumUnavailableError.
+ *
+ * Один экземпляр = одна «браузерная сессия». Для анонимного чтения хватает
+ * одного общего, для каждого игрока нужен свой.
+ */
+export class ForumHttp {
+    env;
+    limiter;
+    jar = new CookieJar();
+    health;
+    retryDelaysMs;
+    constructor(env, limiter, options = {}) {
+        this.env = env;
+        this.limiter = limiter;
+        this.health = options.health ?? new ForumHealth();
+        this.retryDelaysMs = options.retryDelaysMs ?? [1000, 2000];
+    }
+    get(path) {
+        return this.withHealth(() => this.withRetries(path, () => this.request(path, { method: "GET" })));
+    }
+    postForm(path, fields, extraHeaders) {
+        const body = new URLSearchParams();
+        for (const [k, v] of Object.entries(fields))
+            if (v !== undefined)
+                body.append(k, String(v));
+        return this.withHealth(() => this.request(path, {
+            method: "POST",
+            headers: { ...extraHeaders, "content-type": "application/x-www-form-urlencoded; charset=utf-8" },
+            body: body.toString(),
+        }));
+    }
+    absoluteUrl(path) {
+        return new URL(path, this.env.baseUrl + "/").toString();
+    }
+    async withHealth(run) {
+        this.health.check();
+        try {
+            const page = await run();
+            this.health.success();
+            return page;
+        }
+        catch (error) {
+            // Форум ответил, но что-то не так (редиректы по кругу и т.п.) — он жив.
+            if (error instanceof RetryableError)
+                this.health.failure();
+            else
+                this.health.success();
+            throw error;
+        }
+    }
+    async withRetries(path, run) {
+        for (let attempt = 0;; attempt++) {
+            try {
+                return await run();
+            }
+            catch (error) {
+                const delay = this.retryDelaysMs[attempt];
+                if (!(error instanceof RetryableError) || delay === undefined)
+                    throw error;
+                logger.warn(`GET ${path} failed (${error.message}), retry ${attempt + 1}/${this.retryDelaysMs.length} in ${delay}ms`);
+                await new Promise((r) => setTimeout(r, delay));
+            }
+        }
+    }
+    async request(path, init) {
+        let url = this.absoluteUrl(path);
+        let current = init;
+        for (let hop = 0; hop <= MAX_REDIRECTS; hop++) {
+            const res = await this.limiter.schedule(() => this.fetchOnce(url, current));
+            this.jar.absorb(res.headers);
+            const location = res.headers.get("location");
+            if (res.status >= 300 && res.status < 400 && location) {
+                await res.body?.cancel();
+                url = new URL(location, url).toString();
+                // 301/302/303 после POST браузеры превращают в GET, повторяем это поведение.
+                current = res.status === 307 || res.status === 308 ? current : { method: "GET" };
+                continue;
+            }
+            const html = decode(await res.arrayBuffer(), res.headers.get("content-type"));
+            logger.debug(`${current.method} ${url} -> ${res.status}${hop ? ` (after ${hop} redirect(s) from ${init.method} ${path})` : ""}`);
+            if (res.status >= 500) {
+                throw new RetryableError(`Forum returned HTTP ${res.status} for ${url}`);
+            }
+            return { url, status: res.status, html };
+        }
+        throw new ForumError(`Too many redirects starting from ${path}`);
+    }
+    async fetchOnce(url, init) {
+        const headers = new Headers(init.headers);
+        headers.set("user-agent", USER_AGENT);
+        headers.set("accept", "text/html,application/xhtml+xml");
+        const cookie = this.jar.header();
+        if (cookie)
+            headers.set("cookie", cookie);
+        try {
+            return await fetch(url, {
+                ...init,
+                headers,
+                redirect: "manual",
+                signal: AbortSignal.timeout(this.env.timeoutMs),
+            });
+        }
+        catch (error) {
+            const timeout = error instanceof DOMException && error.name === "TimeoutError";
+            throw new RetryableError(timeout ? `Forum timed out: ${url}` : `Request to forum failed: ${url}`, { cause: error });
+        }
+    }
+}
+/** Форум отдаёт UTF-8 и пишет charset в заголовке; на всякий случай уважаем его. */
+function decode(body, contentType) {
+    const charset = /charset=([^;]+)/i.exec(contentType ?? "")?.[1]?.trim() || "utf-8";
+    try {
+        return new TextDecoder(charset).decode(body);
+    }
+    catch {
+        return new TextDecoder("utf-8").decode(body);
+    }
+}
+//# sourceMappingURL=http.js.map