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

Prueba este MCPPatrocinado

Documentación

Servidor MCP Tripitaka

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 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 original para ningún libro de Abhidhamma). Conteos en vivo vía list_structure.
⚖️ Búsqueda híbrida — la mayor precisión al combinar búsqueda por palabras clave y semántica mediante Fusión de Rango Recíproco (RRF). Lista para usar.
🔍 Búsqueda por palabras clave — coincidencia difusa de trigramas con 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 contenido de suttas por ID (p. ej. mn1, pli-tv-bu-vb-pj1, patthana1.1) y genera citas académicas con formato correcto.
🔬 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 propio del proyecto (Pāli + inglés, con un ancla de segmento que resalta el verso citado). El lector muestra 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 contexto como recursos.
📄 Páginas de referencia curadas en /topics/* — seis páginas markdown que cubren la estructura del canon, inicio rápido + selección de herramientas, lugares (Mahājanapada + sitios sagrados + cosmología), 10 temas fundamentales con locus classicus, ~30 figuras principales y una línea de tiempo por fases de la misión de 45 años del Buda. IDs de suttas verificados contra datos en vivo; los clientes de IA pueden obtener una página de una sola vez en lugar de ejecutar más de 30 llamadas de herramientas.
🤖 Habilidad para 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	Incrustaciones 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 ejecutan 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 tu 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 a continuación — sustituye YOUR_NPX_PATH con la salida del paso 1, y YOUR_NODE_BIN_DIR con el directorio padre 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 esquina inferior izquierda debería mostrar tripitaka con 12 herramientas disponibles.

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

Una vez conectado, intenta preguntarle 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 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 se ejecuta 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

Si la instalación falla así:

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

pipx está usando un intérprete diferente al que crees. Construye su propio entorno aislado a propósito e ignora cualquier venv que tengas activo — por lo que se elige un Python antiguo del sistema incluso cuando el shell en el que escribes tiene 3.12. Indícale cuál usar:

pipx install --python python3.12 tripitaka-mcp

(Cualquier versión 3.10 o más reciente funciona; pipx environment muestra a cuál recurre por defecto.)

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

¿Necesitas una URL en lugar de stdio? Algunas herramientas — scripts, notebooks, cualquier cosa que quiera compartir un servidor entre varios clientes — prefieren un endpoint HTTP en lugar de un subproceso:

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

Se vincula a 127.0.0.1 a menos que indiques lo contrario; el canon es de solo lectura, pero nada aquí pregunta quién llama, así que piensa antes de vincular una interfaz pública.

Alojado vs. local — cuál es la diferencia

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	trigrama PostgreSQL — difusa, tolerante a errores tipográficos, clasificada por similitud	SQLite FTS5 — coincidencia de palabra completa / token; los resultados y la clasificación pueden diferir del alojado
Datos del canon	siempre actuales	una instantánea de cuando 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 la 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 trigrama necesitan PostgreSQL + pgvector + un modelo de incrustación 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 permite 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.

🏎️ 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 a 4 horas (carga de datos + generación de incrustaciones) a unos ~5 minutos. (Si ya existe un archivo de volcado local, se usa la copia local en su lugar.)

El instalador:

Verificará que docker, compose, openssl y curl estén instalados
Generará .env con contraseñas aleatorias (tanto para el usuario administrador como para el de solo lectura)
Descargará el volcado desde Hugging Face (si aún no está 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 lista para pegar en Claude Desktop

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 pruebas 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 ni volver a ejecutar el modelo de incrustación, 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, sistema de archivos 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 frente a 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`	Autoalojaste 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 se enrutan a través de 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 por 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 por palabras clave con trigramas — ideal para los primeros resultados de una palabra exacta (`appamāda`, `ānāpānassati`).
`survey_corpus`	Exhaustiva encuesta del corpus — total exacto + desglose por pitaka + las formas de palabras coincidentes, para "cuántas veces / en cada lugar aparece X" (cobertura, no solo mejores coincidencias). `mode=thorough` añade recuperación semántica a nivel de conceptos.
`search_semantic`	Similitud vectorial pura — normalmente querrás `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 llama puede adjuntar una traducción automática de los segmentos mostrados al idioma del usuario (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 versiones 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 del diccionario de 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 de 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 aproximadas, no recomendadas
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
SuttaCentral bilara-data	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 (debido al 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.

Gratitud a:

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

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