EGW Research

Complete offline research platform for Ellen Gould White's writings with PDF generation and Docker deployment

🚀 Quick Start with Docker

The fastest way to get started is with our pre-built Docker image:

# Pull and run the latest image
docker pull ghcr.io/gospelsounders/egw-writings-mcp/egh-research-server:latest
docker run -p 3000:3000 ghcr.io/gospelsounders/egw-writings-mcp/egh-research-server:latest

# Test the API
curl http://localhost:3000/health
curl http://localhost:3000/api/docs

🌐 Live API Documentation | 📚 Full Documentation

🌟 Overview

EGW Research is a comprehensive platform for offline research of Ellen Gould White's writings, providing both Model Context Protocol (MCP) and HTTP REST API access with advanced PDF generation capabilities.

Key Components

🔌 EGW Research Server: Dual-protocol server (MCP + HTTP API) with offline database
📥 Content Downloader: Bulk data extraction and database population tools
📊 Web Interface: Modern React-based research platform
🐳 Docker Deployment: Production-ready containerization with GitHub Actions

Core Features

⚡ Offline Operation: Complete independence from external services
🔍 Advanced Search: FTS5 full-text search with sub-millisecond response times
📄 PDF Generation: On-demand PDF creation with customizable formatting
🌐 Dual APIs: Both MCP and REST APIs for maximum compatibility
🐳 Docker Ready: Multi-architecture containers (AMD64, ARM64)
📱 Modern UI: Responsive web interface for research

📦 Architecture

├── apps/
│   ├── local-server/        # Main EGW Research Server (MCP + HTTP API)
│   ├── downloader/          # Data extraction and database tools
│   ├── api-server/          # Live API integration server
│   └── website/             # React-based research interface
├── packages/
│   ├── shared/              # Common utilities and database management
│   └── egw-pdf-generator/   # PDF generation engine
└── .github/workflows/       # CI/CD with Docker builds

🛠 Installation Options

Option 1: Docker (Recommended)

# Using Docker Run
docker pull ghcr.io/gospelsounders/egw-writings-mcp/egh-research-server:latest
docker run -p 3000:3000 ghcr.io/gospelsounders/egw-writings-mcp/egh-research-server:latest

# Using Docker Compose
curl -O https://raw.githubusercontent.com/GospelSounders/egw-writings-mcp/master/apps/local-server/docker-compose.yml
docker-compose up -d

Option 2: Global NPM Installation

# Install the research server
npm install -g @surgbc/egw-research-server

# Install supporting tools
npm install -g @surgbc/egw-writings-downloader

# Start the server
egw-research-server --http --port 3000

Option 3: Local Development

# Clone and setup
git clone https://github.com/surgbc/egh-research.git
cd egh-research
pnpm install && pnpm build

# Start HTTP server
cd apps/local-server
npm run start:http

# Or start MCP server
npm run start:mcp

🔧 Configuration

Environment Variables

NODE_ENV: Development/production mode
LOG_LEVEL: Logging verbosity (debug, info, warn, error)
PDF_CLEANUP_INTERVAL: PDF file cleanup frequency

MCP Client Configuration

{
  "mcpServers": {
    "egh-research": {
      "command": "egw-research-server"
    }
  }
}

Database Setup

# Download sample data
npx @surgbc/egw-writings-downloader quick-start --zip

# Or use the Make target (development)
make egw-quick-start

📖 API Reference

HTTP REST API

# Health and status
GET /health
GET /api/docs
GET /stats

# Content access
GET /content/books?page=1&limit=50&lang=en
GET /content/books/{id}
GET /content/books/{id}/toc
GET /search?q=righteousness&limit=20

# PDF generation
POST /content/books/{id}/generate-pdf
GET /pdf/status/{token}
GET /pdf/download/{token}

MCP Tools

search_local - Full-text search with FTS5 highlighting
get_local_book - Book information and metadata
get_local_content - Chapter and paragraph content
list_local_books - Paginated book listings
browse_by_reference - Navigation by EGW reference codes
get_context - Contextual paragraph retrieval
get_database_stats - Database metrics and statistics

