CLI для N Lobby

Примечание: Разработчик не несет ответственности за любой ущерб, который может возникнуть в результате использования этого инструмента. Данное программное обеспечение разработано в образовательных целях, и его работа не гарантируется.

Двухрежимный CLI и сервер Model Context Protocol (MCP) для доступа к данным школьного портала N Lobby. Используйте его интерактивно из терминала с помощью nlobby или подключите к ИИ-ассистенту в качестве MCP-сервера с помощью nlobby serve.

Функции

• Режим CLI: Прямой доступ к данным N Lobby из терминала — новости, расписание, курсы, профиль и многое другое

• Режим MCP: Полноценный MCP-сервер, совместимый с Claude, Cursor и другими ИИ-ассистентами с поддержкой MCP

• Аутентификация через браузер: Интерактивный вход в систему через автоматизированное окно браузера Puppeteer

• Сохранение сессии: В режиме CLI файлы cookie сохраняются в ~/.nlobby/session для удобного последующего использования

• Доступ к школьной информации: Получение объявлений, расписаний и учебных ресурсов

• Управление обязательными курсами: Доступ к информации об обязательных курсах и академическим данным

• Различные типы календарей: Поддержка как личных, так и школьных календарей

• Поддержка ролей пользователей: Различные уровни доступа для студентов, родителей и сотрудников

Related MCP server: MCP Server Sample

Установка

Вариант 1: Установка из npm (рекомендуется)

npm install -g nlobby-cli

Вариант 2: Установка для разработки

1. Клонируйте репозиторий:

git clone https://github.com/minagishl/nlobby-cli.git
cd nlobby-cli

2. Установите зависимости:

pnpm install

3. Соберите проект:

pnpm run build

Конфигурация

Создайте файл .env, если вам нужно переопределить значения по умолчанию (необязательно):

NLOBBY_BASE_URL=https://nlobby.nnn.ed.jp
MCP_SERVER_NAME=nlobby-cli
MCP_SERVER_VERSION=1.0.0

Использование CLI

Аутентификация

# Interactive browser login (recommended)
nlobby login

# Set cookies manually
nlobby cookies set "__Secure-next-auth.session-token=ey...;"

# Check current authentication status
nlobby cookies check

Новости

# List latest news (default: 10, newest first)
nlobby news

# Filter and sort
nlobby news --limit 20 --category お知らせ --sort oldest --unread

# Show full article
nlobby news show 980

# Download the first attachment to /tmp
nlobby news download 980 --index 1 --output-dir /tmp

# Mark as read
nlobby news read 980

Расписание и календарь

# Today's schedule
nlobby schedule

# Specific date
nlobby schedule 2026-04-01

# This week's personal calendar
nlobby calendar

# School calendar for a date range
nlobby calendar --type school --from 2026-04-01 --to 2026-04-07

Курсы

# All required courses
nlobby courses

# Filter by grade / semester
nlobby courses --grade 2 --semester 2025

Профиль и здоровье

nlobby profile
nlobby health

MCP-сервер

# Start MCP server (stdio transport)
nlobby serve
# or
nlobby mcp

Все команды поддерживают флаг --json для вывода необработанного JSON вместо отформатированного текста.

Использование MCP

Настройка в Cursor IDE

Добавьте следующее в настройки Cursor (~/.cursor/config.json):

{
  "mcpServers": {
    "nlobby": {
      "command": "npx",
      "args": ["-y", "nlobby-cli", "serve"],
      "env": {
        "NLOBBY_BASE_URL": "https://nlobby.nnn.ed.jp"
      }
    }
  }
}

Настройка в Claude Desktop

Добавьте в конфигурацию Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json на macOS):

{
  "mcpServers": {
    "nlobby": {
      "command": "npx",
      "args": ["-y", "nlobby-cli", "serve"],
      "env": {
        "NLOBBY_BASE_URL": "https://nlobby.nnn.ed.jp"
      }
    }
  }
}

Другие MCP-клиенты

Для любого MCP-совместимого клиента используйте:

• Команда: nlobby serve (если установлена глобально) или node /path/to/dist/index.js serve

• Протокол: stdio

• Окружение: Дополнительные переменные окружения, указанные в разделе «Конфигурация»

Ресурсы MCP

Инструменты MCP

Аутентификация

Новости

Расписание и календарь

Курсы и экзамены

Аккаунт и навигация

Отладка

Процесс аутентификации

Способ 1: Интерактивный вход через браузер (рекомендуется)

CLI:

nlobby login

MCP-инструмент: interactive_login

Автоматически открывается окно браузера. Завершите вход в N Lobby, после чего файлы cookie будут извлечены и сохранены.

Способ 2: Ручная настройка файлов cookie

1. Войдите в N Lobby в своем веб-браузере

2. Откройте DevTools → Application / Storage → Cookies

3. Скопируйте все файлы cookie в виде строки

CLI:

nlobby cookies set "__Secure-next-auth.session-token=ey...;"

MCP-инструмент: set_cookies cookies="__Secure-next-auth.session-token=ey...;"

Типы пользователей

Сервер поддерживает три типа пользователей на основе домена электронной почты:

Структура проекта

src/
├── index.ts              # Entry point — CLI vs MCP mode detection
├── config.ts             # Configuration management
├── logger.ts             # Logging utilities
├── trpc-client.ts        # tRPC client for API calls
├── types.ts              # TypeScript type definitions
├── api/
│   ├── index.ts          # NLobbyApi facade + session persistence
│   ├── context.ts        # ApiContext interface
│   ├── shared.ts         # Shared utilities (fetchRenderedHtml, …)
│   ├── news.ts           # News functions
│   ├── schedule.ts       # Schedule / calendar functions
│   ├── courses.ts        # Course / exam functions
│   ├── account.ts        # Account info / student card functions
│   ├── navigation.ts     # Navigation / notification / interest functions
│   └── health.ts         # Health check / debug functions
├── auth/
│   ├── browser.ts        # Puppeteer browser authentication
│   ├── nextauth.ts       # NextAuth.js session handling
│   └── credentials.ts    # Credential validation and guidance
├── cli/
│   ├── index.ts          # Commander program wiring
│   ├── commands/         # login, news, schedule, courses, profile, health, serve
│   └── formatters/       # Human-readable output formatters
└── mcp/
    └── server.ts         # MCP server (28 tools, 4 resources)

Разработка

Скрипты

pnpm run build   # Build (esbuild bundle + tsc type declarations)
pnpm run dev     # Watch mode
pnpm run start   # Start MCP server
pnpm run lint    # Lint
pnpm run format  # Format

Примечания по безопасности

• Файлы cookie CLI хранятся в ~/.nlobby/session (в открытом виде — защищайте соответствующим образом)

• Режим MCP хранит все токены аутентификации только в оперативной памяти

• Автоматизация браузера используется только для аутентификации, а не для парсинга данных

• Конфиденциальные данные не логируются

Лицензия

Этот проект лицензирован по лицензии MIT — подробности см. в файле LICENSE.