Quran MCP (Tanjim Noor)

具有OAuth身份验证的古兰经MCP服务器

这是一个 模型上下文协议（MCP） 服务器，该服务器通过GitHub OAuth身份验证提供对Quran Foundation API的访问。用户可以通过自然语言交互查询古兰经经文、翻译、tafsir（评论）等。

______________________________________________________________________

📖 贡献者快速链接

______________________________________________________________________

🕌 特性

• 翻译发现：浏览56多种语言的125多种翻译
• 诗歌检索：获取任何包含阿拉伯语文本、翻译和元数据的诗句
• 多个翻译：支持100多种语言的翻译
• 逐字分析：获取诗歌的详细单词分解
• 塔夫希尔（评论）：获取学术解释和说明
• OAuth身份验证：通过GitHub OAuth进行安全访问控制
• Cloudflare Workers：快速、全球分布式的无服务器部署

🚀 可用工具

getAvailableTranslations

发现可用的古兰经翻译及其ID，以便与 getVerse.

示例查询：

• “有哪些英文翻译？”
• “显示所有乌尔都语翻译”
• “列出所有可用的古兰经翻译”

支持的语言： 英语、乌尔都语、阿拉伯语、西班牙语、法语、土耳其语、孟加拉语、印度尼西亚语、俄语、波斯语以及40多种语言，共有125多种翻译。

getVerse

获取古兰经经文，包括可选的翻译、单词分析和tafsir。使用 getAvailableTranslations 首先发现翻译ID。

示例查询：

• 《古兰经》2:255节
• “显示1:1节，英文翻译ID为20”
• “得到112:1节，逐字分解和翻译”

工作流程：

1. 使用 getAvailableTranslations 查找翻译ID
2. 使用 getVerse 使用发现的ID

看 src/quran/README.md 详细文档。

📋 先决条件

您需要：

1. GitHub OAuth应用程序 -用于用户身份验证
2. 古兰经基金会API证书 - 在此处请求访问权限
3. Cloudflare帐户 -用于部署

🛠️ 设置

1.安装依赖项

直接克隆仓库并安装依赖项：

git clone 
cd quran-mcp
pnpm install

2.配置机密

设置您的API证书和机密：

GitHub OAuth应用程序设置

创建新的 :

• 主页网址： https://quran-mcp..workers.dev
• 授权回调URL: https://quran-mcp..workers.dev/callback
• 记下您的客户端ID并生成客户端密钥

古兰经基金会API

从请求API凭据 古兰经基金会

通过牧马人设定秘密

# GitHub OAuth
npx wrangler secret put GITHUB_CLIENT_ID
npx wrangler secret put GITHUB_CLIENT_SECRET
npx wrangler secret put COOKIE_ENCRYPTION_KEY  # Generate: openssl rand -hex 32

# Quran Foundation API
npx wrangler secret put QURAN_CLIENT_ID
npx wrangler secret put QURAN_CLIENT_SECRET

\[！重要\] 当你创建第一个秘密时，牧马人会询问你是否要创建一个新的Worker。提交“Y”以创建新的Worker并保存密钥。

3.设置KV命名空间

为OAuth状态存储创建KV命名空间：

npx wrangler kv namespace create "OAUTH_KV"

更新 wrangler.jsonc 使用生成的KV ID。

4.测试SDK（可选但推荐）

在部署之前，请测试您的Quran API证书是否有效：

# Set environment variables (PowerShell)
$env:QURAN_CLIENT_ID="your-client-id"
$env:QURAN_CLIENT_SECRET="your-client-secret"

# Install tsx for testing
pnpm add -D tsx

# Run the test script
npx tsx src/quran/test.ts

您应该看到成功的API调用，如：

✅ Environment variables found
✅ Quran client initialized
📖 Test 1: Fetching Ayat al-Kursi (2:255)...
✅ Success!

要测试新的翻译发现工具，请执行以下操作：

pnpm test:sdk:translations

5.部署

将MCP服务器部署到Cloudflare Workers：

npx wrangler deploy

6.连接MCP客户端

部署后，您可以将各种MCP客户端连接到服务器。替换 `` 使用您实际的Cloudflare Workers子域名。

🔍 MCP检验员（测试与调试）

使用测试远程服务器 检查员:

