🚀 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 中使用。