Translation Helps MCP Server v6.6.3

🚨 MAJOR UPDATE: 100% Real Data - Zero Mock Fallbacks

A comprehensive MCP (Model Context Protocol) server that provides AI agents with access to Bible translation resources from Door43's Content Service (DCS). This server enables AI assistants to fetch, process, and intelligently work with translation helps including scripture texts, translation notes, translation words, and translation questions.

🎉 What's New in v6.6.3

Complete Architecture Overhaul

✅ 100% Real Data - All mock data removed, every endpoint fetches from DCS
✅ Unified Architecture - Single UnifiedResourceFetcher class handles all data
✅ Markdown Support Everywhere - All endpoints support format=md for LLMs
✅ Wrangler-Only Testing - Standardized on port 8787 with real KV/R2 bindings
✅ No Mock Fallbacks - Real errors instead of fake success

Breaking Changes

Removed Endpoints:

/api/fetch-ult-scripture → Use fetch-scripture?resource=ult
/api/fetch-ust-scripture → Use fetch-scripture?resource=ust
/api/fetch-resources → Use specific endpoints
/api/resource-recommendations → Removed completely
/api/language-coverage → Removed completely
/api/get-words-for-reference → Use fetch-translation-words

See MIGRATION_GUIDE.md for detailed migration instructions.

🚀 Key Features

Core Translation Resources

Scripture Texts: Multiple translations (ULT, UST, T4T, UEB) with real-time DCS fetching
Translation Notes: Verse-by-verse explanations from TSV data
Translation Words: Biblical term definitions from markdown files
Translation Word Links: Connections between scripture and word articles
Translation Questions: Comprehension questions from TSV data
Translation Academy: Training modules for translators

🤖 MCP Prompts (NEW!)

Guided workflows that teach AI assistants to chain tools intelligently:

translation-helps-for-passage - Get everything: scripture + notes + questions + words (with titles) + academy articles
get-translation-words-for-passage - Show dictionary entry titles (not technical IDs)
get-translation-academy-for-passage - Find training articles referenced in notes

📖 Complete Usage Guide → | 📚 Technical Docs →

Why prompts matter:

One command replaces 6-10 tool calls
Shows human-readable titles instead of IDs
Standardizes best practices for translation workflows
Makes AI assistants much smarter about Bible translation

Technical Excellence

Real Data Only: No mock data, no fake responses, no fallbacks
Unified Fetcher: Single class (UnifiedResourceFetcher) for all resources
Smart Caching: KV for catalogs, R2 for ZIPs, Cache API for extracted files
Format Support: JSON, Markdown, Text, and TSV (where applicable)
Cloudflare Pages: Global edge deployment with sub-100ms response times

🌟 Deployment

Live Production

API Base: https://tc-helps.mcp.servant.bible/api/
Documentation: https://tc-helps.mcp.servant.bible/
Health Check: https://tc-helps.mcp.servant.bible/api/health

Quick Start

# Fetch scripture
curl "https://tc-helps.mcp.servant.bible/api/fetch-scripture?reference=John%203:16"

# Get translation notes in markdown (for LLMs)
curl "https://tc-helps.mcp.servant.bible/api/translation-notes?reference=Genesis%201:1&format=md"

# Fetch translation word links
curl "https://tc-helps.mcp.servant.bible/api/fetch-translation-word-links?reference=Titus%201:1"

# Browse translation academy modules
curl "https://tc-helps.mcp.servant.bible/api/browse-translation-academy?language=en"

🛠️ Architecture

Unified Data Fetching

All endpoints use the same architecture:

API Endpoint → createSimpleEndpoint → UnifiedResourceFetcher → ZipResourceFetcher2 → DCS

Key Components:

UnifiedResourceFetcher - Single interface for all resource types
ZipResourceFetcher2 - Handles ZIP archives with intelligent caching
createSimpleEndpoint - Standardized endpoint creation pattern
Real Error Handling - No mock fallbacks, actual error messages

Caching Strategy

DCS API → KV Cache (1hr TTL) → Catalog Metadata
        ↓
     R2 Storage → ZIP Files
        ↓
    Cache API → Extracted Files

🚨 Production Setup

⚠️ CRITICAL: R2 bucket must be populated with ZIP files for production to work!

See R2 Setup Guide for instructions on populating the R2 bucket.

🧪 Testing with Wrangler

⚠️ IMPORTANT: All tests MUST use Wrangler for KV/R2 functionality

Setup

# Start Wrangler (REQUIRED for tests)
cd ui && npx wrangler pages dev .svelte-kit/cloudflare --port 8787

# In another terminal, run tests
npm test

Test Configuration

Port: Always 8787 (enforced by test setup)
Bindings: Real KV and R2 bindings
No Mocks: Tests use real Cloudflare services

See tests/TESTING_REQUIREMENTS.md for details.

📚 API Documentation

Scripture Endpoints

# Fetch multiple translations
GET /api/fetch-scripture?reference=John%203:16&resource=ult,ust

# Response format options
GET /api/fetch-scripture?reference=John%203:16&format=md    # Markdown
GET /api/fetch-scripture?reference=John%203:16&format=text  # Plain text