CLI de N Lobby

Nota: El desarrollador no asume ninguna responsabilidad por los daños que puedan ocurrir al usar esta herramienta. Este software fue desarrollado con fines educativos y su funcionamiento no está garantizado.

Un servidor CLI y de Protocolo de Contexto de Modelo (MCP) de modo dual para acceder a los datos del portal escolar N Lobby. Úselo de forma interactiva desde la terminal con nlobby, o conéctelo a un asistente de IA como servidor MCP con nlobby serve.

Características

• Modo CLI: Acceda a los datos de N Lobby directamente desde la terminal: noticias, horarios, cursos, perfil y más.

• Modo MCP: Servidor MCP completo compatible con Claude, Cursor y otros asistentes de IA habilitados para MCP.

• Autenticación basada en navegador: Inicio de sesión interactivo a través de una ventana de navegador Puppeteer automatizada.

• Persistencia de sesión: El modo CLI guarda las cookies en ~/.nlobby/session para un uso posterior sin interrupciones.

• Acceso a información escolar: Recupere anuncios, horarios y recursos de aprendizaje.

• Gestión de cursos obligatorios: Acceda a información de cursos obligatorios y datos académicos.

• Múltiples tipos de calendario: Soporte tanto para calendarios personales como escolares.

• Soporte de roles de usuario: Diferentes niveles de acceso para estudiantes, padres y personal.

Related MCP server: MCP Server Sample

Instalación

Opción 1: Instalar desde npm (Recomendado)

npm install -g nlobby-cli

Opción 2: Instalación de desarrollo

1. Clone el repositorio:

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

2. Instale las dependencias:

pnpm install

3. Construya el proyecto:

pnpm run build

Configuración

Cree un archivo .env si necesita anular los valores predeterminados (opcional):

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

Uso de CLI

Autenticación

# 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

Noticias

# 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

Horarios y Calendario

# 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

Cursos

# All required courses
nlobby courses

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

Perfil y Salud

nlobby profile
nlobby health

Servidor MCP

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

Todos los comandos admiten --json para generar JSON sin formato en lugar de texto formateado.

Uso de MCP

Configuración de Cursor IDE

Añada lo siguiente a su configuración de Cursor (~/.cursor/config.json):

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

Configuración de Claude Desktop

Añada a su configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

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

Otros clientes MCP

Para cualquier cliente compatible con MCP, utilice:

• Comando: nlobby serve (si está instalado globalmente) o node /ruta/a/dist/index.js serve

• Protocolo: stdio

• Entorno: Variables de entorno opcionales como se indica en la sección de Configuración

Recursos MCP

Herramientas MCP

Autenticación

Noticias

Horarios y Calendario

Cursos y Exámenes

Cuenta y Navegación

Depuración

Flujo de autenticación

Método 1: Inicio de sesión interactivo en navegador (Recomendado)

CLI:

nlobby login

Herramienta MCP: interactive_login

Se abre una ventana del navegador automáticamente. Complete el inicio de sesión en N Lobby, y las cookies se extraerán y guardarán.

Método 2: Configuración manual de cookies

1. Inicie sesión en N Lobby en su navegador web

2. Abra DevTools → Aplicación / Almacenamiento → Cookies

3. Copie todas las cookies como una cadena

CLI:

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

Herramienta MCP: set_cookies cookies="__Secure-next-auth.session-token=ey...;"

Tipos de usuario

El servidor admite tres tipos de usuario según el dominio de correo electrónico:

Estructura del proyecto

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)

Desarrollo

Scripts

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

Notas de seguridad

• Las cookies de CLI se almacenan en ~/.nlobby/session (texto plano — protéjalas en consecuencia)

• El modo MCP mantiene todos los tokens de autenticación solo en memoria

• La automatización del navegador se utiliza solo para la autenticación, no para el raspado de datos

• No se registran datos confidenciales

Licencia

Este proyecto tiene licencia MIT — consulte el archivo LICENSE para obtener más detalles.