Ezanvakti.mcp.server

🚀 EzanVakti MCP 服務器

EzanVakti MCP 服務器是一個用 C# 實現的模型上下文協議（MCP）服務器，用於從 EzanVakti API（Diyanet - 土耳其宗教事務局）獲取伊斯蘭教祈禱時間。

✨ 主要特性

• 國家列表：獲取所有可用的國家。
• 城市搜索：查找某個國家內的城市。
• 地區查詢：獲取某個城市內的地區。
• 祈禱時間：檢索任何地區的月度祈禱時間表。
• 智能搜索：通過名稱搜索城市並獲取其祈禱時間。
• 今日時間：獲取當前日期的祈禱時間表。

🚀 快速開始

先決條件

• .NET 8.0 SDK 或更高版本。
• 兼容的 MCP 客戶端（如帶有 Copilot 的 VS Code、Claude Desktop 等）。

📦 安裝指南

1. 克隆或下載項目文件。
2. 恢復依賴項：

   dotnet restore
   

3. 構建項目：

   dotnet build
   

運行服務器

開發環境：

dotnet run

生產環境：

dotnet publish -c Release
./bin/Release/net8.0/publish/EzanVakti.MCP.Server

📚 詳細文檔

MCP 客戶端配置

VS Code 配置

在 .vscode/mcp.json 中添加以下內容：

{
  "mcpServers": {
    "ezanvakti": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/EzanVakti.MCP.Server.csproj"],
      "env": {}
    }
  }
}

Claude Desktop 配置

在 Claude Desktop 配置中添加以下內容：

{
  "mcpServers": {
    "ezanvakti": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/EzanVakti.MCP.Server.csproj"]
    }
  }
}

可用工具

1. GetCountries

列出 EzanVakti 數據庫中所有可用的國家。 用法：“Show me all countries with prayer times”

2. GetCities

獲取特定國家的城市/省份。 參數：

• countryId：國家 ID（例如，土耳其的 ID 為 "2"） 用法：“Show me cities in Turkey”

3. GetDistricts

獲取特定城市內的地區。 參數：

• cityId：城市 ID（例如，伊斯坦布爾的 ID 為 "539"） 用法：“Show me districts in Istanbul”

4. GetPrayerTimes

獲取某個地區的完整月度祈禱時間表。 參數：

• districtId：地區 ID 用法：“Get prayer times for district 9535”

5. SearchCityPrayerTimes

搜索城市並獲取其祈禱時間。 參數：

• cityName：要搜索的城市名稱
• countryId：國家 ID（默認為土耳其的 "2"） 用法：“Get prayer times for Istanbul”

6. GetTodayPrayerTimes

獲取某個地區今日的祈禱時間。 參數：

• districtId：地區 ID 用法：“What are today's prayer times for district 9535?”

祈禱時間數據結構

每個祈禱時間條目包括：

• 日期信息：伊斯蘭曆和公曆日期。
• 祈禱時間：
  • Imsak：黎明前（晨禮時間）
  • Gunes：日出
  • Ogle：中午（晌禮）
  • Ikindi：下午（晡禮）
  • Aksam：傍晚（昏禮）
  • Yatsi：夜晚（宵禮）
• 其他信息：
  • KibleSaati：朝向麥加的時間（太陽位於克爾白方向）
  • GunesDogus/GunesBatis：精確的日出/日落時間

示例查詢

以下是一些可以使用的自然語言查詢：

• “What are the prayer times in Istanbul?”
• “Show me all cities in Turkey”
• “Get today's prayer schedule for Ankara”
• “Find districts in Izmir”
• “What time is Maghrib prayer in Istanbul today?”

Docker 支持

構建 Docker 鏡像：

dotnet publish --os linux --arch x64 /t:PublishContainer

在容器中運行：

docker run -it ezanvakti-mcp-server:latest

API 速率限制

EzanVakti API 有以下限制：

• 每 5 分鐘 30 個請求。
• 每天 200 個請求。

由於祈禱時間是按月提供的，通常每個地點每月只需要一個請求。

架構

此 MCP 服務器基於以下技術構建：

• ModelContextProtocol SDK：官方 C# 實現。
• HttpClient：用於與 API 進行通信，並進行了適當的資源釋放。
• 依賴注入：實現了關注點的清晰分離。
• 日誌記錄：全面的錯誤跟蹤。
• JSON 序列化：使用快速的 System.Text.Json。

🔧 技術細節

該 MCP 服務器運用 ModelContextProtocol SDK 官方 C# 實現，藉助 HttpClient 與 EzanVakti API 通信，同時注重資源的合理釋放。採用依賴注入模式，將不同功能模塊的關注點分離，提高了代碼的可維護性和可擴展性。使用 System.Text.Json 進行 JSON 序列化，保證了數據處理的高效性。日誌記錄功能則有助於全面跟蹤和排查錯誤，確保系統的穩定性。

🤝 貢獻指南

1. 分叉倉庫。
2. 創建功能分支。
3. 提交更改。
4. 推送到分支。
5. 創建拉取請求。

📄 許可證

本項目是開源的。EzanVakti API 由土耳其宗教事務局提供。

🛠️ 支持

如果遇到問題或有疑問：

• 查看日誌以獲取錯誤詳細信息。
• 驗證 API 連接性。
• 確保 MCP 客戶端配置正確。
• 如果收到 429 錯誤，請檢查速率限制。