ytssamuel/FHL-MCP-Server

FHL Bible MCP Server 📖

A Model Context Protocol (MCP) server for accessing the Faith, Hope, Love (信望愛站) Bible API.

📖 Overview

FHL Bible MCP Server 是一個基於 Model Context Protocol 的伺服器，整合了信望愛站提供的豐富聖經資源 API。透過此 MCP Server，AI 助手（如 Claude）可以直接查詢聖經經文、原文字彙分析、註釋書、主題查經等專業研經資源。

✅ v0.1.2 最新版本 (2025-11-05)
所有已知問題已修復完成（7/7, 100%），包括書卷映射錯誤、Strong's 字典功能增強等。系統功能完整且穩定。
📋 | 📝

✨ 主要功能

• 🔍 經文查詢: 支援多種聖經譯本（和合本、KJV、現代中文譯本等）
• 📚 原文研究: 提供希臘文、希伯來文字彙分析與 Strong's 字典
• 💡 註釋研經: 查詢多種註釋書與牧師講道內容
• 🔎 經文搜尋: 關鍵字搜尋與進階原文編號搜尋
• 🎯 主題查經: 查詢主題相關的聖經教導
• 🎵 有聲聖經: 取得多語言有聲聖經連結
• 🌏 繁簡支援: 完整支援繁體/簡體中文切換

🚀 Quick Start

🎯 方法一：一鍵安裝（推薦）

使用自動化安裝腳本，快速完成環境配置：

# 1. 下載專案
git clone https://github.com/ytssamuel/FHL_MCP_SERVER.git
cd FHL_MCP_SERVER

# 2. 執行一鍵安裝
# Windows:
.\scripts\install.bat

# macOS/Linux:
chmod +x scripts/install.sh
bash scripts/install.sh

# 3. 生成配置（互動式）
python scripts/generate_config.py

腳本功能:

• ✅ 自動檢查 Python 版本
• ✅ 建立虛擬環境
• ✅ 安裝所有依賴
• ✅ 驗證安裝結果
• ✅ 生成 AI 助手配置

📝 方法二：手動安裝

1. 下載專案

   git clone https://github.com/ytssamuel/FHL_MCP_SERVER.git
   cd FHL_MCP_SERVER
   

2. 安裝依賴

   # Windows
   python -m venv venv
   .\venv\Scripts\activate
   pip install -e .
   
   # macOS/Linux
   python3 -m venv venv
   source venv/bin/activate
   pip install -e .
   

3. 配置 AI 助手

   使用自動生成腳本（推薦）：

   python scripts/generate_config.py
   

   或選擇您偏好的 AI 助手手動添加配置：

   Claude Desktop 配置 (推薦) ⭐

   編輯配置文件（%APPDATA%\Claude\claude_desktop_config.json on Windows 或 ~/Library/Application Support/Claude/claude_desktop_config.json on macOS）：

   Windows:

   {
     "mcpServers": {
       "fhl-bible": {
         "command": "C:\\path\\to\\FHL_MCP_SERVER\\venv\\Scripts\\python.exe",
         "args": ["-m", "fhl_bible_mcp"],
         "env": {
           "PYTHONPATH": "C:\\path\\to\\FHL_MCP_SERVER\\src",
           "LOG_LEVEL": "INFO",
           "FHL_CACHE_DIR": "C:\\path\\to\\FHL_MCP_SERVER\\.cache"
         }
       }
     }
   }
   

   macOS/Linux:

   {
     "mcpServers": {
       "fhl-bible": {
         "command": "/path/to/FHL_MCP_SERVER/venv/bin/python",
         "args": ["-m", "fhl_bible_mcp"],
         "env": {
           "PYTHONPATH": "/path/to/FHL_MCP_SERVER/src",
           "LOG_LEVEL": "INFO",
           "FHL_CACHE_DIR": "/path/to/FHL_MCP_SERVER/.cache"
         }
       }
     }
   }
   

   ⚠️ 重要: 必須使用虛擬環境中的 Python 執行檔（venv/bin/python 或 venv/Scripts/python.exe），而非系統的 Python！

   GitHub Copilot (VS Code) 配置 💻

   編輯 VS Code 設定（settings.json）：

   Windows:

   {
     "github.copilot.chat.mcp.enabled": true,
     "github.copilot.chat.mcp.servers": {
       "fhl-bible": {
         "command": "C:\\path\\to\\FHL_MCP_SERVER\\venv\\Scripts\\python.exe",
         "args": ["-m", "fhl_bible_mcp"],
         "env": {
           "PYTHONPATH": "C:\\path\\to\\FHL_MCP_SERVER\\src",
           "LOG_LEVEL": "INFO",
           "FHL_CACHE_DIR": "C:\\path\\to\\FHL_MCP_SERVER\\.cache"
         }
       }
     }
   }
   

   macOS/Linux:

   {
     "github.copilot.chat.mcp.enabled": true,
     "github.copilot.chat.mcp.servers": {
       "fhl-bible": {
         "command": "/path/to/FHL_MCP_SERVER/venv/bin/python",
         "args": ["-m", "fhl_bible_mcp"],
         "env": {
           "PYTHONPATH": "/path/to/FHL_MCP_SERVER/src",
           "LOG_LEVEL": "INFO",
           "FHL_CACHE_DIR": "/path/to/FHL_MCP_SERVER/.cache"
         }
       }
     }
   }
   

   ⚠️ 重要:

   • 將 /path/to/FHL_MCP_SERVER 替換為您的實際專案路徑
   • Windows 路徑使用雙反斜線 \\ 或單斜線 /
   • PYTHONPATH 必須指向專案的 src 目錄

