Nlobby MCP

🚀 N Lobby MCP Server

N Lobby MCP Serverは、N Lobby学校ポータルのデータにアクセスするためのModel Context Protocol (MCP)サーバーです。このサーバーは、ブラウザベースの認証を通じて、学校のお知らせ、スケジュール、学習リソースなどの情報に安全にアクセスできるようにします。

⚠️ 重要注意

このMCPサーバーを使用して生じた損害について、開発者は一切の責任を負いません。このソフトウェアは教育目的で開発されており、その動作は保証されていません。

✨ 主な機能

• ブラウザベースの認証：自動化されたブラウザウィンドウを介した対話型ログイン
• 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 Configuration
NLOBBY_BASE_URL=https://nlobby.nnn.ed.jp

# MCP Server Configuration
MCP_SERVER_NAME=nlobby-mcp
MCP_SERVER_VERSION=1.0.0

💻 使用例

サーバーの起動

npmでインストールした場合：

nlobby-mcp

開発用インストールの場合：

pnpm run start

{
  "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. 完全なCookie文字列を使用してset_cookiesツールを使用します
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;

👥 ユーザータイプ

サーバーは、メールドメインに基づいて3種類のユーザータイプをサポートしています：

• 学生：@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クライアント：REST API呼び出し用のAxiosベースのクライアント
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 - 認証ステータスの検証

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています - 詳細についてはLICENSEファイルを参照してください。