使用说明

圣经mcp

查询圣经章节
搜索正文关键字/语义
查看人物、地点和事件元数据
人物关系查询
查询与实体相关联的代表性语句
返回MCP tool形式的结构化响应

也就是说，Bible MCP不是“直接说出答案的应用程序”。前面的LLM或客户端可以调用 圣经搜索引擎+结构化查询工具套件 是。

核心Use Case

根据目前的实施标准，核心用例有以下5种：

准确的章节查询
- 示例： 창1:1, 창 1:1-3, 롬8장, John 3:16
- 合适的工具： lookup_passage, expand_context
搜索主题/关键字正文
- 示例： 믿음, 창조, 하나님 나라, 태초
- 合适的工具： search_bible
搜索实体
- 示例： 아브라함, 예루살렘 위치, 출애굽 사건
- 合适的工具： search_entities, route_entity_query
关系查询
- 示例： 예수의 제자들, 다윗의 아버지, 야곱의 자녀
- 合适的工具： get_entity_relations, route_entity_query
实体代表语句查询
- 示例： 예루살렘 대표 구절, 출애굽 사건 관련 구절, 아브라함 등장 구절
- 合适的工具： get_entity_passages, route_entity_query

界限

当前实施的主要限制包括：

不是一般的交互式问答系统。
- 示例： 예수는 왜 십자가에 달렸나 对于同一个解释性问题，您的角色不是立即生成完整答案。
实体关系查询以direct relation为中心。
- 示例： 야곱의 손자, 다윗의 후손 전체 同样的multi-hop查询超出了当前范围。
search_entities直接调用时，默认范围为 people是。
- 地点/事件 entity_type=places|events明确表示比较安全。
韩语实体元数据仍然有限。
- 目前使用以英语为中心的元数据，建议在韩语查询失败时重新尝试前面的LLM中的英语。
summarize_passage, suggest_related_passages不是直接输入问题的工具。
- 它类似于一种后处理工具，可以将已获取的正文文本进行摘要或查找类似句子。
- 特别是，不能直接用于替代章节查询响应，只在显示正文全文后用户单独要求摘要时使用比较安全。

一目了然

准备好后，通常会出现以下文件。

data/source.sqlite 用户准备的圣经原始数据库
data/app.sqlite bible-mcp内部使用的应用程序DB
data/chunks.faiss 用于正文搜索的矢量索引
data/vendor/theographic/... 下载的圣经元数据快照

准备物

python 3.12 异常
终端可用环境
一个包含圣经正文的SQLite文件
互联网连接
- fetch-theographic 在步骤中，从GitHub下载元数据。
- 初 index 如果步骤中的嵌入模型不在本地，则可能会出现其他下载。

快速产品视图摘要

实际粘贴该项目时，通常可以理解为以下内容：

lookup_passage：查看准确的章节
search_bible：搜索正文
route_entity_query：以实体为中心的自然查询入口点
get_entity_relations：人际关系查询的低级工具
get_entity_passages：实体代表性语句查询的低级工具

建议的入口点大部分是 lookup_passage, search_bible, route_entity_query 三个。前面的应用程序可以收到此结果并配置韩语答案。

选择结构的原因

该项目不是“将所有东西都放在一个SQLite中的结构”，也不是“必须运行单独的矢量数据库的结构”。现在 SQLite+FTS5+失败 使用组合。

data/source.sqlite 用户拥有的原始圣经DB。
data/app.sqlite 包含正文区块、FTS索引目标数据和实体元数据的应用程序DB。
data/chunks.faiss 存储正文块嵌入的矢量索引。

选择此配置的原因如下：

简化了本地运行和部署。
- 无需PostgreSQL、Elasticsearch或单独的矢量数据库即可运行。
确保准确的单词搜索和语义搜索。
- 正确的关键词，章节附近的表达是SQLite FTS5抓好了。
- 即使表达不同，意义相似的主题查询也会嵌入+ FAISS进行补充。
易于数据检查和恢复。
- 应用程序DB sqlite3可以直接打开查看，矢量索引 chunks.faiss 通过文件分离，简化了再生。
明确角色分离。
- 原始DB是“圣经正文来源”
- 应用程序DB为“搜索/元数据的加工结果”
- FAISS是“用于语义搜索的索引”

也就是说，该项目与其说是“以矢量数据库为中心的产品”，不如说是“以矢量数据库为中心的产品”。 混合搜索服务器，在圣经搜索应用程序DB上同时添加FTS和矢量搜索接近。

简单的体系结构图

