EGH Research

Complete offline research platform for Ellen Gould Harmon'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

Related MCP server: theosis-mcp

🌟 Overview

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

Key Components

• 🔌 EGH 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 EGH 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 Harmon'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

1. Fork the repository

2. Create a feature branch from main

3. Make your changes with tests

4. Run pnpm lint && pnpm build && pnpm test

5. 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 Harmon'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:

EGH Research Platform. (2024). 
Offline research platform for Ellen Gould Harmon's writings.
GitHub: https://github.com/surgbc/egh-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