Tripitaka MCP

Busca y cita el Canon Pāli completo (Tipiṭaka, ~444K segmentos) — Sutta, Vinaya, Abhidhamma a la par con SuttaCentral. Búsqueda híbrida, recuperación de suttas completos, comparación de traducciones, búsqueda de palabras en Pāli. Gratuito, no comercial, ofrecido como Dhamma Dāna.

GitHub

Documentación

Tripitaka MCP Server

Un servidor MCP para buscar y citar contenido del Tipiṭaka Pāli. Brinda a los agentes de IA (como Claude o Cursor) la capacidad de consultar suttas, citar las enseñanzas y comparar traducciones entre idiomas.

🙏 Este proyecto se ofrece como Dhamma Dāna — 100% gratuito, solo sin fines comerciales. Detalles de la licencia: LICENSE (código) + NOTICE.md (datos)

✨ Características

📚 Cobertura completa del Tipiṭaka a la par de SuttaCentral — los tres cestones indexados (~444K segmentos): Sutta (Pāli + inglés de Sujato), Vinaya (Pāli + inglés de Brahmali) y Abhidhamma (solo Pāli — sin inglés en el bilara-data oficial para ningún libro de Abhidhamma). Recuentos en vivo vía list_structure.
⚖️ Búsqueda híbrida — la mayor precisión combinando búsqueda por palabras clave y semántica mediante Reciprocal Rank Fusion (RRF). Lista para usar.
🔍 Búsqueda por palabras clave — coincidencia difusa con trigramas y alineación entre idiomas.
🧠 Búsqueda semántica — búsqueda basada en significado mediante similitud vectorial (pgvector).
📖 Comparación de traducciones — visualiza y compara versiones entre ediciones, alineadas a nivel de segmento.
📚 Puente de diccionario — diccionario integrado con más de 20 000 entradas (P. A. Payutto, PTS, DPPN).
📖 Obtener Sutta y Referencia — recupera el contenido del sutta por ID (p. ej. mn1, pli-tv-bu-vb-pj1, patthana1.1) y genera citas académicas correctamente formateadas.
🔬 Analizador de palabras en Pāli — elimina sufijos flexivos para encontrar la forma raíz cuando la búsqueda en el diccionario falla (bhikkhūnaṁ → bhikkhu).
🔗 URLs de referencia cruzada en cada respuesta — un enlace profundo clicable al lector bilingüe del propio proyecto (Pāli + inglés, con un ancla de segmento que resalta el verso citado). El lector reproduce el bilara-data de SuttaCentral textualmente, por lo que es el texto autoritativo; los clientes de IA muestran este enlace para que los usuarios verifiquen la fuente con un clic.
📡 Transporte dual — tanto SSE heredado (/sse) como HTTP Streamable canónico (/mcp, especificación MCP 2025-03-26).
📦 Recursos MCP — tripitaka://structure, tripitaka://sutta/{id}, tripitaka://word/{w} para clientes que fijan el contexto como recursos.
📄 Páginas de referencia seleccionadas en /topics/* — seis páginas Markdown que cubren la estructura del canon, primeros pasos + selección de herramientas, lugares (Mahājanapada + sitios sagrados + cosmología), 10 temas fundamentales con su locus classicus, ~30 figuras principales y una línea de tiempo por fases de la misión de 45 años del Buda. Los IDs de los suttas están verificados contra datos en vivo; los clientes de IA pueden obtener una página en una sola llamada en lugar de ejecutar más de 30 llamadas de herramientas.
🤖 Habilidad de Claude — skills/tipitaka-research.md incluye un archivo de flujo de trabajo listo para instalar que activa un patrón de investigación en varios pasos (aclarar → verificar cobertura → buscar → profundizar → citar) en Claude Desktop / Claude Code.
📮 Listo para Postman — incluye una colección de Postman para probar la API.

🏗️ Stack Tecnológico

Tecnología	Rol
Python + FastMCP	Servidor MCP
PostgreSQL + pgvector	Base de datos + Búsqueda Vectorial
sentence-transformers	Embeddings para búsqueda semántica
Docker Compose	Infraestructura

🚀 Inicio Rápido

🌐 Sin configuración — conéctate al servidor público Dhamma Dāna

Los mantenedores operan una instancia pública gratuita en tripitaka-mcp.com.

Endpoint	Uso
`https://mcp.tripitaka-mcp.com/mcp`	HTTP Streamable (especificación MCP 2025-03-26)
`https://mcp.tripitaka-mcp.com/sse`	SSE heredado (clientes más antiguos)

Conecta Claude Desktop en tres pasos (sin instalación, sin Docker, sin GPU — solo necesitas Node.js):

1. Encuentra la ruta absoluta de npx. Claude Desktop no lee tu perfil de shell, por lo que un npx simple no se resolverá. Abre una terminal:

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

2. Abre claude_desktop_config.json (~/Library/Application Support/Claude/ en macOS, %APPDATA%\Claude\ en Windows) y agrega la entrada siguiente — sustituye YOUR_NPX_PATH con el resultado del paso 1 y YOUR_NODE_BIN_DIR con el directorio principal de esa ruta:

{
  "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. Cierra Claude Desktop por completo (⌘Q en macOS, bandeja → Salir en Windows) y vuelve a abrirlo. El indicador 🔌 en la parte inferior izquierda debería mostrar tripitaka con 12 herramientas disponibles.

La primera conexión tarda 5–10 segundos mientras npx descarga mcp-remote bajo demanda — dale un momento a Claude Desktop después del reinicio antes de asumir que falló.

Una vez conectado, prueba a pedirle a Claude cosas como:

"¿Qué enseña el Buda sobre la atención plena a la respiración? Cita los pasajes relevantes de MN 118."
"Muéstrame el texto completo del Karaṇīyamettasutta en Pāli e inglés."
"¿Qué significa la palabra pāli sati según el diccionario de Payutto?"
"Encuentra suttas donde el Buda hable sobre la ira."

Claude elegirá la herramienta correcta, obtendrá el Pāli canónico y mostrará un enlace clicable al lector bilingüe del proyecto para su verificación.

El servidor alojado tiene límite de tasa (10 solicitudes/10 s + 60 solicitudes/min por IP) y se ofrece para estudio personal, investigación y práctica del dhamma — consulta NOTICE.md antes de redistribuir o usar comercialmente.

💻 Ejecútalo completamente sin conexión (`pipx` — SQLite local, sin servidor)

¿Prefieres mantener todo en tu propia máquina — sin llamadas de red al servidor alojado? Instala la edición local. Incluye todo el canon Pāli como un único archivo SQLite (~120 MB) y funciona como un 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

Luego apunta Claude Desktop / Cursor al comando local — sin npx, sin mcp-remote, sin internet:

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

(Si tripitaka-mcp no está en el PATH del cliente, usa la ruta absoluta de which tripitaka-mcp.)

Alojado vs local — qué cambia

Ambos sirven el mismo canon de ~444K segmentos. Las diferencias:

	Alojado (`mcp.tripitaka-mcp.com`)	Local (`pipx`)
Herramientas	las 12	9 (10 con `TRIPITAKA_MCP_APP=1`) — sin `search_semantic` / `search_hybrid`
Búsqueda conceptual / semántica	✅ búsqueda vectorial (pgvector)	❌ — usa `search_by_keyword` en su lugar
Búsqueda por palabras clave	PostgreSQL trigram — difusa, tolerante a errores, ordenada por similitud	SQLite FTS5 — coincidencia por palabra completa / token; los resultados y el orden pueden diferir del alojado
Datos del canon	siempre actualizados	una instantánea del momento en que ejecutaste `init` — vuelve a ejecutar `tripitaka-mcp init` para actualizar
Actualizaciones	automáticas	`pipx upgrade tripitaka-mcp` para el código; vuelve a ejecutar `init` para los datos
Privacidad	las consultas llegan al servidor alojado (nada se registra — consulta Política de Privacidad)	nada sale de tu máquina
Internet	requerido	no necesario después de `init`
Límite de tasa	10 solicitudes / 10 s, 60 solicitudes / min por IP	ninguno
Configuración	cero / un clic	Python 3.10+, pipx, descarga única de ~120 MB

search_semantic / search_hybrid y el índice de palabras clave por trigramas necesitan PostgreSQL + pgvector + un modelo de embeddings de ~1 GB — demasiado pesado para una instalación local ligera, por lo que permanecen solo en el alojado. En modo local esas dos herramientas no se registran en absoluto: un cliente conectado solo ve las 9 herramientas disponibles, por lo que nunca intenta llamar a una herramienta que no puede funcionar.

Como el servidor local es un servidor MCP stdio estándar, también habilita un stack de IA completamente sin conexión — combínalo con un modelo local (p. ej. Ollama) y cualquier interfaz de chat compatible con MCP, y nada saldrá de tu máquina.

🏎️ La ruta local más rápida — usa el instalador (recomendado para no desarrolladores)

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

El instalador descarga un volcado de base de datos preparado desde Hugging Face — dhamma-seeker/tripitaka-mcp-dump y lo restaura automáticamente — reduciendo el tiempo de configuración de 2–4 horas (carga de datos + generación de embeddings) a ~5 minutos. (Si ya existe un archivo de volcado local, se usa la copia local.)

El instalador hará lo siguiente:

Verificar que docker, compose, openssl y curl estén instalados
Generar .env con contraseñas aleatorias (tanto para el usuario administrador como para el usuario de solo lectura)
Descargar el volcado desde Hugging Face (si no está ya en local)
Iniciar la base de datos y restaurar el volcado
Configurar el rol de solo lectura y los tiempos de espera de ejecución
Imprimir una configuración de Claude Desktop lista para pegar

Opciones:

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

🔧 Configuración manual (para desarrolladores)

1. Clonar y 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 la Base de Datos

docker compose up db -d

3. Instalar Dependencias

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

4. Inicializar la Base de Datos y Cargar Datos

# 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. Ejecutar el Servidor MCP

python main.py

🧪 Pruebas con Postman

El proyecto admite probar con Postman en modo SSE:

Ejecuta el servidor con: MCP_TRANSPORT=sse python main.py
Importa postman_collection.json en Postman
Invoca las herramientas directamente

🚢 Despliegue en Producción

Para desplegar en producción sin volver a cargar los datos y sin volver a ejecutar el modelo de embeddings, restaurar desde un volcado de base de datos es la ruta recomendada.

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

El stack de producción ejecuta 3 servicios:

db — PostgreSQL + pgvector (solo interno, sin puerto expuesto)
mcp-server — FastMCP (se ejecuta como usuario de solo lectura, FS de solo lectura, cap_drop: ALL)
caddy — proxy inverso + Let's Encrypt + límite de tasa (10 solicitudes/10 s y 60 solicitudes/1 min por IP)

Para una capa adicional de endurecimiento, coloca Cloudflare delante de Caddy (proxy DNS + reglas de límite de tasa + protección DDoS en el nivel gratuito).

👉 Detalles completos: DEPLOYMENT.md

🔧 Conexión a Claude Desktop

El repositorio incluye claude_desktop_config.example.json con tres entradas listas para usar — copia la que se ajuste a tu configuración en claude_desktop_config.json (~/Library/Application Support/Claude/ en macOS, %APPDATA%\Claude\ en Windows) y luego edita las rutas absolutas:

Entrada	Cuándo usarla	Transporte
`tripitaka-local`	Ejecutaste el instalador localmente en la misma máquina que Claude Desktop	stdio (sin red)
`tripitaka-remote`	Autogestionaste el servidor en un VPS y quieres el transporte moderno	HTTP Streamable (`/mcp`)
`tripitaka-remote-sse`	Tu cliente aún no admite HTTP Streamable	SSE heredado (`/sse`)

Las entradas remotas pasan por mcp-remote — Claude Desktop ↔ puente npx ↔ MCP remoto. El archivo de ejemplo tiene comentarios anotados que explican cada campo; elimina las claves _comment antes de guardar.

Aviso para usuarios de nvm: command y env.PATH necesitan rutas absolutas de node — Claude Desktop no lee tu perfil de shell. Encuentra las rutas correctas con which npx / which python mientras tu shell normal está activo.

Opcional: instala la habilidad de investigación

Para usuarios de Claude Desktop / Claude Code, copiar la habilidad incluida activa automáticamente el flujo de trabajo de investigación en varios pasos:

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

Detalles en skills/README.md.

📦 Herramientas MCP (13 en total)

Herramienta	Descripción
`search_hybrid`	(Recomendada para búsqueda de conceptos) Búsqueda combinada de palabras clave + semántica mediante RRF — la mejor opción cuando buscas "discursos sobre X".
`search_by_keyword`	Búsqueda de palabras clave por trigramas — la mejor para las primeras coincidencias de una palabra exacta (`appamāda`, `ānāpānassati`).
`survey_corpus`	Estudio exhaustivo del corpus — total exacto + desglose por pitaka + las formas de palabras coincidentes, para "cuántas veces / en cada lugar donde aparece X" (cobertura, no solo las mejores coincidencias). `mode=thorough` añade recuperación semántica a nivel de concepto.
`search_semantic`	Similitud vectorial pura — normalmente quieres `search_hybrid` en su lugar.
`get_sutta`	Obtener un sutta por ID (p. ej. `mn1`, `dn22`, `dhp1-20`) con URLs de referencias cruzadas. Sutta completo por defecto; para los largos usa `mode="outline"` (tabla de contenidos, sin texto), `around="<segment_id>"`+`window` (contexto alrededor de una coincidencia), o `segment_range`/`offset`+`limit` para obtener solo un fragmento.
`open_sutta_viewer`	Visor interactivo de suttas (MCP Apps) — muestra el sutta en línea en el chat con Pāli + inglés lado a lado, con el segmento citado resaltado. El modelo que realiza la llamada puede adjuntar una traducción al idioma del usuario de los segmentos mostrados (parámetro `translations`) como una tercera fila claramente etiquetada — el canon en sí permanece en Pāli + inglés. Requiere un host compatible con MCP Apps (Claude, Claude Desktop, VS Code Copilot, …); otros hosts reciben un respaldo de texto elegante.
`get_reference`	Generar una cita académica correctamente formateada con todas las URLs de las fuentes.
`compare_translations`	Comparar representaciones de un solo segmento entre ediciones.
`list_structure`	Mostrar la estructura del Tipiṭaka con cobertura de recuento de segmentos por nikāya.
`list_editions`	Listar las ediciones de traducción al tailandés/inglés actualmente cargadas.
`get_word_definition`	Consulta al diccionario Pāli (PTS, DPPN y el diccionario tailandés de Payutto).
`define_from_suttas`	Encontrar cómo los suttas/Vinaya definen un término con sus propias palabras — fórmulas canónicas como "Katamañca X? ... ayaṁ vuccati X", "X adhivacana", Vinaya "X nāma". Complementa `get_word_definition` con definiciones de fuentes primarias en lugar de glosas de diccionario.
`parse_pali_word`	Eliminar sufijos Pāli para recuperar la forma raíz cuando `get_word_definition` falla (`bhikkhūnaṁ` → `bhikkhu`).

⚠️ Nota sobre `search_semantic`

El índice vectorial se construye solo sobre text_pali (los datos bilara-data de SuttaCentral aún no incluyen traducciones al tailandés) usando un modelo MiniLM multilingüe que no está específicamente entrenado en Pāli. Como resultado:

Consultas en Pāli / inglés → precisas (buena alineación entre idiomas)
Consultas en tailandés → coincidencias imprecisas, no recomendado
Para palabras clave exactas como appamāda, search_by_keyword es más preciso
Para búsqueda de propósito general, search_hybrid (palabras clave + semántica) tolera mejor esta limitación

Actualizar a un modelo de incrustación entrenado en Pāli (p. ej. bge-m3) además de incrustar la edición tailandesa está en la hoja de ruta.

📁 Estructura del Proyecto

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

📜 Fuentes de Datos y Licencia

Este proyecto agrega datos de múltiples fuentes bajo diferentes licencias. Por favor, lee NOTICE.md completo antes de redistribuir.

Fuente	Licencia	Nota
Código fuente	MIT	Libre de usar, bifurcar, modificar
Datos bilara-data de SuttaCentral	CC0	Dominio público
Traducciones al tailandés (Dhīranando, Jayasāro)	CC0	Vía SuttaCentral
Diccionario de Budismo de Somdet Phra Buddhaghosacariya (P. A. Payutto)	Dhamma Dāna	⚠️ Solo uso no comercial
Diccionarios PTS / DPPN / Dhammika	Dominio público / CC	—

⚠️ Si planeas bifurcar o redistribuir

✅ Uso en proyectos gratuitos / dhamma-dāna / educativos — permitido
✅ Ejecutar en tu propia máquina / uso personal — permitido
❌ No usar en ningún producto o servicio de pago (por el diccionario de Payutto)
❌ No modificar el contenido del diccionario

Para uso comercial: elimina el componente del diccionario, o contacta con Wat Nyanavesakavan para obtener permiso.

🙏 Créditos y Atribución

Consulta CREDITS.md para detalles de los colaboradores y NOTICE.md para los términos de licencia.

Agradecimiento a:

Somdet Phra Buddhaghosacariya (P. A. Payutto) + Wat Nyanavesakavan
SuttaCentral y los traductores al tailandés e inglés
84000.org

Sādhu 🙏 — Que el compartir este Dhamma traiga beneficio y felicidad a todos los seres.