# Absher Voice Assistant MCP Server
Standalone MCP (Model Context Protocol) server for Saudi government services (Absher platform).
## Overview
This MCP server provides 8 tools for handling authentication, user data, and government services:
### Authentication & Identity Tools (3)
1. **verify_national_id** - Check if a national ID exists in the system
2. **get_security_questions** - Fetch security questions for user verification
3. **verify_security_answers** - Verify user's answers to security questions
### User Data Tool (1)
4. **get_user_data** - Load complete user profile information
### Service Discovery Tool (1)
5. **get_service_requirements** - Get required fields for a specific service
### Service Execution Tools (3)
6. **renew_passport** - Submit passport renewal request
7. **get_traffic_fines** - Query traffic violations
8. **book_appointment** - Schedule government office appointment
## Installation
```bash
# Install dependencies
pip install -r requirements.txt
```
## Running the Server
### Standalone Mode (for testing)
```bash
python absher_server.py
```
### With MCP Client (recommended)
Use with any MCP-compatible client (Claude Desktop, custom clients, etc.)
Example configuration for Claude Desktop (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"absher": {
"command": "python",
"args": ["/path/to/mcp-servers/absher_server.py"]
}
}
}
```
## Mock Data
The server includes 3 test users:
### User 1
- **National ID**: 1234567890
- **Name**: أحمد محمد
- **Passport**: A12345678
- **Traffic Fines**: 2 unpaid fines (650 SAR total)
- **Security Question**: ما هو اسم مدينة ميلادك? → الرياض
### User 2
- **National ID**: 0987654321
- **Name**: فاطمة أحمد
- **Passport**: B98765432
- **Traffic Fines**: 1 paid fine
- **Security Question**: ما هو اسم مدينة ميلادك? → جدة
### User 3
- **National ID**: 1122334455
- **Name**: خالد عبدالله
- **Passport**: C11223344
- **Traffic Fines**: None
- **Security Question**: ما هو اسم مدينة ميلادك? → الدمام
## Tool Usage Examples
### 1. Verify National ID
```python
verify_national_id(national_id="1234567890")
# Returns: {"exists": true, "message": "تم العثور على رقم الهوية الوطنية في النظام"}
```
### 2. Get Security Questions
```python
get_security_questions(national_id="1234567890")
# Returns: {"success": true, "questions": [{"question_id": "q1", "question": "ما هو اسم مدينة ميلادك؟"}]}
```
### 3. Verify Security Answers
```python
verify_security_answers(
national_id="1234567890",
answers=[{"question_id": "q1", "answer": "الرياض"}]
)
# Returns: {"verified": true, "message": "تم التحقق من هويتك بنجاح"}
```
### 4. Get User Data
```python
get_user_data(national_id="1234567890")
# Returns: Complete user profile with name, phone, passport info, etc.
```
### 5. Get Service Requirements
```python
get_service_requirements(service_name="passport_renewal")
# Returns: List of required fields with sources (user_data vs user_input)
```
### 6. Renew Passport
```python
renew_passport(
national_id="1234567890",
renewal_reason="انتهاء الصلاحية",
delivery_method="استلام من المكتب"
)
# Returns: {"success": true, "request_id": "PR20241208123456", "message": "..."}
```
### 7. Get Traffic Fines
```python
get_traffic_fines(national_id="1234567890")
# Returns: List of fines with summary (total, unpaid, amount)
```
### 8. Book Appointment
```python
book_appointment(
national_id="1234567890",
service_type="الجوازات",
location="الرياض",
preferred_date="2024-12-15"
)
# Returns: {"success": true, "appointment_id": "APT20241208123456", "details": {...}}
```
## Authentication Flow (as per new_flow.txt)
1. **Identity Check**: Call `verify_national_id` with user's national ID
2. **Security Questions**: Call `get_security_questions` to fetch questions
3. **Security Verification**: Ask user questions one-by-one, then call `verify_security_answers`
4. **Load User Data**: Call `get_user_data` after successful verification
5. **Service Selection**: User chooses a service
6. **Requirements Check**: Call `get_service_requirements` to see what's needed
7. **Data Collection**: Ask for missing information one question at a time
8. **Confirmation**: Show summary and ask for confirmation
9. **Execution**: Call service tool (renew_passport, get_traffic_fines, book_appointment)
10. **Confirmation**: Return success message to user
## Service Requirements
### Passport Renewal
**Required from user_data**: national_id, first_name, last_name, phone, passport_number
**Required from user_input**: renewal_reason, delivery_method
**renewal_reason options**:
- انتهاء الصلاحية
- تلف
- ضياع
- امتلاء الصفحات
**delivery_method options**:
- استلام من المكتب
- توصيل بالبريد
### Traffic Fines
**Required from user_data**: national_id
### Book Appointment
**Required from user_data**: national_id
**Required from user_input**: service_type, location, preferred_date
**service_type options**:
- الجوازات
- الأحوال المدنية
- المرور
**location options**:
- الرياض
- جدة
- الدمام
## Files
- `absher_server.py` - Main MCP server with all 8 tools
- `mock_data.py` - Mock users, fines, appointments, and service requirements
- `requirements.txt` - Python dependencies
- `README.md` - This file
## Integration with AI Clients
This MCP server is designed to work with any MCP-compatible AI client:
- **Claude Desktop**: Add to config file
- **OpenAI Realtime API**: Use with custom MCP client bridge
- **Ollama**: Use with mcp_client.py bridge
- **Custom Clients**: Any client that supports MCP protocol
The server is fully independent and stateless - all data is in `mock_data.py`.
## Notes
- All responses are in Arabic with English function names
- Server uses stdio transport (standard MCP approach)
- All tools return JSON strings for easy parsing
- Mock data can be easily extended or replaced with real database
