Nlobby MCP

🚀 N Lobby MCP 服務器

N Lobby MCP 服務器是一個用於訪問 N Lobby 學校門戶數據的模型上下文協議（MCP）服務器。它通過基於瀏覽器的身份驗證，為用戶提供對學校信息（包括公告、日程安排和學習資源）的安全訪問。

🚀 快速開始

安裝

選項 1：從 npm 安裝（推薦）

npm install -g nlobby-mcp

選項 2：開發環境安裝

1. 克隆倉庫：

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

2. 安裝依賴：

pnpm install

3. 設置環境變量：

cp .env.example .env
# 如有需要，編輯 .env 文件（默認值通常可用）

4. 構建項目：

pnpm run build

配置

創建一個 .env 文件，包含以下變量（可選，提供了默認值）：

# N Lobby 配置
NLOBBY_BASE_URL=https://nlobby.nnn.ed.jp

# MCP 服務器配置
MCP_SERVER_NAME=nlobby-mcp
MCP_SERVER_VERSION=1.0.0

運行服務器

npm 安裝方式：

nlobby-mcp

開發環境安裝方式：

pnpm run start

與 Cursor 和其他 MCP 客戶端的設置

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

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

MCP 資源

服務器提供以下資源：

• nlobby://news - 學校新聞和通知
• nlobby://schedule - 每日課程表和活動安排
• nlobby://required-courses - 必修課程和學術信息
• nlobby://user-profile - 當前用戶信息

MCP 工具

身份驗證工具

• interactive_login - 打開瀏覽器進行手動登錄到 N Lobby（推薦）
• login_help - 獲取個性化的登錄幫助和故障排除信息
• set_cookies - 手動設置身份驗證 cookie
• check_cookies - 檢查身份驗證 cookie 狀態
• verify_authentication - 驗證所有客戶端的身份驗證狀態

數據檢索工具

• get_news - 檢索學校新聞，支持過濾和排序選項
• get_news_detail - 檢索特定新聞文章的詳細信息
• get_required_courses - 檢索必修課程信息，支持過濾選項
• get_schedule - 獲取特定日期的日程安排（向後兼容）
• get_calendar_events - 獲取日曆活動，支持高級選項（個人/學校）
• test_calendar_endpoints - 測試個人和學校日曆端點
• mark_news_as_read - 將新聞文章標記為已讀

調試工具

• health_check - 測試 N Lobby API 連接
• debug_connection - 詳細調試 N Lobby 連接
• test_page_content - 測試頁面內容檢索並顯示示例內容
• test_trpc_endpoint - 測試特定的 tRPC 端點並顯示詳細響應

MCP 提示

本服務器不提供任何預配置的提示。

身份驗證流程

方法 1：交互式瀏覽器登錄（推薦）

1. 使用 interactive_login 工具（無需憑證）
2. 瀏覽器窗口將打開到 N Lobby
3. 在瀏覽器中手動完成登錄過程
4. 系統將檢測到你已登錄並自動提取 cookie
5. 立即訪問真實的 N Lobby 數據

方法 2：手動設置 cookie

1. 通過網頁瀏覽器登錄到 N Lobby
2. 從瀏覽器開發者工具中提取 cookie：
   • 打開開發者工具（F12）
   • 轉到應用程序/存儲選項卡
   • 將所有 cookie 複製為字符串
3. 使用 set_cookies 工具並提供完整的 cookie 字符串
4. 使用 health_check 工具驗證連接
5. 通過其他工具訪問真實的 N Lobby 數據

快速開始示例

學生用戶

# 獲取學生賬戶幫助
login_help email="your.name@nnn.ed.jp"

# 使用交互式登錄（推薦）
interactive_login

# 獲取今日新聞
get_news

# 獲取特定新聞文章的詳細信息
get_news_detail newsId="980"

# 獲取新聞詳情並標記為已讀
get_news_detail newsId="980" markAsRead=true

# 獲取今日個人日曆活動
get_calendar_events calendar_type="personal" period="today"

