Smartschool Mcp

Smartschool MCP サーバー 🏫

AI アシスタントが Smartschool API に安全にアクセスできるようにする、動的な Model Context Protocol（MCP）サーバーです。このサーバーは利用可能な Smartschool のすべてのメソッドを自動的に検出し、包括的な安全対策を備えた MCP ツールとして公開します。

✨ 機能

• 🔄 動的な自動検出：Smartschool API のすべてのメソッドを自動的に検出します
• 🛡️ エンタープライズ向けの安全性：破壊的な操作に対する多層的な保護を提供します
• 🧠 AI 向けに最適化：AI による理解を深めるための豊富なコンテキストとドメイン知識を提供します
• 🚀 将来にも対応：Smartschool SDK の更新に自動的に適応します
• 📚 ドメインの専門知識：ベルギーの学校制度と慣習に関する知識を内蔵しています
• ⚡ メンテナンス不要：ツールを手動で定義する必要はありません

🚀 クイックスタート

前提条件

• Node.js 18+ または互換性のある JavaScript ランタイム
• Smartschool インスタンスへのアクセス
• 有効な Smartschool API 認証情報

インストール

# Clone the repository
git clone https://github.com/AbriantoLabs/smartschool-mcp.git
cd smartschool-mcp

# Install dependencies
npm install

# Build the project
npm run build

設定

環境変数を設定します。

# Required: Smartschool API Configuration
export SMARTSCHOOL_API_ENDPOINT="https://your-school.smartschool.be/Webservices/V3"
export SMARTSCHOOL_ACCESS_CODE="your-access-code"

# Optional: Safety Configuration
export ALLOW_DESTRUCTIVE=false          # Enable destructive operations
export REQUIRE_CONFIRMATION=true        # Require confirmation for risky operations

サーバーを手動で実行する

# Direct execution
node build/mod.js

# Or via npm script
npm start

🔧 AI アシスタントでの使用

Claude Desktop

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "smartschool": {
      "command": "npx",
      "args": ["-y", "@abrianto/smartschool-mcp"],
      "env": {
        "SMARTSCHOOL_API_ENDPOINT": "https://your-school.smartschool.be/Webservices/V3",
        "SMARTSCHOOL_ACCESS_CODE": "your-access-code",
        "ALLOW_DESTRUCTIVE": "false",
        "REQUIRE_CONFIRMATION": "true"
      }
    }
  }
}

または手動で追加します。

{
  "mcpServers": {
    "smartschool": {
      "command": "node",
      "args": ["/path/to/smartschool-mcp-server/build/mod.js"],
      "env": {
        "SMARTSCHOOL_API_ENDPOINT": "https://your-school.smartschool.be/Webservices/V3",
        "SMARTSCHOOL_ACCESS_CODE": "your-access-code",
        "ALLOW_DESTRUCTIVE": "false",
        "REQUIRE_CONFIRMATION": "true"
      }
    }
  }
}

その他の MCP 対応 AI システム

このサーバーは stdio 経由で通信し、MCP 仕様に準拠しています。AI システムを次のように設定してください。

1. サーバーをサブプロセスとして起動する
2. stdin/stdout 経由で接続する
3. 必要な環境変数を設定する

🛡️ 安全システム

このサーバーでは、包括的な 4 段階の安全分類を実装しています。

安全レベル

レベル	説明	例	動作
🟢 安全	読み取り専用の操作	getUserDetails、getAbsents	制限なし
🟡 中程度	元に戻せる変更	sendMsg、savePassword	常に許可
🔥 破壊的	影響の大きい変更	saveUser、saveClass	ALLOW_DESTRUCTIVE=true が必要
💀 重大	恒久的な削除	delUser、delClass	ALLOW_DESTRUCTIVE=true が必要

確認システム

破壊的および重大な操作には、明示的な確認が必要です。

// This will be blocked without confirmation
{
  "username": "john.doe",
  "name": "John",
  "surname": "Doe",
  "basisrol": "leerling"
}

// This will execute (with confirmDestructiveAction)
{
  "username": "john.doe", 
  "name": "John",
  "surname": "Doe",
  "basisrol": "leerling",
  "confirmDestructiveAction": true  // ← Required!
}

環境による制御

# Production (safe defaults)
export ALLOW_DESTRUCTIVE=false      # Blocks destructive operations
export REQUIRE_CONFIRMATION=true    # Requires explicit confirmation

# Development (more permissive)
export ALLOW_DESTRUCTIVE=true       # Allows all operations
export REQUIRE_CONFIRMATION=false   # No confirmation required (not recommended)

