# JW Research MCP

A remote Model Context Protocol server for traceable research across JW.org and
the Watchtower Online Library. This project extends
[`advenimus/jw-mcp`](https://github.com/advenimus/jw-mcp) with full WOL
articles, publication pagination, direct library search, Study Bible footnotes,
full-text cross-references, daily texts, caching, and optional server-side
research synthesis with Kimi. Paragraphs, scriptures, related articles, and
publication images retain direct source links for verification.

## What is preserved

The original tool names and workflows remain available:

- `search_bible_books`
- `get_bible_verse`
- `get_verse_with_study`
- `get_bible_verse_url`
- `getWorkbookLinks` / `getWorkbookContent`
- `getWatchtowerLinks` / `getWatchtowerContent`
- `get_jw_captions`

`get_verse_with_study.fields` now also accepts `footnotes`. WOL exposes
translation footnotes separately from both study notes and marginal
cross-references, so no content is duplicated between those fields.

## Research tools

| Tool | Purpose |
| --- | --- |
| `get_footnotes` | Full translation footnotes for a verse |
| `get_article_full` | Complete article with paragraph anchors, live inline links, images, and related material |
| `get_article_media` | Paginated full-size images, thumbnails, captions, alt text, and exact source anchors |
| `get_related_content` | Linked subheadings and WOL-recommended similar material |
| `get_book_content` | Bounded publication slices by sequential TOC entry and paragraph page |
| `get_publication_toc` | Direct article URLs, including natural TOC pages for large works |
| `search_wol_library` | Direct WOL full-text search |
| `search_wol_media` | Topic search for images across matching WOL articles |
| `get_cross_references` | Marginal references with complete cited verse text |
| `get_daily_text` | Daily scripture and comment for a date |
| `analyze_research` | Conversational Kimi K3 synthesis with evidence, URLs, confidence, gaps, and follow-ups |

All network-backed responses contain:

```json
{
  "metadata": {
    "source_url": "https://...",
    "timestamp": "2026-07-28T00:00:00.000Z",
    "cache_hit": false
  }
}
```

The default cache TTL is 15 minutes. Retrieval tools accept `langwritten`;
supported WOL routes currently include `E`, `S`, `F`, `X`, `I`, `T`, `J`,
`KO`, and `U`. Research retrieval tools support `format: "json"` and
`format: "markdown"`.

Markdown output uses clickable titles, paragraph source anchors, scripture
references, footnotes, related articles, and image links. JSON output retains
both plain text and source URLs for programmatic use.

## Deep and conversational research

`analyze_research` supports four modes:

- `answer` — direct evidence-based response
- `explore` — map themes and connections
- `compare` — contrast publications, passages, or time periods
- `verify` — audit a claim and identify missing evidence

Use `depth: "focused"`, `"deep"`, or `"exhaustive"`. For follow-up questions,
pass a concise `conversation_context`; it preserves continuity but is never
treated as source evidence. Every result includes a short answer, deep
synthesis, source-linked key points, confidence ratings, consistency or
tension findings, uncertainties, a source index, and suggested follow-ups.

For maximum accuracy, retrieve broad evidence in bounded pages first, include
each block's `source` and `source_url`, and then call `analyze_research`.

## Publication pagination

`get_book_content` treats `chapter` as a 1-based sequential entry in the
publication TOC. A call returns at most three chapters and 25 paragraphs per
chapter. Use `page` and `next_page`, or an explicit `paragraph_range`, to walk
the content without placing an entire bound volume in one model context.

```json
{
  "publication_code": "it",
  "chapter_range": "1-3",
  "page": 1,
  "page_size": 15,
  "langwritten": "E",
  "format": "json"
}
```

For large reference works such as *Insight on the Scriptures*,
`get_publication_toc` also exposes WOL's natural TOC pages.

## Local development

Requires Node.js 20 or newer.

```bash
npm install
npm run typecheck
npm test
npm start
```

To test Streamable HTTP:

```bash
cp .env.example .env
npm run build
MCP_TRANSPORT=http MCP_AUTH=false npm run start:http
```

Then run the MCP Inspector:

```bash
npx @modelcontextprotocol/inspector
```

Connect it to `http://localhost:8080/mcp`.

The live WOL smoke test is:

```bash
npm run build
node scripts/smoke-live.mjs
```

## Environment variables

| Variable | Default | Description |
| --- | --- | --- |
| `MCP_TRANSPORT` | `stdio` | Use `http` for Railway |
| `PORT` / `MCP_PORT` | `8080` | HTTP listen port |
| `MCP_BASE_URL` | local URL | Public Railway URL used in OAuth metadata |
| `MCP_AUTH` | `true` | Set `false` only for isolated testing |
| `MCP_AUTH_SECRET` | — | Required when OAuth is enabled; minimum 8 characters |
| `KIMI_API_KEY` | — | Required only by `analyze_research` |
| `KIMI_MODEL` | `kimi-k3` | Kimi model used for research synthesis |
| `KIMI_BASE_URL` | `https://api.moonshot.ai/v1` | OpenAI-compatible Kimi API base URL |
| `CACHE_TTL_SECONDS` | `900` | In-memory fetch cache TTL |
| `DEFAULT_LANGUAGE` | `E` | Default `langwritten` value |

## Railway

The included multi-stage `Dockerfile` compiles TypeScript and the included
`railway.toml` uses `/health` for deployment health checks. Configure the
environment variables above, deploy, generate a Railway domain, then set
`MCP_BASE_URL` to that exact `https://...` domain and redeploy.

The MCP endpoint is:

```text
https://YOUR-RAILWAY-DOMAIN/mcp
```

Keep this connector separate from existing services until its retrieval and
analysis behavior has been verified with your own research workflow.

## Tests

The automated suite verifies:

- footnotes remain distinct from study notes and cross-references
- full-article paragraph numbering and marker preservation
- linked paragraph citations, media captions, and related-material parsing
- hard paragraph pagination bounds
- cache-hit behavior
- localized WOL route construction
- schema-validated `analyze_research` JSON without Markdown fences

The live smoke test additionally verifies a real *Insight* TOC and pagination,
WOL search, article media, related research trails, full-text cross-references,
daily text parsing, and cached repeats.

## Attribution and license

Forked from [`advenimus/jw-mcp`](https://github.com/advenimus/jw-mcp).
Licensed under the MIT license of the upstream project.