JW。组织MCP工具
     
一个模型上下文协议（MCP）服务器，为AI应用程序和LLM集成提供对jw.org内容的受控、可验证的访问。
概述
JW。Org MCP Tool确保圣经和教义信息仅来自jw.Org官方来源，消除了处理宗教问题时产生幻觉或外部污染的风险。该工具充当人工智能应用程序和jw.org内容之间的可信中介。
特性
- 可信来源强制：严格从jw.org域获取数据
- 综合搜索：在文章、视频、出版物、音频和经文中搜索
- 智能查询解析：从自然语言查询中提取有意义的搜索词
- 全文检索：获取包含经文参考的完整文章内容
- 经文查询：直接圣经参考搜索
- 性能优化：15分钟缓存、Brotli压缩、异步操作
- 结构化输出：带有验证元数据的机器可读响应
安装
需求
- Python 3.13+
- 紫外线 用于包管理
使用uv进行安装
# Clone the repository
git clone https://github.com/Bjern/jw-org-mcp.git
cd jw-org-mcp
# Install dependencies
uv sync
# Install with development dependencies
uv sync --group dev用法
运行MCP服务器
uv run jw-org-mcp服务器在stdio模式下运行，并通过模型上下文协议进行通信。
添加到Claude桌面
要将此MCP服务器与Claude Desktop一起使用，请将其添加到您的Claude配置文件中：
地点：
- macOS：
~/Library/Application Support/Claude/claude_desktop_config.json - 窗户：
%APPDATA%\Claude\claude_desktop_config.json
配置：
{
"mcpServers": {
"jw-org": {
"command": "uv",
"args": [
"--directory",
"E:\\Projects\\Python\\jw-org-mcp",
"run",
"jw-org-mcp"
]
}
}
}注： 替换 E:\\Projects\\Python\\jw-org-mcp 带有项目目录的实际路径。在Windows上，使用双反斜杠(\\)在路上。
WINDOWS->2026年2月->如果您将其用作自定义连接器MCP工具，那么您可能会发现WINDOWS上的Claude Desktop应用程序工作不正常。应用程序无法启动等。。。 这是因为，存在一个错误，即新应用程序（自2026年2月以来）已将其默认文件夹更改为MSIX虚拟化路径： C： \\用户｛用户名｝\\AppData\\Local\\Packages\\Claude_pzs8sxrjxfjjc\\LocalCache\\Roaming\\Claude\\Claude_desktop_config.json 或者在windows的“运行”对话框中粘贴%localappdata%\\Packages\\Claude_pzs8sxrjxfjjc\\LocalCache\\Roaming\\Claude。
保存配置后：
- 重新启动克劳德桌面
- JW。组织MCP工具将在您的对话中可用
- 寻找以下工具
search_content,get_article，以及get_scripture
配置
配置是通过带有前缀的环境变量完成的 JWORG_MCP_:
# Cache settings
export JWORG_MCP_CACHE_TTL_SECONDS=900 # 15 minutes (default)
export JWORG_MCP_ENABLE_CACHE=true
# Request settings
export JWORG_MCP_REQUEST_TIMEOUT=30
export JWORG_MCP_MAX_RETRIES=3
# Search settings
export JWORG_MCP_DEFAULT_LANGUAGE=E # English
export JWORG_MCP_DEFAULT_SEARCH_LIMIT=10
# Logging
export JWORG_MCP_LOG_LEVEL=INFOMCP工具
搜索内容
搜索JW。跨多种类型组织内容。
参数：
query（必填）：搜索查询-可以是自然语言filter（可选）：内容类型-all,publications,videos,audio,bible,indexes（默认值：all)language（可选）：语言代码-E对于英语，S西班牙语等。（默认值：E)limit（可选）：最大结果（默认值：10）
例子：
{
"query": "What does the Bible say about love?",
"filter": "all",
"limit": 5
}查询解析器自动提取“love”作为搜索词。
获取_文章
从jw.org URL检索完整的文章内容。支持直接文章URL和发布查找器URL。
当给定一个发布级别的URL（例如，一期杂志）时，该工具会返回一个目录，其中列出了单个文章及其直接URL，然后可以单独获取。
参数：
url（必填）：来自wol.jw.org的文章URL或出版物查找器URL
例子：
{
"url": "https://wol.jw.org/en/wol/d/r1/lp-e/1985720"
}get_scripture
通过引用获取经文。
参数：
reference（必填）：圣经参考（例如，“约翰福音3:16”，“帖撒罗尼迦前书5:3”）translation（可选）：圣经翻译代码（默认：“nwtsty”）
例子：
{
"reference": "John 3:16"
}get_ache_stats
获取缓存统计信息，包括命中率和条目计数。
参数： 无
发展
设置开发环境
# Install with development dependencies
uv sync --group dev
# Install pre-commit hooks (optional)
uv run pre-commit install运行测试
# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=jw_org_mcp --cov-report=html
# Run specific test file
uv run pytest tests/test_parser.py代码质量
# Run linter
uv run ruff check .
# Format code
uv run ruff format .
# Type checking
uv run mypy src/
# Security scan
uv run bandit -r src/ -c pyproject.toml项目结构
jw-org-mcp/
├── .github/
│ └── workflows/
│ └── tests.yml # CI pipeline (lint, type check, security, tests)
├── src/
│ └── jw_org_mcp/
│ ├── __init__.py # Entry point
│ ├── auth.py # Authentication & CDN discovery
│ ├── cache.py # Caching layer
│ ├── client.py # JW.Org API client
│ ├── config.py # Configuration management
│ ├── exceptions.py # Custom exceptions
│ ├── models.py # Data models
│ ├── parser.py # Content parsers
│ └── server.py # MCP server implementation
├── tests/ # Test suite
├── docs/ # Documentation
├── pyproject.toml # Project configuration
└── README.md建筑
认证流程
- 从jw.org主页发现CDN URL
- 从CDN端点请求JWT令牌
- 对经过身份验证的API请求使用令牌
- 过期前自动刷新令牌
搜索流程
- 解析用户查询以提取搜索词
- 检查缓存中的现有结果
- 如果缓存未命中，则发出经过身份验证的API请求
- 解析和结构响应
- 缓存结果15分钟
- 返回结构化数据
内容检索
- 从wol.jw.org获取HTML内容
- 如果页面是出版物索引（目录），则提取文章链接并返回它们
- 否则，解析文章结构（标题、段落、参考文献）
- 提取没有HTML伪影的干净文本
- 缓存已解析的内容
- 返回结构化文章数据
API响应格式
所有回复均包含用于验证的元数据：
{
"data": {
// Response-specific data
},
"metadata": {
"source_domain": "jw.org",
"source_url": "https://...",
"timestamp": "2024-01-01T00:00:00Z",
"query_params": {},
"cache_hit": false
}
}演出
- 响应时间：搜索查询时间\<2秒（缓存时间：\<100ms）
- 缓存TTL：15分钟（可配置）
- 压缩：所有API请求的Brotli
- 并发：带连接池的异步I/O
错误处理
该工具为特定异常类型提供了优雅的错误处理：
AuthenticationError：JWT令牌问题CDNDiscoveryError：CDN发现失败SearchError：搜索操作失败ContentRetrievalError：内容获取失败ParseError：内容解析失败
所有错误都会被记录并返回描述性消息。
安全与隐私
- 无PII记录：未记录任何个人身份信息
- 仅限HTTPS：所有外部请求都使用HTTPS
- 令牌安全：JWT令牌在内存中安全管理
- 输入验证：所有用户输入都经过消毒
贡献
- 分叉存储库
- 创建要素分支
- 通过测试进行更改
- 确保所有测试均已通过，且代码已格式化
- 提交拉取请求
许可证
该项目根据 GNU通用公共许可证v3.0.
支持
对于问题和疑问：
- GitHub问题：https://github.com/Bjern/jw-org-mcp/issues
- 文件：见
docs/文件夹
致谢
- 内置于 FastMCP
- 使用模型上下文协议标准
- 提供对jw.org内容的验证访问权限