flowchart LR
    A["source.sqlite<br/>원본 성경 DB"] --> B["bible-mcp index"]
    C["Theographic snapshot<br/>people / places / events / verses"] --> D["bible-mcp sync-theographic"]
    D --> E["app.sqlite<br/>verses / passage_chunks / entity metadata"]
    B --> E
    B --> F["chunks.faiss<br/>passage chunk embeddings"]
    E --> G["bible-mcp serve"]
    F --> G
    G --> H["MCP tools<br/>lookup_passage / search_bible / route_entity_query"]
    H --> I["LLM / MCP client"]

从一行来看，加工原始圣经DB和元数据快照 app.sqlite哇 chunks.faiss创建， serve 在步骤中将两者一起阅读，以提供章节查询、混合正文搜索和实体查询的结构。

搜索方式

此项目中的搜索根据目的的不同而有不同的行为。

简单的搜索流程图

flowchart TD
    A["사용자 질문"] --> B{"질문 유형은?"}
    B -->|"정확한 장절/본문"| C["lookup_passage"]
    C --> D["필요하면 expand_context"]
    B -->|"주제/키워드 본문 검색"| E["search_bible"]
    E --> F["FTS5 + FAISS 하이브리드 결과"]
    B -->|"이미 확보한 본문과 유사 구절"| G["suggest_related_passages"]
    G --> H["FAISS 유사 청크 추천"]
    B -->|"인물/장소/사건 중심 질문"| I["route_entity_query"]
    I --> J["search_entities / get_entity_relations / get_entity_passages"]

实际上，首先要区分“是否是正确的引用”、“是否是主题搜索”、“是否是实体问题”。发送到相应工具的方式最稳定。

0、准确的章节查询

工具： lookup_passage, expand_context
用途：
- 用户 창 1:1, 롬 8장, John 3:16像这样给出了正确的参照。
特性：
- 比搜索更接近“精确查询”。
- 在这种情况下，返回正文全文优先于摘要。

1.搜索主题/关键词正文

工具： search_bible
用途：
- 믿음, 자녀 교육, 하나님 나라, 태초如所示查找主题或关键字。
动作：
- FTS5 查找关键字搜索候选项。
- 嵌入相同的查询 FAISS 还查找语义搜索候选项。
- 将两个结果合并，生成最终排名。

按照当前实施标准 search_bible不是纯矢量搜索 混合搜索是。分数现在 keyword 0.6 + semantic 0.4 以方式合计。

所以像下面这样理解就可以了。

查找包含正确单词的正文：
- FTS方面比较强。
即使表达方式不同，也要寻找类似的主题：
- 嵌入式+FAISS方面比较强。
最终结果：
- 混合两种方式，另一方弥补一方的弱点。

2.推荐类似文本

工具： suggest_related_passages
用途：
- 想找与已经找到的正文相似的其他句子时
动作：
- 嵌入输入文本后 FAISS在中查找类似区块。

与其说这个工具是直接提出问题的切入点， 基于已获取的正文扩展类似正文的后处理工具确实是这么看的。

3.人物/地点/事件搜索

工具： search_entities, route_entity_query
用途：
- 아브라함, 예루살렘, 출애굽 사건像这样以图元为中心的查询
动作：
- 基于元数据和alias查找实体，而不是嵌入正文搜索。

4.搜索关系/代表句

工具： get_entity_relations, get_entity_passages, route_entity_query
用途：
- 다윗의 아버지, 예수의 제자들, 예루살렘 대표 구절
动作：
- 使用实体关系表格和实体-语句链接。

更改译本时

如果将原始圣经DB替换为相同结构的其他译本，例如 개역개정从 한글개역如果换成， bible-mcp index确实要重新运行。

原因如下：

verses 表格正文将更改。
从那篇课文 passage_chunks.text将重新创建。
基于区块文本 FTS 索引和 FAISS 必须重新创建向量。

实际上，理解如下即可。

如果只更改了元数据 sync-theographic通常不需要重新进行。
如果改变了本文的翻译 index必须重新做。

注意：

目前的完整性检查主要检查是否与chunk ID匹配映射。
如果在保持相同章节范围的情况下改变本文， chunks.faiss在格式上仍然可以通过。
因此，在替换译本后，您可以使用现有的 app.sqlite, chunks.faiss不要完全信任 bible-mcp index重新运行比较安全。

1.安装

1-1.创建虚拟环境

在项目文件夹中运行以下命令：

python3 -m venv .venv

1-2.打开虚拟环境

macOS/Linux：

source .venv/bin/activate

虚拟环境打开后，通常在终端左侧 (.venv)显示。

1-3.安装项目

pip install -e '.[dev]'

安装完成后 bible-mcp 可以写命令。

2.准备圣经原始SQLite文件

bible-mcp读取用户拥有的SQLite圣经DB。基本上 verses 找到表格，必须有以下列。

book
chapter
verse
text

translation 专栏可有可无。

2-1.首要条件

book 根据目前的标准，专栏必须是英语圣经书的名称。例如：

Genesis
Exodus
Matthew
John