npx @modelcontextprotocol/inspector@latest

进入 https://quran-mcp..workers.dev/mcp 并连接。

______________________________________________________________________

🤖 克劳德桌面

地点： %APPDATA%\Claude\claude_desktop_config.json （Windows）或 ~/Library/Application Support/Claude/claude_desktop_config.json （Mac）

打开克劳德桌面： 设置→ 开发者→ 编辑配置

添加此配置：

{
  "mcpServers": {
    "quran": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://quran-mcp..workers.dev/mcp"
      ]
    }
  }
}

重新启动克劳德桌面 并在GitHub上进行身份验证。现在你可以问克劳德：

• “有哪些英文翻译？”
• 从《古兰经》中获取2:255节，并附上英文翻译
• “给我看乌尔都语翻译的《法蒂哈》第一首诗”
• “112:1节说了什么？”

______________________________________________________________________

⚡ 光标

地点： .vscode/mcp.json 在您的工作空间中

创建或编辑 .vscode/mcp.json:

{
  "servers": {
    "https://quran-mcp..workers.dev": {
      "url": "https://quran-mcp..workers.dev/sse",
      "type": "http"
    }
  },
  "inputs": []
}

注： 游标使用 /sse （服务器发送事件）终结点。

重新启动游标 并在提示时向GitHub进行身份验证。《古兰经》工具将在Cursor的AI聊天中提供。

______________________________________________________________________

🔷 GitHub副本（VS代码）

地点： .vscode/mcp.json 在您的工作空间中

与游标配置相同：

{
  "servers": {
    "https://quran-mcp..workers.dev": {
      "url": "https://quran-mcp..workers.dev/sse",
      "type": "http"
    }
  },
  "inputs": []
}

