واجهة القبلة البرمجية والأداة وموصِّل الذكاء الاصطناعي

واجهة JSON البرمجية

أرسلوا طلب GET يحمل lat وlon بالدرجات العشرية، أو city: أي مدينة يبلغ سكانها 15,000 نسمة أو أكثر، مكتوبة بلغات كثيرة. وأضيفوا country إذا اشتركت عدة أماكن في الاسم نفسه.

https://awwab.app/api/qibla?lat=51.5074&lon=-0.1278
https://awwab.app/api/qibla?city=Karachi
https://awwab.app/api/qibla?city=Hyderabad&country=IN

تعطي الإجابة الزاوية من الشمال الحقيقي، والزاوية على البوصلة المغناطيسية والانحراف المغناطيسي لليوم، والاتجاه، والمسافة بالكيلومتر والميل، وجملة من سطر واحد، وعبارة النسبة، ورابطًا إلى البوصلة الحيّة لذلك المكان:

{
  "place_name": "Karachi",
  "bearing_true": 267.7,
  "bearing_magnetic": 266.4,
  "magnetic_declination": 1.3,
  "cardinal": "W",
  "distance_km": 2801,
  "distance_mi": 1740,
  "attribution": "Qibla direction by Awwab · https://awwab.app/qibla",
  "live_compass_url": "https://awwab.app/qibla?city=karachi"
}

الطلبات من أي موقع آخر مسموح بها. نرجو ألا تتجاوز الطلبات طلبًا واحدًا في الثانية تقريبًا؛ فالعملاء الأسرع يُبطَّؤون.

مساعدو الذكاء الاصطناعي

يشغّل أوّاب خادم MCP بعيدًا، ليتمكّن مساعدو الذكاء الاصطناعي من تحديد القبلة لمستخدميهم مع نسبة الفضل إلى أوّاب. ولا يحتاج إلى تسجيل دخول.

https://awwab.app/mcp

أداة القبلة فيه، find_qibla، تأخذ إحداثيات أو مدينة. في ChatGPT تأتي الإجابة مع بطاقة بوصلة صغيرة؛ وفي Claude والمساعدين الآخرين تصل نصًّا وبيانات مع الرابط نفسه إلى البوصلة الحيّة. ولتجربته، يُضاف العنوان أعلاه موصِّلًا مخصّصًا في Claude، أو تطبيقًا في وضع المطوّرين في ChatGPT.

يشغّل الخادم نفسه أسئلة أوّاب بأداتين إضافيتين. تأخذ start_quiz موضوعًا ولغة اختياريين، وتعيد جولة من خمسة أسئلة بلا إجاباتها؛ وتصحّح check_answer إجابة واحدة وتعيد الشرح ومصادره. وفي التطبيقات التي تدعم الأدوات المصغّرة تُلعب الجولة في بطاقة أسئلة؛ وفي غيرها تصل نصًّا وبيانات. وتحمل النتائج عبارة النسبة «Quiz by Awwab · awwab.app».

ربط تطبيق الذكاء الاصطناعي

انسخوا الإعداد الخاص بتطبيقكم. كلها تشير إلى الخادم نفسه ولا تحتاج إلى مفتاح.

Claude (موصِّل مخصّص)

في Claude، افتحوا Settings ← Connectors ← Add custom connector، ثم املؤوا:

Name: Awwab Qibla
URL:  https://awwab.app/mcp

Claude Code

claude mcp add --transport http awwab-qibla https://awwab.app/mcp

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "awwab-qibla": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://awwab.app/mcp"]
    }
  }
}

ChatGPT (وضع المطوّرين)

في ChatGPT، افتحوا Settings ← Apps ← Advanced settings، وفعّلوا وضع المطوّرين، واختاروا Create app، ثم املؤوا:

Name:                Awwab Qibla
MCP server URL:      https://awwab.app/mcp
Authentication:      No authentication

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "awwab-qibla": { "url": "https://awwab.app/mcp" }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "awwab-qibla": { "type": "http", "url": "https://awwab.app/mcp" }
  }
}

Gemini CLI (~/.gemini/settings.json)

{
  "mcpServers": {
    "awwab-qibla": { "httpUrl": "https://awwab.app/mcp" }
  }
}

OpenAI: Responses API وAgents SDK

// Responses API: a remote MCP tool
{
  "type": "mcp",
  "server_label": "awwab_qibla",
  "server_url": "https://awwab.app/mcp",
  "allowed_tools": ["find_qibla"],
  "require_approval": "never"
}

# Agents SDK (Python)
from agents import Agent
from agents.mcp import MCPServerStreamableHttp

async with MCPServerStreamableHttp(name="awwab-qibla", params={"url": "https://awwab.app/mcp"}) as qibla:
    agent = Agent(name="Assistant", mcp_servers=[qibla])

الاكتشاف

بطاقة الخادم على /mcp/server-card ومُدرجة في /.well-known/ai-catalog.json. والواجهة البرمجية JSON موصوفة بصيغة OpenAPI 3.1 لإجراءات GPT وأطر الوكلاء الأخرى.

الأداة

يمكن للمساجد والمدارس والمدوّنات عرض القبلة على صفحاتها ببضعة أسطر من الشيفرة. وتُختار المدينة أو موقع كل زائر، والمظهر الفاتح أو الداكن، واللغة في صفحة محدّد القبلة.

الخصوصية

لا نسجّل ولا نحفظ الإحداثيات ولا المدن المرسلة إلى الواجهة البرمجية أو الموصِّل. لا يُحتفظ بشيء بعد الإجابة، ولا توضع ملفات تعريف ارتباط. ولمنع إساءة الاستخدام تَعُدّ Cloudflare الطلبات لكل عنوان IP لمدة دقيقة تقريبًا. والتفاصيل الكاملة في سياسة الخصوصية.

كيف تُحسب الأرقام

الزاوية هي اتجاه بداية الدائرة العظمى من المكان إلى الكعبة (21.422487° شمالًا، 39.826206° شرقًا) على كرة، وهي الطريقة المعتادة لحساب القبلة. ويقلّ الفرق بينها وبين الحساب على الشكل الإهليلجي للأرض عن نصف درجة. وتُحسب المسافة بنصف القطر المتوسط للأرض. ويأتي الانحراف المغناطيسي من النموذج المغناطيسي العالمي 2025، الصالح حتى نهاية 2029.

الشروط

الاستخدام مجاني، بشرط ذكر «Qibla direction by Awwab» مع رابط إلى awwab.app/qibla حيثما تُعرض النتيجة. وأسماء المدن ومواقعها من GeoNames بترخيص CC BY 4.0؛ فاذكروا GeoNames أيضًا إذا أعدتم استخدامها. للأسئلة: support@awwab.app.