# 獲取本週學校日曆活動
get_calendar_events calendar_type="school" period="week"

# 獲取必修課程信息
get_required_courses

# 獲取特定年級的必修課程
get_required_courses grade=2

# 將新聞文章標記為已讀
mark_news_as_read id="980"

教職工用戶

# 獲取教職工賬戶幫助
login_help email="your.name@nnn.ac.jp"

# 使用交互式登錄
interactive_login

# 測試兩個日曆端點
test_calendar_endpoints

家長用戶

# 獲取家長賬戶幫助
login_help email="parent@gmail.com"

# 使用交互式登錄
interactive_login

# 查看孩子的新聞
get_news

# 獲取孩子的日程安排
get_calendar_events calendar_type="personal" period="today"

故障排除

# 獲取通用幫助
login_help

# 檢查連接狀態
health_check

# 檢查 cookie 狀態
check_cookies

# 驗證所有系統的身份驗證狀態
verify_authentication

# 詳細調試連接
debug_connection

# 測試頁面內容檢索
test_page_content endpoint="/news"

必修課程

get_required_courses 工具允許你檢索學術課程信息：

# 獲取所有必修課程
get_required_courses

# 按年級過濾
get_required_courses grade=1
get_required_courses grade=2

# 組合多個過濾條件
get_required_courses grade=2 semester="2024"

響應包含全面的課程信息：

• 課程詳情：學科代碼/名稱、課程代碼/名稱
• 學分：學分小時數和批准的學分
• 進度跟蹤：報告完成百分比、平均分數
• 狀態信息：獲取狀態、評估等級
• 考試信息：考試狀態、定期考試結果、補考 URL
• 在校數據：出勤次數和要求
• 時間信息：學期年份、年級（1 年次、2 年次、3 年次）
• 計算字段：進度百分比、完成狀態、平均分數

日曆活動

get_calendar_events 工具支持高級選項：

# 獲取今日個人日曆
get_calendar_events calendar_type="personal" period="today"

# 獲取本週學校日曆
get_calendar_events calendar_type="school" period="week"

# 獲取特定日期範圍的活動
get_calendar_events calendar_type="personal" from_date="2024-01-15" to_date="2024-01-20"

# 獲取單日活動
get_calendar_events calendar_type="personal" from_date="2024-01-15"

Cookie 格式

使用 set_cookies 時，提供從瀏覽器獲取的完整 cookie 字符串：

__Secure-next-auth.session-token=ey...; __Host-next-auth.csrf-token=abc123...; other-cookies=values;

✨ 主要特性

• 基於瀏覽器的身份驗證：通過自動化瀏覽器窗口進行交互式登錄
• 基於 Cookie 的會話管理：使用 NextAuth.js cookie 進行安全的會話處理
• 學校信息訪問：檢索公告、日程安排和學習資源
• 必修課程管理：訪問必修課程信息和學術數據
• 多種日曆類型：支持個人和學校日曆
• 用戶角色支持：為學生、家長和教職工提供不同的訪問級別
• MCP 協議合規：與支持 MCP 的 AI 助手完全兼容
• 高級測試工具：內置調試和測試功能

📦 安裝指南

選項 1：從 npm 安裝（推薦）

npm install -g nlobby-mcp

選項 2：開發環境安裝

1. 克隆倉庫：

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

2. 安裝依賴：

pnpm install

3. 設置環境變量：

cp .env.example .env
# 如有需要，編輯 .env 文件（默認值通常可用）

4. 構建項目：

pnpm run build

📚 詳細文檔

配置

創建一個 .env 文件，包含以下變量（可選，提供了默認值）：

# N Lobby 配置
NLOBBY_BASE_URL=https://nlobby.nnn.ed.jp

# MCP 服務器配置
MCP_SERVER_NAME=nlobby-mcp
MCP_SERVER_VERSION=1.0.0

用戶類型

服務器根據電子郵件域名支持三種用戶類型：

