SDKs
Two clients wrap the MCP calls, so a script or an app can use the tools without speaking the
protocol. One is for JavaScript and TypeScript, one is for Python. They live in the repository
under packages/.
These are the 2.0 clients. They are not on npm or PyPI yet: the packages published there under the same names are the older 1.x clients, which have other methods. Until 2.0 is published, install it from the repository, as shown below.
Give each client the server address. The examples below show this site’s own address. The clients also have a built-in default address; pass yours so that you know which server answers.
JavaScript and TypeScript
@translation-helps/mcp-client, MIT licence. It has a typed method for each tool and
helpers to read the answer. Source and README
# The 2.0 client is not on npm yet: build it from the repository.
git clone --branch v2 https://github.com/unfoldingWord/translation-helps-mcp.git
cd translation-helps-mcp && npm install
npm run build --workspace packages/js-sdk
# Then, in your project:
npm install ../translation-helps-mcp/packages/js-sdkPython
translation-helps-mcp-client. The command below installs httpx with it,
so both clients work: TranslationHelpsClient (synchronous) and AsyncTranslationHelpsClient. No extra install is needed for the async client. Source and README
# The 2.0 client is not on PyPI yet: install it from the repository.
pip install "git+https://github.com/unfoldingWord/translation-helps-mcp.git@v2#subdirectory=packages/python-sdk"One method for each tool
Both clients follow the workflow: the method names are the tool names. Arguments are the ones on the tools page.
| Tool | JavaScript | Python |
|---|---|---|
| list_languages | listLanguages() | list_languages() |
| list_resources | listResources() | list_resources() |
| search_articles | searchArticles() | search_articles() |
| get_passage | getPassage() | get_passage() |
| get_passage_context | getPassageContext() | get_passage_context() |
| get_passage_index | getPassageIndex() | get_passage_index() |
| get_questions | getQuestions() | get_questions() |
| get_note | getNote() | get_note() |
| get_academy_article | getAcademyArticle() | get_academy_article() |
| get_word_article | getWordArticle() | get_word_article() |
| get_obs_story | getObsStory() | get_obs_story() |
| get_obs_notes | getObsNotes() | get_obs_notes() |
| get_obs_index | getObsIndex() | get_obs_index() |
| get_obs_questions | getObsQuestions() | get_obs_questions() |
| get_obs_study_notes | getObsStudyNotes() | get_obs_study_notes() |
| get_obs_study_questions | getObsStudyQuestions() | get_obs_study_questions() |
Reading an answer
An answer has content (text), structuredContent (the data, which both
helpers prefer), and isError. When a language or book lacks a resource, the answer is
not an error: isError is false and the data says available: false. The
helper isResourceNotAvailable (Python: is_resource_not_available) tests
for it. Limits and errors lists the codes.
Library packages
The repository holds two more packages under @translation-helps/.
door43: the code the server uses to read Door43. It searches the catalog, downloads a resource’s ZIP file, and parses USFM and TSV into verses, notes, questions and articles. It is an internal workspace package, not published to npm. Sourceshared-prompts: retired. Its system prompts moved into the two clients above. Notes