Nlobby Mcp

笔记 TypeScript

🚀 N Lobby MCP 服务器

N Lobby MCP 服务器是一个用于访问 N Lobby 学校门户数据的模型上下文协议（MCP）服务器。它通过基于浏览器的身份验证，为用户提供对学校信息（包括公告、日程安排和学习资源）的安全访问。

🚀 快速开始

安装

选项 1：从 npm 安装（推荐）

npm install -g nlobby-mcp

选项 2：开发环境安装

克隆仓库：

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

安装依赖：

pnpm install

设置环境变量：

cp .env.example .env
# 如有需要，编辑 .env 文件（默认值通常可用）

构建项目：

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 客户端的设置

Cursor IDE 设置

在你的 Cursor 设置文件（~/.cursor/config.json）中添加以下内容：

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

Claude Desktop 设置

在你的 Claude Desktop 配置文件（macOS 系统为 ~/Library/Application Support/Claude/claude_desktop_config.json）中添加以下内容：

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

其他 MCP 客户端

对于任何兼容 MCP 的客户端，使用以下设置：

命令：nlobby-mcp（如果全局安装）或 node /path/to/nlobby-mcp/dist/index.js
协议：stdio
环境：可选的环境变量，如配置部分所列

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：交互式浏览器登录（推荐）

使用 interactive_login 工具（无需凭证）
浏览器窗口将打开到 N Lobby
在浏览器中手动完成登录过程
系统将检测到你已登录并自动提取 cookie
立即访问真实的 N Lobby 数据

方法 2：手动设置 cookie

通过网页浏览器登录到 N Lobby
从浏览器开发者工具中提取 cookie：
- 打开开发者工具（F12）
- 转到应用程序/存储选项卡
- 将所有 cookie 复制为字符串
使用 set_cookies 工具并提供完整的 cookie 字符串
使用 health_check 工具验证连接
通过其他工具访问真实的 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：开发环境安装

克隆仓库：

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

安装依赖：

pnpm install

设置环境变量：

cp .env.example .env
# 如有需要，编辑 .env 文件（默认值通常可用）

构建项目：

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 访问：

浏览器身份验证：用于交互式登录的自动化浏览器
Cookie 管理：处理 NextAuth.js 会话 cookie
HTTP 客户端：基于 Axios 的 REST API 调用客户端
tRPC 客户端：用于 tRPC 端点的类型安全客户端
凭证管理器：验证用户类型并提供指导

安全注意事项

所有身份验证令牌仅存储在内存中
服务器使用安全的基于 cookie 的身份验证
访问仅限于授权的 N High School Group 电子邮件域名
不记录或持久化任何敏感数据
浏览器自动化仅用于身份验证，而不是数据抓取

故障排除

常见问题

身份验证失败：使用 interactive_login 进行最可靠的身份验证
Cookie 同步问题：运行 verify_authentication 检查同步情况
连接问题：使用 health_check 和 debug_connection 进行诊断
结果为空：确保你已进行身份验证并具有适当的权限

调试工具

服务器包含全面的调试工具：

debug_connection - 网络和身份验证调试
test_page_content - 内容检索测试
test_trpc_endpoint - API 端点测试
verify_authentication - 身份验证状态验证

🔧 技术细节

服务器使用多个层进行身份验证和 API 访问：

浏览器身份验证：通过自动化浏览器实现交互式登录，为用户提供便捷的登录方式。
Cookie 管理：负责处理 NextAuth.js 会话 cookie，确保会话的安全性和有效性。
HTTP 客户端：基于 Axios 构建，用于进行 REST API 调用，保证数据的高效传输。
tRPC 客户端：作为类型安全的客户端，用于调用 tRPC 端点，提高开发的准确性和效率。
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 服务器可能造成的任何损害负责。本软件是为教育目的开发的，不保证其运行效果。

0 条评论
分类：笔记

Nlobby Mcp

🚀 N Lobby MCP 服务器

🚀 快速开始

安装

选项 1：从 npm 安装（推荐）

选项 2：开发环境安装

配置

运行服务器

npm 安装方式：

开发环境安装方式：

与 Cursor 和其他 MCP 客户端的设置

Cursor IDE 设置

Claude Desktop 设置

其他 MCP 客户端

MCP 资源

MCP 工具

身份验证工具

数据检索工具

调试工具

MCP 提示

身份验证流程

方法 1：交互式浏览器登录（推荐）

方法 2：手动设置 cookie

快速开始示例

学生用户

教职工用户

家长用户

故障排除

必修课程

日历活动

Cookie 格式

✨ 主要特性

📦 安装指南

选项 1：从 npm 安装（推荐）

选项 2：开发环境安装

📚 详细文档

配置

用户类型

开发

脚本

项目结构

架构

安全注意事项

故障排除

常见问题

调试工具

🔧 技术细节

📄 许可证

0 个评论

相似服务问题

相关AI产品

热议话题 »