内容
# 圣经-MCP
只读 [MCP](https://modelcontextprotocol.io) 服务器，使用 Go 编写，通过 Model Context Protocol 提供葡萄牙语圣经文本（**ARA**、**ARC** 和 **NVI** 版本）作为 AI 代理的工具 - 搜索单个经文、一段经文或一整章。
## 概要
- [关于](#关于)
- [MCP 工具](#mcp-工具)
- [架构](#架构)
- [需求](#需求)
- [安装](#安装)
- [配置](#配置)
- [使用](#使用)
- [开发](#开发)
- [项目结构](#项目结构)
- [领域和架构决策](#领域和架构决策)
- [路线图](#路线图)
## 关于
`bible-mcp` 通过 Model Context Protocol 将 LLM 连接到葡萄牙语圣经的三个版本 - Almeida Revista e Atualizada (ARA)、Almeida Revista e Corrigida (ARC) 和 Nova Versão Internacional (NVI)。服务器：
- 通过固定的葡萄牙语**规范名称**解析书籍（66 个值的枚举），独立于每个版本内部的书写方式（参见 [ADR-0001](docs/adr/0001-canonical-book-identity.md)）。
- 在**运行时**发现可用版本，扫描可配置的数据目录 - 没有 `.sqlite` 文件嵌入二进制文件（参见 [ADR-0002](docs/adr/0002-external-data-directory.md)）。
- 永远不会在工具响应中包含版权元数据或除请求经文/段落/章节以外的任何文本。
- 如果发现的任何版本与 66 本书的正典不完全匹配，则在初始化时快速失败 - 永远不会部分/降级启动。
## MCP 工具
| 工具 | 描述 | 必需参数 | 可选参数 |
| --- | --- | --- | --- |
| `get_verse` | 返回单个经文。 | `book`、`chapter`、`verse` | `version` |
| `get_passage` | 返回同一章内的经文区间。 | `book`、`chapter`、`verse_start`、`verse_end` | `version` |
| `get_chapter` | 返回章的所有经文。 | `book`、`chapter` | `version` |
- `book`：具有 66 个规范名称的固定枚举（例如 `"Gênesis"`、`"1Coríntios"`）。
- `version`：动态枚举，从 `BIBLE_MCP_DATA_DIR` 中发现的版本构建。如果省略，则使用 `"Almeida Revista e Corrigida"`。
所有成功响应均以“引用”格式返回：每行一个经文（编号），后跟一行归属。
```
$ get_verse(book="João", chapter=3, verse=16)
16 因为上帝爱世界，甚至将他的独生子赐给他们，叫一切信他的，不至灭亡，反得永生。
- 约翰福音 3:16
```
任何无效引用（枚举外的书籍、`verse_start > verse_end`、版本中不存在的章节/经文）都会返回 MCP 工具错误 - 永远不会返回空成功响应。
## 架构
```
main.go → 读取 BIBLE_MCP_DATA_DIR，打开 Store，注册工具，运行 stdio
internal/mcpserver/ → 协议层：输入模式、处理程序、注册
internal/bible/ → 领域层：正典、存储（发现/验证）、经文、格式引用
<版本>.sqlite → 数据层：通过 database/sql + modernc.org/sqlite 进行只读访问
```
没有输入字符串被拼接成 SQL（所有参数都经过 `?`）；所有连接都在 `mode=ro` 下打开。完整的设计决策在 [领域和架构决策](#领域和架构决策) 中。
## 需求
- Go 1.25 或更高版本。
- 一个或多个遵循 [CLAUDE.md](CLAUDE.md#数据-模式-sqlite-数据库) 中描述的 `metadata`/`book`/`verse` 模式的 `.sqlite` 文件 - 仓库中已包含 `data/ARA.sqlite`、`data/ARC.sqlite` 和 `data/NVI.sqlite`。
## 安装
```bash
git clone git@github.com:RogerioLimas/bible-mcp.git
cd bible-mcp
go build -o bible-mcp .
```
## 配置
服务器通过单个环境变量进行配置：
| 变量 | 必需 | 描述 |
| --- | --- | --- |
| `BIBLE_MCP_DATA_DIR` | 是 | 包含要公开的版本 `.sqlite` 文件的目录。 |
每个版本的标识符（`version` 参数接受的值）来自文件本身的 `metadata.name` 字段，而不是文件名。在初始化时，会根据 66 本书的正典验证每个发现的文件；如果变量为空，目录中没有有效的 `.sqlite`，或者任何文件验证失败（或两个版本具有相同的 `metadata.name`），进程会立即以错误终止 - 没有部分初始化模式。
## 使用
直接运行二进制文件，使用仓库中已包含的数据：
```bash
BIBLE_MCP_DATA_DIR=./data ./bible-mcp
```
服务器通过 stdio 与 Model Context Protocol 协议通信 - 对于交互式使用，请在 MCP 客户端中注册它（例如 Claude Desktop、`claude mcp add` 或任何兼容的客户端）。配置示例：
```json
{
"mcpServers": {
"bible": {
"command": "/绝对路径/到/bible-mcp",
"env": {
"BIBLE_MCP_DATA_DIR": "/绝对路径/到/bible-mcp/data"
}
}
}
}
```
## 开发
```bash
go test ./...
```
项目约定（命名、错误处理、验证）：领域函数返回 `error` 作为最后一个值（输入无效时永远不会 `panic`）；MCP 工具处理程序永远不会将领域错误转换为成功 - 始终 `(nil, nil, err)`，SDK 将其转换为 `CallToolResult{IsError: true}`。完整规范见 [spdd/prompt/GGQPA-XXX-202607162106-\[Feat\]-mcp-verse-passage-chapter-tools.md](spdd/prompt/GGQPA-XXX-202607162106-%5BFeat%5D-mcp-verse-passage-chapter-tools.md)。
## 项目结构
```
.
├── main.go # 二进制文件：引导和 stdio 传输
├── internal/
│ ├── bible/ # 领域：正典、存储、查询、格式化
│ │ ├── canon.go
│ │ ├── store.go
│ │ ├── query.go
│ │ └── format.go
│ └── mcpserver/ # 协议：模式、处理程序、注册
│ ├── schema.go
│ ├── tools.go
│ └── server.go
├── data/ # 默认 .sqlite 版本（ARA/ARC/NVI）
├── docs/
│ ├── adr/ # 架构决策记录
│ └── BACKLOG.md # 未来版本延迟的功能
├── spdd/ # 结构化规范（REASONS Canvas）
└── CONTEXT.md # 领域通用语言
```
## 领域和架构决策
- [`CONTEXT.md`](CONTEXT.md) - 通用语言（书、规范名称、章节、经文、段落、版本）。
- [`docs/adr/0001-canonical-book-identity.md`](docs/adr/0001-canonical-book-identity.md) - 为什么书的身份是一个固定的规范枚举，而不是每个版本的 `book.name`。
- [`docs/adr/0002-external-data-directory.md`](docs/adr/0002-external-data-directory.md) - 为什么版本是运行时发现的外部目录，具有快速验证失败。
## 路线图
故意延迟到未来版本的项目（参见 [`docs/BACKLOG.md`](docs/BACKLOG.md)）：
- 文本搜索（FTS5）- 按内容查找经文，而不仅仅是按引用。
- 可配置的响应格式 - 今天固定为“引用”；未来版本应允许替代格式（例如结构化 JSON）。
