{"_id":"@abrianto/smartschool-mcp","_rev":"3-cbf430c49ffdaf9855039a03bf8706ba","name":"@abrianto/smartschool-mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.0.1":{"name":"@abrianto/smartschool-mcp","version":"0.0.1","keywords":["mcp","smartschool","claude"],"author":{"name":"Maarten Coppens"},"license":"MIT","_id":"@abrianto/smartschool-mcp@0.0.1","maintainers":[{"name":"maartennnn","email":"martinuske@gmail.com"}],"bin":{"smartschool-mcp":"build/mod.js"},"dist":{"shasum":"487749033933e2b15b6ce741a76ab79881c3efec","tarball":"https://registry.npmjs.org/@abrianto/smartschool-mcp/-/smartschool-mcp-0.0.1.tgz","fileCount":9,"integrity":"sha512-ikWNj23SNrKf471JxdfTFyxKftUWi/cq2a+0he3optPhsKZYlkyH00MS1yXMowZ0NVDAPArS1ppVPQ1MgvlAIw==","signatures":[{"sig":"MEQCIARfQr6qrDJP4y4e4OlimRSLxlgQQx8ZIQ7qvyzvnQrxAiAU2mHrmK/69z3sMrYBcnv/1yT+vgZSQPhHS+BZJZ7FEg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":113418},"main":"build/mod.js","type":"module","gitHead":"a54f0e0eebc53e4d7d7a7a19dad08d11b338b1cb","scripts":{"dev":"tsc-watch --onSuccess \"node build/mod.js\"","build":"tsc && chmod +x build/mod.js","start":"node build/mod.js"},"_npmUser":{"name":"maartennnn","email":"martinuske@gmail.com"},"_npmVersion":"10.8.2","description":"MCP Server for Smartschool API","directories":{},"_nodeVersion":"20.19.0","dependencies":{"zod":"^3.25.51","dotenv":"^16.5.0","@abrianto/smartschool-kit":"^0.0.11","@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.2","tsc-watch":"^6.3.1","typescript":"^5.8.3","@types/node":"^20.17.57"},"_npmOperationalInternal":{"tmp":"tmp/smartschool-mcp_0.0.1_1749537611923_0.14421718551056784","host":"s3://npm-registry-packages-npm-production"}},"0.0.2":{"name":"@abrianto/smartschool-mcp","version":"0.0.2","keywords":["mcp","smartschool","claude"],"author":{"name":"Maarten Coppens"},"license":"MIT","_id":"@abrianto/smartschool-mcp@0.0.2","maintainers":[{"name":"maartennnn","email":"martinuske@gmail.com"}],"bin":{"smartschool-mcp":"build/mod.js"},"dist":{"shasum":"384512b91fa0da1a452b6c18cfef38af5ec7bf7b","tarball":"https://registry.npmjs.org/@abrianto/smartschool-mcp/-/smartschool-mcp-0.0.2.tgz","fileCount":9,"integrity":"sha512-uctlFXo2jDqonvV3Kfm+F81msgrmNI8dRpdpmP1CISrb3oGsOiUAZjXGoiIGGkqMKfUK/shEttdry9+teClMYA==","signatures":[{"sig":"MEQCIFiFdKvtghGxsh7BSuwU3253VsaCyOG3QxRNaC5w6S0dAiAIbXFWn0zlr0etWJqH8qiOGFhnC/4H0BQCztdc+709Eg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":113826},"main":"build/mod.js","type":"module","gitHead":"bf643c7cc3e444dfb5058ed859b1d315f5a8e23b","scripts":{"dev":"tsc-watch --onSuccess \"node build/mod.js\"","build":"tsc && chmod +x build/mod.js","start":"node build/mod.js"},"_npmUser":{"name":"maartennnn","email":"martinuske@gmail.com"},"_npmVersion":"10.8.2","description":"MCP Server for Smartschool API","directories":{},"_nodeVersion":"20.19.0","dependencies":{"zod":"^3.25.51","dotenv":"^16.5.0","@abrianto/smartschool-kit":"^0.0.11","@modelcontextprotocol/sdk":"^1.12.1"},"_hasShrinkwrap":false,"devDependencies":{"ts-node":"^10.9.2","tsc-watch":"^6.3.1","typescript":"^5.8.3","@types/node":"^20.17.57"},"_npmOperationalInternal":{"tmp":"tmp/smartschool-mcp_0.0.2_1749635346821_0.9651000852556637","host":"s3://npm-registry-packages-npm-production"}},"0.1.0":{"name":"@abrianto/smartschool-mcp","version":"0.1.0","description":"MCP Server for Smartschool API","main":"build/mod.js","type":"module","bin":{"smartschool-mcp":"build/mod.js"},"scripts":{"build":"tsc && chmod +x build/mod.js","start":"node build/mod.js","dev":"tsc-watch --onSuccess \"node build/mod.js\""},"keywords":["mcp","smartschool","claude"],"author":{"name":"Maarten Coppens"},"license":"MIT","dependencies":{"@abrianto/smartschool-kit":"^0.0.11","@modelcontextprotocol/sdk":"^1.12.1","dotenv":"^16.5.0","zod":"^3.25.51"},"devDependencies":{"@types/node":"^20.17.57","ts-node":"^10.9.2","tsc-watch":"^6.3.1","typescript":"^5.8.3"},"gitHead":"7d90f28bb30c68e7cf072d17c75d3b0eacda56bc","_id":"@abrianto/smartschool-mcp@0.1.0","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-wmSCgiu8tFs5p63PzbXHoLcdsbrWx2yA3nh5l/6yRruPrpqwPWQqMjm1cON5GKeAU5ueVVVwEYiarCr56KJyTA==","shasum":"19bca3b2fdbf2be06d5d2e0bfbeeb046832474ce","tarball":"https://registry.npmjs.org/@abrianto/smartschool-mcp/-/smartschool-mcp-0.1.0.tgz","fileCount":9,"unpackedSize":153348,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGLi4QpdT6JAob/Rg21YW4OCLfl2Rq8P7PZUARqIiOvHAiEAtvr2z45oAUPJJlakfUunSzhT1UVd6TXYpamqik9FC1E="}]},"_npmUser":{"name":"maartennnn","email":"martinuske@gmail.com"},"directories":{},"maintainers":[{"name":"maartennnn","email":"martinuske@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/smartschool-mcp_0.1.0_1788937652276_0.9151383276546563"},"_hasShrinkwrap":false}},"time":{"created":"2025-06-10T06:40:11.795Z","modified":"2026-09-09T07:07:32.702Z","0.0.1":"2025-06-10T06:40:12.116Z","0.0.2":"2025-06-11T09:49:07.034Z","0.1.0":"2026-09-09T07:07:32.415Z"},"author":{"name":"Maarten Coppens"},"license":"MIT","keywords":["mcp","smartschool","claude"],"description":"MCP Server for Smartschool API","maintainers":[{"name":"maartennnn","email":"martinuske@gmail.com"}],"readme":"# Smartschool MCP Server 🏫\n\nA dynamic Model Context Protocol (MCP) server that provides AI assistants with secure access to Smartschool APIs. This server automatically discovers all available Smartschool methods and exposes them as MCP tools with comprehensive safety guardrails.\n\n## ✨ Features\n\n- 🔄 **Dynamic Auto-Discovery**: Automatically detects all Smartschool API methods\n- 🛡️ **Enterprise Safety**: Multi-level protection against destructive operations\n- 🧠 **AI-Optimized**: Rich context and domain knowledge for better AI understanding\n- 🚀 **Future-Proof**: Adapts automatically when Smartschool SDK updates\n- 📚 **Domain Expert**: Built-in knowledge of Belgian school systems and conventions\n- ⚡ **Zero Maintenance**: No manual tool definitions required\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- Node.js 18+ or compatible JavaScript runtime\n- Access to a Smartschool instance\n- Valid Smartschool API credentials\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/AbriantoLabs/smartschool-mcp.git\ncd smartschool-mcp\n\n# Install dependencies\nnpm install\n\n# Build the project\nnpm run build\n```\n\n### Configuration\n\nSet up your environment variables:\n\n```bash\n# Required: Smartschool API Configuration\nexport SMARTSCHOOL_API_ENDPOINT=\"https://your-school.smartschool.be/Webservices/V3\"\nexport SMARTSCHOOL_ACCESS_CODE=\"your-access-code\"\n\n# Optional: Safety Configuration\nexport ALLOW_DESTRUCTIVE=false          # Enable destructive operations\nexport REQUIRE_CONFIRMATION=true        # Require confirmation for risky operations\n```\n\n### Running the Server manually\n\n```bash\n# Direct execution\nnode build/mod.js\n\n# Or via npm script\nnpm start\n```\n\n## 🔧 Usage with AI Assistants\n\n### Claude Desktop\n\nAdd to your `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"smartschool\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@abrianto/smartschool-mcp\"],\n      \"env\": {\n        \"SMARTSCHOOL_API_ENDPOINT\": \"https://your-school.smartschool.be/Webservices/V3\",\n        \"SMARTSCHOOL_ACCESS_CODE\": \"your-access-code\",\n        \"ALLOW_DESTRUCTIVE\": \"false\",\n        \"REQUIRE_CONFIRMATION\": \"true\"\n      }\n    }\n  }\n}\n```\n\nor manually:\n\n```json\n{\n  \"mcpServers\": {\n    \"smartschool\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/smartschool-mcp-server/build/mod.js\"],\n      \"env\": {\n        \"SMARTSCHOOL_API_ENDPOINT\": \"https://your-school.smartschool.be/Webservices/V3\",\n        \"SMARTSCHOOL_ACCESS_CODE\": \"your-access-code\",\n        \"ALLOW_DESTRUCTIVE\": \"false\",\n        \"REQUIRE_CONFIRMATION\": \"true\"\n      }\n    }\n  }\n}\n```\n\n### Other MCP-Compatible AI Systems\n\nThe server communicates via stdio and follows the MCP specification. Configure your AI system to:\n\n1. Launch the server as a subprocess\n2. Connect via stdin/stdout \n3. Set the required environment variables\n\n## 🛡️ Safety System\n\nThe server implements a comprehensive 4-level safety classification:\n\n### Safety Levels\n\n| Level | Description | Examples | Behavior |\n|-------|-------------|----------|----------|\n| 🟢 **SAFE** | Read-only operations | `getUserDetails`, `getAbsents` | No restrictions |\n| 🟡 **MODERATE** | Reversible changes | `sendMsg`, `savePassword` | Always allowed |\n| 🔥 **DESTRUCTIVE** | High-impact changes | `saveUser`, `saveClass` | Requires `ALLOW_DESTRUCTIVE=true` |\n| 💀 **CRITICAL** | Permanent deletions | `delUser`, `delClass` | Requires `ALLOW_DESTRUCTIVE=true` |\n\n### Confirmation System\n\nDestructive and critical operations require explicit confirmation:\n\n```javascript\n// This will be blocked without confirmation\n{\n  \"username\": \"john.doe\",\n  \"name\": \"John\",\n  \"surname\": \"Doe\",\n  \"basisrol\": \"leerling\"\n}\n\n// This will execute (with confirmDestructiveAction)\n{\n  \"username\": \"john.doe\", \n  \"name\": \"John\",\n  \"surname\": \"Doe\",\n  \"basisrol\": \"leerling\",\n  \"confirmDestructiveAction\": true  // ← Required!\n}\n```\n\n### Environment Controls\n\n```bash\n# Production (safe defaults)\nexport ALLOW_DESTRUCTIVE=false      # Blocks destructive operations\nexport REQUIRE_CONFIRMATION=true    # Requires explicit confirmation\n\n# Development (more permissive)\nexport ALLOW_DESTRUCTIVE=true       # Allows all operations\nexport REQUIRE_CONFIRMATION=false   # No confirmation required (not recommended)\n```\n\n## 🧠 AI Context & Domain Knowledge\n\nThe server provides rich context to help AI understand Smartschool conventions:\n\n### Username Conventions\n- **Pattern**: `firstname.lastname` (e.g., \"John Doe\" → \"john.doe\")\n- **Auto-conversion**: Names automatically converted to usernames\n- **Smart suggestions**: Helpful tips when name-like input detected\n\n### Absence Codes\nComprehensive explanation of Belgian school absence codes:\n\n| Code | Meaning | Description |\n|------|---------|-------------|\n| `\\|` | Present | Student was in attendance |\n| `L` | Late | Student arrived late |\n| `Z` | Sick | Absent due to illness |\n| `D` | Doctor | Medical appointment |\n| `B` | Known | Pre-notified absence |\n| `R` | Unforeseen | Emergency/family reasons |\n| `-` | Unknown | Unexplained absence |\n\n*[See full list in code for all 20+ codes]*\n\n### User Roles\n- `leerling`: Student\n- `leerkracht`: Teacher  \n- `directie`: Management/Administration\n- `andere`: Other staff\n\n### Co-Account System\n- `0`: Main account (student/teacher)\n- `1`: First co-account (typically first parent)\n- `2`: Second co-account (typically second parent)\n- `3-6`: Additional co-accounts\n\n## 📚 Available Operations\n\nThe server automatically exposes all Smartschool API methods. Here are some key categories:\n\n### 👥 User Management\n- `getUserDetails` - Get comprehensive user information\n- `saveUser` - Create or update users *(Destructive)*\n- `delUser` - Delete users permanently *(Critical)*\n- `setAccountStatus` - Activate/deactivate accounts\n- `savePassword` - Set/change passwords\n\n### 🏛️ Classes & Groups  \n- `getClassTeachers` - List class-teacher assignments\n- `saveClass` - Create/modify classes *(Destructive)*\n- `saveUserToClass` - Assign students to classes\n- `delClass` - Delete classes permanently *(Critical)*\n\n### 📬 Communication\n- `sendMsg` - Send messages to users/parents\n- `saveSignature` - Set email signatures\n\n### 📊 Attendance & Reporting\n- `getAbsents` - Get student absence records\n- `getAbsentsByDate` - Daily attendance reports\n- `getStudentCareer` - Academic history\n\n### ⚙️ Administration\n- `startSkoreSync` - System synchronization *(Critical)*\n- `addHelpdeskTicket` - Create support tickets\n- `getAllAccountsExtended` - Bulk user data export\n\n## 🔍 Example Interactions\n\n### Safe Operations (No confirmation needed)\n\n```bash\n# Get student details by name (auto-converts to username)\n{\n  \"tool\": \"smartschool-getUserDetails\",\n  \"params\": {\n    \"userIdentifier\": \"John Doe\"  # Becomes \"john.doe\"\n  }\n}\n\n# Check attendance for a date  \n{\n  \"tool\": \"smartschool-getAbsentsByDate\", \n  \"params\": {\n    \"date\": \"2024-12-15\"\n  }\n}\n```\n\n### Destructive Operations (Confirmation required)\n\n```bash\n# Create a new student (requires confirmation)\n{\n  \"tool\": \"smartschool-saveUser\",\n  \"params\": {\n    \"username\": \"jane.smith\",\n    \"name\": \"Jane\", \n    \"surname\": \"Smith\",\n    \"basisrol\": \"leerling\",\n    \"email\": \"jane.smith@student.school.be\",\n    \"confirmDestructiveAction\": true  # Required!\n  }\n}\n```\n\n### Critical Operations (Extreme caution)\n\n```bash\n# Delete a user (requires ALLOW_DESTRUCTIVE=true + confirmation)\n{\n  \"tool\": \"smartschool-delUser\",\n  \"params\": {\n    \"userIdentifier\": \"former.student\", \n    \"confirmDestructiveAction\": true  # Required!\n  }\n}\n```\n\n## 🚨 Error Handling\n\nThe server provides comprehensive error handling:\n\n### Safety Blocks\n```\n🚫 Operation blocked: saveUser requires confirmation.\n\n🔥 HIGH RISK: This operation will create, modify, or remove important data. \nChanges may be difficult to reverse.\n\nTo proceed, add: confirmDestructiveAction: true\n```\n\n### Configuration Errors\n```\n⚠️ Skipping delUser: 🚫 CRITICAL operations are disabled. \nSet ALLOW_DESTRUCTIVE=true to enable.\n```\n\n### API Errors\n```\nError in getUserDetails: Invalid username or user not found\n```\n\n## 🔧 Development\n\n### Project Structure\n\n```\nsmartschool-mcp-server/\n├── src/\n│   └── mod.ts              # Main server implementation\n├── build/                  # Compiled JavaScript\n├── package.json           # Dependencies and scripts\n├── tsconfig.json          # TypeScript configuration\n└── README.md              # This file\n```\n\n### Building\n\n```bash\n# Development build\nnpm run build\n\n# Watch mode (for development)\nnpm run dev\n\n# Type checking\nnpm run type-check\n```\n\n### Adding Custom Context\n\nTo enhance AI understanding for specific methods, edit the `METHOD_CONTEXT` object:\n\n```typescript\nconst METHOD_CONTEXT = {\n  yourMethodName: {\n    description: \"Human-friendly description\",\n    useCase: \"When to use this method\", \n    category: \"Logical grouping\",\n    examples: [\"Example use case 1\", \"Example 2\"],\n    smartschoolContext: \"Smartschool-specific details\"\n  }\n};\n```\n\n### Safety Classification\n\nTo modify safety levels, update the `METHOD_SAFETY` object:\n\n```typescript\nconst METHOD_SAFETY = {\n  yourMethodName: SAFETY_LEVELS.DESTRUCTIVE,  // or SAFE, MODERATE, CRITICAL\n};\n```\n\n## 📋 Requirements\n\n### System Requirements\n- Node.js 18.0.0 or higher\n- 256MB+ available memory\n- Network access to Smartschool API endpoint\n\n### Smartschool Requirements\n- Active Smartschool instance\n- API access enabled\n- Valid access code with appropriate permissions\n\n### Permissions\n\nThe MCP server requires Smartschool API access with permissions for:\n\n- **User management** (for user operations)\n- **Group/class management** (for organizational operations)  \n- **Messaging** (for communication features)\n- **Reporting** (for attendance/academic data)\n\nConsult your Smartschool administrator for proper API access configuration.\n\n## 🔒 Security Considerations\n\n### Production Deployment\n\n1. **Environment Variables**: Never commit credentials to version control\n2. **Access Control**: Restrict `ALLOW_DESTRUCTIVE` in production\n3. **Monitoring**: Log all destructive operations\n4. **Backup**: Ensure database backups before bulk operations\n5. **Testing**: Thoroughly test in development environment first\n\n### API Security\n\n- API access codes should be rotated regularly\n- Monitor API usage for unusual patterns\n- Implement rate limiting if needed\n- Use HTTPS endpoints only\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n### Development Guidelines\n\n- Follow TypeScript best practices\n- Add appropriate safety classifications for new methods\n- Update documentation for significant changes\n- Test with multiple Smartschool configurations\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙋‍♂️ Support\n\n### Getting Help\n\n1. **Documentation**: Check this README and inline code comments\n2. **Issues**: Open a GitHub issue for bugs or feature requests\n3. **Discussions**: Use GitHub Discussions for questions\n4. **Smartschool Support**: Contact your Smartschool administrator for API access issues\n\n### Common Issues\n\n**Server won't start**\n- Check environment variables are set correctly\n- Verify Node.js version compatibility\n- Ensure Smartschool API endpoint is accessible\n\n**Operations being blocked**\n- Check `ALLOW_DESTRUCTIVE` setting\n- Verify `confirmDestructiveAction` parameter for destructive operations\n- Review safety level classifications\n\n**AI not understanding context**\n- Check method descriptions in `METHOD_CONTEXT`\n- Verify domain knowledge sections are accurate\n- Consider adding method-specific examples\n\n## 🙏 Acknowledgments\n\n### Abrianto & Smartschool-Kit\n\nThis MCP server is built on top of the excellent **[@abrianto/smartschool-kit](https://jsr.io/@abrianto/smartschool-client)** library, created by [**Abrianto**](https://github.com/AbriantoLabs). \n\n**Abrianto** is a technology company focused on creating developer-friendly tools and APIs for educational systems. Their work bridges the gap between complex school management platforms and modern development practices.\n\n#### About Smartschool-Kit\n\nThe `@abrianto/smartschool-kit` library provides:\n\n- 🚀 **Runtime Agnostic**: Works in Deno, Browser, and Node.js environments\n- 💪 **Full TypeScript Support**: Comprehensive type definitions for all endpoints\n- 🔧 **CLI Interface**: Command-line tools for quick operations\n- 🎯 **Complete API Coverage**: Supports all Smartschool API endpoints\n- 📘 **Excellent Documentation**: Detailed examples and method descriptions\n\n```bash\n# Install the underlying library\nnpm install @abrianto/smartschool-kit\n\n# Or from JSR\njsr add @abrianto/smartschool-client\n```\n\n<!--\n## 🚀 Roadmap\n\n- [ ] GraphQL endpoint support\n- [ ] Bulk operation optimization\n- [ ] Advanced error recovery\n- [ ] Performance monitoring\n- [ ] Multi-tenant support\n- [ ] Real-time change notifications\n-->\n\n---\n\n**Made with ❤️ for the education community by [Abrianto](https://github.com/AbriantoLabs)**\n\n*This MCP server bridges the gap between AI assistants and school management systems, enabling natural language interaction with complex educational data while maintaining the highest safety standards.*\n","readmeFilename":"README.md"}