N Lobby MCP Server

Instructions

Implementation Reference

• src/server.ts:1033-1070 (handler)

  The main execution logic for the 'login_help' tool. Parses optional email argument, calls credentialManager methods to generate personalized login guidance, troubleshooting tips, and session statistics, then returns formatted text response.
  case "login_help": { const { email } = args as { email?: string }; let helpMessage = `[LOGIN] N Lobby Login Help\n\n`; if (email) { const emailValidation = this.credentialManager.validateEmail(email); helpMessage += `[EMAIL] Email: ${email}\n`; helpMessage += `[USER] User Type: ${emailValidation.userType}\n`; helpMessage += `[SUCCESS] Valid: ${emailValidation.valid ? "Yes" : "No"}\n\n`; if (!emailValidation.valid) { helpMessage += `[ERROR] Issue: ${emailValidation.message}\n\n`; } helpMessage += this.credentialManager.getLoginGuidance( emailValidation.userType, ); } else { helpMessage += this.credentialManager.getLoginGuidance("unknown"); } helpMessage += `\n\n${this.credentialManager.getTroubleshootingTips()}`; // Add session stats const stats = this.credentialManager.getSessionStats(); helpMessage += `\n\n[STATUS] Session Stats:\n- Active sessions: ${stats.total - stats.expired}\n- Expired sessions: ${stats.expired}`; return { content: [ { type: "text", text: helpMessage, }, ], }; }
• src/server.ts:419-431 (schema)

  Input schema definition for the 'login_help' tool, specifying an optional 'email' string parameter for personalized help.
  name: "login_help", description: "Get help and troubleshooting tips for N Lobby login", inputSchema: { type: "object", properties: { email: { type: "string", description: "Your email address (optional, for personalized help)", }, }, }, },
• src/server.ts:154-451 (registration)

  Registers the 'login_help' tool by including it in the response to ListToolsRequestSchema, making it discoverable by MCP clients.
  this.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: "get_news", description: "Retrieve school news", inputSchema: { type: "object", properties: { category: { type: "string", description: "Filter by category (optional)", }, limit: { type: "number", description: "Maximum number of news items to retrieve (optional, default: 10)", minimum: 1, default: 10, }, sort: { type: "string", description: "Sort order: 'newest' (default), 'oldest', 'title-asc', 'title-desc'", enum: ["newest", "oldest", "title-asc", "title-desc"], }, }, }, }, { name: "get_news_detail", description: "Retrieve detailed information for a specific news article", inputSchema: { type: "object", properties: { newsId: { type: "string", description: "The ID of the news article to retrieve", }, markAsRead: { type: "boolean", description: "Mark the news article as read (optional, default: false)", default: false, }, }, required: ["newsId"], }, }, { name: "get_account_info", description: "Extract account information by parsing Next.js flight data from a rendered page", inputSchema: { type: "object", properties: {}, }, }, { name: "get_student_card_screenshot", description: "Capture a screenshot of the student ID card by following the secure portal redirect flow", inputSchema: { type: "object", properties: {}, }, }, { name: "get_required_courses", description: "Retrieve required courses information with detailed progress tracking", inputSchema: { type: "object", properties: { grade: { type: "number", description: "Filter by grade level (1, 2, or 3) (optional)", }, semester: { type: "string", description: 'Filter by term year (e.g., "2024", "2025") (optional)', }, category: { type: "string", description: 'Filter by curriculum category (e.g., "国語", "数学", "英語") (optional)', }, }, }, }, { name: "get_schedule", description: "Get school schedule for a specific date (backward compatibility)", inputSchema: { type: "object", properties: { date: { type: "string", description: "Date in YYYY-MM-DD format (optional, defaults to today)", }, }, }, }, { name: "get_calendar_events", description: "Get calendar events with advanced options", inputSchema: { type: "object", properties: { calendar_type: { type: "string", enum: ["personal", "school"], description: "Type of calendar to retrieve (personal or school)", default: "personal", }, from_date: { type: "string", description: "Start date in YYYY-MM-DD format (optional). If only from_date is provided, it will be treated as a single day.", }, to_date: { type: "string", description: "End date in YYYY-MM-DD format (optional). Must be at least 1 day after from_date when both are provided.", }, period: { type: "string", enum: ["today", "week", "month"], description: 'Predefined period (optional, overrides from/to dates). Use "today" for single day queries.', }, }, }, }, { name: "test_calendar_endpoints", description: "Test both personal and school calendar endpoints", inputSchema: { type: "object", properties: { from_date: { type: "string", description: "Start date in YYYY-MM-DD format (optional). If only from_date is provided, it will be treated as a single day.", }, to_date: { type: "string", description: "End date in YYYY-MM-DD format (optional). Must be at least 1 day after from_date when both are provided.", }, }, }, }, { name: "set_cookies", description: "Set authentication cookies for N Lobby access", inputSchema: { type: "object", properties: { cookies: { type: "string", description: "Cookie string from authenticated N Lobby session", }, }, required: ["cookies"], }, }, { name: "check_cookies", description: "Check if authentication cookies are set", inputSchema: { type: "object", properties: {}, }, }, { name: "health_check", description: "Check if N Lobby API connection is working", inputSchema: { type: "object", properties: {}, }, }, { name: "debug_connection", description: "Debug N Lobby connection with detailed information", inputSchema: { type: "object", properties: { endpoint: { type: "string", description: "Endpoint to test (default: /news)", default: "/news", }, }, }, }, { name: "test_page_content", description: "Test page content retrieval and show sample content", inputSchema: { type: "object", properties: { endpoint: { type: "string", description: "Endpoint to test (default: /news)", default: "/news", }, length: { type: "number", description: "Number of characters to show (default: 1000)", default: 1000, }, }, }, }, { name: "test_trpc_endpoint", description: "Test specific tRPC endpoint with detailed response", inputSchema: { type: "object", properties: { method: { type: "string", description: "tRPC method to test (e.g., news.getUnreadNewsCount, user.updateLastAccess)", default: "user.updateLastAccess", }, params: { type: "string", description: "JSON string of parameters (optional)", }, }, }, }, { name: "verify_authentication", description: "Verify authentication status and cookie synchronization across all clients", inputSchema: { type: "object", properties: {}, }, }, { name: "interactive_login", description: "Open browser for manual login to N Lobby (no credentials required)", inputSchema: { type: "object", properties: {}, }, }, { name: "login_help", description: "Get help and troubleshooting tips for N Lobby login", inputSchema: { type: "object", properties: { email: { type: "string", description: "Your email address (optional, for personalized help)", }, }, }, }, { name: "mark_news_as_read", description: "Mark news articles as read", inputSchema: { type: "object", properties: { ids: { type: "array", items: { type: "string", }, description: "Array of news article IDs to mark as read", }, }, required: ["ids"], }, }, ], }; });
