UofT Student Helper MCP Server

# UofT Student Helper MCP Server 🎓 A Model Context Protocol (MCP) server that helps University of Toronto students access their academic information through AI assistants. This server provides tools to interact with ACORN (course enrollment system) and Quercus (learning management system) to retrieve course information and syllabi. ## 🎯 Features ### ACORN Integration - **View Enrolled Courses**: Get a list of all courses you're currently enrolled in - **Course Details**: Access detailed information about specific courses - **Course Schedule**: View your class schedule and timetable - **Academic History**: Retrieve past course enrollments and grades ### Quercus Integration - **Access Syllabi**: Download and view course syllabi - **Course Modules**: Browse course content and modules - **Assignments**: View upcoming assignments and due dates - **Announcements**: Get latest course announcements ## 🏗️ Architecture This MCP server is built using the **Cohere North MCP Python SDK** and provides the following tools: ### Available Tools 1. **`get_enrolled_courses`** - Retrieves all courses the student is currently enrolled in - Returns: Course codes, names, sections, and credits 2. **`get_course_details`** - Gets detailed information about a specific course - Parameters: `course_code` (e.g., "CSC148H1") - Returns: Course description, prerequisites, meeting times, instructor info 3. **`get_course_schedule`** - Retrieves the student's weekly class schedule - Returns: Day, time, location, and course for each class 4. **`get_syllabus`** - Fetches the syllabus for a specific course from Quercus - Parameters: `course_code` - Returns: Syllabus content (PDF or text) 5. **`get_course_assignments`** - Lists all assignments for a course - Parameters: `course_code` - Returns: Assignment names, due dates, and submission status 6. **`get_course_announcements`** - Gets recent announcements from a course - Parameters: `course_code`, `limit` (optional, default 5) - Returns: Announcement titles, content, and dates ## 📋 Prerequisites - Python 3.9 or higher - University of Toronto student account - Access to ACORN and Quercus - Cohere North MCP Python SDK ## 🚀 Installation ### Step 1: Clone the Repository ```bash git clone https://github.com/yourusername/uoft-student-helper-mcp.git cd uoft-student-helper-mcp ``` ### Step 2: Install Dependencies ```bash # Install the Cohere North MCP SDK pip install -e path/to/north-mcp-python-sdk # Or if you have it locally cd ../north-mcp-python-sdk pip install -e . cd ../uoft-student-helper-mcp # Install other dependencies pip install requests beautifulsoup4 pydantic python-dotenv ``` ### Step 3: Configure Credentials Create a `.env` file in the project root: ```bash # ACORN Credentials ACORN_USERNAME=your_utorid ACORN_PASSWORD=your_password # Quercus API Token QUERCUS_API_TOKEN=your_api_token # Server Configuration SERVER_PORT=3002 ``` **⚠️ Security Note**: Never commit your `.env` file to version control. It's already included in `.gitignore`. #### How to Get Your Quercus API Token 1. Log in to [Quercus](https://q.utoronto.ca/) 2. Go to Account → Settings 3. Scroll down to "Approved Integrations" 4. Click "+ New Access Token" 5. Enter a purpose (e.g., "MCP Server") 6. Click "Generate Token" 7. Copy the token and paste it in your `.env` file ## 🎮 Usage ### Running the Server ```bash python uoft_student_helper.py ``` The server will start on `http://0.0.0.0:3002` (or the port specified in your `.env` file). ### Exposing with ngrok (Optional) To make the server accessible from Cohere North or other remote clients: ```bash ngrok http 3002 ``` Copy the HTTPS URL (e.g., `https://abc123.ngrok.io`) to use in your MCP client configuration. ### Testing the Server ```bash # Test health endpoint curl http://localhost:3002/health # Test getting enrolled courses curl -X POST http://localhost:3002/call \ -H "Content-Type: application/json" \ -d '{"tool": "get_enrolled_courses", "arguments": {}}' # Test getting course details curl -X POST http://localhost:3002/call \ -H "Content-Type: application/json" \ -d '{"tool": "get_course_details", "arguments": {"course_code": "CSC148H1"}}' ``` ## 🔌 Connecting to Cohere North 1. Start your MCP server locally 2. Expose it with ngrok: `ngrok http 3002` 3. Log in to [Cohere North](https://north.cohere.com/) 4. Go to Settings → MCP Servers 5. Add a new server: - **Name**: UofT Student Helper - **URL**: Your ngrok HTTPS URL - **Auth Token**: (if configured) 6. Save and test the connection ### Example Conversations Once connected, you can ask your AI assistant: - "What courses am I enrolled in this semester?" - "Show me the syllabus for CSC148" - "What assignments do I have for MAT137?" - "When is my next CSC148 class?" - "What are the recent announcements in my courses?" ## 🛠️ Development ### Project Structure ``` uoft-student-helper-mcp/ ├── README.md # This file ├── uoft_student_helper.py # Main MCP server ├── acorn_client.py # ACORN API client ├── quercus_client.py # Quercus API client ├── .env.example # Example environment variables ├── .gitignore # Git ignore file ├── requirements.txt # Python dependencies ├── test_server.py # Test script └── docs/ # Additional documentation ├── ACORN_API.md # ACORN API documentation └── QUERCUS_API.md # Quercus API documentation ``` ### Adding New Tools To add a new tool to the MCP server: 1. Open `uoft_student_helper.py` 2. Add a new function with the `@mcp.tool()` decorator: ```python @mcp.tool() def your_new_tool(param1: str, param2: int) -> dict: """ Description of what your tool does. Args: param1: Description of param1 param2: Description of param2 Returns: A dictionary with the result """ # Your implementation here return {"result": "success"} ``` 3. Restart the server 4. Test your new tool ### API Clients #### ACORN Client (`acorn_client.py`) The ACORN client handles authentication and data retrieval from the ACORN system. It uses web scraping since ACORN doesn't provide a public API. **Key Methods**: - `login()`: Authenticate with ACORN - `get_enrolled_courses()`: Fetch current courses - `get_course_details(course_code)`: Get course information - `get_schedule()`: Retrieve class schedule #### Quercus Client (`quercus_client.py`) The Quercus client uses the Canvas LMS API (Quercus is built on Canvas). **Key Methods**: - `get_courses()`: List all courses - `get_syllabus(course_id)`: Fetch course syllabus - `get_assignments(course_id)`: List assignments - `get_announcements(course_id)`: Get announcements ## 🔒 Security & Privacy ### Important Considerations 1. **Credential Storage**: Your ACORN and Quercus credentials are stored locally in the `.env` file. Never share this file or commit it to version control. 2. **API Token Security**: The Quercus API token has the same permissions as your account. Keep it secure. 3. **HTTPS Only**: When exposing the server publicly, always use HTTPS (ngrok provides this automatically). 4. **Authentication**: Consider adding authentication to your MCP server to prevent unauthorized access. 5. **Data Privacy**: This server accesses your academic information. Only run it on trusted machines and networks. ### Recommended Security Practices - Use environment variables for all sensitive data - Rotate your Quercus API token regularly - Use ngrok's authentication features for public exposure - Run the server in a secure, isolated environment - Regularly update dependencies for security patches ## 🐛 Troubleshooting ### Common Issues #### "ModuleNotFoundError: No module named 'north_mcp_python_sdk'" **Solution**: Install the SDK from source: ```bash cd path/to/north-mcp-python-sdk pip install -e . ``` #### "Authentication failed" for ACORN **Possible causes**: - Incorrect username/password in `.env` - Two-factor authentication enabled (requires additional setup) - ACORN session expired **Solution**: Verify credentials and check if 2FA is enabled. #### "Invalid API token" for Quercus **Solution**: Generate a new API token from Quercus settings and update your `.env` file. #### Server won't start **Check**: 1. Port 3002 is not already in use: `lsof -i :3002` (Mac/Linux) or `netstat -ano | findstr :3002` (Windows) 2. All dependencies are installed: `pip list` 3. `.env` file exists and is properly formatted ### Getting Help If you encounter issues: 1. Check the [Issues](https://github.com/yourusername/uoft-student-helper-mcp/issues) page 2. Review the [Documentation](docs/) 3. Contact the maintainers ## 📚 Resources ### Official Documentation - [Model Context Protocol](https://modelcontextprotocol.io/) - [Cohere North MCP SDK](https://github.com/cohere-ai/north-mcp-python-sdk) - [Canvas LMS API](https://canvas.instructure.com/doc/api/) (Quercus uses Canvas) - [UofT ACORN](https://acorn.utoronto.ca/) - [UofT Quercus](https://q.utoronto.ca/) ### Related Projects - [MCP Server Collection](https://github.com/modelcontextprotocol/servers) - [Awesome MCP Servers](https://github.com/serpvault/awesome-mcp-servers) ## 🤝 Contributing Contributions are welcome! Please follow these steps: 1. Fork the repository 2. Create a feature branch: `git checkout -b feature/your-feature` 3. Commit your changes: `git commit -m "Add your feature"` 4. Push to the branch: `git push origin feature/your-feature` 5. Open a Pull Request ### Contribution Guidelines - Follow PEP 8 style guidelines - Add tests for new features - Update documentation as needed - Ensure all tests pass before submitting ## 📄 License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## ⚠️ Disclaimer This project is not officially affiliated with, endorsed by, or connected to the University of Toronto. It is an independent project created to help students access their academic information more easily. **Use at your own risk.** The developers are not responsible for any issues arising from the use of this software, including but not limited to: - Account security issues - Data loss or corruption - Violations of university policies - Service disruptions Always ensure you comply with the University of Toronto's IT policies and terms of service when using this tool. ## 👥 Authors - **Alice** - Initial work - [@Alice0416](https://github.com/Alice0416) ## 🙏 Acknowledgments - Cohere team for the North MCP Python SDK - University of Toronto for providing ACORN and Quercus - The MCP community for inspiration and support - All contributors who help improve this project ## 📞 Contact For questions, suggestions, or issues: - Open an issue on GitHub - Email: your.email@mail.utoronto.ca - Discord: [Your Discord] --- **Made with ❤️ by UofT students, for UofT students** *Last updated: January 2026*