MCP Quran

MCP Quran Server

  ](https://www.docker.com/)

一个模型上下文协议（MCP）服务器，通过 《古兰经》API该服务器使人工智能助手和应用程序能够检索古兰经内容，包括章节、经文、翻译、tafsir等。

🌟 特性

• 完整的古兰经访问权限全部114章6236节
• 多种检索方法：按章、诗键、页、朱兹、希兹布、揉
• 丰富的内容：阿拉伯语文本、翻译、tafsir、逐字分解
• 搜索功能：古兰经全文搜索
• 音频支持：背诵选项和音频文件
• 类型安全：通过适当的SDK类型完全支持TypeScript
• MCP合规性：标准模型上下文协议实现
• Docker支持：易于集装箱化部署

📦 安装

先决条件

• Node.js 18+
• pnpm（推荐）或npm
• Docker（可选，用于容器化部署）

设置

地方发展

# Clone the repository
git clone https://github.com/your-username/mcp-quran.git
cd mcp-quran

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run in debug mode with MCP Inspector
pnpm debug

Docker部署

# Build and run with Docker Compose
docker-compose up -d

# For development with hot reload
docker-compose --profile dev up -d

# Build Docker image manually
docker build -t mcp-quran .

# Run container
docker run -d --name mcp-quran-server mcp-quran

🚀 快速开始

基本用法

MCP古兰经服务器提供访问古兰经内容的工具。以下是一些示例：

获取所有章节

{
  "name": "all_chapters",
  "arguments": {}
}

按章节获取诗句

{
  "name": "verses_by_chapter",
  "arguments": {
    "chapterId": 1,
    "options": {
      "language": "en",
      "translations": [131, 85],
      "words": true
    }
  }
}

搜索古兰经

{
  "name": "search_quran",
  "arguments": {
    "query": "mercy",
    "options": {
      "language": "en",
      "size": 10,
      "page": 1
    }
  }
}

🛠️ 可用工具

此MCP服务器公开与QuranJS API端点对应的以下工具：

📖 章节

• all_chapters -获取所有章节
• chapter_by_id -按ID获取章节

📜 诗句

• verse_by_key -逐章获取：诗键
• verses_by_chapter -按章节ID获取经文
• verses_by_page -按页码获取经文
• verses_by_juz -通过juz数字获取诗句
• verses_by_hizb -按hizb编号获取诗句
• verses_by_rub -按摩擦数获取诗句
• random_verse -随机获得一首诗

🔍 搜索

• search_quran -搜索古兰经

📚 朱兹

• all_juzs -获取所有juzs

📚 API文档

有关可用参数、选项和响应格式的详细信息，请参阅QuranJS API官方文档：

• QuranJS API文档 -完整的API参考
• API章节 -章节相关端点
• 与API相比 -Verse相关端点
• 搜索API -搜索功能
• Juzs API公司 -Juz相关端点

MCP工具遵循与QuranJS API相同的参数结构和选项。

🌐 支持的语言

服务器通过以下方式支持多种语言 Language 枚举。请参阅 QuranJS语言文档 查看支持的语言的完整列表。

🔧 配置

MCP客户端配置

将此添加到MCP客户端配置中：

{
  "mcpServers": {
    "quran": {
      "command": "node",
      "args": ["/path/to/your/mcp-quran/build/index.js"],
      "env": {}
    }
  }
}

Docker配置

对于Docker部署，请使用容器化版本：

{
  "mcpServers": {
    "quran": {
      "command": "docker",
      "args": ["run", "--rm", "mcp-quran"],
      "env": {}
    }
  }
}

🏗️ 建筑

服务器由以下组件构建：

• TypeScript：用于类型安全和更好的开发经验
• 模型上下文协议SDK：用于MCP合规性
• 《古兰经》API：用于古兰经数据访问
• 萨德：用于运行时验证
• pnpm：用于包管理
• 码头工人：用于集装箱化部署

项目结构

mcp-quran/
├── src/
│   ├── index.ts          # Main server entry point
│   ├── tools/            # MCP tools implementation
│   │   ├── chapters.ts   # Chapter-related tools
│   │   ├── verses.ts     # Verse-related tools
│   │   ├── search.ts     # Search functionality
│   │   └── juzs.ts       # Juz-related tools
│   └── helper/           # Helper functions
├── media/
│   └── logo.png          # Project logo
├── build/                # Compiled JavaScript
├── Dockerfile            # Docker configuration
├── docker-compose.yml    # Docker Compose setup
├── .dockerignore         # Docker ignore rules
└── package.json          # Project configuration

🧪 发展

设置开发环境

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run in debug mode with MCP Inspector
pnpm debug

Docker开发

# Start development environment with hot reload
docker-compose --profile dev up -d

# View logs
docker-compose logs -f mcp-quran-dev

# Stop development environment
docker-compose --profile dev down

🤝 贡献

欢迎投稿！请随时提交拉取请求。

开发指南

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

🙏 致谢

• 《古兰经》API 提供古兰经数据
• 模型上下文协议 对于MCP规范
• 开源社区提供灵感和支持

📞 支持

如果您遇到任何问题或有疑问：

• 在GitHub上打开一个问题
• 检查 QuranJS文档
• 查看 MCP规范

______________________________________________________________________

Made with ❤️ for the Quranic community