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 服务器可能造成的任何损害负责。本软件是为教育目的开发的，不保证其运行效果。