UAAR University MCP Server

Model Context Protocol (MCP) Server for PMAS Arid Agriculture University Rawalpindi

A comprehensive MCP server that provides AI agents with structured access to university academic resources, admissions, student services, and administrative functions through 53 specialized tools.

✨ Features

🎓 Academic & Admissions

• Course Management: Search courses by name or code across all departments

• Department Information: List all academic departments with faculty details

• Merit Lists: Access latest department-specific merit rankings for admissions

• Admission System: Multi-step admission form with progress tracking

• Program Availability: Check available academic programs and requirements

• Class Schedules: Get timetables filtered by course or day

📚 Student Services

• Library System: Search books by title, author, ISBN; check availability and borrowing status

• Hostel Management: Check room availability, view mess menus, fee structures

• Transport Services: Bus routes, stops, and transport card information

• Scholarship Portal: Browse scholarships, check eligibility criteria, view details

• Academic Results: Semester results, CGPA calculation, transcript request info

🏛️ Administrative Functions

• Faculty Directory: Search faculty by name or research interests

• Department Contacts: Emergency contacts and departmental information

• Event Management: University events, workshops, and announcements

• News System: Latest university news categorized by relevance

• Financial Aid: Financial aid office information and fee structures

🔧 Administrative Tools (Admin Only)

• Data Management: Add departments, courses, faculty members

• Content Management: Add library books, scholarships, events, news

• System Administration: Full CRUD operations for university data

⚡ Technical Features

• Multi-Transport Support: Stdio (Claude Code CLI) and HTTP/SSE modes

• JWT Authentication: Secure token-based authentication system

• SQLite Database: Lightweight database with auto-initialization and seeding

• Async Architecture: All tools implemented as async functions

• Type Safety: Full Pydantic validation with comprehensive type hints

• Paginated Responses: Efficient handling of large datasets

🚀 Quick Start

Prerequisites

• Python 3.10 or higher

• Git (for development)

• Claude Desktop or Claude Code CLI

Installation Methods

Method 1: PyPI Installation (Recommended)

Method 2: Using uv (Modern Python Package Manager)

Method 3: Local Development Setup

🖥️ Usage

Running the MCP Server

Stdio Mode (Claude Code CLI Integration)

This mode is optimized for integration with Claude Code CLI and other MCP clients using stdio transport.

HTTP/SSE Mode (Alternative Transport)

Use this mode for HTTP-based clients or testing via REST API.

Integration with Claude

Claude Desktop Configuration

Add to your claude_desktop_config.json:

Claude Code Configuration

Option A: PyPI Installation (Recommended) Use the included claude-code-config-pypi.json:

Option B: Local Development

Option C: Universal Configuration Use the included claude-code-config-universal.json for general-purpose setup.

Environment Configuration

1. Create your .env file:

2. Configure environment variables:

🛠️ Available Tools

The server provides 53 tools organized into 17 categories:

📊 Complete Tool Reference

🔑 Key Tools

Academic Operations

• search_courses(query) - Search courses by name or code

• list_departments() - Get all university departments

• get_merit_list(dept_id) - Get department merit rankings

• get_class_schedule() - Get class timetables

• get_exam_schedule() - Get exam schedules

• get_today_classes() - Get all classes scheduled for today

Admission System

• check_admission_status(cnic) - Check admission status by CNIC

• start_admission_form() - Begin new admission application

• fill_admission_field() - Step-by-step form filling

• fill_multiple_admission_fields() - Bulk field filling

• get_admission_form_status() - Check form completion status

• preview_admission_form() - Review form before submission

• confirm_and_submit_admission_form() - Final submission

• get_available_programs() - List available academic programs

• get_admission_requirements() - Get admission eligibility criteria

Student Services

• get_semester_result(student_id) - Get semester academic results

• get_cgpa(student_id) - Calculate cumulative GPA

• calculate_gpa(grades) - Manual GPA calculator

• get_transcript_request_info() - Information for transcript requests

• search_library_books(query) - Search library catalog

• check_book_availability(book_id) - Check book availability

• check_hostel_availability() - Check hostel room availability

• get_mess_menu(day) - Get daily mess menu

• list_scholarships() - Browse available scholarships

• check_scholarship_eligibility() - Check scholarship eligibility

• get_bus_routes() - Get university bus routes

• find_bus_stop(location) - Find nearest bus stops

Administrative Functions

• search_faculty(query) - Search faculty members

• get_department_contact() - Get department contact information

• get_emergency_contacts() - Emergency contact numbers

• list_upcoming_events() - Upcoming university events

• get_latest_news() - Latest news and announcements

• submit_help_ticket() - Submit IT/administrative help request

• get_university_info() - General university information

• get_important_links() - Important website links

• get_fee_structure() - Program fee structures

• log_interaction() - Log AI agent interactions (audit)

Admin Tools (Requires Admin Privileges)

• admin_add_department() - Add new academic department

• admin_add_course() - Add new course to catalog

• admin_add_faculty() - Add new faculty member

• admin_add_event() - Add university event

• admin_add_news() - Add news announcement

• admin_add_book() - Add library book

• admin_add_scholarship() - Add scholarship program

🏗️ Architecture & Development

Project Structure

Database Schema

The SQLite database (university.db) contains 25 tables covering:

• Academic Data: Departments, courses, faculty, merit lists, schedules

• Student Records: Users, results, grade points, admission forms

• Student Services: Library books, hostel rooms, mess menu, bus routes

