Quran MCP Server

🚀 Quran.com API 的 MCP 服務器

本項目是一個 MCP 服務器，它藉助官方的 REST API v4 實現與 Quran.com 文本的交互，為相關應用提供便利。

🚀 快速開始

此 MCP 服務器由 OpenAPI 規範 (v4.json) 生成。

✨ 主要特性

該服務器提供了豐富的 API 端點，LLM 可通過兼容客戶端使用，涵蓋章節、經文、Juzs、搜索、翻譯等多個方面的查詢功能。

📦 安裝指南

測試

# 運行測試
npm test

💻 使用示例

基礎用法

以下是部分 API 端點的使用示例：

# 獲取所有章節列表
curl https://your-server-url/chapters

# 獲取一條隨機經文
curl https://your-server-url/verses/random

高級用法

在實際應用中，可根據需求組合使用不同的端點，例如先搜索特定術語，再獲取相關經文：

# 在古蘭經中搜索特定術語
curl https://your-server-url/search?term=your_search_term

# 根據搜索結果獲取經文
curl https://your-server-url/verses/by_key/your_verse_key

📚 詳細文檔

端點詳情

章節

經文

Juzs

搜索

翻譯

環境變量

詳細日誌模式

當 VERBOSE_MODE 設置為 'true' 時，服務器會在控制檯中輸出詳細的 API 請求和響應日誌。這對於調試和監控 API 交互非常有用。

詳細日誌包括：

• 請求：記錄每個傳入請求的工具名稱和參數
• 響應：記錄每個響應的結果數據及工具名稱
• 錯誤：記錄錯誤信息，包括錯誤名稱、消息和堆棧跟蹤（如有可用）

每條日誌都帶有時間戳，並且前面有標識符（如 REQUEST、RESPONSE 或 ERROR），以便於識別。

環境配置示例

使用 bash：

export API_KEY="your_api_key_here"
export PORT=8000
export VERBOSE_MODE=true

使用 PowerShell（Windows）：

$env:API_KEY = "your_api_key_here"
$env:PORT = 8000
$env:VERBOSE_MODE = "true"

在 Claude Desktop 中配置

將以下內容添加到 claudius.json 配置文件中：

{
  "mcpServers": {
    "quranComMCP": {
      "type": "custom",
      "executablePath": "/path/to/node/bin/npm",
      "scriptName": "start",
      "args": [
        "--port",
        "8000",
        "--api-key",
        "your_api_key_here"
      ],
      "environmentVariables": {
        "VERBOSE_MODE": "true"
      }
    }
  }
}

完整的日誌示例

當 VERBOSE_MODE 啟用時，控制檯輸出可能如下：

[2023-10-01 12:34:56] REQUEST - GET /verses/random 
[2023-10-01 12:34:57] RESPONSE - {
  "chapter": {
    "number": 1,
    "name": "Al-Fatiha",
    "translation": "The Opening"
  },
  "verse": {
    "number": 1,
    "text": "In the name of Allah, Most Gracious, Most Merciful..."
  }
}
[2023-10-01 12:35:01] ERROR - 獲取經文時發生錯誤：網絡連接中斷

🔧 技術細節

該服務器基於 OpenAPI 規範生成，使用了相關的 Web 技術來處理 API 請求和響應。通過環境變量的配置，可以靈活地調整服務器的運行參數，如 API 密鑰、端口和日誌模式等。

📄 許可證

此項目 licensed under the MIT License.

總結

通過設置 API_KEY、指定端口和啟用詳細日誌模式，您可以輕鬆地將 Quran.com API 集成到 MCP 服務器中，並在 Claude Desktop 中使用。