absher-mcp-server

ali-bouali/absher-mcp-server

3.3

If you are the rightful owner of absher-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Absher Voice Assistant MCP Server is a standalone server designed to facilitate access to Saudi government services through the Absher platform.

Tools
8
Resources
0
Prompts
0

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)

  1. get_user_data - Load complete user profile information

Service Discovery Tool (1)

  1. get_service_requirements - Get required fields for a specific service

Service Execution Tools (3)

  1. renew_passport - Submit passport renewal request
  2. get_traffic_fines - Query traffic violations
  3. 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