EGH Research

# EGW Writings MCP Server **Model Context Protocol server for Ellen Gould White writings with offline API and PDF generation capabilities** [](https://github.com/surgbc/egh-research/actions/workflows/docker-build.yml) [](https://github.com/surgbc/egh-research/actions/workflows/ci.yml) ## Overview The EGW Writings MCP Server provides both **Model Context Protocol (MCP)** and **HTTP REST API** access to a locally stored database of Ellen Gould White's writings. This enables offline research capabilities with fast search, content retrieval, and on-demand PDF generation. ## 🚀 Quick Start ### Start MCP Server (Recommended) ```bash # Clone and start immediately git clone https://github.com/pythondev-pro/egw_writings_mcp_server.git cd egw_writings_mcp_server npm install node apps/local-server/src/server.smithery.js ``` ### Start with Docker ```bash # Pull and run the latest image docker pull ghcr.io/surgbc/egh-research-server:latest docker run -p 3000:3000 ghcr.io/surgbc/egh-research-server:latest # Access the API curl http://localhost:3000/health ``` ### Using Docker Compose ```bash # Download docker-compose.yml curl -O https://raw.githubusercontent.com/surgbc/egh-research/main/apps/local-server/docker-compose.yml # Start the service docker-compose up -d # Check status docker-compose ps ``` ## 🌟 Features ### **Dual Protocol Support** - **MCP Server**: For Claude and other MCP clients - **HTTP REST API**: Standard web API with full compatibility ### **Research Capabilities** - **Offline Database**: Complete independence from internet connectivity - **Full-text Search**: Advanced FTS5 search with sub-millisecond response times - **Reference Navigation**: Browse by EGW reference codes (e.g., "AA 15.1", "DA 123") - **Context Retrieval**: Get surrounding paragraphs for better understanding - **Content Statistics**: Comprehensive database metrics ### **PDF Generation** - **On-demand PDF creation** with customizable formatting - **Background processing** with real-time progress tracking - **Configurable options**: Page size, fonts, margins, table of contents - **Multiple download formats** and automatic cleanup ### **Production Ready** - **Docker containerization** with multi-architecture support (AMD64, ARM64) - **Health monitoring** and observability endpoints - **Automatic builds** via GitHub Actions - **Security scanning** and dependency management ## 📖 API Documentation ### Health Check ```bash GET /health ``` ### API Documentation ```bash GET /api/docs ``` ### Search Content ```bash GET /search?q=righteousness&limit=10 ``` ### List Books ```bash GET /content/books?page=1&limit=50&lang=en ``` ### Generate PDF ```bash POST /content/books/123/generate-pdf Content-Type: application/json { "config": { "pageSize": "A4", "fontSize": 12, "fontFamily": "Times" } } ``` ### Check PDF Status ```bash GET /pdf/status/{token} ``` ### Download PDF ```bash GET /pdf/download/{token} ``` ## 🛠 Development Setup ### Prerequisites - **Node.js 18+** - **npm** or **pnpm** package manager - **Docker** (optional, for containerized deployment) ### Local Development #### Option 1: Quick Start with Pre-built Database ```bash # 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 MCP server (database is already included) node apps/local-server/src/server.smithery.js ``` #### Option 2: Full Development Setup with Database Download ```bash # Clone the repository git clone https://github.com/pythondev-pro/egw_writings_mcp_server.git cd egw_writings_mcp_server # Install dependencies npm install # Build the project npm run build # Download and populate the database node apps/downloader/dist/index.js quick-start --zip # Start the MCP server node apps/local-server/src/server.smithery.js # Or start the HTTP server instead node apps/local-server/src/server.smithery.js --http ``` #### Option 3: Using Package Scripts ```bash # Clone and install git clone https://github.com/pythondev-pro/egw_writings_mcp_server.git cd egw_writings_mcp_server npm install # Build all packages npm run build # Start MCP server npm run start:mcp # Or start HTTP server npm run start:http ``` ### Database Setup #### Method 1: Use Included Database (Recommended) The project comes with a pre-populated database in `apps/local-server/data/egw-writings.db`. No additional setup required. #### Method 2: Download Fresh Database If you want to download the latest data: ```bash # Using the downloader tool npx @surgbc/egw-writings-downloader quick-start --zip # Or build and run locally cd apps/downloader npm run build node dist/index.js quick-start --zip ``` #### Method 3: Manual Database Setup ```bash # Navigate to downloader cd apps/downloader # Download and parse data npm run download -- --source https://egwdata.org --output ../local-server/data/ # Build the SQLite database npm run download -- --build-db --input ../local-server/data/ --output ../local-server/data/egw-writings.db ``` ### Running the MCP Server #### Direct Execution ```bash # From project root node apps/local-server/src/server.smithery.js # From local-server directory cd apps/local-server node src/server.smithery.js ``` #### Using npm scripts ```bash # From local-server directory npm run start:mcp ``` #### Running as MCP Client with Claude 1. Configure your MCP client (e.g., Claude Desktop) to use this server: ```json { "mcpServers": { "egw-research": { "command": "node", "args": ["path/to/egw_writings_mcp_server/apps/local-server/src/server.smithery.js"] } } } ``` 2. Restart Claude Desktop 3. The EGW Writings tools will be available in your Claude interface ### Running the HTTP Server #### Start HTTP Server ```bash # From project root node apps/local-server/src/server.smithery.js --http # Or using npm script cd apps/local-server npm run start:http ``` #### Test HTTP Server ```bash # Health check curl http://localhost:3000/health # Search content curl "http://localhost:3000/search?q=righteousness&limit=5" # List books curl "http://localhost:3000/content/books?limit=10" ``` ### Development Workflow #### Watch Mode for Development ```bash # For TypeScript development with auto-reload cd apps/local-server npm run dev:mcp # MCP server with watch npm run dev:http # HTTP server with watch ``` #### Building the Project ```bash # Build all packages npm run build # Build specific package cd apps/local-server npm run build ``` #### Running Tests ```bash # Run all tests npm test # Test specific functionality node apps/local-server/src/test-final-integration.cjs ``` ## 🐳 Docker ### Build Local Image ```bash # From project root ./scripts/build-docker.sh --tag local # Run locally built image docker run -p 3000:3000 egh-research-server:local ``` ### Production Deployment ```bash # Production image from GitHub Container Registry docker pull ghcr.io/surgbc/egh-research-server:latest # Run with persistent data volume docker run -d \ --name egh-research \ -p 3000:3000 \ -v egh-data:/app/apps/local-server/data \ ghcr.io/surgbc/egh-research-server:latest ``` ## 🔧 Configuration ### Environment Variables - `NODE_ENV`: Development/production mode - `LOG_LEVEL`: Logging verbosity - `PDF_CLEANUP_INTERVAL`: PDF file cleanup frequency ### MCP Client Configuration ```json { "mcpServers": { "egh-research": { "command": "egw-research-server" } } } ``` ## 📊 Available MCP Tools - `search_local` - Full-text search with FTS5 highlighting - `get_local_book` - Get book information from local database - `get_local_content` - Retrieve paragraphs from books - `list_local_books` - List available books with filters - `browse_by_reference` - Find content by EGW reference codes - `get_context` - Get surrounding paragraphs for context - `get_database_stats` - Database statistics and metrics ## 🏥 Health & Monitoring ### Health Check Endpoint ```bash curl http://localhost:3000/health ``` ### Container Health Check Docker includes automatic health checks that monitor the `/health` endpoint. ### Statistics ```bash curl http://localhost:3000/stats ``` ## 📚 Educational and Research Use This tool is designed specifically for educational and research purposes related to Ellen Gould White's writings. The software respects intellectual property rights and provides tools for fair use research and study. ### Key Benefits for Researchers - **Complete offline access** - No dependency on external services - **Advanced search capabilities** - Find specific passages quickly - **Reference cross-linking** - Navigate between related content - **PDF generation** - Create formatted documents for study - **Context preservation** - Maintain surrounding content for accuracy ## 🤝 Contributing We welcome contributions! Please see our contributing guidelines and code of conduct. ### Development Workflow 1. Fork the repository 2. Create a feature branch 3. Make your changes with tests 4. Submit a pull request ### Building and Testing ```bash # Run tests pnpm test # Lint code pnpm lint # Build all packages pnpm build # Test Docker build ./scripts/build-docker.sh --tag test ``` ## 📄 License MIT License - Open source software for educational and research use. ## 🙋‍♂️ Support - **Issues**: [GitHub Issues](https://github.com/surgbc/egh-research/issues) - **Documentation**: [Project Documentation](https://surgbc.github.io/egh-research/) - **Discussions**: [GitHub Discussions](https://github.com/surgbc/egh-research/discussions) --- **Developed by [surgbc](https://github.com/surgbc) • Part of the EGW Writings Project**