# UAAR University MCP Server - Claude Configuration Guide
## Project Overview
**InstituaionMCPServer** is a comprehensive Model Context Protocol (MCP) server implementation for PMAS Arid Agriculture University Rawalpindi (UAAR). This server provides AI agents with structured access to university academic resources, admissions, student services, and administrative functions through 53 specialized tools organized into 17 categories.
## Key Highlights
- **53 MCP Tools**: Comprehensive coverage of university operations
- **Dual Transport**: Supports stdio (Claude Code CLI) and HTTP/SSE modes
- **SQLite Database**: 25 tables with auto-initialization and seeding
- **JWT Authentication**: Secure token-based authentication with bcrypt
- **Multi-Step Forms**: Interactive admission system with progress tracking
- **GPA Calculation**: Academic result processing with grade point calculations
- **Scholarship Matching**: Eligibility checking with criteria parsing
- **Tool Annotations**: Semantic hints for AI agent guidance
- **Async Architecture**: All tools implemented as async functions
- **Pydantic Validation**: Comprehensive input/output validation
## Quick Start
## Quick Start
### 1. Setup Environment
```bash
# Clone the repository
git clone https://github.com/SARAMALI15792/InstituaionMCPServer.git
cd InstituaionMCPServer
# Install dependencies
pip install -e .
# Or using uv: uv pip install -e .
# Copy environment template
cp .env.example .env
# Edit .env with your configuration
```
### 2. Running the Server
**For Claude Desktop integration:**
```bash
python -m server.cli
```
**For HTTP/SSE mode (alternative):**
```bash
python -m server.main
# Server runs on http://localhost:8000
```
### 3. Claude Integration
Add to your Claude Desktop configuration (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"uaar-university": {
"command": "python",
"args": ["-m", "server.cli"],
"cwd": "/path/to/InstituaionMCPServer",
"description": "UAAR University MCP Server - Academic resources, admissions, student services"
}
}
}
```
**For Claude Code:** Use the included configuration file:
- `claude-code-config-pypi.json` - Primary configuration for PyPI installation
## Project Structure
```
InstituaionMCPServer/
├── .claude/ # Claude configuration (this file)
│ └── claude.md # Project documentation for Claude
├── server/
│ ├── main.py # FastAPI app with HTTP/SSE transport
│ ├── cli.py # CLI entry point for stdio transport
│ ├── database.py # SQLite setup, queries, and seeding (442 lines)
│ ├── auth.py # JWT authentication
│ ├── schemas.py # Pydantic models (236 lines)
│ └── tools/ # 17 tool modules with 53 MCP tools
│ ├── __init__.py # Tool registry
│ ├── academic_tools.py # Courses, departments, schedules
│ ├── admission_form_tools.py # Multi-step form system (398 lines)
│ ├── result_tools.py # Results, GPA calculation (172 lines)
│ ├── scholarship_tools.py # Scholarship eligibility (142 lines)
│ ├── transport_tools.py # Bus routes and stops (110 lines)
│ └── ... 12 more tool modules
├── pyproject.toml # Project dependencies
├── .env.example # Environment template
├── .gitignore # Git ignore patterns
├── LICENSE # MIT License
├── README.md # Comprehensive project documentation
├── claude-code-config-pypi.json # Primary Claude Code configuration
└── requirements.txt # Python dependencies
```
## Core Technologies
- **FastMCP**: MCP Python SDK
- **FastAPI**: Web framework for HTTP/SSE transport
- **SQLite**: Database with 25 tables
- **JWT + bcrypt**: Authentication system
- **Pydantic**: Data validation and serialization
## Available Tool Categories
### Academic Operations (5 tools)
- `list_departments()` - Get all university departments
- `search_courses(query)` - Search courses by name or code
- `get_merit_list(dept_id)` - Get department merit rankings
- `get_class_schedule()` - Get timetables
- `get_exam_schedule()` - Get exam schedules
### Admission System (8 tools)
- `check_admission_status(cnic)` - Check admission by CNIC
- `start_admission_form()` - Begin new application
- `fill_admission_field()` - Step-by-step form filling
- `preview_admission_form()` - Review before submission
- `confirm_and_submit_admission_form()` - Final submission
### Student Results (3 tools)
- `get_semester_result(student_id)` - Get academic results
- `get_cgpa(student_id)` - Calculate cumulative GPA
- `calculate_gpa(grades)` - Manual GPA calculator
### Library Services (4 tools)
- `search_library_books(query)` - Search book catalog
- `check_book_availability(book_id)` - Check availability
- `get_borrowed_books(student_id)` - Get current loans
- `get_library_hours()` - Operating hours
### Hostel Management (5 tools)
- `check_hostel_availability()` - Room availability
- `get_mess_menu(day)` - Daily meal plans
- `get_hostel_fees()` - Fee structure
- `get_hostel_rules()` - Rules & regulations
### Scholarship Management (3 tools)
- `list_scholarships()` - Available scholarships
- `check_scholarship_eligibility()` - Eligibility checker
- `get_scholarship_details()` - Detailed info
### Transport Services (4 tools)
- `get_bus_routes()` - University bus routes
- `find_bus_stop(location)` - Find nearest stops
- `get_route_by_stop(stop_name)` - Routes through stop
- `get_transport_card_info()` - Transport card details
### Administrative Tools (7 tools)
- `admin_add_department()` - [Admin] Add department
- `admin_add_course()` - [Admin] Add course
- `admin_add_faculty()` - [Admin] Add faculty
- `admin_add_event()` - [Admin] Add event
- `admin_add_news()` - [Admin] Add news
- `admin_add_book()` - [Admin] Add library book
- `admin_add_scholarship()` - [Admin] Add scholarship
### Support & Information (13 tools)
- `get_user_profile()` - User information
- `search_faculty()` - Faculty directory
- `get_latest_news()` - University news
- `list_upcoming_events()` - Events calendar
- `get_department_contact()` - Department contacts
- `get_emergency_contacts()` - Emergency numbers
- `submit_help_ticket()` - IT/Admin support
- `get_university_info()` - University metadata
- `get_important_links()` - Website links
- `get_fee_structure()` - Program fees
- `get_admission_requirements()` - Admission criteria
- `get_financial_aid_office_info()` - Financial aid
- `log_interaction()` - Audit logging
## Database Schema
The SQLite database (`university.db`) contains 25 tables covering:
### Academic Data
- `departments`, `courses`, `faculty`, `merit_lists`
- `class_schedule`, `exam_schedule`
### Student Records
- `users`, `results`, `grade_points`
### Services
- `library_books`, `hostel_rooms`, `hostel_fees`, `hostel_rules`, `mess_menu`
- `bus_routes`, `events`, `news`, `scholarships`
### Administrative
- `admission_forms`, `help_tickets`, `admission_programs`, `admission_requirements`
### System Tables
- `audit_logs`, `department_contacts`, `university_info`, `important_links`
- `emergency_contacts`, `transport_info`, `library_hours`
## Key Features
### 1. Multi-Step Admission Form System
- Stateless design with application IDs (APP-2026-00001 format)
- Progress tracking with collected/missing fields
- Auto-calculation of percentages and aggregate scores
- Preview before submission with confirmation
### 2. GPA Calculation Engine
- Semester-level and cumulative GPA tracking
- Grace handling with fallback credit hours
- Formula: Σ(grade_points × credit_hours) / Σ(credit_hours)
### 3. Scholarship Eligibility Checking
- Parses eligibility criteria from JSON strings
- Regex-based requirement matching
- Returns qualification reasons
### 4. Paginated Responses
All list endpoints return:
```json
{
"total": 100,
"count": 10,
"offset": 0,
"items": [...],
"has_more": true,
"next_offset": 10
}
```
### 5. Tool Annotation Hints
Each tool includes semantic hints for AI agents:
- `readOnlyHint`: True for safe read operations
- `destructiveHint`: True for irreversible operations
- `idempotentHint`: True for safe retries
- `openWorldHint`: True for non-deterministic results
## Development Workflow
### Adding New Tools
1. Create or add to existing tool module in `server/tools/`
2. Define async function with proper type hints:
```python
async def my_tool(param: str) -> Dict:
"""Tool description for AI agents."""
result = query_db("SELECT ...", params)
return {"data": result}
```
3. Register with decorator:
```python
@mcp.tool(
name="my_tool",
annotations={
"readOnlyHint": True,
"destructiveHint": False,
"idempotentHint": True,
"openWorldHint": False
}
)
```
4. Add registration call in `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
- `execute_db(sql, params=None)` - For INSERT/UPDATE/DELETE
- `init_db()` - Initializes database on first run
- `seed_db()` - Populates with demo data
### Adding New Tables
1. Add SQL CREATE TABLE to `init_db()` function
2. Create Pydantic model in `schemas.py`
3. Add seed data if needed in `seed_db()`
4. Create tools for CRUD operations
## Environment Variables
Create `.env` file from `.env.example`:
```env
DATABASE_URL=sqlite:///university.db
SECRET_KEY=your-secret-key-here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
HOST=0.0.0.0
PORT=8000
DEBUG=True
```
## Testing
### Manual Testing
```bash
# Start HTTP server
python -m server.main
# Test endpoints
curl http://localhost:8000/token \
-X POST \
-d "username=admin&password=admin"
# Use JWT token for protected routes
curl http://localhost:8000/api/departments \
-H "Authorization: Bearer YOUR_TOKEN"
```
### Claude Integration Testing
1. Start CLI server: `python -m server.cli`
2. Configure Claude Desktop with the server
3. Test tool invocation through Claude interface
## Common Tasks for Claude
### When users ask about:
- **Courses/Departments**: Use `search_courses()`, `list_departments()`
- **Admission status**: Use `check_admission_status(cnic)`
- **Application forms**: Use `start_admission_form()` and related tools
- **Grades/GPA**: Use `get_semester_result()`, `get_cgpa()`
- **Library books**: Use `search_library_books()`, `check_book_availability()`
- **Scholarships**: Use `list_scholarships()`, `check_scholarship_eligibility()`
- **Hostel availability**: Use `check_hostel_availability()`
- **Bus routes**: Use `get_bus_routes()`, `find_bus_stop()`
- **Events/News**: Use `list_upcoming_events()`, `get_latest_news()`
- **Faculty search**: Use `search_faculty()`
- **Emergency contacts**: Use `get_emergency_contacts()`
- **Fee structure**: Use `get_fee_structure()`
### For administrative tasks:
- Adding new departments: `admin_add_department()`
- Adding courses: `admin_add_course()`
- Adding faculty: `admin_add_faculty()`
- Adding events: `admin_add_event()`
- Adding news: `admin_add_news()`
- Adding books: `admin_add_book()`
- Adding scholarships: `admin_add_scholarship()`
## Error Handling
### Common Error Patterns
- **Tool returns error dictionary**: Check for `{"error": "message"}` structure
- **Database connection issues**: Verify `university.db` exists and is writable
- **Authentication failures**: Check JWT token expiration (30 minutes default)
- **Missing parameters**: Tools validate input types and required fields
### Tool Response Structure
Successful responses:
```json
{
"data": {...},
"message": "optional success message"
}
```
Error responses:
```json
{
"error": "Descriptive error message",
"details": "Optional additional info"
}
```
## Performance Considerations
1. **Database queries**: Use pagination for large datasets
2. **JSON storage**: Complex data stored as JSON strings in TEXT columns
3. **Connection management**: Each query opens/closes connection (simple MVP approach)
4. **Async patterns**: All tools are async for potential concurrency
## Security Notes
- JWT tokens expire after 30 minutes (configurable)
- Passwords hashed with bcrypt
- SQL queries use parameterization to prevent injection
- Admin tools marked with `[Admin]` prefix and `destructiveHint=True`
- Audit logging via `log_interaction()` tool
## Deployment
### Production Considerations
1. Use environment variables for secret keys
2. Consider PostgreSQL for production database
3. Add CORS configuration for web clients
4. Implement connection pooling
5. Add request rate limiting
6. Set up logging/monitoring
### Docker Deployment
```dockerfile
FROM python:3.10-slim
WORKDIR /app
COPY . .
RUN pip install -e .
CMD ["python", "-m", "server.cli"]
```
## Troubleshooting
### Server Won't Start
1. Check Python version (3.10+ required)
2. Verify all dependencies installed: `pip install -e .`
3. Check `.env` file exists with required variables
### Database Issues
1. Ensure `university.db` is writable
2. Check SQLite is installed
3. Try deleting `university.db` to trigger auto-creation
### Claude Integration Issues
1. Verify server runs: `python -m server.cli`
2. Check Claude Desktop configuration
3. Ensure correct working directory in config
4. Test tools directly via HTTP if in doubt
## Contributing
### Code Standards
- Use type hints for all function parameters and returns
- Document tool purpose in docstrings
- Follow existing patterns in tool modules
- Use async/await consistently
- Include necessary tool annotations
### Testing New Tools
1. Test through Claude interface
2. Verify error handling
3. Check pagination for list endpoints
4. Validate input parameter types
5. Test edge cases
## Support
- **Repository**: https://github.com/SARAMALI15792/InstituaionMCPServer
- **Issues**: GitHub repository issues page
- **Documentation**: This claude.md file
- **Configuration**: See example config files in root
- **Database**: SQLite file with comprehensive demo data
## License
MIT License
---
This document provides Claude with comprehensive context about the UAAR University MCP Server project structure, capabilities, and usage patterns.
