TheologAI: Instructions file for Claude Code

TheologAI — Development Guide

This developer guide is not release-identity authority. For the sole active production and preview-control snapshot, see docs/CURRENT-RELEASE.md; release identities below are dated historical evidence.

Production MCP server for theological research. Eleven tools, six prompts, eight Bible translations, six commentaries, 35 historical documents and works, Greek/Hebrew language tools, and on-chain donation support. Tools, resources, and prompts are available on every transport; MCP Logging is stdio-only because HTTP is stateless.

Quick Start

npm run dev          # Start dev server (stdio, tsx watch)
npm run build        # TypeScript compile + copy data to dist/
npm run build:db     # Rebuild SQLite database from source data
npm test             # Run all tests (vitest)
npm run test:unit    # Unit tests only
npm start            # Production server (requires build first)

Set PORT=3000 in .env for HTTP transport; omit for stdio.

Architecture

src/
├── index.ts              # Entry point — stdio or HTTP transport (Node.js)
├── worker.ts             # Entry point — Cloudflare Workers (Streamable HTTP)
├── server.ts             # Node wrapper around the shared MCP registrar
├── worker-server.ts      # Worker wrapper around the shared MCP registrar
├── mcp/                  # Shared tools/resources/prompts, schemas, and errors
├── http/                 # Node and Worker transport policies
├── worker-env.ts         # Env type for Workers bindings (D1, secrets, vars)
├── tools/v2/             # Tool handlers + Node.js composition root
│   └── index.ts          # createCompositionRoot() — Node.js wiring (better-sqlite3)
├── tools/worker/         # Workers composition root
│   └── index.ts          # createWorkerCompositionRoot() — D1 wiring (per-request)
├── services/             # Business logic — async, works with both SQLite and D1
│   ├── bible/            # BibleService, CrossReferenceService, ParallelPassageService
│   ├── commentary/       # CommentaryService
│   ├── historical/       # HistoricalDocumentService
│   ├── languages/        # StrongsService, MorphologyService
│   └── donation/         # DonationService
├── adapters/             # External API clients + data repositories
│   ├── bible/            # EsvAdapter, NetBibleAdapter, HelloAoAdapter
│   ├── commentary/       # HelloAoCommentaryAdapter, metadata-only CcelSearchAdapter
│   ├── donation/         # OnChainVerifier
│   ├── data/             # SQLite repositories (Node.js — better-sqlite3)
│   ├── d1/               # D1 repositories (Workers — Cloudflare D1)
│   └── shared/           # Database.ts, HttpClient.ts, HtmlParser.ts
├── formatters/           # Pure Markdown formatting functions
├── kernel/               # Shared domain primitives
│   ├── reference.ts      # THE canonical Bible reference parser
│   ├── books.ts          # 66-book registry with all external format codes
│   ├── repositories.ts   # Async repository interfaces (shared by SQLite + D1)
│   ├── types.ts          # Shared TypeScript interfaces
│   ├── errors.ts         # Typed error hierarchy
│   └── cache.ts          # Generic LRU cache with TTL
└── data/                 # Compiled data (parallel-passages.json)

data/                     # Source data files
├── theologai.db          # SQLite database (built from source data)
├── biblical-languages/   # Strong's concordance, STEPBible morphology/lexicons
├── cross-references/     # OpenBible.info cross-reference TSV
├── historical-documents/ # 17 legacy creeds, confessions, catechisms (JSON)
└── historical-source-packs/ # 18 reviewed, sectioned-only source-pack editions

skills/                   # Agent skill workflows
├── word-study/           # Greek/Hebrew word study methodology
├── passage-exegesis/     # Systematic exegetical analysis
└── confession-study/     # Cross-tradition doctrinal comparison

test/
├── unit/                 # Fast unit, contract, parity, and boundary tests
│   ├── kernel/           # reference, books, cache, errors (94 tests)
│   ├── formatters/       # bibleFormatter, commentary, historical, languages (75 tests)
│   ├── services/         # bible/, commentary/, historical/, languages/, async-compat/ (64 tests)
│   ├── adapters/d1/      # D1 repository tests (61 tests)
│   ├── tools/worker/     # Worker composition root (11 tests)
│   └── worker/           # Worker entry point and policy tests
├── integration/current/  # Shared Node/Worker MCP contract tests
├── worker-runtime/       # Real Workerd endpoint with isolated D1
├── helpers/              # Reusable test utilities (mockD1.ts)
├── fixtures/             # Shared test data
└── setup.ts              # Global test config