📚 Complete API Documentation

🐳 Docker & Production

Production Deployment

# Pull latest production image
docker pull ghcr.io/surgbc/egh-research-server:latest

# Run with persistent storage and health checks
docker run -d \
  --name egh-research \
  -p 3000:3000 \
  -v egh-data:/app/apps/local-server/data \
  --restart unless-stopped \
  --health-cmd="curl -f http://localhost:3000/health || exit 1" \
  --health-interval=30s \
  ghcr.io/surgbc/egh-research-server:latest

Build from Source

# Build local image
./scripts/build-docker.sh --tag local

# Build with custom registry
./scripts/build-docker.sh --registry ghcr.io/yourname --tag v1.0.0

GitHub Actions

The project includes comprehensive CI/CD workflows:

🔨 Build & Test: Automated testing and building on push/PR
🐳 Docker Build: Multi-architecture container builds
📋 Security Scan: Vulnerability scanning with Trivy
📚 Documentation: Auto-deployment to GitHub Pages
🚀 Release: Automated releases with Docker publishing

📊 Performance & Capabilities

Search Performance

Sub-millisecond search response times
FTS5 full-text search with ranking
Highlighted search results with context
Reference navigation (e.g., "AA 15.1", "DA 123")

PDF Generation

Customizable formatting: Page size, fonts, margins
Table of contents: Automatic generation with configurable depth
Background processing: Non-blocking PDF generation
Progress tracking: Real-time generation status
Automatic cleanup: Scheduled file cleanup

Database Features

SQLite with FTS5 full-text search
Efficient storage with reference indexing
Multi-language support (150+ languages)
Offline operation - no internet required after setup

🎯 Use Cases

Research Applications

Academic research on Ellen Gould White's writings
Topic compilation across multiple books
Reference verification and cross-referencing
Contextual analysis with surrounding paragraphs

Educational Use

Classroom instruction with offline access
Student research projects with PDF generation
Study materials creation with custom formatting
Reference lookup during presentations

Technical Integration

MCP clients (Claude, etc.) for AI-assisted research
REST API integration for custom applications
Docker deployment for institutional use
Batch processing for large-scale analysis

🤝 Contributing

We welcome contributions! Here's how to get started:

Development Workflow

Fork the repository
Create a feature branch from main
Make your changes with tests
Run pnpm lint && pnpm build && pnpm test
Submit a pull request

Development Commands

# Setup development environment
pnpm install
pnpm build

# Run tests and linting
pnpm test
pnpm lint

# Start development servers
pnpm dev                    # All packages in watch mode
pnpm --filter local-server dev   # Just the research server
pnpm --filter website dev        # Just the web interface

# Build for production
pnpm build

# Docker development
./scripts/build-docker.sh --tag dev
docker run -p 3000:3000 egh-research-server:dev

📚 Educational and Research Use

This platform is designed specifically for educational and research purposes related to Ellen Gould White's writings. The software:

Respects intellectual property rights and fair use guidelines
Provides tools for legitimate academic research
Enables offline access for educational institutions
Supports citation and reference verification

Key Benefits for Researchers

Complete offline access - No dependency on external services
Advanced search capabilities - Find specific passages quickly
PDF generation - Create formatted documents for study
Reference cross-linking - Navigate between related content
Context preservation - Maintain surrounding content for accuracy

Academic Citation

When using this software in academic work, please cite:

EGW Research Platform. (2024). 
Offline research platform for Ellen Gould White's writings.
GitHub: https://github.com/surgbc/egw-research

🔒 Security & Privacy

No data collection: All processing happens locally
Open source: Fully auditable codebase
Security scanning: Automated vulnerability detection
Container security: Non-root user and minimal attack surface

📄 License

MIT License - Open source software for educational and research use.

See LICENSE for full terms.

🙋‍♂️ Support

📖 Documentation: https://surgbc.github.io/egh-research/
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions
📧 Email: Contact maintainers for security issues

Developed by surgbc • Built with ❤️ for educational and research purposes

pythondev-pro-egw_writings_mcp_server

Documentation