• Administrative: Events, news, scholarships, help tickets

• System Tables: Audit logs, contacts, university info, emergency contacts

Technical Architecture

• Framework: FastMCP (MCP Python SDK) with FastAPI backend

• Database: SQLite with auto-initialization and seeding

• Authentication: JWT tokens with bcrypt password hashing

• Transport: Dual-mode (stdio for CLI, HTTP/SSE for web)

• Async Pattern: All tools implemented as async functions

• Validation: Pydantic models for all request/response schemas

• Error Handling: Structured error responses with context

Adding New Tools

1. Create or modify tool module in server/tools/

2. Define async function with proper type hints and docstring

3. Register with decorator:

   @mcp.tool( name="tool_name", annotations={ "readOnlyHint": True, # Safe read operations "destructiveHint": False, # No destructive side effects "idempotentHint": True, # Safe to retry "openWorldHint": False # Deterministic results } ) async def tool_name(param: str) -> Dict: """Tool description for AI agents."""

4. Add registration to module's register_*_tools() function

5. Import and register in tools/__init__.py

Database Operations

Use helper functions from database.py:

• query_db(sql, params=None) - For SELECT queries (returns list)

• execute_db(sql, params=None) - For INSERT/UPDATE/DELETE (returns lastrowid)

• init_db() - Creates all tables (called automatically)

• seed_db() - Populates with demo data (if tables are empty)

🔧 Development Guide

Setting Up Development Environment

Running in Development Mode

Testing Tool Execution

🧪 Testing

Tool Testing Checklist

1. ✅ Input Validation - Test with invalid/missing parameters

2. ✅ Edge Cases - Empty results, pagination boundaries

3. ✅ Error Handling - Database errors, authentication failures

4. ✅ Performance - Response times for large datasets

5. ✅ Integration - Test with Claude Desktop/Code

Database Testing

⚙️ Configuration Reference

Environment Variables

MCP Configuration Files

• claude-desktop-config.json: Claude Desktop integration

• claude-code-config-pypi.json: PyPI installation for Claude Code

• claude-code-config-universal.json: Universal configuration

• uaar-university-mcp.json: MCP server definition for uv launcher

📈 Performance & Security

Performance Optimization

1. Pagination: All list endpoints support pagination (limit, offset)

2. Database Indexing: Critical fields indexed for fast queries

3. Connection Management: Lightweight connection per query (MVP approach)

4. Async Operations: Non-blocking tool execution

Security Considerations

1. JWT Tokens: 30-minute expiration prevents token reuse

2. Password Hashing: bcrypt with salt for secure storage

3. SQL Injection Prevention: Parameterized queries throughout

4. Input Validation: Pydantic models validate all inputs

5. Admin Protection: Admin tools marked with destructiveHint=True

6. Audit Logging: All agent interactions logged via log_interaction()

Production Deployment

For production deployment, consider:

1. Use PostgreSQL instead of SQLite for scalability

2. Environment Variables for all secrets

3. Connection Pooling for database connections

4. Rate Limiting on API endpoints

5. CORS Configuration for web clients

6. Logging & Monitoring setup

7. Docker Containerization for consistency

🤝 Contributing

We welcome contributions! Here's how you can help:

Reporting Issues

• Check existing issues before creating new ones

• Include detailed reproduction steps

• Provide relevant error messages and logs

Submitting Pull Requests

1. Fork the repository

2. Create a branch for your feature/fix

3. Write tests for your changes

4. Ensure code style matches existing patterns

5. Update documentation as needed

6. Submit PR with clear description

Code Standards

• Type Hints: All functions must have complete type annotations

• Docstrings: Include descriptive docstrings for all tools

• Async Patterns: Use async/await consistently

• Error Handling: Return structured error dictionaries

• Testing: Include tests for new functionality

📚 Resources & References

Documentation

• MCP Specification: Official MCP protocol documentation

• FastMCP Documentation: Python SDK documentation

• Claude Code Guide: Comprehensive project documentation for Claude AI

• API Documentation: Interactive API docs when running in HTTP mode

Related Projects

• Model Context Protocol: Official MCP organization

• Claude Code: Anthropic's CLI tool for Claude

• FastAPI: Modern web framework for APIs

University Resources

• UAAR University: Official university website

• PMAS Arid Agriculture University: Parent institution

📄 License

This project is licensed under the MIT License - see the LICENSE file for complete details.

Permissions

• ✅ Commercial use

• ✅ Modification

• ✅ Distribution

• ✅ Private use

Conditions

• ❗ Include original copyright notice

• ❗ Include license copy

Limitations

• ⚠️ No warranty

• ⚠️ No liability

🙏 Acknowledgments

Core Technologies

• Model Context Protocol: For enabling AI agent integration

• FastMCP: Python SDK for MCP development

• FastAPI: Modern, fast web framework for APIs

• Pydantic: Data validation and settings management

• SQLite: Lightweight, serverless database

Inspiration

• UAAR University Digital Transformation: Inspired by the university's commitment to educational technology

• Open Source Education Tools: Building on the tradition of open educational resources

• AI-Assisted Learning: Advancing the integration of AI in educational administration

Contributors

• The UAAR University IT Department for their vision and support

• Open source contributors who help improve the project

• The MCP community for developing this revolutionary protocol

Special Thanks

To the students, faculty, and staff of PMAS Arid Agriculture University Rawalpindi for inspiring this project and for their dedication to educational excellence.

Made with ❤️ for the UAAR University community