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

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

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

腳本功能:

• ✅ 自動檢查 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 助手手動添加配置：

   編輯配置文件（%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！

   編輯 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 助手完整配置教學

• ✅ 常見問題疑難排解

• ✅ 進階配置選項

🛠️ 安裝輔助工具

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

快速使用:

詳細說明請參考 scripts/README.md

📚 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 格式輸出，方便程式處理。詳見 JSON 輸出格式文檔

註腳查詢 ⭐ NEW

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

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

• search_fhl_articles - 搜尋信望愛站文章（8000+ 篇文章，支援完整內容或預覽模式）

• list_fhl_article_columns - 列出可用的文章專欄

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

資訊工具

• list_bible_versions - 列出所有可用的聖經版本

• list_commentaries - 列出所有可用的註釋書

• get_book_list - 取得聖經書卷列表

多媒體

• get_audio_bible - 取得有聲聖經連結

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

🏗️ Architecture

📖 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 查看完整功能介紹和使用教學！
📚 詳細說明請參閱 Prompts 使用指南

🔧 Development

Setup Development Environment

Project Structure

⚖️ 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 - 詳見 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 增強計劃 - 完成 (次經、使徒教父、註腳、文章) 🎊

🎯 功能統計

📊 測試統計

詳細測試報告請參考 PHASE_4_2_FINAL_REPORT.md

📚 Documentation

📖 使用手冊

• API 完整文件 - 所有 Tools、Resources、Prompts 的詳細說明

• 使用範例 - Claude Desktop 整合與實際案例

• Prompts 快速參考 - 19 個 Prompts 速查表

👨‍💻 開發文件

• 開發者指南 - 架構說明與貢獻指南

• 安裝指南 - 詳細安裝步驟

• 專案規劃 - 專案規劃與 API 分析

• 測試報告 - 完整測試覆蓋率報告

🎯 Prompts 相關

• Prompts 使用指南 - 19 個 Prompts 完整教學

• Prompts 增強計劃 - 15 個新 Prompts 設計文件

• Prompts 改進報告 - 重構優化記錄

📂 文件導航

• 文件總覽 - 完整的文件結構導航

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