STARWARCLOUD STARWAR.AI
返回市场
游廊-mcp

游廊-mcp

作者：minagishl3 星标更新：2025-11-04
安装使用来源：spider==github.com

项目介绍

N Lobby MCP Server

注意： 开发者不对使用此MCP服务器可能产生的任何损害承担责任。该软件旨在教育用途，其运行不保证无误。

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

特性

  • 基于浏览器的身份验证： 通过自动化浏览器窗口进行交互式登录
  • 基于Cookie的会话管理： 使用NextAuth.js Cookie进行安全会话处理
  • 学校信息访问： 获取公告、日程和学习资源
  • 必修课程管理： 访问必修课程信息和学术数据
  • 多种日历类型： 支持个人和学校日历
  • 用户角色支持： 学生、家长和教职工的不同访问级别
  • MCP协议兼容性： 完全兼容启用MCP的人工智能助手
  • 高级测试工具： 内置调试和测试能力

安装

方案1：从npm安装（推荐）

npm install -g nlobby-mcp

方案2：开发安装

  1. 克隆仓库：
git clone https://github.com/minagishl/nlobby-mcp.git
cd nlobby-mcp
  1. 安装依赖项：
pnpm install
  1. 设置环境变量：
cp .env.example .env
# 如需编辑，请修改.env文件（默认值应能正常工作）
  1. 构建项目：
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
<details> <summary>与Cursor和其他MCP客户端设置</summary>

Cursor IDE 设置

安装MCP服务器

在您的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
  • 环境：如配置部分所述的可选环境变量
</details>

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 - 标记新闻文章为已读（支持多个ID）

调试工具

  • 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）
    • 前往Application/Storage标签
    • 复制所有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

# 标记新闻文章为已读（单个ID）
mark_news_as_read ids=["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"

响应包括全面的课程信息：

  • 课程详情：科目代码/名称，课程大纲代码/名称
  • 学分：学时和批准学分
  • 进度跟踪：报告完成百分比，平均分数
  • 状态信息：获取状态，评估等级
  • 考试信息：考试状态，定期考试结果，补考网址
  • 在校数据：出勤次数和要求
  • 时间信息：学期年份，年级（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;

用户类型

服务器根据电子邮件域支持三种用户类型：

  • 学生：@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        # tRPC客户端用于API调用
├── 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高中集团电子邮件域
  • 不记录或持久化任何敏感数据
  • 浏览器自动化仅用于身份验证，而非数据抓取

故障排除

常见问题

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

调试工具

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

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

许可证

本项目采用MIT许可证 - 详情请参阅LICENSE文件。