相反，如果是这样的值，则当前import可能会失败。

창세기
출애굽기
마태복음

2-2.文件位置示例

例如，将原始DB文件保留如下。

data/source.sqlite

2-3.检查我的SQLite文件结构

可以在终端上查看如下内容。

查看表格列表：

sqlite3 data/source.sqlite ".tables"

verses 查看表格结构：

sqlite3 data/source.sqlite "PRAGMA table_info(verses);"

正常情况下，结果至少应显示以下名称。

book
chapter
verse
text

查看示例数据：

sqlite3 data/source.sqlite "SELECT book, chapter, verse, text FROM verses LIMIT 5;"

2-4.表格名称为 `verses`如果不是

默认值为 verses是。如果源数据库中的表名称不同 BIBLE_SOURCE_TABLE 必须指定为环境变量。

示例：

export BIBLE_SOURCE_TABLE=my_verses

3.设置环境变量

至少 BIBLE_SOURCE_DB必须指定。

export BIBLE_SOURCE_DB=data/source.sqlite

如果需要，还可以更改以下值。

export BIBLE_APP_DB=data/app.sqlite
export BIBLE_FAISS_INDEX=data/chunks.faiss
export THEOGRAPHIC_VENDOR_DIR=data/vendor/theographic

大部分都可以按默认值写。

4.数据import完整顺序

第一次设置时，按照以下顺序进行即可。

bible-mcp fetch-theographic
bible-mcp sync-theographic
bible-mcp index

最后运行服务器。

bible-mcp serve

5.详细说明数据import

这一步是最重要的。特别是不熟悉电脑的话。 fetch, sync, index很容易混淆每个是什么角色。

5-1. `fetch-theographic`

bible-mcp fetch-theographic

该命令从GitHub下载圣经人物、地点和事件元数据。

根据首选项，请使用以下存储库：

GitHub存储库： robertrouse/theographic-bible-metadata
缺省分支/参照值： master

也就是说，默认情况下，这是将此存储库中的数据复制到本地的步骤。

实际上在下载什么？

fetch-theographic将整个存储库 git clone 不做。相反，只使用GitHub API和raw文件URL下载所需的JSON文件。

内部顺序如下：

首先，使用GitHub API master确认当前指向哪个提交。
然后，根据确认的提交哈希值，只下载所需的单独JSON文件。
将下载的文件保存到本地快照文件夹中。
最后从哪个提交收到了什么文件 manifest.json写入。

默认情况下，将下载以下4个文件。

people.json
places.json
events.json
verses.json

也就是说，“只选择下载所需的元数据文件”。

下载到哪个URL

根据代码，大致如下所示。

首先，使用GitHub API检查提交哈希。

https://api.github.com/repos/robertrouse/theographic-bible-metadata/commits/master

然后，使用收到的实际提交哈希作为响应导入raw文件。

例如 people.json从这种形式的地址接收。

https://raw.githubusercontent.com/robertrouse/theographic-bible-metadata/<커밋해시>/json/people.json

其他文件也是同样的方式。

.../json/places.json
.../json/events.json
.../json/verses.json

也就是说，不只是简单地获得“当前master”。 **首先固定master指向的实际提交，然后接收该提交的raw JSON文件。**是。

这样以后很容易跟踪“写的是什么时间点的数据”。

运行结果：

data/vendor/theographic/... 下面将出现快照文件夹。
还没有进入应用程序DB。
顾名思义，只是“下载”的状态。

更确切地说，按默认路径存储如下：

data/vendor/theographic/<실제커밋해시>/

例如，出现了这种结构。

data/vendor/theographic/<commit>/
├── manifest.json
└── raw/
    ├── people.json
    ├── places.json
    ├── events.json
    └── verses.json

`manifest.json`里面有什么

此文件是记录“这次下载是什么”的元文件。

这里通常包含以下信息。

从哪个GitHub存储库收到的
以什么样的ref为基准收到的
实际解释的提交哈希是什么
什么时候下载的
每个文件的大小和SHA-256散列
许可信息

也就是说，以后出现问题时：

收到了哪个版本的数据
文件是否中途更改
重新接收是否也是同一快照

可以查看。

许可证的标识是什么？

当前fetch步骤中记录的Theographic许可标记为以下值：

CC BY-SA 4.0

这个值也是。 manifest.json一起记录在中。

仅fetch还无法检索

这部分很重要。

fetch-theographic只下载。
还 app.sqlite不导入到。
还 search_entities不是直接在中使用的状态。

也就是说，以下步骤应该继续。

bible-mcp fetch-theographic
bible-mcp sync-theographic

sync-theographic只有这样，下载的JSON才会正规化并进入应用程序DB。

如果成功的话，通常会出现这种意思的信息。

Theographic snapshot fetched: ...