🧠 AI コンテキストとドメイン知識

このサーバーは、AI が Smartschool の慣習を理解できるよう、豊富なコンテキストを提供します。

ユーザー名の慣習

• 形式：firstname.lastname（例：「John Doe」→「john.doe」）
• 自動変換：名前は自動的にユーザー名に変換されます
• スマートな候補提示：名前らしい入力を検出すると、役立つヒントを提示します

欠席コード

ベルギーの学校の欠席コードについて詳しく説明します。

コード	意味	説明
|	出席	生徒は出席しました
L	遅刻	生徒は遅れて到着しました
Z	病気	病気による欠席
D	医師	通院
B	既知	事前に通知された欠席
R	予期せぬ欠席	緊急または家庭の事情
-	不明	理由不明の欠席

[20 種類以上のコードをすべて含む完全な一覧はコードを参照してください]

ユーザーの役割

• leerling：生徒
• leerkracht：教師
• directie：管理職／運営
• andere：その他の職員

共同アカウントシステム

• 0：メインアカウント（生徒／教師）
• 1：1 つ目の共同アカウント（通常は最初の保護者）
• 2：2 つ目の共同アカウント（通常は2人目の保護者）
• 3-6：追加の共同アカウント

📚 利用可能な操作

このサーバーは、Smartschool API のすべてのメソッドを自動的に公開します。主なカテゴリを以下に示します。

👥 ユーザー管理

• getUserDetails - ユーザー情報の詳細を取得します
• saveUser - ユーザーを作成または更新します（破壊的）
• delUser - ユーザーを完全に削除します（重大）
• setAccountStatus - アカウントを有効化／無効化します
• savePassword - パスワードを設定／変更します

🏛️ クラスとグループ

• getClassTeachers - クラスと教師の割り当て一覧を取得します
• saveClass - クラスを作成／変更します（破壊的）
• saveUserToClass - 生徒をクラスに割り当てます
• delClass - クラスを完全に削除します（重大）

📬 コミュニケーション

• sendMsg - ユーザー／保護者にメッセージを送信
• saveSignature - メールの署名を設定

📊 出欠・レポート

• getAbsents - 生徒の欠席記録を取得
• getAbsentsByDate - 日別の出欠レポート
• getStudentCareer - 学業履歴

⚙️ 管理

• startSkoreSync - システムを同期 (重要)
• addHelpdeskTicket - サポートチケットを作成
• getAllAccountsExtended - ユーザーデータを一括エクスポート

🔍 やり取りの例

安全な操作（確認不要）

# Get student details by name (auto-converts to username)
{
  "tool": "smartschool-getUserDetails",
  "params": {
    "userIdentifier": "John Doe"  # Becomes "john.doe"
  }
}

# Check attendance for a date  
{
  "tool": "smartschool-getAbsentsByDate", 
  "params": {
    "date": "2024-12-15"
  }
}

破壊的な操作（確認が必要）

# Create a new student (requires confirmation)
{
  "tool": "smartschool-saveUser",
  "params": {
    "username": "jane.smith",
    "name": "Jane", 
    "surname": "Smith",
    "basisrol": "leerling",
    "email": "[email protected]",
    "confirmDestructiveAction": true  # Required!
  }
}

重要な操作（最大限の注意が必要）

# Delete a user (requires ALLOW_DESTRUCTIVE=true + confirmation)
{
  "tool": "smartschool-delUser",
  "params": {
    "userIdentifier": "former.student", 
    "confirmDestructiveAction": true  # Required!
  }
}

🚨 エラー処理

サーバーは包括的なエラー処理を提供します。

安全上のブロック

🚫 Operation blocked: saveUser requires confirmation.

🔥 HIGH RISK: This operation will create, modify, or remove important data. 
Changes may be difficult to reverse.

To proceed, add: confirmDestructiveAction: true

設定エラー

⚠️ Skipping delUser: 🚫 CRITICAL operations are disabled. 
Set ALLOW_DESTRUCTIVE=true to enable.

API エラー

Error in getUserDetails: Invalid username or user not found

🔧 開発

プロジェクト構成

smartschool-mcp-server/
├── src/
│   └── mod.ts              # Main server implementation
├── build/                  # Compiled JavaScript
├── package.json           # Dependencies and scripts
├── tsconfig.json          # TypeScript configuration
└── README.md              # This file

ビルド

# Development build
npm run build

# Watch mode (for development)
npm run dev

# Type checking
npm run type-check

カスタムコンテキストの追加

特定のメソッドに対する AI の理解を深めるには、METHOD_CONTEXT オブジェクトを編集します。