重新加载VS代码 (Ctrl+Shift+P → “开发者：重新加载窗口”）并在GitHub上进行身份验证。使用GitHub Copilot Chat时，这些工具将可用。

______________________________________________________________________

📱 其他MCP客户端

对于其他MCP兼容客户端，请使用以下端点之一：

• 现代客户端（流式HTTP）： https://quran-mcp..workers.dev/mcp
• 传统客户（SSE）： https://quran-mcp..workers.dev/sse

______________________________________________________________________

🔐 认证流程

所有客户端都会将您重定向到GitHub OAuth进行身份验证：

1. 点击客户端提供的授权链接
2. 批准GitHub OAuth应用程序
3. 您将被重定向回MCP服务器
4. 身份验证完成！开始查询古兰经经文

______________________________________________________________________

7.示例查询

连接后，尝试以下自然语言查询：

翻译发现：

• “有哪些英文翻译？”
• “显示所有乌尔都语翻译”
• “列出可用的西班牙语古兰经翻译”

诗歌检索：

• 《古兰经》2:255节
• “给我看1:1的英文翻译”
• “用乌尔都语翻译Surah Al-Ikhlas（第112章）”
• “18:10节逐字逐句地说了什么？”
• “用塔夫希尔（注释）读2:255节。”

🧪 地方发展

对于本地测试，请使用以下命令创建另一个GitHub OAuth应用程序：

• 主页网址： http://localhost:8788
• 授权回调URL: http://localhost:8788/callback

设置本地环境变量：

$env:QURAN_CLIENT_ID="your-client-id"
$env:QURAN_CLIENT_SECRET="your-client-secret"

运行开发服务器：

pnpm dev

📚 文档

• 古兰经工具文档 -详细的工具使用和API
• 翻译工具指南 -如何发现和使用翻译ID
• 身份验证指南 -完成OAuth2身份验证设置和故障排除
• 技术集成 -实施细节和架构
• 古兰经SDK知识库 -完整的SDK参考
• 可用资源 -翻译和tafsir的完整列表
• API官方文件 -古兰经基金会API

🔐 认证

《古兰经》API使用 OAuth2客户端凭据 身份验证流程。这 @quranjs/api SDK处理此问题 自动地:

• ✅ 自动代币获取 根据首次请求
• ✅ 令牌缓存 持续1小时（3600秒）
• ✅ 自动续期 令牌到期时
• ✅ 正确的标题 (x-auth-token, x-client-id)随每个请求一起发送

无需手动管理令牌！

看 认证.md 有关以下内容的完整详细信息：

• OAuth2身份验证的工作原理
• 环境配置（生产与预生产）
• 常见问题排查
• 安全最佳实践

🔐 安全

\[！警告\] 虽然我们已经实施了安全控制， 在生产部署之前，您必须审查并实施所有安全措施。参见 保护MCP服务器.

🛣️ 路线图

已实现的功能：

• ✅ 通过翻译、逐字逐句和tafsir进行诗歌检索
• ✅ 按语言列出可用的翻译

计划功能：

• ✨ 列出可用的tafsir（评论）
• ✨ 搜索古兰经和翻译
• ✨ 获取章节信息和元数据
• ✨ 获取Juz/Hizb/Page的诗句
• ✨ 随机诗（今日诗）
• ✨ 音频朗诵支持

看 src/quran/README.md 查看完整的缩放指南。

📄 许可证

该项目建立在Cloudflare MCP模板的基础上，并与库兰基金会API集成。

🤝 贡献与社区

我们欢迎社区的贡献！以下是如何参与其中：

📋 贡献之前

• 阅读我们的 行为准则 -请尊重和包容
• 审查 贡献.md -关于如何贡献、代码风格和提交约定的完整指南

🐛 报告Bug

发现问题？使用我们的 错误报告模板 帮助我们快速理解和修复它。

✨ 请求功能

有主意吗？使用我们的 功能请求模板.

📝 改进文档

发现文件不清楚？使用我们的 文档问题模板.

🔀 提交代码更改

1. 分叉存储库 并创建功能分支
2. 遵循我们的指导方针:

- 测试您的更改： pnpm type-check && pnpm test:sdk - 遵循代码风格指南（TypeScript、camelCase、JSDoc注释） - 在您的提交中引用相关问题

1. 创建拉取请求 使用我们的 PR模板
2. 地址反馈 来自审稿人
3. 庆祝 合并时！ 🎉

看 贡献.md 了解详细的分步说明。

🔒 安全

发现安全漏洞？请 不要 公开问题。相反，请遵循我们的 安全策略 负责披露。

💬 问题或讨论？

• 打开一个问题 question 标签
• 检查 知识库/ 对于现有文档
• 加入

______________________________________________________________________

内置❤️ 使用：

• 模型上下文协议
• 古兰经基金会API
• Cloudflare Workers
• 记下您的客户端ID并生成客户端密钥。
• 创建一个 .dev.vars 在项目根目录中使用以下文件：

GITHUB_CLIENT_ID=your_development_github_client_id
GITHUB_CLIENT_SECRET=your_development_github_client_secret

开发和测试

在本地运行服务器，使其在以下位置可用 http://localhost:8788 wrangler dev

要测试本地服务器，请输入 http://localhost:8788/sse 进入Inspector并点击连接。按照提示操作后，您将能够“列出工具”。

它是如何工作的？

OAuth提供者

OAuth Provider库是Cloudflare Workers的完整OAuth 2.1服务器实现。它处理OAuth流的复杂性，包括令牌发放、验证和管理。在这个项目中，它扮演着双重角色：

• 对连接到服务器的MCP客户端进行身份验证
• 管理与GitHub OAuth服务的连接
• 在KV存储器中安全存储令牌和身份验证状态

耐用MCP

Durable MCP通过Cloudflare的Durable Objects扩展了基本MCP功能，提供：

• MCP服务器的持久状态管理
• 请求之间身份验证上下文的安全存储
• 通过以下方式访问经过身份验证的用户信息 this.props
• 支持基于用户身份的有条件工具可用性

MCP远程

MCP Remote库使您的服务器能够公开可由MCP客户端（如检查器）调用的工具。它

• 定义客户端和服务器之间的通信协议
• 提供了一种结构化的方法来定义工具
• 处理请求和响应的序列化和反序列化
• 维护客户端和服务器之间的服务器发送事件（SSE）连接

📖 额外资源

• 行为准则 -社区标准和期望
• 贡献指南 -如何贡献代码、报告错误和请求功能
• **** -使用我们的模板报告错误
• **** -提出问题并讨论想法

📄 许可证

该项目根据 MIT许可证.

______________________________________________________________________

内置❤️ 使用：

• 模型上下文协议
• 古兰经基金会API
• Cloudflare Workers