moab-notify 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# moab-notify (MCP)
+
+MCP-сервер для управления уведомлениями moab.tools (`apprise.moab.tools`) — адресная книга
+получателей (Telegram + email) из LLM. Доступ закрыт Keycloak-ролью `apprise-admin` (device-flow).
+
+## Инструменты
+
+| Tool | Назначение |
+|---|---|
+| `login` / `auth_status` / `auth_logout` | вход через device-flow (auth.moab.tools, клиент `apprise-cli`) |
+| `recipient_list` | показать адресную книгу |
+| `recipient_set` | создать/изменить получателя (email + каналы; Telegram-only = только chat_id) |
+| `recipient_remove` | удалить получателя |
+| `notify_test` | тестовое уведомление по каналам получателя |
+
+## Запуск (в конфиге Claude)
+
+```json
+{
+  "mcpServers": {
+    "moab-notify": { "command": "npx", "args": ["-y", "moab-notify"] }
+  }
+}
+```
+
+## Конфиг (env, опционально)
+
+| Переменная | Default |
+|---|---|
+| `NOTIFY_API_BASE` | `https://apprise.moab.tools` |
+| `KEYCLOAK_AUTHORITY` | `https://auth.moab.tools/realms/moab` |
+| `KEYCLOAK_CLIENT` | `apprise-cli` |
+| `MOAB_CONFIG_DIR` | `~/.moab` (токены — `~/.moab/notify-mcp/credentials.json`, 0600) |
+
+## Разработка
+
+```bash
+npm install
+npm run build      # tsc → dist/
+npm test           # vitest
+```
+
+Релиз — публикация в npm (`npm publish`); `prepublishOnly` собирает `dist/`.
+
+## Как получить chat_id
+
+Получатель жмёт **Start** у `@MoabAlertsBot`. Его numeric id (= chat_id для лички) — это его
+Telegram user id. Временно: вытаскивается через `getUpdates` бота (см. `cluster-infra/deploy/apprise`);
+позже — tool `pending_starts` (перенос getUpdates в gateway, follow-up).

package/dist/api-client.js

@@ -0,0 +1,61 @@
+import { ApiError } from './errors.js';
+export class HttpApiClient {
+    cfg;
+    auth;
+    fetchFn;
+    constructor(cfg, auth, fetchFn = fetch) {
+        this.cfg = cfg;
+        this.auth = auth;
+        this.fetchFn = fetchFn;
+    }
+    listRecipients() {
+        return this.json('/admin/recipients', { method: 'GET' });
+    }
+    upsertRecipient(r) {
+        return this.json('/admin/recipients', this.jsonBody('PUT', r));
+    }
+    deleteRecipient(email) {
+        return this.json(`/admin/recipients/${encodeURIComponent(email)}`, { method: 'DELETE' });
+    }
+    testRecipient(email) {
+        return this.json(`/admin/test/${encodeURIComponent(email)}`, { method: 'POST' });
+    }
+    jsonBody(method, body) {
+        return { method, headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) };
+    }
+    // ── низкоуровневое: bearer + один 401-retry + разбор {error} ──────────────
+    async request(path, init) {
+        const token = await this.auth.getAccessToken();
+        let res = await this.fetchFn(this.cfg.apiBase + path, this.withAuth(init, token));
+        if (res.status === 401) {
+            const fresh = await this.auth.invalidateAndRefresh();
+            res = await this.fetchFn(this.cfg.apiBase + path, this.withAuth(init, fresh));
+        }
+        return res;
+    }
+    async json(path, init) {
+        const res = await this.request(path, init);
+        return (await this.readOk(res));
+    }
+    withAuth(init, token) {
+        const headers = {
+            ...init.headers,
+            Authorization: `Bearer ${token}`,
+            Accept: 'application/json',
+        };
+        return { ...init, headers };
+    }
+    async readOk(res) {
+        const r = res.clone();
+        if (r.ok) {
+            const text = await r.text();
+            return text ? JSON.parse(text) : null;
+        }
+        let code = null;
+        try {
+            code = JSON.parse(await r.text()).error ?? null;
+        }
+        catch { /* нет тела */ }
+        throw new ApiError(code, res.status);
+    }
+}

