mcgl-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,196 +1,84 @@
 # mcgl-mcp
 
-MCP-сервер для форума [Minecraft Galaxy](https://forum.minecraft-galaxy.ru/main/). API у форума нет, поэтому сервер ходит на него как браузер: HTML, формы, кука `PHPSESSID`.
+[![npm](https://img.shields.io/npm/v/mcgl-mcp)](https://www.npmjs.com/package/mcgl-mcp)
+[![CI](https://github.com/exi66/mcgl-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/exi66/mcgl-mcp/actions/workflows/ci.yml)
 
-**Текущее состояние:** авторизация игрока и чтение общего форума. Действий от лица игрока пока нет.
+MCP-сервер для [форума Minecraft Galaxy](https://forum.minecraft-galaxy.ru/main/). Подключается к Claude, Cursor и другим AI-ассистентам и даёт им читать форум: разделы, темы, посты, опросы.
 
-## Инструменты
-
-Все инструменты публичные: авторизация не нужна, работают в обоих режимах. В локальном режиме с кредами страницы читаются залогиненным.
-
-| Инструмент | Страница | Что возвращает |
-|---|---|---|
-| `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`); об этом сказано в описаниях инструментов.
+- «Что нового на форуме MCGL?»
+- «Перескажи последние сообщения в теме про Гран-при амфибий»
+- «О чём спорят в разделе Предложения?»
+- «Найди в теме 133931 рецепт крафта и объясни его»
 
-Парсеры в `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`.
+Нужен [Node.js](https://nodejs.org) 22 или новее. Отдельно ставить ничего не надо: клиент сам скачает и запустит сервер через `npx`.
 
 **Claude Code:**
 
 ```bash
-claude mcp add mcgl -e FORUM_LOGIN=ник -e FORUM_PASSWORD=пароль -- npx -y mcgl-mcp
+claude mcp add mcgl -- npx -y mcgl-mcp
 ```
 
-**Claude Desktop, Cursor и другие** (`claude_desktop_config.json`, `.cursor/mcp.json` и т.п.):
+**Claude Desktop, Cursor и другие:** добавьте в конфиг MCP-серверов (`claude_desktop_config.json`, `.cursor/mcp.json` и т.п.):
 
 ```json
 {
   "mcpServers": {
     "mcgl": {
       "command": "npx",
-      "args": ["-y", "mcgl-mcp"],
-      "env": {
-        "FORUM_LOGIN": "ник",
-        "FORUM_PASSWORD": "пароль"
-      }
+      "args": ["-y", "mcgl-mcp"]
     }
   }
 }
 ```
 
-`FORUM_LOGIN` и `FORUM_PASSWORD` необязательны: без них доступно только чтение.
-
-Если на Windows клиент не находит `npx`, укажи `"command": "cmd"` и `"args": ["/c", "npx", "-y", "mcgl-mcp"]`.
+На 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
+claude mcp add mcgl -e FORUM_LOGIN=ник -e FORUM_PASSWORD=пароль -- npx -y mcgl-mcp
 ```
 
-Эндпоинт: `https://<домен>/public/mcp`, проверка здоровья: `/health`. `FORUM_LOGIN` и `FORUM_PASSWORD` HTTP-режим не читает.
-
-## Устройство
+В JSON-конфиге то же самое задаётся через `"env": { "FORUM_LOGIN": "ник", "FORUM_PASSWORD": "пароль" }`.
 
-```
-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
-```
+Пароль хранится только в конфиге клиента на вашем компьютере и отправляется только на форум. Если войти не получилось, текст ошибки форума виден в логах MCP-сервера в клиенте. У форума есть лимит попыток входа, поэтому после неудачи сервер больше не пытается войти: исправьте пароль и перезапустите клиент.
 
-Добавление инструмента: объявить через `definePublicTool` или `definePlayerTool` и положить в массив в `mcp/tools/index.ts`. В player-инструментах обращения к форуму оборачиваются в `ctx.session.withAuth(...)`, а страницы получаются через `ctx.session.getAuthed(...)`.
+## Инструменты
 
-## Тесты
+| Инструмент            | Что делает                                                                           |
+| --------------------- | ------------------------------------------------------------------------------------ |
+| `forum_list_sections` | разделы форума по категориям                                                         |
+| `forum_latest_topics` | темы со свежими сообщениями во всех разделах                                         |
+| `forum_list_topics`   | темы раздела: закреплённые, закрытые, кто может отвечать                             |
+| `forum_get_topic`     | посты темы по 15 штук; по умолчанию — последние, плюс опрос и кто читает тему сейчас |
+| `forum_get_post`      | один пост по ссылке `/post/N` и где он находится в теме                              |
+| `forum_find_users`    | игроки по началу ника                                                                |
+| `forum_user_topics`   | темы, созданные игроком (по нику или id)                                             |
 
-```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`.
+| Переменная                      | По умолчанию                        | Что это                                    |
+| ------------------------------- | ----------------------------------- | ------------------------------------------ |
+| `FORUM_LOGIN`, `FORUM_PASSWORD` | —                                   | вход под своим аккаунтом                   |
+| `LOG_LEVEL`                     | `info`                              | `debug` — подробные логи для отладки       |
+| `FORUM_MIN_INTERVAL_MS`         | `300`                               | минимальная пауза между запросами к форуму |
+| `FORUM_TIMEOUT_MS`              | `15000`                             | таймаут одного запроса к форуму            |
+| `FORUM_BASE_URL`                | `https://forum.minecraft-galaxy.ru` | адрес форума                               |
 
-Фикстуры — замороженные копии страниц форума, они лежат в git. Если форум поменял вёрстку, запусти `pnpm fixtures:update` и посмотри, какие тесты упали.
+## Документация
 
-CI ([.github/workflows/ci.yml](.github/workflows/ci.yml)) на push в `main` и на PR прогоняет typecheck, тесты, сборку и проверку состава пакета. Перед публикацией `prepublishOnly` прогоняет то же самое.
+- [Как сервер работает с форумом](docs/forum.md): вход, пагинация тем, bbCode, предметы, недоступность форума.
+- [Разработка](docs/development.md): запуск из исходников, тесты, релизы, свой HTTP-сервер.
 
-`tsconfig.json` проверяет типы в `src`, тестах и скриптах, а `tsconfig.build.json` собирает только `src` в `dist`.
+Нашли ошибку или форум что-то поменял — [заведите issue](https://github.com/exi66/mcgl-mcp/issues/new/choose).
 
 ## Лицензия
 

package/dist/forum/http.js

@@ -119,7 +119,9 @@ export class ForumHttp {
         }
         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 });
+            throw new RetryableError(timeout ? `Forum timed out: ${url}` : `Request to forum failed: ${url}`, {
+                cause: error,
+            });
         }
     }
 }

package/dist/forum/objects.js

@@ -16,6 +16,28 @@ export function parseObjectLiteral(raw) {
     }
     return Object.keys(result).length ? result : undefined;
 }
+/**
+ * Ответ точного поиска игрока `/object/0/9?q=nick`: `[{'id':'714893','login':'pozziittiivo'}]`.
+ * Если игрока нет, форум отвечает `player$0` с id 0 — тогда undefined.
+ */
+export function parseUserExact(raw) {
+    const obj = parseObjectLiteral(raw.trim().replace(/^\[/, "").replace(/\]$/, ""));
+    const id = Number(obj?.id);
+    if (!obj?.login || !Number.isInteger(id) || id <= 0)
+        return undefined;
+    return { id, name: obj.login };
+}
+/**
+ * Ответ поиска по началу ника `/object/0/4?q=prefix`: строки `nick|group|id`.
+ * Пустые строки (`|guest|`) и удалённые аккаунты (`player$N`) отбрасываются.
+ */
+export function parseUserPrefix(raw) {
+    return raw
+        .split(/\r?\n/)
+        .map((line) => line.trim().split("|"))
+        .filter(([name, , id]) => name && !/^player\$\d+$/.test(name) && Number(id) > 0)
+        .map(([name, group, id]) => ({ id: Number(id), name, group: group || undefined }));
+}
 /** Маркер предмета в тексте поста, который ставит content.ts и раскрывает ItemResolver. */
 export const ITEM_TOKEN = /⟦item:(\d+):(\d+)⟧/g;
 export const itemToken = (id, meta) => `⟦item:${id}:${meta}⟧`;

package/dist/forum/parsers/content.js

@@ -24,7 +24,10 @@ export function postHtmlToText($, el) {
     node.find(".bc_quote").each((_, block) => {
         const b = $(block);
         const title = b.children(".bc_quote_title").first();
-        const who = title.text().replace(/\s*писал\(а\):\s*$/, "").trim();
+        const who = title
+            .text()
+            .replace(/\s*писал\(а\):\s*$/, "")
+            .trim();
         title.remove();
         b.prepend(`\n[quote${who ? `: ${who}` : ""}]\n`).append("\n[/quote]\n");
         b.replaceWith(b.contents());

package/dist/forum/reader.js

@@ -1,5 +1,5 @@
 import { ForumError } from "./errors.js";
-import { ItemResolver } from "./objects.js";
+import { ItemResolver, parseUserExact, parseUserPrefix } from "./objects.js";
 import { parseSections, parseTopicList } from "./parsers/topic-list.js";
 import { parsePostPage, parseTopicPage } from "./parsers/topic.js";
 import { site } from "./site.js";
@@ -48,6 +48,37 @@ export class ForumReader {
     async sectionTopics(sectionId, page = 1) {
         return this.rememberPages(parseTopicList(await this.get(site.section(sectionId, page)), page));
     }
+    /** Игроки, чей ник начинается с prefix (без учёта регистра). */
+    async findUsers(prefix, limit = 20) {
+        return parseUserPrefix((await this.http.get(site.userPrefix(prefix))).html).slice(0, limit);
+    }
+    /** Темы, созданные игроком. Игрок задаётся id или точным ником (регистр не важен). */
+    async userTopics(user, page = 1) {
+        let id = user.id;
+        if (id === undefined) {
+            const nick = user.nick?.trim() ?? "";
+            const found = nick ? parseUserExact((await this.http.get(site.userExact(nick))).html) : undefined;
+            if (!found) {
+                // Подсказки: ники с тем же началом; при опечатке в середине — по первым 4 буквам.
+                let prefix = nick;
+                let similar = nick ? await this.findUsers(nick, 10) : [];
+                if (similar.length === 0 && nick.length > 4) {
+                    prefix = nick.slice(0, 4);
+                    similar = await this.findUsers(prefix, 10);
+                }
+                throw new ForumError(`Player "${nick}" not found.` +
+                    (similar.length ? ` Nicks starting with "${prefix}": ${similar.map((u) => u.name).join(", ")}` : ""));
+            }
+            id = found.id;
+        }
+        const list = parseTopicList(await this.get(site.userTopics(id, page)), page);
+        if (list.topics.length === 0 && page > 1) {
+            throw new ForumError(`Player ${id} has fewer than ${page} pages of topics`);
+        }
+        // Заголовок страницы: «Темы пользователя <ник>».
+        const name = list.title?.replace(/^Темы пользователя\s+/, "") ?? user.nick ?? String(id);
+        return { ...this.rememberPages(list), user: { id, name } };
+    }
     /** page — от начала темы (с 1); без него — последние pageSize постов. */
     async topic(topicId, page, pageSize = DEFAULT_PAGE_SIZE) {
         try {

package/dist/forum/site.js

@@ -21,6 +21,12 @@ export const site = {
     topic: (topicId, page) => `/topic/${topicId}/${page - 1}`,
     /** Отдельный пост. */
     post: (postId) => `/post/${postId}`,
+    /** Темы игрока. В URL id игрока + 1 со знаком минус: игрок 714893 → /forum/-714894. */
+    userTopics: (userId, page) => `/forum/-${userId + 1}/${page - 1}`,
+    /** Точный поиск игрока по нику (без учёта регистра): [{'id':'714893','login':'nick'}], нет такого → player$0. */
+    userExact: (nick) => `/object/0/9?q=${encodeURIComponent(nick)}`,
+    /** Поиск игроков по началу ника: строки "nick|group|id". */
+    userPrefix: (prefix) => `/object/0/4?q=${encodeURIComponent(prefix)}`,
     /** Страница с формой логина: из неё берутся скрытые поля (form, ref, fcode, recap). */
     loginPage: () => "/guilogin/",
     /** Куда отправляется форма логина. Успех: 302 на ref, неудача: 302 на /guilogin/4?f=N. */

package/dist/mcp/tools/index.js

@@ -1,4 +1,5 @@
 import { readTools } from "./public/read.js";
+import { userTools } from "./public/users.js";
 /**
  * Реестр инструментов.
  *
@@ -6,6 +7,6 @@ import { readTools } from "./public/read.js";
  * `definePlayerTool(...)` и добавить в нужный массив.
  * Player-инструменты автоматически не попадают в HTTP-режим.
  */
-export const publicTools = [...readTools];
+export const publicTools = [...readTools, ...userTools];
 export const playerTools = [];
 //# sourceMappingURL=index.js.map

package/dist/mcp/tools/public/read.js

@@ -9,7 +9,8 @@ const FLAGS_NOTE = " Boolean flags appear only when true.";
 const page = z.number().int().positive().default(1).describe("1-based page number");
 const TOPIC_ROW_FIELDS = "Topic fields: pinned; closed (title struck through on the forum, no replies allowed); " +
     "whoCanReply: all | vip | premium_platinum | moderators (only visible in topic lists, not on the topic page); " +
-    "pages (topic page count); created/last: author and time." + FLAGS_NOTE;
+    "pages (topic page count); created/last: author and time; author.group is the player's privilege (paid or staff role, e.g. vip, platinum, admin); 'girls' is only a nick color anyone can pick, not gender." +
+    FLAGS_NOTE;
 export const listSections = definePublicTool({
     name: "forum_list_sections",
     title: "Forum sections",
@@ -22,8 +23,7 @@ export const listSections = definePublicTool({
 export const latestTopics = definePublicTool({
     name: "forum_latest_topics",
     title: "Latest topics",
-    description: "Recently active topics across all sections, newest first; each row includes its section name. " +
-        TOPIC_ROW_FIELDS,
+    description: "Recently active topics across all sections, newest first; each row includes its section name. " + TOPIC_ROW_FIELDS,
     inputSchema: { page },
     annotations: readOnly,
     handler: async ({ page }, { reader }) => jsonResult(await reader.latestTopics(page)),
@@ -48,12 +48,18 @@ export const getTopic = definePublicTool({
         "is ceil(N/pageSize). Post numbers (#N) are continuous. Returns title, section, totalPages, totalPosts, " +
         "posts (number, id, author, postedAt, text, rating; deleted posts are {deleted:true}). The latest view and " +
         "page 1 also include poll (if any), notices (e.g. 'moved from section') and current readers. " +
-        "author.accountDeleted: account removed or banned. " +
+        "author.accountDeleted: account removed or banned; author.group is the player's privilege (paid or staff role, e.g. vip, platinum, admin); 'girls' is only a nick color anyone can pick, not gender. " +
         "Post text markup: [quote: nick]..[/quote], [spoiler: title]..[/spoiler], [image: url], [video: url], " +
-        "[audio: url], [Item name #id] or [item #id] (#id:meta for variants), [craft] grid of item ids with a legend." + FLAGS_NOTE,
+        "[audio: url], [Item name #id] or [item #id] (#id:meta for variants), [craft] grid of item ids with a legend." +
+        FLAGS_NOTE,
     inputSchema: {
         topicId: z.number().int().positive(),
-        page: z.number().int().positive().optional().describe("1-based page from the topic start; omit for the newest posts"),
+        page: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("1-based page from the topic start; omit for the newest posts"),
         pageSize: z.number().int().min(1).max(50).default(DEFAULT_PAGE_SIZE).describe("Posts per page"),
     },
     annotations: readOnly,

package/dist/mcp/tools/public/users.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+import { ForumError } from "../../../forum/errors.js";
+import { definePublicTool, jsonResult } from "../../define-tool.js";
+const readOnly = { readOnlyHint: true, openWorldHint: true };
+export const findUsers = definePublicTool({
+    name: "forum_find_users",
+    title: "Find players",
+    description: "Players whose nick starts with the given text (case-insensitive): name, id, group. " +
+        "group is the player's privilege (paid or staff role, e.g. vip, platinum, admin); 'girls' is only a nick color anyone can pick, not gender.",
+    inputSchema: {
+        prefix: z.string().trim().min(1).max(32).describe("Beginning of the nick"),
+        limit: z.number().int().min(1).max(50).default(20),
+    },
+    annotations: readOnly,
+    handler: async ({ prefix, limit }, { reader }) => jsonResult(await reader.findUsers(prefix, limit)),
+});
+export const userTopics = definePublicTool({
+    name: "forum_user_topics",
+    title: "Topics by player",
+    description: "Topics created by a player, newest first, same row format as forum_list_topics. " +
+        "Give nick (exact, case-insensitive) or userId. If the nick is unknown, the error lists similar nicks.",
+    inputSchema: {
+        nick: z.string().trim().min(1).max(32).optional(),
+        userId: z.number().int().positive().optional(),
+        page: z.number().int().positive().default(1).describe("1-based page number"),
+    },
+    annotations: readOnly,
+    handler: async ({ nick, userId, page }, { reader }) => {
+        if (!nick && !userId)
+            throw new ForumError("Pass nick or userId");
+        return jsonResult(await reader.userTopics({ id: userId, nick }, page));
+    },
+});
+export const userTools = [findUsers, userTopics];
+//# sourceMappingURL=users.js.map

package/package.json

@@ -1,12 +1,10 @@
 {
   "name": "mcgl-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for the Minecraft Galaxy (MCGL) game forum: read sections, topics and posts.",
   "keywords": [
     "mcp",
     "model-context-protocol",
-    "minecraft-galaxy",
-    "mcgl",
     "forum",
     "claude"
   ],
@@ -48,7 +46,9 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:live": "vitest run --config vitest.live.config.ts",
-    "fixtures:update": "tsx --env-file-if-exists=.env scripts/update-fixtures.ts"
+    "fixtures:update": "tsx --env-file-if-exists=.env scripts/update-fixtures.ts",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.2",
@@ -60,6 +60,7 @@
     "@modelcontextprotocol/inspector": "^2.15.0",
     "@types/express": "^5.0.6",
     "@types/node": "^26.6.6",
+    "prettier": "^3.10.1",
     "tsx": "^4.23.15",
     "typescript": "^7.0.2",
     "vitest": "^5.1.0"