圣经文本分析服务器

Context-Fabric MCP

Biblical text analysis server powered by Context-Fabric, providing morphologically annotated Hebrew Bible (BHSA) and Greek New Testament (Nestle 1904) data via both an MCP (Model Context Protocol) interface and a REST API.

Features

• Hebrew Bible -- 39 books (Genesis--2 Chronicles) with full morphological annotation from ETCBC/bhsa
• Greek New Testament -- 27 books (Matthew--Revelation) from ETCBC/nestle1904
• Passage retrieval -- verse-level text with per-word lexeme, gloss, part of speech, and morphological features
• Morphological search -- find words by part of speech, verbal stem, tense, gender, number, person, state, and more
• Structural search -- find syntactic patterns (clauses, phrases) using search templates
• Vocabulary extraction -- unique lexemes in a passage sorted by corpus frequency
• LLM chat -- agentic conversation powered by Groq (GPT-OSS 120B, free tier) with optional OpenAI fallback; can call all the above tools
• Quiz generation -- configurable quiz engine for Hebrew morphology drills
• AI-assisted quiz builder -- teachers describe a quiz in natural language and the AI builds a validated quiz definition
• Dual interface -- same engine exposed as MCP tools (for AI assistants) and as a FastAPI HTTP API (for web frontends)

Quick Start

# Clone and set up
git clone https://github.com/larsgson/context-fabric-mcp.git
cd context-fabric-mcp
cp .env.example .env   # configure API keys

# Start the REST API server
uv run cf-api

The API runs at http://localhost:8000. The first request loads corpus data into memory (~2s with cached data).

Run as MCP server

uv run cf-mcp

This starts the MCP (Model Context Protocol) server for use with Claude Desktop or other MCP-compatible clients.

Client Demo

A working client application that uses this server as its backend is available at biblical-text-quizz-generator. It is a web-based quiz tool for biblical Hebrew and Greek morphology, demonstrating how a frontend can consume the REST API endpoints (passage retrieval, morphological search, quiz generation, and AI-assisted quiz building) provided by this server.

API Endpoints

Book identifiers

Books are identified by their three-letter USFM code (GEN, PSA, 1SA, MAT, ...) in both corpora. Responses return book (the code) and book_name (the display name, English for now).

On input, the book parameter also accepts English names (Psalms, 1 Samuel) and the Latin names used by BHSA (Psalmi), case-insensitively. An unknown book returns 404 with a suggestion. The mapping lives in src/context_fabric_mcp/books.py.

To search within a passage, pass book (and optionally chapter, verse_start, verse_end) to /api/search/constructions or /api/search/advanced and send only the pattern as template; the server nests it inside the scope. A template that repeats the scope returns 400.

If you write the scope by hand instead, a plain book=<name> on a book, chapter or verse line is rewritten to the corpus's own form (the raw Hebrew book feature is Latin), so book=PSA, book=Psalms and book=Psalmi all work. More complex constraints (alternation, negation, regex, book@en=) are passed through untouched.

MCP Tools

When running as an MCP server, the following tools are available to AI assistants:

• list_corpora, list_books, get_schema -- corpus introspection
• get_passage, get_word_context -- text retrieval
• search_words, search_constructions -- linguistic search
• search_advanced, search_comparative -- advanced search with statistics and cross-corpus comparison
• search_syntax_guide -- search template syntax documentation
• describe_feature, list_features -- feature discovery with sample values
• list_edge_features, get_edge_features -- linguistic relationship exploration
• compare_distribution -- feature distribution comparison across sections
• get_lexeme_info, get_vocabulary -- vocabulary queries
• build_quiz -- build and validate a quiz definition (returns JSON, no server-side storage)

Project Structure

src/context_fabric_mcp/
├── server.py          # MCP server entry point
├── api.py             # FastAPI HTTP layer
├── cf_engine.py       # Context-Fabric data access
├── chat.py            # Groq + OpenAI fallback LLM integration
├── models.py          # Pydantic data models
├── quiz_engine.py     # Quiz generation engine
├── quiz_models.py     # Quiz data models
└── tools/             # MCP tool definitions
    ├── passage.py
    ├── schema.py
    ├── search.py
    ├── vocab.py
    └── quiz.py
tests/
├── test_api.py
├── test_cf_engine.py
└── test_quiz.py

AI-Assisted Quiz Builder

Teachers can create quizzes in two ways:

Via the REST API (for web frontends)

POST /api/chat-quiz accepts a natural language description and returns a validated quiz definition:

{
  "message": "Create a quiz on qal perfect verbs in Genesis 1-3, showing the gloss and asking for verbal stem and tense"
}

The AI explores the text, builds a QuizDefinition, validates it against the corpus, and returns the definition with a preview. The frontend can then save it via POST /api/quizzes.

Via MCP (for AI assistants like Claude Desktop)

The build_quiz tool lets an AI assistant build quiz definitions interactively. The teacher describes what they want, the AI explores passages with search_words and get_passage, then calls build_quiz to produce a validated definition. The result is returned as portable JSON -- nothing is stored on the server.

Testing

uv run pytest

Tests require corpus data on first run (cached in ~/text-fabric-data/).

Configuration

Deployment

See DEPLOYMENT.md for full instructions on deploying to Fly.io, Railway, or Docker.

# Docker
docker build -t context-fabric-mcp .
docker run -p 8000:8000 context-fabric-mcp

License

MIT