EGW Writings MCP Server

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

Docker Build NPM Package License: MIT

🚀 Quick Start

Start MCP Server Locally (Recommended)

# Clone the repository git clone https://github.com/pythondev-pro/egw_writings_mcp_server.git cd egw_writings_mcp_server # Install dependencies npm install # Start the local MCP server (with database warming) node apps/local-server/src/server-universal.js

Start EGW Chat CLI (Interactive Interface)

# In a new terminal, start the chat CLI cd egw_writings_mcp_server/egw-chat-cli # Start the HTTP-based chat CLI (recommended) - will prompt for API key node egw-chat-cli-http.js # Or start the stdio-based chat CLI - will prompt for API key node egw-chat-cli.js

🔐 API Key Security: The chat CLI will prompt you for your DeepSeek API key at the start of each session. Your API key is used only for that session and is not stored anywhere. Get your free API key at: https://platform.deepseek.com/

Quick Test Commands

# Test the MCP server is running curl http://localhost:3000/health # Test chat CLI connection cd egw_writings_mcp_server/egw-chat-cli && node egw-chat-cli-http.js # Then try: "give me a quote on love"

Start with Docker (Alternative)

# Pull and run 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

Start with Docker

# 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

🌐 | 📚

🌟 Overview

EGW Writings MCP Server 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 Writings MCP 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 Writings MCP 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

📚

🐳 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 Writings MCP Server. (2024). Offline research platform for Ellen Gould White'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