• src/credential-manager.ts:24-56 (helper)

  Validates email format and determines user type (student/staff/parent) based on domain, used for personalized login guidance in login_help.
  validateEmail(email: string): { valid: boolean; userType: "student" | "staff" | "parent" | "unknown"; message?: string; } { const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/; if (!emailRegex.test(email)) { return { valid: false, userType: "unknown", message: "Invalid email format", }; } const domain = email.split("@")[1].toLowerCase(); // N High School Group domains if (domain === "nnn.ed.jp") { return { valid: true, userType: "student" }; } else if (domain === "nnn.ac.jp") { return { valid: true, userType: "staff" }; } else if ( domain === "gmail.com" || domain === "yahoo.com" || domain === "outlook.com" || domain === "hotmail.com" ) { return { valid: true, userType: "parent" }; } else { return { valid: true, userType: "parent" }; // Allow other domains for parents } }
• src/credential-manager.ts:106-142 (helper)

  Generates user-type-specific login instructions, called by login_help handler.
  getLoginGuidance( userType: "student" | "staff" | "parent" | "unknown", ): string { switch (userType) { case "student": return ` [STUDENT] Student Login Guide: - Use your @nnn.ed.jp email address - Use your N High School password - If you have 2FA enabled, you'll need to complete it during login - Contact your homeroom teacher if you've forgotten your password`; case "staff": return ` [STAFF] Staff Login Guide: - Use your @nnn.ac.jp email address - Use your N High School staff password - If you have 2FA enabled, you'll need to complete it during login - Contact IT support if you're having trouble accessing your account`; case "parent": return ` [PARENT] Parent Login Guide: - Use the email address registered with your child's school account - Use the password you set when creating your parent account - If you haven't created a parent account yet, contact your child's school - If you've forgotten your password, use the password reset option`; default: return ` [LOGIN] General Login Guide: - Use your registered email address - Use your N Lobby password - If you have 2FA enabled, you'll need to complete it during login - Contact support if you're having trouble`; } }
• src/credential-manager.ts:147-179 (helper)

  Provides general troubleshooting tips for login issues, appended to login_help response.
  getTroubleshootingTips(): string { return ` [TIPS] Common Login Issues & Solutions: 1. **Wrong Email/Password** - Double-check your email address and password - Make sure Caps Lock is off - Try typing your password in a text editor first 2. **2FA Issues** - Make sure your authenticator app is synced - Try using backup codes if available - Wait for the next code if the current one doesn't work 3. **Browser Issues** - Clear your browser cache and cookies - Try using incognito/private mode - Disable browser extensions temporarily 4. **Account Locked** - Wait 15-30 minutes before trying again - Contact support if your account is suspended 5. **Network Issues** - Check your internet connection - Try using a different network or VPN - Make sure N Lobby isn't blocked by your firewall [PRO-TIP] Pro Tips: - Use 'interactive_login' if automated login fails - The browser window will stay open for manual completion - You can close the browser once login is complete`; }
• src/credential-manager.ts:203-217 (helper)

  Retrieves session statistics (active/expired counts), displayed in login_help response.
  getSessionStats(): { total: number; expired: number } { const now = Date.now(); let expired = 0; for (const stored of this.credentialStore.values()) { if (now - stored.timestamp > this.SESSION_TIMEOUT) { expired++; } } return { total: this.credentialStore.size, expired, }; }