AI导哈

JW.Org内容访问工具

一个提供对jw.org官方内容的可控访问的工具，确保AI应用和LLM集成获取的宗教信息准确无误。

  • by Bjern
  • Python
  • 本地部署
  • 16 星标
  • 更新于
在 GitHub 查看 Bjern/jw-org-mcp

使用说明

JW。组织MCP工具

一个模型上下文协议（MCP）服务器，为AI应用程序和LLM集成提供对jw.org内容的受控、可验证的访问。

概述

JW。Org MCP Tool确保圣经和教义信息仅来自jw.Org官方来源，消除了处理宗教问题时产生幻觉或外部污染的风险。该工具充当人工智能应用程序和jw.org内容之间的可信中介。

特性

  • 可信来源强制：严格从jw.org域获取数据
  • 综合搜索：在文章、视频、出版物、音频和经文中搜索
  • 智能查询解析：从自然语言查询中提取有意义的搜索词
  • 全文检索：获取包含经文参考的完整文章内容
  • 经文查询：直接圣经参考搜索
  • 性能优化：15分钟缓存、Brotli压缩、异步操作
  • 结构化输出：带有验证元数据的机器可读响应

安装

需求

使用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。

保存配置后：

  1. 重新启动克劳德桌面
  2. JW。组织MCP工具将在您的对话中可用
  3. 寻找以下工具 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=INFO

MCP工具

搜索内容

搜索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

建筑

认证流程

  1. 从jw.org主页发现CDN URL
  2. 从CDN端点请求JWT令牌
  3. 对经过身份验证的API请求使用令牌
  4. 过期前自动刷新令牌

搜索流程

  1. 解析用户查询以提取搜索词
  2. 检查缓存中的现有结果
  3. 如果缓存未命中，则发出经过身份验证的API请求
  4. 解析和结构响应
  5. 缓存结果15分钟
  6. 返回结构化数据

内容检索

  1. 从wol.jw.org获取HTML内容
  2. 如果页面是出版物索引（目录），则提取文章链接并返回它们
  3. 否则，解析文章结构（标题、段落、参考文献）
  4. 提取没有HTML伪影的干净文本
  5. 缓存已解析的内容
  6. 返回结构化文章数据

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令牌在内存中安全管理
  • 输入验证：所有用户输入都经过消毒

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 通过测试进行更改
  4. 确保所有测试均已通过，且代码已格式化
  5. 提交拉取请求

许可证

该项目根据 GNU通用公共许可证v3.0.

支持

对于问题和疑问：

  • GitHub问题：https://github.com/Bjern/jw-org-mcp/issues
  • 文件：见 docs/ 文件夹

致谢

  • 内置于 FastMCP
  • 使用模型上下文协议标准
  • 提供对jw.org内容的验证访问权限

相关 MCP