ptx-mcp

로컬 Paratext 프로젝트 폴더(USFM 파일)에서 성경 본문을 직접 읽어 LLM이 호출할 수 있는 도구로 노출하는 MCP(Model Context Protocol) 서버입니다.

지원되는 예시 프롬프트

서버가 설치되면(아래 참조) Claude에게 자연어 질문을 할 수 있습니다. Claude가 적절한 도구와 인수를 스스로 선택합니다.

• "사용 가능한 Paratext 프로젝트가 무엇인가요?"

• "WEB 프로젝트에는 어떤 책들이 있나요?"

• "WEB에서 창세기 1:1을 보여줘."

• "WEB에서 요한복음 3장을 가져와."

• "WEB에서 요나서 전체를 보여줘."

• "WEB과 BTBK에서 창세기 1:1-5를 나란히 비교해줘."

• "WEB과 BTBK에서 야고보서 1장을 함께 가져오고, 둘 중 하나에 없는 절은 건너뛰어."

• "BTBK에서 창세기 1:26부터 2:3까지 읽어줘."

• "BTBK에 요한복음 번역이 있나요? 있다면 1장을 보여줘."

Related MCP server: GetBible MCP

주의사항

• 이 코드는

  • 지금까지 매우 제한적으로만 테스트되었습니다. Mac과 Windows에서 작동하는 것을 확인했습니다.

  • Claude Desktop에서만 테스트되었습니다.

  • RVR80과 같은 Paratext 리소스 프로젝트 접근을 지원하지 않습니다.

• Claude가 이 stdin MCP 서버에 접근하려면 Claude가 클라우드가 아닌 로컬 머신에서 실행 중이어야 합니다.

  • 채팅 시작 시 'Cowork' 옵션이 아닌 'Chat' 옵션을 선택해야 한다고 생각합니다. 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 서버를 로드하려면 Claude를 닫고 다시 시작하세요.

ptx-mcp 패키지는 Claude에게 Paratext 관련 명령을 처음 내릴 때 NPM 라이브러리에서 자동으로 다운로드됩니다.

설치를 테스트하려면 Claude에게 "List Paratext projects"라고 물어보세요.

설치 문제 해결

• 명령줄로 이동하여 'npx -y @milesnl/ptx-mcp'를 실행해 보세요.

  • 성공하면 실행 후 터미널 입력을 기다립니다. Control C로 종료하세요. 대신 오류 메시지가 출력되면 @milesn/ptx-mcp NPM 패키지에 접근할 수 없는 이유가 있는 것입니다.

• Claude를 다시 시작한 후 Settings/Developers로 이동하세요. 여기에 ptx-mcp가 Local MCP Server로 표시되어야 합니다. 그렇지 않다면 로드 중 문제가 발생한 것입니다.

• "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 클라이언트의 config(예: claude_desktop_config.json)에 추가하세요.

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

Paratext가 설치되어 있지 않다면 '/path/to/source/PtxMCP/myParatextProjects'를 args에 추가할 수 있습니다. 이렇게 하면 WEB 프로젝트에 접근할 수 있습니다.

MCP 지원 명령

참고: 대부분의 경우 이러한 저수준 명령을 알 필요가 없습니다. Claude가 요청을 자동으로 이 형식으로 변환하여 MCP에 접근합니다.

list-projects

프로젝트 루트 아래에서 찾은 Paratext 프로젝트 ID(폴더 이름)를 나열합니다.

list-books

지정된 프로젝트에 있는 3글자 USFM 책 코드를 나열합니다.

• project — 프로젝트 ID(폴더 이름)

get-scripture

하나 이상의 프로젝트에서 책, 장 또는 절 범위에 대한 본문 텍스트를 반환합니다.

• projects — 텍스트를 가져올 하나 이상의 프로젝트 ID

• book — 3글자 USFM 책 코드(예: GEN, MAT, 1CO)

• startChapter / startVerse / endChapter / endVerse — 선택 사항; 전체 책은 네 개 모두 생략하고, 전체 장은 절을 생략하거나, 전체 범위(장을 넘을 수 있음)를 지정하세요.

• allowPartial — true이면 오류를 반환하는 대신 누락된 프로젝트/책/절을 조용히 생략합니다.

출력은 일반 본문 텍스트만 — 절 제목, 책 제목, 각주 또는 상호 참조 없음 — 절당 한 줄로, BOOK CHAPTER:VERSE text 형식입니다.

여러 프로젝트가 요청되면 각 줄 앞에 프로젝트 ID가 붙고 절은 프로젝트별로 인터리브됩니다:

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)

테스트는 myParatextProjects/ 폴더에서 Paratext 프로젝트 데이터를 읽습니다.

감사의 말

이 프로젝트가 의존하는 USFM 파서인 usfm-js를 제공한 unfoldingWord에 특별히 감사드립니다.

할 일

• 자동 설치 제공, 예: 'npx @milesnl/ptx-mcp --install'

• Gemini CLI 등으로 시도해 보기.