如果想使用其他存储库或分支

如果希望使用其他存储库或其他ref而不是默认值，可以将其替换为环境变量。

示例：

export THEOGRAPHIC_REPO=robertrouse/theographic-bible-metadata
export THEOGRAPHIC_REF=master

简单地说，原理是：

THEOGRAPHIC_REPO：从哪个GitHub存储库接收
THEOGRAPHIC_REF：根据哪个分支、标签和提交接收

表示。

5-2. `sync-theographic`

bible-mcp sync-theographic

此命令将刚才下载的元数据 bible-mcp整理成写的形式 app.sqlite放入。

运行前在内部检查：

BIBLE_SOURCE_DB 文件是否真实存在
是否存在源数据库所需的表和列
元数据指向的圣经句子是否真的存在于原始数据库中

运行结果：

data/app.sqlite将创建或更新。
包含人物、地点、事件、alias和句子连接信息。
可以跳过原始数据库中不存在的句子链接。

如果成功的话，通常会出现这样的信息。

Theographic sync complete: ...

如果中间出现类似如下的消息，则表示元数据中的某些句子链接与当前圣经DB不符，因此被跳过。

Skipped ... unresolved entity verse links during sync

5-3. `index`

bible-mcp index

此命令创建搜索实际正文所需的索引。

发生了什么：

原版 source.sqlite在读圣经正文。
app.sqlite的 verses 将正文移到表格中。
创建用于搜索的passage chunk。
创建FTS搜索索引。
用于矢量搜索 chunks.faiss 创建文件。

重要信息：

此命令 sync-theographic必须先结束。
如果元数据为空，则失败。
由于模型下载，首次运行可能需要更长的时间。

成功的话一般都会这样

Index build complete

5-4. `serve`

bible-mcp serve

此命令检查准备好的数据库和索引，然后运行MCP服务器。

运行前检查：

app.sqlite是否有
看看有没有需要的桌子。
chunks.faiss是否有
FAISS索引和DB chunk ID是否相互匹配

6.最简单的开始示例

在项目文件夹中按以下顺序运行即可。

python3 -m venv .venv
source .venv/bin/activate
pip install -e '.[dev]'
export BIBLE_SOURCE_DB=data/source.sqlite
bible-mcp fetch-theographic
bible-mcp sync-theographic
bible-mcp index
bible-mcp serve

7.经常堵车的情况

`Missing required environment variable: BIBLE_SOURCE_DB`

意思是没有指定原始圣经DB路径。

export BIBLE_SOURCE_DB=data/source.sqlite

`Source DB not found: ...`

文件路径无效或文件尚未存在。请重新检查路径。

`Source table not found: verses ...`

在源SQLite中 verses 意思是没有桌子。如果表格名称不同 BIBLE_SOURCE_TABLE必须一起指定。

示例：

export BIBLE_SOURCE_TABLE=my_verses

`Missing required source columns: ...`

在源数据库中 book, chapter, verse, text 意思是没有一部分。

请使用以下命令再次检查表格结构。

sqlite3 data/source.sqlite "PRAGMA table_info(verses);"

`Unknown book name: ...`

book 这意味着该值与import当前期望的英语书名不同。例如 창세기像这样，如果是韩文书的名字，可能会失败。

`No Theographic snapshot found. Run fetch-theographic first.`

必须先执行以下命令。

bible-mcp fetch-theographic

`Theographic metadata is missing or incomplete. Run bible-mcp sync-theographic before bible-mcp index.`

index更早 sync-theographic意思是要做。

顺序要像下面一样。

bible-mcp fetch-theographic
bible-mcp sync-theographic
bible-mcp index

8.整理主要命令

bible-mcp fetch-theographic 下载Theographic元数据快照。
bible-mcp sync-theographic 将下载的元数据与本地应用程序DB同步。
bible-mcp index 导入原始圣经正文并创建搜索索引。
bible-mcp serve 使用准备好的应用程序DB和索引运行MCP服务器。
bible-mcp doctor 确保原始数据库和运行时交付项正常，而不释放服务器。

9.实体搜索和韩语输入

目前，Bible MCP的前提是在MCP客户端处理实体重试，而不是在服务器内部。

例如，用户 요단강的元数据是英语 Jordan如果保存为，建议前面的LLM依次重试英语候选。

建议的提示策略如下：

route_entity_query首先调用用户的原文
结果 not_found仅在时生成英语候选
对同一工具依次重新调用英语候选项
如果出现成功、模糊或错误，请立即停止
对用户隐藏内部重试过程，只返回韩语答案

有关详细规则，请参阅以下文档。

docs/integrations/llm-entity-rewrite.md

10.章节回复和摘要规则

如果直接要求圣经句子或正文 lookup_passage 不要概括结果。 passage_text 建议原封不动地返回全文。