• 學生：@nnn.ed.jp
• 教職工：@nnn.ac.jp
• 家長：任何其他註冊的電子郵件地址（Gmail、Yahoo、公司郵件等）

開發

腳本

• pnpm run build - 構建 TypeScript 項目
• pnpm run dev - 開發模式下的監聽模式
• pnpm run start - 啟動 MCP 服務器
• pnpm run test - 運行測試
• pnpm run lint - 代碼檢查
• pnpm run format - 代碼格式化

項目結構

src/
├── index.ts              # 入口點
├── server.ts             # MCP 服務器實現
├── api.ts                # N Lobby API 集成
├── browser-auth.ts       # 用於登錄的瀏覽器自動化
├── credential-manager.ts # 用戶憑證驗證和管理
├── nextauth.ts           # NextAuth.js 會話處理
├── trpc-client.ts        # 用於 API 調用的 tRPC 客戶端
├── config.ts             # 配置管理
├── logger.ts             # 日誌實用工具
└── types.ts              # TypeScript 類型定義

架構

服務器使用多個層進行身份驗證和 API 訪問：

1. 瀏覽器身份驗證：用於交互式登錄的自動化瀏覽器
2. Cookie 管理：處理 NextAuth.js 會話 cookie
3. HTTP 客戶端：基於 Axios 的 REST API 調用客戶端
4. tRPC 客戶端：用於 tRPC 端點的類型安全客戶端
5. 憑證管理器：驗證用戶類型並提供指導

安全注意事項

• 所有身份驗證令牌僅存儲在內存中
• 服務器使用安全的基於 cookie 的身份驗證
• 訪問僅限於授權的 N High School Group 電子郵件域名
• 不記錄或持久化任何敏感數據
• 瀏覽器自動化僅用於身份驗證，而不是數據抓取

故障排除

常見問題

1. 身份驗證失敗：使用 interactive_login 進行最可靠的身份驗證
2. Cookie 同步問題：運行 verify_authentication 檢查同步情況
3. 連接問題：使用 health_check 和 debug_connection 進行診斷
4. 結果為空：確保你已進行身份驗證並具有適當的權限

調試工具

服務器包含全面的調試工具：

• debug_connection - 網絡和身份驗證調試
• test_page_content - 內容檢索測試
• test_trpc_endpoint - API 端點測試
• verify_authentication - 身份驗證狀態驗證

🔧 技術細節

服務器使用多個層進行身份驗證和 API 訪問：

1. 瀏覽器身份驗證：通過自動化瀏覽器實現交互式登錄，為用戶提供便捷的登錄方式。
2. Cookie 管理：負責處理 NextAuth.js 會話 cookie，確保會話的安全性和有效性。
3. HTTP 客戶端：基於 Axios 構建，用於進行 REST API 調用，保證數據的高效傳輸。
4. tRPC 客戶端：作為類型安全的客戶端，用於調用 tRPC 端點，提高開發的準確性和效率。
5. Credential Manager：驗證用戶類型並提供相應的指導，確保不同用戶角色的正確訪問。

項目結構清晰，各模塊分工明確：

• index.ts 作為入口點，啟動整個服務器。
• server.ts 實現了 MCP 服務器的核心邏輯。
• api.ts 負責與 N Lobby API 進行集成。
• browser-auth.ts 實現了瀏覽器自動化登錄功能。
• credential-manager.ts 對用戶憑證進行驗證和管理。
• nextauth.ts 處理 NextAuth.js 會話。
• trpc-client.ts 用於進行 tRPC 端點的 API 調用。
• config.ts 管理服務器的配置信息。
• logger.ts 提供日誌記錄功能。
• types.ts 定義了 TypeScript 類型，確保代碼的類型安全。

📄 許可證

本項目採用 MIT 許可證 - 詳情請參閱 LICENSE 文件。

⚠️ 重要提示

開發者不對使用此 MCP 服務器可能造成的任何損害負責。本軟件是為教育目的開發的，不保證其運行效果。