圣经MCP服务器
模型上下文协议（MCP）服务器，使用 mcp-weather 核心基础设施。
该服务器使AI助手能够访问各种翻译的圣经段落，并支持多种部署模式：
--mode stdio（默认）：通过stdin/stdout的MCP协议直接集成AI助手--mode mcp：基于HTTP的MCP协议，用于网络AI助手访问--mode rest：REST API和MCP协议通过HTTP实现最大灵活性
特性
圣经MCP服务器提供：
MCP工具（用于AI助手）
get_passage(passage, version)-检索圣经段落。支持用分号分隔的多个段落（例如，“约翰福音3:16；罗马书8:28”）。
REST API端点
GET /health-健康检查GET /info-服务信息POST /passage-获取圣经段落GET /docs-OpenAPI文档（Swagger UI）
支持的圣经版本
- ESV（英文标准版）
- NIV（新国际版）
- 英王钦定本
- 新美国标准圣经
- NKJV（新国王詹姆斯版）
- NLT（新生活翻译）
- AMP（放大圣经）
- MSG（信息）
安装
先决条件
- Python 3.10+
uv包管理器
安装uv
在Linux/macOS上：
curl -LsSf https://astral.sh/uv/install.sh | sh在Windows上：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"或者，您可以使用pip安装uv：
pip install uv安装后，重新启动终端或运行 source ~/.bashrc （Linux/macOS）或重新启动命令提示符（Windows）。
步骤1：安装依赖项
# From this directory
cd mcp-bible
# Install dependencies
uv sync步骤2：配置环境
# Copy example configuration
cp .env.example .env
# Edit .env with your settings
vi .env用法
Bible MCP服务器通过命令行参数支持三种部署模式：
模式1:stdio（默认）-直接AI助手集成
# Default mode - MCP over stdin/stdout
uv run mcp-bible
# Explicitly specify stdio mode
uv run mcp-bible --mode stdio非常适合与GitHub Copilot、Claude Desktop等人工智能助手直接集成。
模式2:mcp-基于HTTP的mcp协议
# MCP-only server on HTTP (no REST API)
uv run mcp-bible --mode mcp --port 3000 --no-auth在HTTP上提供MCP协议 http://localhost:3000/mcp 用于网络AI助手访问。
模式3：休息-全HTTP服务器（rest+MCP）
# Full server with both REST API and MCP protocol
uv run mcp-bible --mode rest --port 3000 --no-auth服务器将在以下时间启动 http://localhost:3000 与：
- MCP端点：
http://localhost:3000/mcp - REST API：
http://localhost:3000/* - API文件：
http://localhost:3000/docs - 健康检查：
http://localhost:3000/health
测试MCP工具
您可以通过连接GitHub Copilot或使用测试客户端来测试MCP工具：
// .vscode/mcp.json
{
"servers": {
"bible": {
"type": "http",
"url": "http://localhost:3000/mcp"
}
}
}然后问Copilot：
- 《约翰福音》3:16
- “罗马书8章怎么说？”
- “阅读NIV中的诗篇23”
测试REST API
# Health check
curl http://localhost:3000/health
# Get service info
curl http://localhost:3000/info
# Get a Bible passage
curl -X POST "http://localhost:3000/passage" \
-H "Content-Type: application/json" \
-d '{
"passage": "John 3:16",
"version": "ESV"
}'
# Get multiple passages
curl -X POST "http://localhost:3000/passage" \
-H "Content-Type: application/json" \
-d '{
"passage": "John 3:16; Romans 8:28; Philippians 4:13",
"version": "NIV"
}'
# Get an entire chapter
curl -X POST "http://localhost:3000/passage" \
-H "Content-Type: application/json" \
-d '{
"passage": "Mark 2",
"version": "ESV"
}'CLI帮助和选项
# See all available options
uv run mcp-bible --help
# Usage examples:
uv run mcp-bible # stdio mode (default)
uv run mcp-bible --mode stdio # stdio mode
uv run mcp-bible --mode mcp --port 4000 # MCP-only HTTP on port 4000
uv run mcp-bible --mode rest --port 4000 # REST+MCP HTTP on port 4000
uv run mcp-bible --mode rest --no-auth # Disable authentication环境变量（CLI的替代方案）
您还可以使用环境变量配置服务器：
# Alternative: Set environment variables
export MCP_TRANSPORT=http # stdio or http
export MCP_ONLY=false # true for MCP-only, false for REST+MCP
export MCP_HOST=0.0.0.0 # Host to bind to
export MCP_PORT=3000 # Port number
export AUTH_ENABLED=false # Enable/disable authentication
# Then run without arguments
uv run mcp-bible测试所有模式
运行综合测试套件：
uv run tests/test_modes.py或者尝试交互式curl示例：
./examples/curl_examples.sh项目结构
mcp_bible/
├── __init__.py # Package metadata
├── config.py # Configuration management (extends mcp-weather core)
├── bible_service.py # Business logic (Bible API client)
├── service.py # MCP service wrapper (with automatic feature discovery)
├── server.py # Server implementation (CLI mode support)
├── features/ # Feature modules (MODULAR PATTERN)
│ ├── __init__.py
│ └── get_passage/ # Get passage feature
│ ├── __init__.py
│ ├── instructions.md # 📝 Comprehensive documentation (core.utils)
│ ├── models.py # Feature-specific models
│ ├── tool.py # MCP tool definition (uses @inject_docstring)
│ └── routes.py # REST API endpoints (uses load_instruction)
├── shared/ # Shared models and utilities
│ ├── __init__.py
│ └── models.py # Base models, error types
├── tests/ # Test suite
│ └── test_modes.py # Mode support testing
└── examples/ # Usage examples
└── curl_examples.sh # Interactive REST API examplesCore.utils集成
该项目使用 core.utils模式 来自mcp天气动态文档：
instructions.md：markdown中的全面功能文档@inject_docstring：将markdown动态注入MCP工具文档字符串load_instruction：加载REST API文档的降价- 单一事实来源：MCP工具和REST端点的文档相同
运作原理
特征模式（自动发现）
此服务器使用 自动特征发现 -就像 mcp-weather!
通过4个步骤添加新功能：
- 创建功能目录:
features/my_feature/ - 添加说明.md：全面的降价文档
- 添加tool.py：与
register_tool(mcp, service)功能使用@inject_docstring - 添加路由.py （可选）：带
create_router(service)功能使用load_instruction
特征结构示例：
# features/my_feature/tool.py
from core.utils import inject_docstring, load_instruction
@mcp.tool()
@inject_docstring(lambda: load_instruction("instructions.md", __file__))
async def my_tool(param: str) -> dict:
"""Documentation loaded from instructions.md"""
return {"result": param}
# features/my_feature/routes.py
from core.utils import load_instruction
@router.post("/endpoint", description=load_instruction("instructions.md", __file__))
async def endpoint():
"""Same documentation for REST API"""
return {"data": "value"}就是这样！ 服务自动：
- 发现您的功能
- 从注册MCP工具
tool.py - 包括来自的REST路由
routes.py - 从以下位置加载文档
instructions.md
无需手动注册！
1.配置层（config.py）
使用特定于服务的设置扩展核心配置类：
from core.config import BaseServerConfig
class BibleAPIConfig(BaseModel):
base_url: str
supported_versions: List[str]
class AppConfig(BaseModel):
server: ServerConfig
bible_api: BibleAPIConfig2.业务逻辑层（bible_service.py）
纯业务逻辑，独立于MCP/REST：
class BibleService:
async def fetch_passage(self, passage: str, version: str) -> dict:
# Bible passage retrieval logic here
...3.MCP服务包装器（Service.py）
实现 BaseService 通过MCP公开业务逻辑：
from core.server import BaseService
class BibleMCPService(BaseService):
def register_mcp_tools(self, mcp: FastMCP) -> None:
# Automatic feature discovery and registration4.服务器实现（Server.py）
扩展 BaseMCPServer 要创建完整的服务器，请执行以下操作：
from core.server import BaseMCPServer
class BibleMCPServer(BaseMCPServer):
@property
def service_title(self) -> str:
return "Bible MCP Server"
def create_router(self) -> APIRouter:
# Add REST endpoints
...使用mcp天气核心的主要好处
通过使用 mcp-weather 作为依赖项，您可以获得：
✅ 无样板 -服务器基础架构已准备好使用\ ✅ 多种部署模式 -stdio、仅MCP HTTP、REST+MCP HTTP通过CLI\ ✅ 动态文档 -通过core.utils实现基于Markdown的文档\ ✅ 双接口 -MCP+REST API自动\ ✅ 配置 -环境变量管理\ ✅ 错误处理 -全面的异常处理\ ✅ 类型安全性 -完整的Pydantic模型和类型提示\ ✅ 异步支持 -异步第一设计贯穿始终\ ✅ 日志记录 -内置结构化日志记录\ ✅ 跨域资源共享 -可配置的CORS支持\ ✅ 健康检查 -标准端点\ ✅ 测试 -包括全面的测试套件
定制
添加新的MCP工具
编辑 mcp_bible/service.py:
def register_mcp_tools(self, mcp: FastMCP) -> None:
@mcp.tool()
async def my_new_tool(param: str) -> dict:
"""Tool description for AI"""
return {"result": "value"}添加新的REST端点
编辑 mcp_bible/server.py:
def create_router(self) -> APIRouter:
router = APIRouter()
@router.get("/my-endpoint")
async def my_endpoint():
return {"data": "value"}
return router添加新配置
编辑 mcp_bible/config.py:
class BibleAPIConfig(BaseModel):
my_new_field: str = Field(default="value")故障排除
导入错误
确保您从以下位置导入 core，不 mcp_weather.core:
from core.server import BaseMCPServer # ✅ Correct
from mcp_weather.core.server import BaseMCPServer # ❌ Wrong未找到模块
确保安装了mcp-weather：
uv pip list | grep mcp-weather如果未安装，请安装：
uv sync # Installs from pyproject.toml已实现的功能✅
✅ 多种部署模式 （stdio、mcp、rest）\ ✅ CLI接口 在全面的帮助下\ ✅ 动态文档 使用core.utils\ ✅ 圣经段落检索 来自BibleGateway.com\ ✅ 8圣经译本 支持\ ✅ 多通道支撑 （以分号分隔）\ ✅ 全面的测试套件 带模式测试\ ✅ REST API示例 和curl脚本\ ✅ 自动发现 特征\ ✅ 结构化日志记录 遍及
后续步骤
- 添加身份验证提供程序（Authentik集成）
- 添加更多圣经API来源（圣经API，ESV API）
- 实施文章搜索和索引
- 添加每日经文和阅读计划
- 添加Redis缓存以提高性能
- 添加指标和监控
- 添加Docker部署示例
了解更多
许可证
本项目按原样提供，供使用和修改。