package/dist/auth.js

@@ -0,0 +1,154 @@
+import { mkdir, readFile, writeFile, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { AuthRequiredError, AuthPendingError } from './errors.js';
+/** Хранит AuthState в <dir>/credentials.json с правами 0600 (posix). */
+export class FileTokenStore {
+    dir;
+    file;
+    constructor(dir) {
+        this.dir = dir;
+        this.file = join(dir, 'credentials.json');
+    }
+    async load() {
+        try {
+            const raw = await readFile(this.file, 'utf8');
+            return JSON.parse(raw);
+        }
+        catch (e) {
+            if (e.code === 'ENOENT')
+                return null;
+            throw e;
+        }
+    }
+    async save(state) {
+        await mkdir(this.dir, { recursive: true, mode: 0o700 });
+        await writeFile(this.file, JSON.stringify(state, null, 2), { mode: 0o600 });
+    }
+    async clear() {
+        await rm(this.file, { force: true });
+    }
+}
+/** Запас перед истечением access — обновляем заранее. */
+const EXPIRY_SKEW_MS = 30_000;
+const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+export class Authenticator {
+    cfg;
+    store;
+    fetchFn;
+    now;
+    constructor(cfg, store, fetchFn = fetch, now = () => Date.now()) {
+        this.cfg = cfg;
+        this.store = store;
+        this.fetchFn = fetchFn;
+        this.now = now;
+    }
+    deviceUrl() { return `${this.cfg.authority}/protocol/openid-connect/auth/device`; }
+    tokenUrl() { return `${this.cfg.authority}/protocol/openid-connect/token`; }
+    /** Стартует device flow, сохраняет pending, возвращает данные для показа пользователю. */
+    async startLogin() {
+        const res = await this.fetchFn(this.deviceUrl(), {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({ client_id: this.cfg.client, scope: 'openid offline_access' }),
+        });
+        if (!res.ok)
+            throw new Error(`device flow start failed: ${res.status}`);
+        const dc = (await res.json());
+        await this.store.save({
+            pending: { deviceCode: dc.device_code, interval: dc.interval, deadline: this.now() + dc.expires_in * 1000 },
+        });
+        return dc;
+    }
+    /** Возвращает валидный access-токен: кэш → refresh → завершение pending. Иначе кидает Auth*Error. */
+    async getAccessToken() {
+        const state = await this.store.load();
+        if (!state)
+            throw new AuthRequiredError('Не авторизовано. Запустите инструмент login.');
+        if (state.tokens && state.tokens.expiresAt - this.now() > EXPIRY_SKEW_MS) {
+            return state.tokens.accessToken;
+        }
+        if (state.tokens) {
+            return this.refreshOrThrow(state.tokens.refreshToken);
+        }
+        if (state.pending) {
+            return this.completePendingOrThrow(state.pending);
+        }
+        throw new AuthRequiredError('Не авторизовано. Запустите инструмент login.');
+    }
+    /** Принудительный refresh (вызывается api-client при 401). */
+    async invalidateAndRefresh() {
+        const state = await this.store.load();
+        if (!state?.tokens)
+            throw new AuthRequiredError('Не авторизовано. Запустите инструмент login.');
+        return this.refreshOrThrow(state.tokens.refreshToken);
+    }
+    async status() {
+        const state = await this.store.load();
+        if (!state?.tokens)
+            return { loggedIn: false };
+        const username = decodeUsername(state.tokens.accessToken);
+        return username ? { loggedIn: true, username } : { loggedIn: true };
+    }
+    async logout() {
+        await this.store.clear();
+    }
+    async refreshOrThrow(refreshToken) {
+        const res = await this.fetchFn(this.tokenUrl(), {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({ grant_type: 'refresh_token', refresh_token: refreshToken, client_id: this.cfg.client }),
+        });
+        if (!res.ok) {
+            await this.store.clear();
+            throw new AuthRequiredError('Сессия истекла. Запустите инструмент login заново.');
+        }
+        const body = (await res.json());
+        const tokens = {
+            accessToken: body.access_token,
+            refreshToken: body.refresh_token,
+            expiresAt: this.now() + body.expires_in * 1000,
+        };
+        await this.store.save({ tokens });
+        return tokens.accessToken;
+    }
+    async completePendingOrThrow(pending) {
+        if (this.now() > pending.deadline) {
+            await this.store.clear();
+            throw new AuthRequiredError('Код подтверждения истёк. Запустите инструмент login заново.');
+        }
+        const res = await this.fetchFn(this.tokenUrl(), {
+            method: 'POST',
+            headers: { 'content-type': 'application/x-www-form-urlencoded' },
+            body: new URLSearchParams({ grant_type: DEVICE_GRANT, device_code: pending.deviceCode, client_id: this.cfg.client }),
+        });
+        if (res.ok) {
+            const body = (await res.json());
+            const tokens = {
+                accessToken: body.access_token,
+                refreshToken: body.refresh_token,
+                expiresAt: this.now() + body.expires_in * 1000,
+            };
+            await this.store.save({ tokens });
+            return tokens.accessToken;
+        }
+        const err = (await res.json().catch(() => ({})));
+        if (err.error === 'authorization_pending' || err.error === 'slow_down') {
+            throw new AuthPendingError('Вход ещё не подтверждён. Подтвердите в браузере и повторите запрос.');
+        }
+        await this.store.clear();
+        throw new AuthRequiredError('Не удалось войти. Запустите инструмент login заново.');
+    }
+}
+/** Достаёт preferred_username/email из payload JWT (без верификации — только для отображения). */
+function decodeUsername(jwt) {
+    const parts = jwt.split('.');
+    if (parts.length < 2)
+        return undefined;
+    try {
+        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+        return payload.preferred_username ?? payload.email ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/config.js

@@ -0,0 +1,12 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export function loadConfig(env = process.env) {
+    const base = (env.NOTIFY_API_BASE ?? 'https://apprise.moab.tools').replace(/\/+$/, '');
+    const rootDir = env.MOAB_CONFIG_DIR ?? join(homedir(), '.moab');
+    return {
+        apiBase: base,
+        authority: env.KEYCLOAK_AUTHORITY ?? 'https://auth.moab.tools/realms/moab',
+        client: env.KEYCLOAK_CLIENT ?? 'apprise-cli',
+        configDir: join(rootDir, 'notify-mcp'),
+    };
+}

package/dist/errors.js

@@ -0,0 +1,45 @@
+// Тексты ошибок admin-API notify-gateway.
+const ERR_RU = {
+    'recipient not found': 'Получатель не найден в адресной книге',
+    'recipient has no channels': 'У получателя не задан ни один канал (chat_id и/или email)',
+    'email required': 'Не указан email получателя',
+    'to required': 'Не указан адрес',
+    'body required': 'Пустое тело сообщения',
+    'not found': 'Не найдено',
+};
+export function ruError(code, status) {
+    if (code && ERR_RU[code])
+        return ERR_RU[code];
+    if (code)
+        return code;
+    if (status === 401)
+        return 'Не авторизовано (нет роли apprise-admin или истёк вход).';
+    if (status >= 500)
+        return 'Ошибка сервера, попробуйте ещё раз';
+    return 'Не удалось выполнить операцию';
+}
+/** Не-2xx ответ admin-API с телом {error: code}. */
+export class ApiError extends Error {
+    code;
+    status;
+    constructor(code, status) {
+        super(`api_error code=${code ?? 'null'} status=${status}`);
+        this.code = code;
+        this.status = status;
+        this.name = 'ApiError';
+    }
+}
+/** Нет валидного токена — нужно запустить login. */
+export class AuthRequiredError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AuthRequiredError';
+    }
+}
+/** Device flow стартован, но вход ещё не подтверждён в браузере. */
+export class AuthPendingError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AuthPendingError';
+    }
+}

