Docs: SDKs

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

Python

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.

ToolJavaScriptPython
list_languageslistLanguages()list_languages()
list_resourceslistResources()list_resources()
search_articlessearchArticles()search_articles()
get_passagegetPassage()get_passage()
get_passage_contextgetPassageContext()get_passage_context()
get_passage_indexgetPassageIndex()get_passage_index()
get_questionsgetQuestions()get_questions()
get_notegetNote()get_note()
get_academy_articlegetAcademyArticle()get_academy_article()
get_word_articlegetWordArticle()get_word_article()
get_obs_storygetObsStory()get_obs_story()
get_obs_notesgetObsNotes()get_obs_notes()
get_obs_indexgetObsIndex()get_obs_index()
get_obs_questionsgetObsQuestions()get_obs_questions()
get_obs_study_notesgetObsStudyNotes()get_obs_study_notes()
get_obs_study_questionsgetObsStudyQuestions()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. Source
  • shared-prompts: retired. Its system prompts moved into the two clients above. Notes