WOL MCP Server

# WOL MCP Server An MCP server that gives LLMs read-only access to the [Watchtower Online Library (WOL)](https://wol.jw.org/pt/wol/h/r5/lp-t). ## Features - Advanced search with operators - Document retrieval (always Markdown) - Browse publication types - Multilingual support (dynamic WOL language config) - Robust error handling and retry logic ## Installation ```bash # Clone and install dependencies git clone https://github.com/LeomaiaJr/wol-mcp-server.git cd wol-mcp npm install # Build the server npm run build ``` ## Available Tools ### wol_search Search the Watchtower Online Library with operators and pagination. Parameters: - query (string, required) - useOperators (boolean, default: true) - scope ("sen" | "par" | "art", default: "par") - publications (array; see list below) - language (string, default: "en") - sort ("occ" | "newest" | "oldest", default: "occ") - page (integer, default: 1) - limit (integer, 1-100, default: 10) — applies only to document results Search operators: - & or + (AND), | or / (OR), ! (NOT), && or ++ (adjacent), "..." (phrase), \* (wildcard), ? (single char), (...) (group) ### wol_get_document Retrieve full content of a specific document (always Markdown). Parameters: - url (string, required) — full WOL document URL Output includes: title, publication, URL, optional date/volume/issue, subheadings, similar materials, followed by the article content. Bible citation links (/wol/bc) are inlined as plain text. ### wol_browse_publications Browse available publications by type. Parameters: - type (string) — optional filter - language (string, default: "en") - year (integer) — optional year filter Publication types (common): `w`, `g`, `bk`, `bi`, `it`, `dx`, `yb`, `syr`, `sgbk`, `mwb`, `km`, `brch`, `bklt`, `es`, `trct`, `kn`, `pgm`, `ca-copgm`, `ca-brpgm`, `co-pgm`, `manual`, `gloss`, `web` ## Available Resources ### wol://publications Lists all available publication types with descriptions. ### wol://operators Details on search operators and examples. ### wol://languages Supported languages for multilingual access. ## Development (Cloudflare Workers) ```bash # Install dependencies npm install # Run locally (wrangler dev) npm start # Local MCP endpoint: http://localhost:8787/sse # Optional: open MCP Inspector in another terminal and connect to the local endpoint npx @modelcontextprotocol/inspector@latest # Type check npm run type-check # Deploy to Cloudflare npx wrangler deploy ``` ## Deploy to Cloudflare Workers (Remote MCP) Cloudflare Workers let you run a remote MCP server reachable over HTTP/SSE. This repo’s server currently starts via `stdio` (subprocess) using `StdioServerTransport`. To expose it remotely, deploy a Workers-based MCP server that implements the HTTP/SSE transport and wires the same tools. Below are two practical paths. ### Option A — Quick deploy (authless template) 1) Create a new Workers project from Cloudflare’s authless remote MCP template: ```bash npm create cloudflare@latest -- wol-mcp-worker --template=cloudflare/ai/demos/remote-mcp-authless cd wol-mcp-worker ``` 2) Develop locally: ```bash npm start # Server runs at http://localhost:8787/sse ``` 3) Deploy (Wrangler is already authenticated on your machine): ```bash npx wrangler@latest deploy ``` 4) Connect using the MCP Inspector: ```bash npx @modelcontextprotocol/inspector@latest open http://localhost:5173 # Enter your server URL, e.g. http://localhost:8787/sse or https://<worker>.<account>.workers.dev/sse ``` 5) Use with a local proxy: ```json { "mcpServers": { "wol-remote": { "command": "npx", "args": ["mcp-remote", "https://<worker>.<account>.workers.dev/sse"] } } } ``` ### Option B — Add authentication (OAuth) Start from Cloudflare’s GitHub OAuth example and deploy: ```bash npm create cloudflare@latest -- wol-mcp-github-auth --template=cloudflare/ai/demos/remote-mcp-github-oauth cd wol-mcp-github-auth npx wrangler@latest deploy ``` Follow the guide to register OAuth apps and set secrets (`GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`). See: Cloudflare “Build a Remote MCP server” guide. ### Porting this server’s tools - This repo is `stdio`-only. Workers cannot run `stdio` subprocesses, so you do not deploy `dist/index.js` directly. - Reuse logic by moving the WOL tool handlers (e.g., `WOLService`) into the Workers project and registering equivalent tools there. - Cloudflare Workers support the MCP HTTP/SSE transport out of the box in their templates. Implement tools that call the same methods you see in this repo’s `wol_search`, `wol_get_document`, and `wol_browse_publications` handlers. Notes: - Spec reference: MCP transports (stdio and Streamable HTTP). Workers templates expose an `/sse` endpoint compatible with MCP clients. - For clients that don’t yet support remote MCP natively, use `mcp-remote` as shown above. ## Configuration ### Environment Variables - `NODE_ENV` - Environment (development/production) - `LOG_LEVEL` - Logging level (error/warn/info/debug) ### Service Availability Currently, no server-side rate limiting is enforced. Upstream availability from WOL may occasionally result in temporary outages (e.g., 502/503), which are surfaced as `SERVICE_UNAVAILABLE` errors. ## Examples ### Basic Search ``` Query: "Jesus Christ" Result: Exact phrase search across all publications ``` ### Advanced Search with Operators ``` Query: (Jesus | Christ) & Jehovah & !Trinity Result: Documents containing (Jesus OR Christ) AND Jehovah but NOT Trinity ``` ### Publication-Specific Search ``` Query: prayer Publications: ["w", "g"] // Watchtower and Awake! only Result: Prayer-related articles from these magazines ``` ### Multilingual Search ``` Query: "reino de Dios" Language: "es" Result: Spanish content about God's Kingdom ``` ## Contributing 1. Fork the repository 2. Create a feature branch: `git checkout -b feature/new-feature` 3. Make changes and add tests 4. Commit: `git commit -am 'Add new feature'` 5. Push: `git push origin feature/new-feature` 6. Submit a Pull Request ## License MIT License - see LICENSE file for details. ## Disclaimer This is an unofficial MCP server for accessing the Watchtower Online Library. It is not affiliated with or endorsed by Jehovah's Witnesses or the Watchtower Bible and Tract Society.