const METHOD_CONTEXT = {
  yourMethodName: {
    description: "Human-friendly description",
    useCase: "When to use this method", 
    category: "Logical grouping",
    examples: ["Example use case 1", "Example 2"],
    smartschoolContext: "Smartschool-specific details"
  }
};

安全性の分類

安全性レベルを変更するには、METHOD_SAFETY オブジェクトを更新します。

const METHOD_SAFETY = {
  yourMethodName: SAFETY_LEVELS.DESTRUCTIVE,  // or SAFE, MODERATE, CRITICAL
};

📋 要件

システム要件

• Node.js 18.0.0 以降
• 256MB 以上の空きメモリ
• Smartschool API エンドポイントへのネットワークアクセス

Smartschool の要件

• 有効な Smartschool インスタンス
• API アクセスが有効であること
• 適切な権限を持つ有効なアクセスコード

権限

MCP サーバーには、以下の権限を持つ Smartschool API アクセスが必要です。

• ユーザー管理（ユーザー操作用）
• グループ／クラス管理（組織関連の操作用）
• メッセージング（コミュニケーション機能用）
• レポート（出欠／学業データ用）

適切な API アクセス設定については、Smartschool の管理者にお問い合わせください。

🔒 セキュリティに関する考慮事項

本番環境へのデプロイ

1. 環境変数：認証情報をバージョン管理にコミットしないでください
2. アクセス制御：本番環境では ALLOW_DESTRUCTIVE を制限してください
3. 監視：すべての破壊的な操作をログに記録してください
4. バックアップ：一括操作の前にデータベースをバックアップしてください
5. テスト：まず開発環境で十分にテストしてください

API セキュリティ

• API アクセスコードは定期的にローテーションしてください
• 通常と異なるパターンがないか、API の使用状況を監視してください
• 必要に応じてレート制限を実装してください
• HTTPS エンドポイントのみを使用してください

🤝 コントリビューション

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

開発ガイドライン

• TypeScript のベストプラクティスに従ってください
• 新しいメソッドには適切な安全性分類を追加してください
• 重要な変更についてはドキュメントを更新してください
• 複数の Smartschool 設定でテストしてください

📄 ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。

🙋‍♂️ サポート

ヘルプを得る

1. ドキュメント：この README とコード内のコメントを確認してください
2. Issue：バグや機能リクエストについては GitHub Issue を作成してください
3. ディスカッション：質問には GitHub Discussions をご利用ください
4. Smartschool サポート：API アクセスに関する問題は、Smartschool の管理者にお問い合わせください

よくある問題

サーバーが起動しない

• 環境変数が正しく設定されていることを確認してください
• Node.js のバージョンに互換性があることを確認してください
• Smartschool API エンドポイントにアクセスできることを確認してください

操作がブロックされる

• ALLOW_DESTRUCTIVE の設定を確認してください
• 破壊的な操作では confirmDestructiveAction パラメーターを確認してください
• 安全性レベルの分類を確認してください

AI がコンテキストを理解できない

• METHOD_CONTEXT のメソッドの説明を確認してください
• ドメイン知識のセクションが正確であることを確認してください
• メソッド固有の例を追加することを検討してください

🙏 謝辞

Abrianto & Smartschool-Kit

この MCP サーバーは、Abrianto が開発した優れた @abrianto/smartschool-kit ライブラリを基盤として構築されています。

Abrianto は、教育システム向けに開発者に使いやすいツールや API の開発に注力するテクノロジー企業です。その取り組みは、複雑な学校管理プラットフォームと最新の開発手法の間をつないでいます。

Smartschool-Kit について

@abrianto/smartschool-kit ライブラリは、以下を提供します。

• 🚀 ランタイムに依存しません：Deno、Browser、Node.js の各環境で動作します
• 💪 TypeScript を全面的にサポート：すべてのエンドポイントに対応する包括的な型定義を備えています
• 🔧 CLI インターフェイス：すばやく操作できるコマンドラインツールを備えています
• 🎯 API を完全に網羅：すべての Smartschool API エンドポイントに対応しています
• 📘 優れたドキュメント：詳細な例とメソッドの説明を掲載しています

# Install the underlying library
npm install @abrianto/smartschool-kit

# Or from JSR
jsr add @abrianto/smartschool-client

---

Abrianto が教育コミュニティのために ❤️ を込めて開発しました

この MCP サーバーは、AI アシスタントと学校管理システムの間をつなぎ、最高水準の安全性を維持しながら、複雑な教育データと自然言語でやり取りできるようにします。