ptx-mcp

MCP-сервер (Model Context Protocol), который читает текст Писания непосредственно из локальных папок проектов Paratext (файлы USFM) и предоставляет его в виде инструментов, которые может вызывать LLM.

Примеры поддерживаемых запросов

После установки сервера (см. ниже) вы можете задавать Клоду вопросы на естественном языке — он сам выбирает нужный инструмент и аргументы.

• «Какие проекты Paratext у меня есть?»

• «Какие книги есть в проекте WEB?»

• «Покажи Бытие 1:1 из WEB.»

• «Получи Евангелие от Иоанна, глава 3, из WEB.»

• «Покажи всю книгу Ионы из WEB.»

• «Сравни Бытие 1:1-5 в WEB и BTBK бок о бок.»

• «Получи Иакова 1 из WEB и BTBK вместе, и пропусти стихи, которых нет ни в одном из них.»

• «Прочитай Бытие 1:26 по 2:3 из BTBK.»

• «Есть ли в BTBK перевод Евангелия от Иоанна? Если да, покажи главу 1.»

Related MCP server: GetBible MCP

Предостережения

• Этот код

  • Пока прошел лишь очень ограниченное тестирование. У меня он работал на Mac и Windows.

  • Был протестирован только с Claude Desktop.

  • Не поддерживает доступ к ресурсным проектам Paratext, например RVR80.

• Чтобы Клод мог получить доступ к этому MCP-серверу через stdin, Клод должен работать на локальной машине, а не в облаке.

  • Я думаю, это означает, что при запуске чата нужно выбрать опцию «Chat», а НЕ «Cowork». Опция «Cowork», похоже, (по крайней мере иногда?) работает в облачной песочнице, у которой нет доступа к локальной машине.

Требования

• Node.js 18+

  • Я думаю, он устанавливается автоматически при установке Claude Desktop

• Одна или несколько папок проектов Paratext на диске (каждая содержит Settings.xml и файлы книг USFM)

Настройка/Установка

В Claude Desktop

• Нажмите кнопку с вашим именем в левом нижнем углу

• Нажмите «Settings»

• Нажмите «Developers»

• Нажмите «Edit Config»

• Дважды щелкните «claude_desktop_config.json», чтобы открыть редактор

Отредактируйте «claude_desktop_config.json», добавив сервер следующим образом

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

ВАЖНО! Закройте и перезапустите Клода, чтобы загрузить новый MCP-сервер.

Пакет ptx-mcp будет автоматически загружен из библиотеки NPM при первом выполнении команды, связанной с Paratext, для Клода.

Чтобы проверить установку, спросите Клода: «Список проектов Paratext»

Устранение неполадок установки

• Перейдите в командную строку и попробуйте «npx -y @milesnl/ptx-mcp»

  • Успешный результат — запуск и ожидание ввода с терминала. Control C для завершения. Если вместо этого выводятся сообщения об ошибках, значит, есть причина, по которой мы не можем получить доступ к пакету NPM @milesn/ptx-mcp.

• После перезапуска Клода перейдите в Settings/Developers. Здесь ptx-mcp должен отображаться как локальный MCP-сервер. Если нет, что-то пошло не так при загрузке.

• Если написано «ptx-mcp failed», нажмите «View Logs», чтобы узнать причину.

Примечания по установке

Если ваша папка My Paratext находится не в месте по умолчанию, C:\My Paratext 9 Projects, вам нужно изменить «args», включив в них это расположение.

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

Запуск ptx-mcp из исходного кода в режиме разработки

Для запуска из локально установленного исходного кода

• cd /path/to/source

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

• cd PtxMCP

• npm install

Добавьте в конфигурацию вашего MCP-клиента (например, claude_desktop_config.json).

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

Если у вас не установлен Paratext, вы можете добавить '/path/to/source/PtxMCP/myParatextProjects' в args. Это обеспечит доступ к проекту WEB.

Поддерживаемые команды MCP

Примечание: В большинстве случаев вам не нужно знать эти низкоуровневые команды. Клод автоматически преобразует ваши запросы в этот формат для доступа к MCP.

list-projects

Выводит список идентификаторов проектов Paratext (имена папок), найденных в корне проектов.

list-books

Выводит список 3-буквенных кодов книг USFM, присутствующих в данном проекте.

• project — идентификатор проекта (имя папки)

get-scripture

Возвращает текст стихов для книги, главы или диапазона стихов из одного или нескольких проектов.

• projects — один или несколько идентификаторов проектов для получения текста

• book — 3-буквенный код книги USFM (например, GEN, MAT, 1CO)

• startChapter / startVerse / endChapter / endVerse — необязательно; опустите все четыре для всей книги, опустите стихи для целой главы или укажите полный диапазон (который может охватывать несколько глав)

• allowPartial — если true, молча пропускает отсутствующие проекты/книги/стихи вместо возврата ошибки

Вывод — только обычный текст стихов — без заголовков разделов, названий книг, сносок или перекрестных ссылок — по одному стиху на строку, в формате BOOK CHAPTER:VERSE text.

Когда запрашивается несколько проектов, каждая строка имеет префикс с идентификатором проекта, и стихи чередуются по проектам:

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

Стиховые мосты в исходном тексте (например, \v 6-7) возвращаются одной строкой с пометкой 6-7, а не дублируются по номеру стиха.

Разработка

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

Тесты читают данные проектов Paratext из папки myParatextProjects/.

Благодарности

Особая благодарность unfoldingWord за usfm-js, парсер USFM, на который опирается этот проект.

В планах

• Предоставить автоматическую установку, например 'npx @milesnl/ptx-mcp --install'

• Попробовать с Gemini CLI и т.д.