Tripitaka MCP

Tripitaka MCP 服务

用于搜索和引用巴利三藏内容的 MCP 服务。 它让 Claude 或 Cursor 等 AI 客户端能够查找经文、引用教法，并比较不同语言的译本。

🙏 本项目作为法施免费提供： 100% 免费，仅限非商业用途。 许可证详情：LICENSE（代码）和 NOTICE.md（数据）

✨ 功能

• 完整覆盖三藏，达到与 SuttaCentral 相同的覆盖范围。 已索引三藏的所有三部分，约 444K 个片段。经藏包含巴利文及 bilara-data 提供的英文译文（DN/MN/SN/AN 和大部分小部由 Bhikkhu Sujato 翻译，少数小部书籍由 John Kelly、Bhikkhu Kovilo 等人翻译）。律藏包含巴利文及 Bhikkhu Brahmali 的英文译文。论藏仅有巴利文，因为上游 bilara-data 未提供任何论藏书籍的英文译文。list_structure 会报告实时数量。
• 混合搜索通过倒数排名融合（RRF）合并关键词和语义搜索结果。它是最精准的搜索工具，无需配置。
• 关键词搜索支持三元组模糊匹配和跨语言对齐。
• 语义搜索按含义搜索，使用向量相似度（pgvector）。
• 译文比较可逐段对齐比较不同版本。
• 词典桥接提供 20,000 多条词条（P. A. Payutto、PTS、DPPN）。
• 获取经文并生成引文。 可通过 ID 获取经文（mn1、pli-tv-bu-vb-pj1、patthana1.1），并生成格式规范的学术引文。
• 巴利语词语分析器会剥除屈折后缀，在词典查询无结果时查找词根形式（bhikkhūnaṁ → bhikkhu）。
• 每个响应都包含交叉引用 URL： 可点击的深层链接，指向项目自带的双语阅读器（巴利文 + 英文），并带有可高亮所引偈颂的片段锚点。阅读器会原样呈现 SuttaCentral 的 bilara-data，因此是权威文本；AI 客户端会显示链接，方便用户一键核验来源。
• 双传输方式： 旧版 SSE（/sse）和标准的 Streamable HTTP（/mcp，MCP 规范 2025-03-26）。
• MCP 资源： tripitaka://structure、tripitaka://sutta/{id}、tripitaka://word/{w}，适用于将上下文固定为资源的客户端。
• 精选参考页面位于 /topics/*：六个 Markdown 页面涵盖经典结构、入门指南和工具选择、地点（Mahājanapada、圣地、宇宙观）、10 个带有典型出处的基础主题、约 30 位重要人物，以及佛陀 45 年弘法历程的分阶段时间线。经文 ID 均已根据实时数据核验，AI 客户端可获取单个页面，而不必调用工具 30 多次。
• Claude 技能。 skills/tipitaka-research.md 是可直接安装的工作流文件，可在 Claude Desktop 和 Claude Code 中启用多步骤研究模式（澄清 → 核验覆盖范围 → 搜索 → 深入研究 → 引用）。
• 附带 Postman 集合用于测试 API。

🏗️ 技术栈

技术	作用
Python + FastMCP	MCP 服务
PostgreSQL + pgvector	数据库 + 向量搜索
sentence-transformers	用于语义搜索的嵌入
Docker Compose	基础设施

🚀 快速开始

🌐 无需设置：连接到公开的 Dhamma Dāna 服务

维护者在 tripitaka-mcp.com 运行着一个免费公共实例。

端点	用途
https://mcp.tripitaka-mcp.com/mcp	可流式传输的 HTTP（MCP 规范 2025-03-26）
https://mcp.tripitaka-mcp.com/sse	旧版 SSE（适用于较早的客户端）

连接 Claude Desktop 只需三步。除了 Node.js 外，无需安装任何东西，也不需要 Docker 或 GPU。

1. 找到 npx 的绝对路径。Claude Desktop 不会读取你的 shell 配置文件，因此单独使用 npx 无法解析。打开终端：

which npx
# example: /Users/you/.nvm/versions/node/v22.14.0/bin/npx

2. 打开 claude_desktop_config.json（macOS 上位于 ~/Library/Application Support/Claude/，Windows 上位于 %APPDATA%\Claude\），并添加以下条目。将 YOUR_NPX_PATH 替换为第 1 步的输出，并将 YOUR_NODE_BIN_DIR 替换为该路径的父目录：

{
  "mcpServers": {
    "tripitaka": {
      "command": "YOUR_NPX_PATH",
      "args": ["-y", "mcp-remote", "https://mcp.tripitaka-mcp.com/mcp"],
      "env": { "PATH": "YOUR_NODE_BIN_DIR:/usr/local/bin:/usr/bin:/bin" }
    }
  }
}

3. 完全退出 Claude Desktop（macOS 上按 ⌘Q，Windows 上选择托盘图标 → 退出），然后重新打开。左下角的 🔌 指示器应显示 tripitaka，并提供 14 个工具。

首次连接需要 5 到 10 秒，因为 npx 会按需下载 mcp-remote。重启后请稍等片刻，再判断连接是否失败。

连接后，可以试着向 Claude 提问：

• “佛陀对入出息念有何教导？请引用 MN 118 中的相关段落。”
• “请展示《应作慈爱经》的巴利语和英语全文。”
• “根据 Payutto 词典，巴利语词汇 sati 是什么意思？”
• “找出佛陀讨论愤怒的经文。”

Claude 会选择合适的工具，获取标准巴利语文本，并提供指向项目双语阅读器的可点击链接，供你核实。

托管服务是一项免费的轻量服务，供个人学习、研究和修习佛法使用。请合理控制请求频率；突发请求可能会在边缘节点受到限流。重新分发或用于商业用途前，请阅读 NOTICE.md。

💻 完全离线运行（pipx、本地 SQLite，无需服务器）

如果你更愿意将所有内容保留在自己的机器上，不向托管服务器发起网络请求，可以安装本地版本。它将整部巴利语大藏经存储在一个 SQLite 文件中（约 120 MB），并作为本地 stdio MCP 服务运行。

pipx install tripitaka-mcp     # needs Python 3.10+
tripitaka-mcp init             # one-time: downloads the SQLite database
tripitaka-mcp serve            # runs the MCP server over stdio

如果安装失败并出现以下情况：

Because the current Python version (3.9.6) does not satisfy Python>=3.10

pipx 使用的解释器和你以为的不一样。它会有意创建自己的隔离环境，并忽略当前激活的任何 venv，因此即使你输入命令的 shell 使用的是 3.12，它也可能选中旧版系统 Python。告诉它要使用哪个版本：

pipx install --python python3.12 tripitaka-mcp

（任何 3.10 或更新版本都可以；pipx environment 会显示它默认使用的版本。）

然后将 Claude Desktop 或 Cursor 指向本地命令，无需 npx 桥接，也无需联网：

{
  "mcpServers": {
    "tripitaka": {
      "command": "tripitaka-mcp",
      "args": ["serve"]
    }
  }
}

（如果客户端的 PATH 中没有 tripitaka-mcp，请使用 which tripitaka-mcp 输出的绝对路径。）

需要 URL 而不是 stdio？ 脚本、笔记本以及任何需要多个客户端共用一个服务的场景，都需要 HTTP 端点，而不是子进程：

tripitaka-mcp serve --http                 # http://127.0.0.1:8765/mcp
tripitaka-mcp serve --http --port 9000     # or MCP_HOST / MCP_PORT

除非另行指定，否则它会绑定到 127.0.0.1；大藏经数据为只读，但这里不会验证调用者身份，因此绑定到公共接口前请三思。

托管版与本地版

两者提供相同的约 44.4 万段大藏经文本。区别如下：

	托管版（mcp.tripitaka-mcp.com）	本地版（pipx）
工具	全部 14 个	11 个；设置 TRIPITAKA_MCP_APP=1 时为 12 个；不含 search_semantic 或 search_hybrid
概念／语义搜索	✅ 向量搜索（pgvector）	❌ 请改用 search_by_keyword
关键词搜索	PostgreSQL 三元组：支持模糊匹配、容错拼写错误，并按相似度排序	SQLite FTS5：整词／词元匹配，因此结果和排序可能与托管版不同
大藏经数据	始终为最新版本	初始化时的快照；重新运行 tripitaka-mcp init 以刷新
更新	自动更新	运行 pipx upgrade tripitaka-mcp 更新代码；重新运行 init 更新数据
隐私	查询会发送到托管服务器（不会记录任何内容，详见隐私政策）	所有数据都保留在你的机器上
互联网	必需	init 后不再需要
速率限制	突发请求可能会在边缘节点受到限流	无
设置	零配置／一键完成	Python 3.10+、pipx，以及一次性约 120 MB 下载

search_semantic、search_hybrid 和三元组关键词索引需要 PostgreSQL、pgvector 以及一个约 1 GB 的嵌入模型，对轻量级本地安装来说负担过重，因此仅在托管版中提供。在本地模式下，这两个工具不会注册：连接的客户端只会看到它实际能够调用的 11 个工具。

由于本地服务是标准的 stdio MCP 服务，它也让你能够搭建完全离线的 AI 技术栈。将它与 Ollama 等本地模型及任意支持 MCP 的聊天界面搭配使用，所有数据都不会离开你的机器。

🏎️ 最快的本地部署方式：安装程序（推荐非开发者使用）

git clone https://github.com/dhamma-seeker/tripitaka-mcp.git
cd tripitaka-mcp
./scripts/install.sh

安装程序会从 Hugging Face 下载预先准备好的数据库转储文件（dhamma-seeker/tripitaka-mcp-dump），并为你恢复数据，将设置时间从两到四小时（加载数据后再生成嵌入）缩短到约五分钟。 （如果磁盘上已有转储文件，安装程序会直接使用该文件。）

安装程序将：

1. 验证是否已安装 docker、compose、openssl 和 curl
2. 生成 .env，并设置随机密码（分别用于管理员和只读用户）
3. 从 Hugging Face 下载转储文件（如果本地还没有）
4. 启动数据库并恢复转储
5. 设置只读角色和运行时超时
6. 输出可直接粘贴的 Claude Desktop 配置

选项：

./scripts/install.sh --dump PATH          # use an existing dump file
./scripts/install.sh --dump-url URL       # override the dump source
./scripts/install.sh --no-dump            # skip restore (load data yourself later)

---

🔧 手动设置（面向开发者）

1. 克隆并设置

git clone https://github.com/dhamma-seeker/tripitaka-mcp.git
cd tripitaka-mcp
cp .env.example .env
# Set POSTGRES_PASSWORD in .env to a random password

2. 启动数据库

docker compose up db -d

3. 安装依赖项

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

4. 初始化数据库并加载数据

# 1. Seed metadata (pitaka, nikāya)
python scripts/seed_metadata.py

# 2. Download & load Sutta Piṭaka data from SuttaCentral
python scripts/data_loader.py

# 3. Load Thai CC0 translations (Dhīranando & Jayasāro)
python scripts/load_thai_cc0.py

# 4. Load dictionaries (DPD, PTS, DPPN, and the Payutto dictionary)
python scripts/load_dictionary.py

# 5. Generate embeddings for semantic / hybrid search
python scripts/generate_embeddings.py

5. 运行 MCP 服务

python main.py

🧪 使用 Postman 测试

你可以在 SSE 模式下通过 Postman 调用这些工具：

1. 运行服务：MCP_TRANSPORT=sse python main.py
2. 将 postman_collection.json 导入 Postman
3. 直接调用这些工具

🚢 生产环境部署

在生产环境中，请从数据库转储文件恢复，而不是重新加载数据并再次运行嵌入模型。

docker compose -f docker-compose.prod.yml up -d --build

生产环境技术栈运行 5 个服务：

• db：PostgreSQL + pgvector（仅限内部访问，不暴露端口）
• mcp-server：通过旧版 SSE 运行的 FastMCP，位于 /sse 后（使用只读数据库用户、只读文件系统、cap_drop: ALL）
• mcp-server-http：同一服务通过 Streamable HTTP 运行，位于 /mcp 后
• reader：双语阅读器，所有交叉引用 URL 都指向此处，位于 /read/* 后
• caddy：反向代理和 Let's Encrypt。其 MCP 网站的 rate_limit 配置块虽已声明，但按当前写法不会生效，详见 DEPLOYMENT.md

如需进一步加固，可在 Caddy 前部署 Cloudflare（DNS 代理、速率限制规则，以及免费套餐提供的 DDoS 防护）。

完整详情见 DEPLOYMENT.md。

🔧 连接到 Claude Desktop

仓库附带 claude_desktop_config.example.json，其中包含 3 个可直接使用的配置项。将适合你的配置复制到 claude_desktop_config.json（macOS 上为 ~/Library/Application Support/Claude/，Windows 上为 %APPDATA%\Claude\），然后编辑绝对路径：

配置项	使用场景	传输方式
tripitaka-local	你在与 Claude Desktop 相同的计算机上本地运行了安装程序	stdio（无需网络）
tripitaka-remote	你在 VPS 上自托管服务，并希望使用现代传输方式	Streamable HTTP（/mcp）
tripitaka-remote-sse	你的客户端尚不支持 Streamable HTTP	旧版 SSE（/sse）

远程配置项通过 mcp-remote 连接；它是一个桥接工具，可通过 npx 将 Claude Desktop 连接到远程 MCP 服务。示例文件对每个字段都添加了注释；保存前请删除 _comment 键。

nvm 用户请注意： command 和 env.PATH 需要使用 node 的绝对路径，因为 Claude Desktop 不会读取你的 shell 配置文件。请在常规 shell 中运行 which npx 和 which python 获取路径。

可选：安装研究技能

在 Claude Desktop 和 Claude Code 中，复制捆绑的技能即可启用多步骤研究工作流：

mkdir -p ~/.claude/skills
cp skills/tipitaka-research.md ~/.claude/skills/
# Restart Claude Desktop (Cmd+Q then reopen) to pick up the skill

详情见 skills/README.md。

📦 MCP 工具（共 14 个）

工具	描述
search_hybrid	通过 RRF 结合关键词搜索与语义搜索。适用于概念搜索，尤其是查找“关于 X 的论述”时。
search_by_keyword	三元组关键词搜索，最适合查找某个确切词语的前几个匹配项（appamāda、ānāpānassati）。
survey_corpus	全面检索语料库：提供确切总数、按三藏划分的结果，以及匹配的词形。适用于查询“出现了多少次”或“X 出现的所有位置”，需要查找每一处出现，而非最佳匹配项时。mode=thorough 会增加概念级语义召回。
search_semantic	纯向量相似度搜索。通常 search_hybrid 是更好的选择。
verify_quote	在引用前核对引文是否出自经典。返回 exact / close / not_found 及匹配片段，让你能将某句话归于来源，而不是凭记忆引用。
get_sutta	按 ID 获取一部经（例如 mn1、dn22、dhp1-20），并附带交叉引用 URL。默认返回整部经；对于较长的经，可使用 mode="outline"（目录，不含正文）、around="<segment_id>"+window（获取命中内容周围的上下文），或使用 segment_range/offset+limit 仅获取一部分内容。
open_sutta_viewer	交互式经文查看器（MCP Apps）。在聊天中以内嵌形式并排显示巴利语与英语的经文，并高亮引用的片段。调用模型可通过 translations 参数，将所显示片段的 AI 翻译附加为带有明确标识的第三行；经典原文仍保持巴利语与英语。需要支持 MCP Apps 的宿主（Claude、Claude Desktop、VS Code Copilot 等）；在其他宿主上会回退为文本。
get_reference	生成格式规范的学术引用，并附上所有来源 URL。
compare_translations	比较不同版本对同一片段的译文。
list_structure	显示三藏结构，并列出各尼柯耶的片段覆盖数量。
list_editions	列出除捆绑的巴利语与英语版本之外加载的其他译本。公共服务目前未提供其他版本，因此会直接说明没有额外版本。
get_word_definition	巴利语词典查询（PTS、DPPN 和 Payutto 泰语词典）。
define_from_suttas	查找经藏和律藏如何用自己的语言定义某个术语：例如经典公式“Katamañca X? ... ayaṁ vuccati X”、“X adhivacana”，以及律藏中的“X nāma”。当 get_word_definition 提供的是词典释义时，此工具可给出一手来源中的定义。
parse_pali_word	在 get_word_definition 无法查到时，去除巴利语后缀以还原词根形式（bhikkhūnaṁ → bhikkhu）。

⚠️ 关于 search_semantic 的说明

向量索引仅基于 text_pali 构建，使用的多语言 MiniLM 模型并非专门针对巴利语训练。（bilara-data 总共仅有 6 个文件包含泰语，公共服务也未加载任何泰语版本。）因此：

• 巴利语和英语查询结果准确，跨语言对齐效果良好。
• 泰语查询会返回较宽泛的匹配项，不建议使用。
• 对于 appamāda 这样的确切关键词，search_by_keyword 更精确。
• 对于通用搜索，search_hybrid（关键词 + 语义）最能适应这一限制。

改用针对巴利语训练的嵌入模型（例如 bge-m3），以及为泰语版本生成嵌入，均已列入路线图。

📁 项目结构

tripitaka-mcp/
├── main.py                       # Main MCP Server (14 tools, 1 resource + 2 resource templates)
├── cli.py                        # `tripitaka-mcp` CLI (init / serve) for the pipx edition
├── sutta_verify.py               # Quote matching behind `verify_quote`
├── sutta_definitions.py          # Canonical definition formulas behind `define_from_suttas`
├── sutta_titles.py               # Sutta title resolution
├── mcp_app.py                    # MCP Apps registration (env-gated, `TRIPITAKA_MCP_APP`)
├── db/
│   ├── connection.py             # Database connection pool
│   └── schema.py                 # Schema (supports translation table)
├── embedding/
│   └── model.py                  # SentenceTransformer wrapper
├── scripts/
│   ├── install.sh                    # One-shot installer (HF dump → DB)
│   ├── deploy.sh                     # Deploy / restart on a VPS
│   ├── backup.sh                     # pg_dump → S3-compatible store
│   ├── dump_and_publish.sh           # Verify embeddings → pg_dump → upload to HuggingFace
│   ├── seed_metadata.py              # Seed pitaka/nikāya metadata
│   ├── data_loader.py                # Load Sutta Piṭaka (Pāli + bilara EN, per-book translator)
│   ├── load_vinaya.py                # Vinaya loader (Vibhaṅga + Pātimokkha + Khandhaka + Parivāra, Brahmali EN)
│   ├── load_abhidhamma.py            # Abhidhamma loader (7 books, Pāli — bilara has no EN)
│   ├── load_thai_cc0.py              # Thai translation loader
│   ├── load_dictionary.py            # Load dictionary data
│   ├── scrape_payutto.py             # Web scraper for the Payutto dictionary
│   ├── generate_embeddings.py        # Generate vector embeddings
│   ├── run_embedding_with_retry.sh   # Resilient wrapper around embedding generation (retries on DB drop)
│   ├── check_embedding_progress.py   # Live progress snapshot (or --watch mode) for the embedding job
│   ├── smoke_test.sh                 # Endpoint smoke test (TLS + /sse + /mcp + /health)
│   ├── test_full_sutta.py            # Full-content smoke test (22 size-tiered suttas, exact pinned counts)
│   ├── test_corpus_parity.py         # Check the corpus against the bilara-data clone it claims parity with
│   ├── test_definitions.py           # `define_from_suttas` regression + snapshot + backend parity
│   ├── test_verify_quote.py          # `verify_quote` regression, both backends
│   ├── test_survey_counts.py         # `survey_corpus` count drift
│   ├── test_pagination.py            # Slice / window / offset behaviour
│   └── test_mcp_prompts.py           # Prompt-level test — a real model picks the tools, a judge reads the answer
├── reader/                       # Bilingual reader served at /read/* (FastAPI)
│   ├── app.py                    # Routes: /read/, /read/{sutta_id}, search, browse
│   ├── queries.py                # Read-side queries
│   ├── featured.py               # Landing-page sutta cards
│   └── sutta_id_decoder.py       # Turn a sutta id into a human-readable location
├── site/                         # Static landing page served at the apex domain
├── topics/                       # Static markdown pages served at /topics/*
│   ├── README.md                 # Index of available topic pages
│   ├── tipitaka-overview.md      # Canon structure + coverage
│   ├── getting-started.md        # Connection paths, tool selection, prompt patterns
│   ├── places.md                 # Geography of the suttas (Mahājanapada, holy sites, cosmology)
│   ├── themes.md                 # 10 foundational teachings + locus classicus
│   ├── people.md                 # ~30 major figures (chief disciples, lay supporters, kings)
│   └── timeline.md               # Phase-based timeline of the 45-year teaching career
├── skills/                       # Portable Claude skills for AI clients
│   ├── README.md                 # How to install
│   └── tipitaka-research.md      # Multi-step research workflow
├── infra/                        # Reverse proxy + deploy config
│   ├── Caddyfile                 # Caddy: TLS, CORS for /mcp, /topics, /sse, /mcp
│   ├── Dockerfile.caddy          # Caddy + caddy-ratelimit plugin
│   ├── cloud-init.yml            # VPS bootstrap
│   └── *.tf                      # Terraform (provider-agnostic)
├── docs/
│   └── CAPACITY.md               # Capacity planning per VPS spec
├── claude_desktop_config.example.json
├── docker-compose.yml            # Dev (single mcp-server)
├── docker-compose.prod.yml       # Prod (db + 2 mcp-server + reader + caddy)
├── Dockerfile
└── requirements.txt

📜 数据来源与许可证

本项目汇集了多个来源的数据，各自适用不同的许可证。 重新分发前，请完整阅读 NOTICE.md。

来源	许可证	备注
源代码	MIT	可自由使用、派生和修改
SuttaCentral bilara-data	CC0	公共领域
泰语译文（Dhīranando、Jayasāro）	CC0	来自 SuttaCentral
Somdet Phra Buddhaghosacariya（P. A. Payutto）编著的 Dictionary of Buddhism	Dhamma Dāna	⚠️ 仅限非商业用途
PTS / DPPN / Dhammika 词典	公共领域 / CC

⚠️ 如果你计划派生或重新分发

• ✅ 用于免费的法施或教育项目
• ✅ 在自己的设备上运行，供个人使用
• ❌ 不要用于任何付费产品或服务，因为其中包含 Payutto 词典
• ❌ 不要修改词典内容

商业用途：请移除词典组件，或联系 Wat Nyanavesakavan 获取许可。

🙏 致谢与署名

贡献者详情请见 CREDITS.md，许可证条款请见 NOTICE.md。

感谢：

• Somdet Phra Buddhaghosacariya（P. A. Payutto）和 Wat Nyanavesakavan
• SuttaCentral 以及泰语和英语译者
• 84000.org

---

善哉 🙏

愿分享此法为一切众生带来利益与幸福。