obs-5m-mcp

MCP server for Open Bible Stories + Theological Formation (Five Movements).

Content resolution: DCS catalog subject=OBS Theological Formation + topic=tc-ready (same defaults as Translation Helps MCP). English comes from Door43 unfoldingWord/en_obs_tf. When DCS has no entry (Indonesian today), tools use extracted text from self-hosted PDFs (R2) — not just a download link (bt-servant-engine#215).

Implements the study-manual surface requested in translation-helps-mcp#36 via fetch_obs_study_manual.

Content license: CC BY-SA 4.0 (unfoldingWord / partners).

Quick start

npm install
npm test                 # unit + contracts
npm run test:unit
npm run test:contracts
npm run dev              # http://localhost:8790
# Chat UI (needs OPENAI_API_KEY in .dev.vars):
#   http://localhost:8790/chat
# with wrangler running:
npm run test:smoke

Copy .dev.vars.example → .dev.vars and set OPENAI_API_KEY for the chat UI. Deployed: wrangler secret put OPENAI_API_KEY.

Endpoints:

Tests & X-ray

Modeled on translation-helps-mcp:

X-ray (pipeline transparency): POST /api/tool with "debug": true returns { result, xray, xrayReport }. Open /debug for an interactive panel. Chat also supports X-ray via the checkbox on /chat (or "debug": true on /api/chat).

Chat (LLM + MCP tools)

Cloned from Translation Helps /chat (SvelteKit + ChatDock + X-ray), rewired for OBS study-for-translation instead of scripture/TN/TW.

# Terminal A — MCP worker (tools, PDFs, docs)
npm run dev

# Terminal B — Svelte chat (primary UI)
npm run dev:web
# → http://localhost:8174/chat

• Study / Translate / Check map onto OBS sessionFlow parts (not Bible workflow modes).

• Session side panel replaces the TH Helps/scripture panel with Five Movements parts.

• API: web/src/routes/api/chat → src/chat/chatHandler + in-process TOOL_REGISTRY (OBS tools).

• Worker :8790/chat still serves a slim HTML fallback if the Svelte app is not running.

Related MCP server: Bible MCP

Tools

Discovery: list_languages, list_resources, list_collections, list_stories
Study manual (#36): fetch_obs_study_manual
Helpers: get_framework, get_story, get_movement, get_devotional, get_study_guide, search_content
PDFs: get_pdf (Indonesian pack)

fetch_obs_study_manual (preferred for BT Servant)

{
  "tool": "fetch_obs_study_manual",
  "arguments": {
    "reference": "1:1",
    "language": "en",
    "movement": 1,
    "format": "json"
  }
}

Returns intro, frames, Community Study, Observation / Translation / Discourse / Theological / Journal, drafting, checking, Ministry / Mission, and conclusion — packaging resolved (shared TX and story-inline look the same). Response includes sections and sessionFlow for agent routing.

Related Translation Helps issues (out of scope here)

Indonesian PDFs → OBS-TF markdown (DCS fallback)

Used only when catalog search finds no OBS Theological Formation for id.

Canonical pipeline: PDF → font-aware plain MD → DCS-shaped MD (do not convert from coarse txt when plain MD is available).

# 1) PDF → plain MD (headings, **NN-NN** frames)
npm run plain-md -- --story=1
# 2) plain MD → en_obs_tf-shaped MD + transclusions
npm run convert:id -- --story=1
# Or generate missing plain MD then convert all:
npm run convert:id:from-pdf
# Force re-extract plain MD from PDF, then convert:
npm run convert:id -- --regen-plain --story=1

Setup steps:

1. Download the zip from bt-servant-engine#215 (or Google Drive).

2. Unpack PDFs into data/incoming/ (names like OBS 1 (Indonesia).pdf).

3. Optional txt fallback: npm run ingest:id -- --text-only → data/indonesian-text.json

4. Run the canonical pipeline above → data/obs-tf-md/id/obs_story_N.md with unique sections (community study, divergent movements) inlined, shared movement/conclusion as ![[…]] transclusions, plus structure-report.json (soft metrics: translation terms, skeleton flags, shared-tx drift).

5. --offline uses the story-1 fixture for DCS compare when network is unavailable.

6. Upload PDF + text to R2: npm run ingest:id or --local for wrangler dev.

Structure cues live in data/structure-maps/id.json. Runtime prefers converted MD (sourceKind: local-md) over coarse PDF text. get_pdf still returns the file URL and extracted text.

Export a Door43 repo tree

After convert, build an upload-ready Resource Container folder (manifest + stories + transclusions):

npm run export:dcs
# or regenerate convert first:
npm run export:dcs -- --convert
# custom output:
npm run export:dcs -- --out=./tmp/id_obs_tf --force

Output: exports/id_obs_tf/ (gitignored). Create an empty Door43 repo, then git init / push from that folder — see exports/id_obs_tf/README.md.

Cloudflare setup

This app deploys as a Cloudflare Worker (MCP Durable Object + Workers Assets for the Ezer chat UI). That is the right host for MCP — not a static Pages site alone.

npx wrangler kv namespace create OBS_5M_CACHE
npx wrangler kv namespace create OBS_5M_CACHE --preview
# Optional (Indonesian PDF hosting) — enable R2 in the dashboard first:
npx wrangler r2 bucket create obs-5m-mcp-assets

Paste the KV ids into wrangler.toml, set PUBLIC_BASE_URL, then:

npm run deploy
npx wrangler secret put OPENAI_API_KEY

Chat: https://<worker>/chat · MCP: https://<worker>/mcp

BT Servant registration

1. Deploy this worker.

2. Register the MCP URL (https://<worker>/mcp) in BT Servant admin (see bt-servant-worker curl examples).

3. Responses include _meta.downstream_api_calls and _meta.cache_status per MCP integration guidelines.

4. Smoke: fetch_obs_study_manual with reference: "1:1", language: "en"; list_resources for id + get_pdf.

Architecture

Modeled on translation-helps-mcp v2: Cloudflare Worker + McpAgent Durable Object, Zod tools, RESOURCE_NOT_AVAILABLE with isError: false.