Tripitaka MCP

Pesquise e cite o Cânone Pāli completo (Tipiṭaka, ~444 mil segmentos) — Sutta, Vinaya, Abhidhamma em paridade com o SuttaCentral. Busca híbrida, recuperação de sutta completo, comparação de traduções, consulta de palavras em Pāli. Gratuito, não comercial, oferecido como Dhamma Dāna.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP Tripitaka

Um servidor MCP para buscar e citar conteúdo do Tipiṭaka em Pāli. Dá a agentes de IA (como Claude ou Cursor) a capacidade de consultar suttas, citar os ensinamentos e comparar traduções entre idiomas.

🙏 Este projeto é oferecido como Dhamma Dāna — 100% gratuito, apenas para uso não comercial. Detalhes da licença: LICENSE (código) + NOTICE.md (dados)

✨ Recursos

📚 Cobertura completa do Tipiṭaka em paridade com o SuttaCentral — todos os três cestos indexados (~444 mil segmentos): Sutta (Pāli + inglês de Sujato), Vinaya (Pāli + inglês de Brahmali) e Abhidhamma (somente Pāli — sem inglês no bilara-data upstream para nenhum livro do Abhidhamma). Contagens ao vivo via list_structure.
⚖️ Busca Híbrida — maior precisão combinando busca por palavras-chave e semântica por meio de Fusão de Classificação Recíproca (RRF). Pronta para uso.
🔍 Busca por Palavras-Chave — correspondência difusa de trigramas com alinhamento entre idiomas.
🧠 Busca Semântica — busca baseada em significado via similaridade vetorial (pgvector).
📖 Comparação de Traduções — visualize e compare versões entre edições, alinhadas no nível do segmento.
📚 Ponte de Dicionário — dicionário integrado com mais de 20.000 verbetes (P. A. Payutto, PTS, DPPN).
📖 Obter Sutta e Referência — busque conteúdo de suttas por ID (ex.: mn1, pli-tv-bu-vb-pj1, patthana1.1) e gere citações acadêmicas formatadas corretamente.
🔬 Analisador de palavras em Pāli — remove sufixos flexionais para encontrar a forma raiz quando a consulta ao dicionário falha (bhikkhūnaṁ → bhikkhu).
🔗 URLs de referência cruzada em cada resposta — um link profundo clicável para o leitor bilíngue do próprio projeto (Pāli + inglês, com uma âncora de segmento que destaca o versículo citado). O leitor renderiza o bilara-data do SuttaCentral literalmente, portanto é o texto autoritativo; clientes de IA exibem esse link para que os usuários verifiquem a fonte com um clique.
📡 Transporte duplo — tanto SSE legado (/sse) quanto HTTP Streamable canônico (/mcp, especificação MCP 2025-03-26).
📦 Recursos MCP — tripitaka://structure, tripitaka://sutta/{id}, tripitaka://word/{w} para clientes que fixam contexto como recursos.
📄 Páginas de referência selecionadas em /topics/* — seis páginas em markdown cobrindo a estrutura do cânon, primeiros passos + seleção de ferramentas, lugares (Mahājanapada + locais sagrados + cosmologia), 10 temas fundamentais com locus classicus, ~30 figuras importantes e uma linha do tempo por fases da missão de 45 anos do Buda. IDs de suttas verificados contra dados ao vivo; clientes de IA podem buscar uma página de uma só vez em vez de executar mais de 30 chamadas de ferramentas.
🤖 Habilidade para Claude — skills/tipitaka-research.md inclui um arquivo de fluxo de trabalho pronto para instalar que ativa um padrão de pesquisa em várias etapas (esclarecer → verificar cobertura → buscar → aprofundar → citar) no Claude Desktop / Claude Code.
📮 Pronto para Postman — acompanha uma coleção do Postman para testar a API.

🏗️ Pilha Tecnológica

Tecnologia	Função
Python + FastMCP	Servidor MCP
PostgreSQL + pgvector	Banco de Dados + Busca Vetorial
sentence-transformers	Embeddings para busca semântica
Docker Compose	Infraestrutura

🚀 Início Rápido

🌐 Sem configuração — conecte-se ao servidor público Dhamma Dāna

Os mantenedores operam uma instância pública gratuita em tripitaka-mcp.com.

Endpoint	Uso
`https://mcp.tripitaka-mcp.com/mcp`	HTTP Streamable (especificação MCP 2025-03-26)
`https://mcp.tripitaka-mcp.com/sse`	SSE legado (clientes mais antigos)

Conecte o Claude Desktop em três passos (sem instalação, sem Docker, sem GPU — você só precisa de Node.js):

1. Encontre o caminho absoluto do seu npx. O Claude Desktop não lê o perfil do seu shell, então um npx simples não será resolvido. Abra um terminal:

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

2. Abra claude_desktop_config.json (~/Library/Application Support/Claude/ no macOS, %APPDATA%\Claude\ no Windows) e adicione a entrada abaixo — substitua YOUR_NPX_PATH pela saída do passo 1 e YOUR_NODE_BIN_DIR pelo diretório pai desse caminho:

{
  "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. Saia completamente do Claude Desktop (⌘Q no macOS, bandeja → Sair no Windows) e reabra. O indicador 🔌 no canto inferior esquerdo deve mostrar tripitaka com 12 ferramentas disponíveis.

A primeira conexão leva de 5 a 10 segundos enquanto npx baixa mcp-remote sob demanda — dê um momento ao Claude Desktop após reiniciar antes de presumir que falhou.

Depois de conectado, tente perguntar ao Claude coisas como:

"O que o Buda ensina sobre a atenção plena na respiração? Cite as passagens relevantes do MN 118."
"Mostre-me o texto completo do Karaṇīyamettasutta em Pāli e inglês."
"O que a palavra em Pāli sati significa segundo o dicionário de Payutto?"
"Encontre suttas em que o Buda discute a raiva."

O Claude escolherá a ferramenta certa, buscará o Pāli canônico e exibirá um link clicável para o leitor bilíngue do projeto para verificação.

O servidor hospedado tem limite de taxa (10 req/10s + 60 req/min por IP) e é oferecido para estudo pessoal, pesquisa e prática do dhamma — consulte NOTICE.md antes de redistribuir ou usar comercialmente.

💻 Execute totalmente offline (`pipx` — SQLite local, sem servidor)

Prefere manter tudo na sua própria máquina — sem chamadas de rede ao servidor hospedado? Instale a edição local. Ela inclui todo o cânon em Pāli como um único arquivo SQLite (~120 MB) e roda como um servidor MCP stdio local.

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

Se a instalação falhar assim:

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

O pipx está usando um interpretador diferente do que você pensa. Ele cria seu próprio ambiente isolado de propósito e ignora qualquer venv que você tenha ativo — então um Python antigo do sistema é escolhido mesmo quando o shell em que você digitou tem 3.12. Diga a ele qual usar:

pipx install --python python3.12 tripitaka-mcp

(Qualquer versão 3.10 ou mais nova funciona; pipx environment mostra qual é o padrão.)

Depois aponte o Claude Desktop / Cursor para o comando local — sem npx, sem mcp-remote, sem internet:

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

(Se tripitaka-mcp não estiver no PATH do cliente, use o caminho absoluto de which tripitaka-mcp.)

Precisa de uma URL em vez de stdio? Algumas ferramentas — scripts, notebooks, qualquer coisa que queira compartilhar um servidor entre vários clientes — querem um endpoint HTTP em vez de um subprocesso:

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

Ele vincula a 127.0.0.1 a menos que você diga o contrário; o cânon é somente leitura, mas nada aqui pergunta quem está chamando, então pense antes de vincular a uma interface pública.

Hospedado vs. local — o que é diferente

Ambos servem o mesmo cânon de ~444 mil segmentos. As diferenças:

	Hospedado (`mcp.tripitaka-mcp.com`)	Local (`pipx`)
Ferramentas	todas as 12	9 (10 com `TRIPITAKA_MCP_APP=1`) — sem `search_semantic` / `search_hybrid`
Busca conceitual / semântica	✅ busca vetorial (pgvector)	❌ — use `search_by_keyword` em vez disso
Busca por palavras-chave	Trigrama PostgreSQL — difusa, tolerante a erros de digitação, classificada por similaridade	SQLite FTS5 — correspondência de palavra inteira / token; resultados e classificação podem diferir do hospedado
Dados do cânon	sempre atuais	um instantâneo de quando você executou `init` — execute `tripitaka-mcp init` novamente para atualizar
Atualizações	automáticas	`pipx upgrade tripitaka-mcp` para código; execute `init` novamente para dados
Privacidade	consultas chegam ao servidor hospedado (nada é registrado — veja Política de Privacidade)	nada sai da sua máquina
Internet	necessária	não é necessária após `init`
Limite de taxa	10 req / 10 s, 60 req / min por IP	nenhum
Configuração	zero / um clique	Python 3.10+, pipx, download único de ~120 MB

search_semantic / search_hybrid e o índice de palavras-chave por trigrama precisam de PostgreSQL + pgvector + um modelo de embeddings de ~1 GB — pesado demais para uma instalação local leve, então permanecem apenas na versão hospedada. No modo local, essas duas ferramentas não são registradas: um cliente conectado vê apenas as 9 ferramentas disponíveis, então nunca tenta chamar uma ferramenta que não pode funcionar.

Como o servidor local é um servidor MCP stdio padrão, ele também permite uma pilha de IA totalmente offline — combine-o com um modelo local (ex.: Ollama) e qualquer interface de chat compatível com MCP, e nada sai da sua máquina.

🏎️ Caminho local mais rápido — use o instalador (recomendado para não desenvolvedores)

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

O instalador baixa um dump de banco de dados preparado do Hugging Face — dhamma-seeker/tripitaka-mcp-dump e o restaura automaticamente — reduzindo o tempo de configuração de 2 a 4 horas (carregando dados + gerando embeddings) para cerca de 5 minutos. (Se um arquivo de dump local já existir, a cópia local é usada em vez disso.)

O instalador irá:

Verificar se docker, compose, openssl e curl estão instalados
Gerar .env com senhas aleatórias (para o usuário admin e o usuário somente leitura)
Baixar o dump do Hugging Face (se ainda não estiver local)
Iniciar o banco de dados e restaurar o dump
Configurar a função somente leitura e os timeouts de tempo de execução
Imprimir uma configuração pronta para colar no Claude Desktop

Opções:

./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)

🔧 Configuração manual (para desenvolvedores)

1. Clonar e Configurar

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. Iniciar o Banco de Dados

docker compose up db -d

3. Instalar Dependências

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

4. Inicializar o Banco de Dados e Carregar Dados

# 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. Executar o Servidor MCP

python main.py

🧪 Testando com Postman

O projeto suporta testes com Postman no modo SSE:

Execute o servidor com: MCP_TRANSPORT=sse python main.py
Importe postman_collection.json no Postman
Invoque as ferramentas diretamente

🚢 Implantação em Produção

Para implantar em produção sem recarregar os dados e reexecutar o modelo de embeddings, restaurar a partir de um dump de banco de dados é o caminho recomendado.

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

A pilha de produção executa 3 serviços:

db — PostgreSQL + pgvector (somente interno, sem porta exposta)
mcp-server — FastMCP (executa como usuário somente leitura, sistema de arquivos somente leitura, cap_drop: ALL)
caddy — proxy reverso + Let's Encrypt + limite de taxa (10 req/10s e 60 req/1 min por IP)

Para uma camada extra de proteção, coloque o Caddy atrás do Cloudflare (proxy DNS + regras de limite de taxa + proteção DDoS no plano gratuito).

👉 Detalhes completos: DEPLOYMENT.md

🔧 Conectando ao Claude Desktop

O repositório inclui claude_desktop_config.example.json com três entradas prontas para uso — copie a que se adequa à sua configuração para claude_desktop_config.json (~/Library/Application Support/Claude/ no macOS, %APPDATA%\Claude\ no Windows) e depois edite os caminhos absolutos:

Entrada	Quando usar	Transporte
`tripitaka-local`	Você executou o instalador localmente na mesma máquina do Claude Desktop	stdio (sem rede)
`tripitaka-remote`	Você auto-hospedou o servidor em um VPS e quer o transporte moderno	HTTP Streamable (`/mcp`)
`tripitaka-remote-sse`	Seu cliente ainda não suporta HTTP Streamable	SSE legado (`/sse`)

As entradas remotas roteiam por mcp-remote — Claude Desktop ↔ ponte npx ↔ MCP remoto. O arquivo de exemplo tem comentários anotados explicando cada campo; remova as chaves _comment antes de salvar.

Aviso para usuários de nvm: command e env.PATH precisam de caminhos absolutos do node — o Claude Desktop não lê o perfil do seu shell. Encontre os caminhos corretos com which npx / which python enquanto seu shell normal estiver ativo.

Opcional: instale a habilidade de pesquisa

Para usuários do Claude Desktop / Claude Code, copiar a habilidade incluída ativa automaticamente o fluxo de trabalho de pesquisa em várias etapas:

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

Detalhes em skills/README.md.

📦 Ferramentas MCP (13 no total)

Ferramenta	Descrição
`search_hybrid`	(Recomendado para busca por conceitos) Palavra-chave combinada + semântica via RRF — melhor para procurar "discursos sobre X".
`search_by_keyword`	Busca por palavra-chave com trigramas — melhor para as poucas correspondências principais de uma palavra exata (`appamāda`, `ānāpānassati`).
`survey_corpus`	Exaustiva pesquisa no corpus — total exato + detalhamento por pitaka + formas de palavras correspondentes, para "quantas vezes / em todos os lugares que X aparece" (cobertura, não apenas melhores correspondências). `mode=thorough` adiciona recall semântico em nível de conceito.
`search_semantic`	Similaridade vetorial pura — geralmente você quer `search_hybrid` em vez disso.
`get_sutta`	Buscar um sutta por ID (ex.: `mn1`, `dn22`, `dhp1-20`) com URLs de referência cruzada. Sutta completo por padrão; para os longos, use `mode="outline"` (sumário, sem texto), `around="<segment_id>"`+`window` (contexto ao redor de uma ocorrência), ou `segment_range`/`offset`+`limit` para buscar apenas um trecho.
`open_sutta_viewer`	Visualizador interativo de suttas (MCP Apps) — renderiza o sutta inline no chat com Pāli + Inglês lado a lado, com o segmento citado destacado. O modelo chamador pode anexar uma tradução em IA dos segmentos exibidos para o idioma do usuário (parâmetro `translations`) como uma terceira linha claramente identificada — o cânon em si permanece em Pāli + Inglês. Requer um host compatível com MCP Apps (Claude, Claude Desktop, VS Code Copilot, …); outros hosts recebem um fallback de texto elegante.
`get_reference`	Gerar uma citação acadêmica formatada corretamente com todas as URLs de origem.
`compare_translations`	Comparar renderizações de um único segmento entre edições.
`list_structure`	Mostrar a estrutura do Tipiṭaka com cobertura de contagem de segmentos por nikāya.
`list_editions`	Listar edições de tradução em tailandês/inglês atualmente carregadas.
`get_word_definition`	Consulta ao dicionário de Pāli (PTS, DPPN e o dicionário tailandês Payutto).
`define_from_suttas`	Descobrir como os suttas/Vinaya definem um termo com suas próprias palavras — fórmulas canônicas como "Katamañca X? ... ayaṁ vuccati X", "X adhivacana", Vinaya "X nāma". Complementa `get_word_definition` com definições de fontes primárias em vez de paráfrases de dicionário.
`parse_pali_word`	Remover sufixos de Pāli para recuperar a forma raiz quando `get_word_definition` não encontrar (`bhikkhūnaṁ` → `bhikkhu`).

⚠️ Nota sobre `search_semantic`

O índice vetorial é construído apenas em text_pali (os dados bilara-data do SuttaCentral ainda não incluem traduções em tailandês) usando um modelo MiniLM multilíngue que não é especificamente treinado em Pāli. Como resultado:

Consultas em Pāli / Inglês → precisas (bom alinhamento entre idiomas)
Consultas em tailandês → correspondências imprecisas, não recomendado
Para palavras-chave exatas como appamāda, search_by_keyword é mais preciso
Para busca de propósito geral, search_hybrid (palavra-chave + semântica) tolera melhor essa limitação

Atualizar para um modelo de incorporação treinado em Pāli (ex.: bge-m3) além de incorporar a edição em tailandês está no roadmap.

📁 Estrutura do Projeto

tripitaka-mcp/
├── main.py                       # Main MCP Server (12 tools + 3 resources)
├── 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 + Sujato English)
│   ├── 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 across all 3 piṭakas)
├── 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)
├── 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, rate limit, /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 + caddy)
├── Dockerfile
└── requirements.txt

📜 Fontes de Dados e Licença

Este projeto agrega dados de várias fontes sob diferentes licenças. Leia NOTICE.md na íntegra antes de redistribuir.

Fonte	Licença	Nota
Código-fonte	MIT	Livre para usar, bifurcar, modificar
Dados bilara-data do SuttaCentral	CC0	Domínio público
Traduções em tailandês (Dhīranando, Jayasāro)	CC0	Via SuttaCentral
Dicionário do Budismo por Somdet Phra Buddhaghosacariya (P. A. Payutto)	Dhamma Dāna	⚠️ Apenas uso não comercial
Dicionários PTS / DPPN / Dhammika	Domínio Público / CC	—

⚠️ Se você planeja bifurcar ou redistribuir

✅ Uso em projetos gratuitos / dhamma-dāna / educacionais — permitido
✅ Executar em sua própria máquina / uso pessoal — permitido
❌ Não use em qualquer produto ou serviço pago (por causa do dicionário Payutto)
❌ Não modifique o conteúdo do dicionário

Para uso comercial: remova o componente do dicionário, ou entre em contato com Wat Nyanavesakavan para obter permissão.

🙏 Créditos e Atribuição

Veja CREDITS.md para detalhes dos colaboradores e NOTICE.md para os termos de licença.

Gratidão a:

Somdet Phra Buddhaghosacariya (P. A. Payutto) + Wat Nyanavesakavan
SuttaCentral e os tradutores de tailandês e inglês
84000.org

Sādhu 🙏 — Que o compartilhamento deste Dhamma traga benefício e felicidade a todos os seres.