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

# Install dependencies
pip install -r requirements.txt

Running the Server

Standalone Mode (for testing)

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):

{
  "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

verify_national_id(national_id="1234567890")
# Returns: {"exists": true, "message": "تم العثور على رقم الهوية الوطنية في النظام"}

2. Get Security Questions

get_security_questions(national_id="1234567890")
# Returns: {"success": true, "questions": [{"question_id": "q1", "question": "ما هو اسم مدينة ميلادك؟"}]}

3. Verify Security Answers

verify_security_answers(
    national_id="1234567890",
    answers=[{"question_id": "q1", "answer": "الرياض"}]
)
# Returns: {"verified": true, "message": "تم التحقق من هويتك بنجاح"}

4. Get User Data

get_user_data(national_id="1234567890")
# Returns: Complete user profile with name, phone, passport info, etc.

5. Get Service Requirements

get_service_requirements(service_name="passport_renewal")
# Returns: List of required fields with sources (user_data vs user_input)

6. Renew Passport

renew_passport(
    national_id="1234567890",
    renewal_reason="انتهاء الصلاحية",
    delivery_method="استلام من المكتب"
)
# Returns: {"success": true, "request_id": "PR20241208123456", "message": "..."}

7. Get Traffic Fines

get_traffic_fines(national_id="1234567890")
# Returns: List of fines with summary (total, unpaid, amount)

8. Book Appointment

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