ptx-mcp

Servidor MCP (Model Context Protocol) que lee texto de las Escrituras directamente desde carpetas de proyectos locales de Paratext (archivos USFM) y lo expone como herramientas que un LLM puede llamar.

Ejemplos de indicaciones compatibles

Una vez que el servidor esté instalado (ver más abajo), puedes hacer preguntas en lenguaje natural a Claude: él elige la herramienta y los argumentos correctos por sí solo.

• "¿Qué proyectos de Paratext tengo disponibles?"

• "¿Qué libros hay en el proyecto WEB?"

• "Muéstrame Génesis 1:1 de WEB."

• "Obtén Juan capítulo 3 de WEB."

• "Muéstrame todo el libro de Jonás de WEB."

• "Compara Génesis 1:1-5 en WEB y BTBK lado a lado."

• "Obtén Santiago 1 de WEB y BTBK juntos, y omite cualquier versículo que falte en cualquiera de los dos."

• "Lee Génesis 1:26 hasta 2:3 de BTBK."

• "¿Tiene BTBK una traducción del Evangelio de Juan? Si es así, muéstrame el capítulo 1."

Related MCP server: GetBible MCP

Advertencias

• Este código

  • Solo ha tenido pruebas muy limitadas hasta ahora. Funcionó para mí en Mac y Windows.

  • Solo se ha probado con Claude Desktop.

  • No admite acceso a proyectos de recursos de Paratext, por ejemplo, RVR80.

• Para que Claude pueda acceder a este servidor MCP de stdin, Claude debe estar ejecutándose en la máquina local, no en la nube.

  • Creo que esto significa que debes elegir la opción 'Chat' y NO la opción 'Cowork' al iniciar el chat. La opción Cowork parece (¿al menos a veces?) ejecutarse en un sandbox en la nube que no tiene acceso a la máquina local.

Requisitos

• Node.js 18+

  • Creo que esto se instala automáticamente cuando instalas Claude Desktop

• Una o más carpetas de proyectos de Paratext en el disco (cada una con un Settings.xml y archivos de libros USFM)

Configuración/Instalación

En Claude Desktop

• Haz clic en el botón con tu nombre en la esquina inferior izquierda

• Haz clic en 'Settings'

• Haz clic en 'Developers'

• Haz clic en 'Edit Config'

• Haz doble clic en 'claude_desktop_config.json' para abrir el editor

Edita 'claude_desktop_config.json' para agregar el servidor de la siguiente manera

{
  "mcpServers": {
    "ptx-mcp": {
      "command": "npx",
      "args": ["-y", "@milesnl/ptx-mcp"]
    }
  }
  ...
}

¡IMPORTANTE! Cierra y reinicia Claude para cargar el nuevo servidor MCP.

El paquete ptx-mcp se descargará automáticamente desde la biblioteca NPM la primera vez que le des un comando relacionado con Paratext a Claude.

Para probar la instalación, pregúntale a Claude: "Lista los proyectos de Paratext"

Solución de problemas de instalación

• Ve a la línea de comandos y prueba 'npx -y @milesnl/ptx-mcp'

  • El resultado exitoso es que se ejecuta y luego espera la entrada del terminal. Control C para terminar. Si imprime mensajes de error en su lugar, hay alguna razón por la que no podemos acceder al paquete NPM @milesn/ptx-mcp.

• Después de reiniciar Claude, ve a Settings/Developers. Esto debería mostrar ptx-mcp como un Servidor MCP Local. Si no, algo salió mal con la carga.

• Si dice "ptx-mcp falló", haz clic en "View Logs" para ver por qué.

Notas de instalación

Si tu carpeta My Paratext no está en la ubicación predeterminada, C:\My Paratext 9 Projects, necesitarás modificar "args" para incluir esa ubicación.

      "args": ["-y", "@milesnl/ptx-mcp", "/path/to/My Paratext 9 Projects"]

Para ejecutar ptx-mcp desde el código fuente en modo de desarrollo

Para ejecutar desde el código fuente instalado localmente

• cd /ruta/al/código/fuente

• git clone https://github.com/Nathan22Miles/PtxMCP

• cd PtxMCP

• npm install

Agrega a la configuración de tu cliente MCP (por ejemplo, claude_desktop_config.json).

"mcpServers": {
    "ptx-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "/path/to/PtxMCP"
      ]
    }
  }

Si no tienes Paratext instalado, puedes agregar '/ruta/al/código/fuente/PtxMCP/myParatextProjects' a args. Esto proporciona acceso al proyecto WEB.

Comandos MCP compatibles

Nota: En la mayoría de los casos no necesitas conocer estos comandos de bajo nivel. Claude traduce automáticamente tus solicitudes a este formato para acceder al MCP.

list-projects

Lista los ids de proyectos de Paratext (nombres de carpetas) que se encuentran bajo la raíz de proyectos.

list-books

Lista los códigos de libros USFM de 3 letras presentes en un proyecto dado.

• project — id del proyecto (nombre de la carpeta)

get-scripture

Devuelve el texto de los versículos para un libro, capítulo o rango de versículos de uno o más proyectos.

• projects — uno o más ids de proyectos de los cuales obtener texto

• book — código de libro USFM de 3 letras (por ejemplo, GEN, MAT, 1CO)

• startChapter / startVerse / endChapter / endVerse — opcional; omite los cuatro para el libro completo, omite los versículos para un capítulo completo, o especifica un rango completo (que puede abarcar capítulos)

• allowPartial — si es true, omite silenciosamente proyectos/libros/versículos faltantes en lugar de devolver un error

La salida es solo texto plano de versículos — sin encabezados de sección, títulos de libros, notas al pie, o referencias cruzadas — un versículo por línea, formateado como BOOK CHAPTER:VERSE text.

Cuando se solicitan múltiples proyectos, cada línea se prefija con el id del proyecto y los versículos se intercalan proyecto por proyecto:

WEB GEN 1:1 In the beginning God created the heavens and the earth.
BTBR GEN 1:1 In the beginning, when God began to create all things,

WEB GEN 1:2 The earth was formless and empty ...
BTBR GEN 1:2 the earth did not exist yet, there still was nothing...

Los puentes de versículos en el texto fuente (por ejemplo, \v 6-7) se devuelven como una sola línea etiquetada 6-7, no duplicados por número de versículo.

Desarrollo

npm install
npm run build   # compile TypeScript to dist/
npm test        # run the Vitest suite (uses the myParatextProjects/ fixture data)

Las pruebas leen datos de proyectos de Paratext de la carpeta myParatextProjects/.

Agradecimientos

Un agradecimiento especial a unfoldingWord por usfm-js, el analizador USFM del que depende este proyecto.

Por hacer

• Proporcionar instalación automática, por ejemplo, 'npx @milesnl/ptx-mcp --install'

• Probar con Gemini CLI, etc.