4. 開始使用

   查詢約翰福音 3:16
   使用 basic_help_guide 查看完整功能
   

📖 詳細安裝步驟: 請參閱

包含：

• ✅ 跨平台詳細步驟 (Windows/macOS/Linux)
• ✅ 三種 AI 助手完整配置教學
• ✅ 常見問題疑難排解
• ✅ 進階配置選項

🛠️ 安裝輔助工具

專案提供完整的自動化腳本，簡化安裝配置流程：

快速使用:

# 1. 安裝前檢查
python scripts/quick_check.py

# 2. 一鍵安裝
# Windows: .\scripts\install.bat
# Unix:    bash scripts/install.sh

# 3. 環境驗證
python scripts/verify_setup.py

# 4. 生成配置
python scripts/generate_config.py

詳細說明請參考

📚 Available Tools

經文查詢

• get_bible_verse - 查詢指定章節的聖經經文
• get_bible_chapter - 查詢整章聖經經文
• search_bible - 在聖經中搜尋關鍵字

原文研究

• get_word_analysis - 取得經文的字彙分析
• lookup_strongs - 查詢 Strong's 原文字典
• search_by_strongs - 以 Strong's Number 搜尋經文

註釋研經

• get_commentary - 取得聖經註釋
• search_commentary - 搜尋註釋內容
• get_topic_study - 查詢主題查經

次經與使徒教父 ⭐ NEW (JSON 格式輸出)

• get_apocrypha_verse - 查詢次經經文（舊約次經 101-115）支援完整書卷名如「瑪加伯上」、「便西拉智訓」
• search_apocrypha - 搜尋次經內容
• list_apocrypha_books - 列出所有次經書卷
• get_apostolic_fathers_verse - 查詢使徒教父經文（201-217）
• search_apostolic_fathers - 搜尋使徒教父內容
• list_apostolic_fathers_books - 列出所有使徒教父書卷

💡 注意: 次經與使徒教父 API 使用結構化 JSON 格式輸出，方便程式處理。詳見

註腳查詢 ⭐ NEW

• get_footnote - 查詢聖經註腳（目前支援 TCV 版本）

文章搜尋 ⭐ NEW (JSON 格式輸出)

• search_fhl_articles - 搜尋信望愛站文章（8000+ 篇文章，支援完整內容或預覽模式）
• list_fhl_article_columns - 列出可用的文章專欄

💡 注意: 文章 API 使用結構化 JSON 格式輸出。預設返回內容預覽（約 200 字），若要完整內容請設定 include_content=true。詳見

資訊工具

• list_bible_versions - 列出所有可用的聖經版本
• list_commentaries - 列出所有可用的註釋書
• get_book_list - 取得聖經書卷列表

多媒體

• get_audio_bible - 取得有聲聖經連結

總計: 27 個工具函數 | 更多詳細說明請參閱 。

🏗️ Architecture

FHL Bible MCP Server
├── Tools (工具) - 執行動作和查詢
├── Resources (資源) - 提供靜態/動態資料
└── Prompts (提示) - 預設對話範本

📖 Resources

本伺服器提供以下 URI schemes：

• bible://verse/{version}/{book}/{chapter}/{verse} - 查詢特定經文
• bible://chapter/{version}/{book}/{chapter} - 查詢整章經文
• strongs://{testament}/{number} - Strong's 字典資源
• commentary://{book}/{chapter}/{verse} - 註釋資源
• info://versions - 版本列表
• info://books - 書卷列表
• info://commentaries - 註釋書列表

🎯 Prompts

內建 19 個專業對話範本，涵蓋從入門到進階的完整研經需求：

📘 基礎類 (Basic) - 快速上手

• basic_help_guide - 完整使用指南，新手必讀
• basic_uri_demo - URI 使用示範，教您直接存取資源
• basic_quick_lookup - 快速查經，簡單方便
• basic_tool_reference - 工具參考手冊，詳細說明所有功能

📖 讀經類 (Reading) - 每日靈修

• reading_daily - 每日讀經計劃，結構化的靈修體驗
• reading_chapter - 整章讀經，深入理解一整章
• reading_passage - 段落讀經，跨章節經文研讀

🎓 研經類 (Study) - 深度研讀