package/dist/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { loadConfig } from './config.js';
+import { FileTokenStore, Authenticator } from './auth.js';
+import { HttpApiClient } from './api-client.js';
+import { createServer } from './server.js';
+async function main() {
+    const config = loadConfig();
+    const store = new FileTokenStore(config.configDir);
+    const auth = new Authenticator({ authority: config.authority, client: config.client }, store);
+    const api = new HttpApiClient(config, auth);
+    const server = createServer({ config, api, auth });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((e) => {
+    // stdout зарезервирован под MCP-протокол — диагностика только в stderr.
+    console.error('moab-notify fatal:', e);
+    process.exit(1);
+});

package/dist/server.js

@@ -0,0 +1,7 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerTools } from './tools/index.js';
+export function createServer(deps) {
+    const server = new McpServer({ name: 'moab-notify', version: '0.1.0' });
+    registerTools(server, deps);
+    return server;
+}

package/dist/tools/auth-tools.js

@@ -0,0 +1,34 @@
+import { run, ok } from './index.js';
+export function registerAuthTools(server, deps) {
+    server.registerTool('login', {
+        title: 'Войти',
+        description: 'Начать вход в управление уведомлениями через auth.moab.tools (device flow). Возвращает ссылку и код для подтверждения в браузере. Требуется роль apprise-admin.',
+        inputSchema: {},
+    }, async () => run(async () => {
+        const dc = await deps.auth.startLogin();
+        return [
+            'Чтобы войти, откройте ссылку и подтвердите вход:',
+            dc.verification_uri_complete,
+            `Код подтверждения: ${dc.user_code}`,
+            '',
+            'После подтверждения просто повторите нужную операцию — вход применится автоматически.',
+        ].join('\n');
+    }));
+    server.registerTool('auth_status', {
+        title: 'Статус входа',
+        description: 'Показать, выполнен ли вход и под каким пользователем.',
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, async () => run(async () => {
+        const s = await deps.auth.status();
+        return s.loggedIn ? `Вы вошли как ${s.username ?? '(неизвестно)'}.` : 'Вход не выполнен. Запустите инструмент login.';
+    }));
+    server.registerTool('auth_logout', {
+        title: 'Выйти',
+        description: 'Удалить сохранённые токены входа.',
+        inputSchema: {},
+    }, async () => {
+        await deps.auth.logout();
+        return ok('Вы вышли. Сохранённые токены удалены.');
+    });
+}

package/dist/tools/index.js

@@ -0,0 +1,28 @@
+import { ApiError, AuthRequiredError, AuthPendingError, ruError } from '../errors.js';
+import { registerAuthTools } from './auth-tools.js';
+import { registerRecipientTools } from './recipients.js';
+export function ok(text) {
+    return { content: [{ type: 'text', text }] };
+}
+export function fail(text) {
+    return { content: [{ type: 'text', text }], isError: true };
+}
+/** Единая обёртка: ловит Auth*Error/ApiError и превращает в дружелюбный текст. */
+export async function run(fn) {
+    try {
+        return ok(await fn());
+    }
+    catch (e) {
+        if (e instanceof AuthRequiredError)
+            return fail(e.message);
+        if (e instanceof AuthPendingError)
+            return fail(e.message);
+        if (e instanceof ApiError)
+            return fail(ruError(e.code, e.status));
+        return fail(`Ошибка: ${e instanceof Error ? e.message : String(e)}`);
+    }
+}
+export function registerTools(server, deps) {
+    registerAuthTools(server, deps);
+    registerRecipientTools(server, deps);
+}

package/dist/tools/recipients.js

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import { run } from './index.js';
+function channelsOf(r) {
+    const ch = [];
+    if (r.telegramChatId != null)
+        ch.push(`Telegram(${r.telegramChatId})`);
+    if (r.emailEnabled)
+        ch.push('email');
+    return ch.length ? ch.join(' + ') : '— нет каналов';
+}
+export function registerRecipientTools(server, deps) {
+    server.registerTool('recipient_list', {
+        title: 'Список получателей',
+        description: 'Показать адресную книгу: получатели и их каналы (Telegram / email).',
+        inputSchema: {},
+        annotations: { readOnlyHint: true },
+    }, async () => run(async () => {
+        const list = await deps.api.listRecipients();
+        if (list.length === 0)
+            return 'Адресная книга пуста.';
+        return list
+            .map((r) => `• ${r.email}${r.displayName ? ` (${r.displayName})` : ''} — ${channelsOf(r)}`)
+            .join('\n');
+    }));
+    server.registerTool('recipient_set', {
+        title: 'Создать/изменить получателя',
+        description: 'Завести получателя или обновить его каналы (по email-идентификатору). Указанные поля перезаписываются, неуказанные сохраняются. ' +
+            'Telegram-only = задать только telegram_chat_id. chat_id берётся из @MoabAlertsBot (получатель должен нажать Start).',
+        inputSchema: {
+            email: z.string().email().describe('email-идентификатор получателя (он же адрес при email_enabled)'),
+            display_name: z.string().optional().describe('отображаемое имя'),
+            telegram_chat_id: z.number().int().optional().describe('Telegram chat_id (личный id пользователя)'),
+            email_enabled: z.boolean().optional().describe('слать ли на email этого получателя'),
+        },
+    }, async ({ email, display_name, telegram_chat_id, email_enabled }) => run(async () => {
+        const e = email.trim().toLowerCase();
+        const existing = (await deps.api.listRecipients()).find((r) => r.email === e);
+        const merged = {
+            email: e,
+            displayName: display_name !== undefined ? (display_name || null) : (existing?.displayName ?? null),
+            telegramChatId: telegram_chat_id !== undefined ? telegram_chat_id : (existing?.telegramChatId ?? null),
+            emailEnabled: email_enabled !== undefined ? email_enabled : (existing?.emailEnabled ?? false),
+        };
+        await deps.api.upsertRecipient(merged);
+        return `Сохранено: ${merged.email} — ${channelsOf(merged)}`;
+    }));
+    server.registerTool('recipient_remove', {
+        title: 'Удалить получателя',
+        description: 'Удалить получателя из адресной книги.',
+        inputSchema: {
+            email: z.string().email().describe('email-идентификатор получателя'),
+        },
+        annotations: { destructiveHint: true },
+    }, async ({ email }) => run(async () => {
+        await deps.api.deleteRecipient(email.trim().toLowerCase());
+        return `Удалён: ${email.trim().toLowerCase()}`;
+    }));
+    server.registerTool('notify_test', {
+        title: 'Тест-уведомление',
+        description: 'Отправить тестовое уведомление получателю по его каналам (из адресной книги).',
+        inputSchema: {
+            email: z.string().email().describe('email-идентификатор получателя'),
+        },
+    }, async ({ email }) => run(async () => {
+        const res = await deps.api.testRecipient(email.trim().toLowerCase());
+        const lines = res.dispatched.map((d) => `  ${d.channel}: ${d.ok ? 'ok' : 'FAIL'} (${d.status})`);
+        return [`Тест отправлен ${res.email}:`, ...lines].join('\n');
+    }));
+}

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "moab-notify",
+  "version": "0.1.0",
+  "description": "MCP server for moab.tools notifications (apprise.moab.tools) — manage notification recipients (Telegram + email) from an LLM.",
+  "type": "module",
+  "bin": { "moab-notify": "dist/index.js" },
+  "files": ["dist"],
+  "engines": { "node": ">=20" },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0",
+    "vitest": "^3.2.4"
+  },
+  "license": "UNLICENSED"
+}