Smartschool Mcp

Smartschool MCP 服务 🏫

一个动态的 Model Context Protocol（MCP）服务，为 AI 助手提供对 Smartschool API 的安全访问。此服务会自动发现所有可用的 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. 设置所需的环境变量

🛡️ 安全系统

此服务采用全面的四级安全分类：

安全级别

级别	描述	示例	行为
🟢 安全	只读操作	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：第一个子账户（通常为第一位家长）
• 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 访问权限：

• 用户管理（用于用户操作）
• 群组/班级管理（用于组织管理操作）
• 消息传递（用于通信功能）
• 报告（用于考勤/学业数据）

请联系 Smartschool 管理员，正确配置 API 访问权限。

🔒 安全注意事项

生产环境部署

1. 环境变量：切勿将凭据提交到版本控制系统
2. 访问控制：在生产环境中限制 ALLOW_DESTRUCTIVE
3. 监控：记录所有破坏性操作
4. 备份：执行批量操作前，确保数据库已备份
5. 测试：先在开发环境中进行全面测试

API 安全

• 应定期轮换 API 访问代码
• 监控 API 使用情况，留意异常模式
• 必要时实施速率限制
• 仅使用 HTTPS 端点

🤝 贡献

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 创建 Pull Request

开发指南

• 遵循 TypeScript 最佳实践
• 为新增方法添加适当的安全分类
• 对重大更改更新文档
• 使用多种 Smartschool 配置进行测试

📄 许可证

本项目采用 MIT License 授权，详情请参阅 LICENSE 文件。

🙋‍♂️ 支持

获取帮助

1. 文档：查阅此 README 和代码内注释
2. 问题：针对缺陷或功能请求提交 GitHub issue
3. 讨论：使用 GitHub Discussions 提问
4. Smartschool 支持：如遇 API 访问问题，请联系 Smartschool 管理员

常见问题

服务无法启动

• 检查环境变量是否设置正确
• 确认 Node.js 版本兼容
• 确保可以访问 Smartschool API 端点

操作被拦截

• 检查 ALLOW_DESTRUCTIVE 设置
• 确认破坏性操作的 confirmDestructiveAction 参数
• 检查安全级别分类

AI 无法理解上下文

• 检查 METHOD_CONTEXT 中的方法描述
• 确认领域知识部分准确无误
• 考虑添加特定于方法的示例

🙏 致谢

Abrianto & Smartschool-Kit

此 MCP 服务基于优秀的 @abrianto/smartschool-kit 库构建，该库由 Abrianto 创建。

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 助手与学校管理系统之间的差距，让用户能够通过自然语言与复杂的教育数据交互，同时保持最高的安全标准。