• study_verse_deep - 深入研讀經文，專業解經分析
• study_topic_deep - 主題研究，全面探討聖經主題
• study_translation_compare - 版本比較，多譯本對照
• study_word_original - 原文字詞研究，希伯來文/希臘文分析

🎯 特殊類 (Special) - 專業應用

• special_sermon_prep - 講道準備，全方位備課資源
• special_devotional - 靈修材料，個人/小組/家庭適用
• special_memory_verse - 背經輔助，記憶技巧與計劃
• special_topical_chain - 主題串連，貫穿聖經的主題追蹤
• special_bible_trivia - 聖經問答，互動式知識測驗

🚀 進階類 (Advanced) - 專業研究

• advanced_cross_reference - 交叉引用分析，多層次引用網絡 (1-3 層深度)
• advanced_parallel_gospels - 符類福音對照，四福音平行比較
• advanced_character_study - 聖經人物研究，9 大維度全面分析

💡 提示: 使用 basic_help_guide prompt 查看完整功能介紹和使用教學！
📚 詳細說明請參閱

🔧 Development

Setup Development Environment

# 安裝開發依賴
pip install -e ".[dev]"

# 執行測試
pytest

# 執行 linting
ruff check .

# 格式化程式碼
black .

# 型別檢查
mypy src/

Project Structure

FHL_MCP_SERVER/
├── src/fhl_bible_mcp/
│   ├── api/          # API 客戶端
│   ├── models/       # 資料模型
│   ├── tools/        # MCP Tools
│   ├── resources/    # MCP Resources
│   ├── prompts/      # MCP Prompts
│   └── utils/        # 工具函式
├── tests/            # 測試
├── docs/             # 文件
└── pyproject.toml    # 專案設定

⚖️ Copyright Notice

重要聲明

本專案使用信望愛站（FHL）提供的聖經 API。請注意：

1. 聖經譯本版權: 信望愛站上各個聖經譯本，有些僅授權給信望愛站使用。使用者必須查閱版權說明，不得任意使用，以免違法。

2. 本專案角色: 本 MCP Server 僅作為 API 的介面層，不儲存或重新分發任何經文內容。所有經文內容均即時從 FHL API 取得。

3. 合理使用: 本專案為非商業性質的研經工具。使用者應遵守相關版權規定，在合理範圍內進行研經活動。

4. 開發者責任: 本 MCP Server 開發者不對使用者違反版權的行為負責。使用者應自行確保其使用方式符合版權規定。

參考資源

• 信望愛站首頁: https://www.fhl.net/
• API 文件: https://bible.fhl.net/api/ (升級版，包含 bid 欄位)
• 舊版 API: https://bible.fhl.net/json/ (仍可使用)
• 版權說明: https://www.fhl.net/main/fhl/fhl8.html

📝 License

本專案採用 MIT License - 詳見 檔案。

注意：此授權僅適用於本專案的程式碼，不包含透過 API 取得的聖經內容及文章。內容的版權歸屬於各譯本的版權方及信望愛站。

🤝 Contributing

歡迎貢獻！如有問題或建議，請開 Issue 討論。

📮 Contact

如有問題或建議，請開 Issue。

🙏 Acknowledgments

• 感謝信望愛站（Faith, Hope, Love）提供豐富的聖經資源 API
• 感謝 Anthropic 開發 Model Context Protocol
• 感謝所有貢獻者

🎊 專案狀態

📈 開發進度

• ✅ Phase 1: API 客戶端實作 - 完成
• ✅ Phase 2: MCP Server 核心功能 - 完成
• ✅ Phase 3: 進階功能與優化 - 完成
• ✅ Phase 4.1: 全面測試套件 - 完成 (138 測試)
• ✅ Phase 4.2: E2E 測試與文檔 - 完成 (160 測試, 83% 覆蓋率)
• ✅ Phase 5: Prompts 增強計劃 - 完成 (19 個 Prompts)
• ✅ Phase 6: API 增強計劃 - 完成 (次經、使徒教父、註腳、文章) 🎊

🎯 功能統計

📊 測試統計

總測試數:    160 個
通過率:      100% ✅
程式碼覆蓋率: 83% 🚀
100% 覆蓋模組: 12 個

詳細測試報告請參考

📚 Documentation

📖 使用手冊

• - 所有 Tools、Resources、Prompts 的詳細說明
• - Claude Desktop 整合與實際案例
• - 19 個 Prompts 速查表

👨‍💻 開發文件

• - 架構說明與貢獻指南
• - 詳細安裝步驟
• - 專案規劃與 API 分析
• - 完整測試覆蓋率報告

🎯 Prompts 相關

• - 19 個 Prompts 完整教學
• - 15 個新 Prompts 設計文件
• - 重構優化記錄

📂 文件導航

• - 完整的文件結構導航

Made with ❤️ for Bible study and research | 讓 AI 成為您的聖經研究助手！ 🙏