Aquifer MCP

Thin Cloudflare Workers MCP server for navigating Bible Aquifer content.

Deploy: Cloudflare dashboard Git integration builds and deploys this repo when you push (see [DEPLOY-SETUP.md](DEPLOY-SETUP.md)). GitHub Actions here only runs tests, not deploy.

Most users should use the deployed endpoint directly. Running locally is primarily for agentic contributors developing this server.

A First-Person Build Account

This MCP server was built by AI coding agents with Klappy.

Klappy gave one clear direction: do not build a heavy platform, build a thin navigable layer.

Oddkit provides epistemic posture, prior MCP work provides implementation shape, and Rick Brannan's Aquifer docs and repos provide source truth. The server is a Cloudflare Worker that indexes metadata, retrieves content on demand, and exposes predictable MCP tools for agents and apps.

Capabilities include: explicit catalog browsing via browse, content-addressed SHA-keyed caching where freshness comes from observed repo state instead of TTL assumptions, in-band README access through the readme tool, dynamic resource discovery from the BibleAquifer GitHub org so new resources appear automatically with zero code changes, multilingual coverage where each resource is indexed and served in its own primary language (resolved from the coverage manifest) rather than English-only, server-side resolution of relative content image paths into absolute CORS-open URLs so consuming apps render images without per-resource handling, deterministic Bible verse retrieval via the scripture tool, and named entity profiling via the entity tool.

The Aquifer Window uses this server as its content backend. The Window and agent clients are two interfaces over the same corpus and the same MCP endpoint.

Production URLs:

• Aquifer MCP: https://aquifer.klappy.dev/mcp
• Aquifer Window: https://aquifer-window.klappy.dev

Staging preview (git branch staging): `https://staging-aquifer-mcp.klappy.workers.dev` (/health, /mcp — same as production). Other branches: `https://<branch-slug>-aquifer-mcp.klappy.workers.dev` (slug matches branch name; check Cloudflare if a branch has an odd slug).

Two slices of one pie:

• Aquifer Window = human exploration
• Aquifer MCP (this) = agent navigation

What It Exposes

Aquifer MCP provides ten tools:

• readme - fetch this README as markdown through MCP
• telemetry_policy - fetch telemetry-sharing policy and client integration guidance
• telemetry_public - fetch public telemetry snapshot and consumer/tool leaderboards
• list - list resources and metadata summary
• search - search by passage, ACAI entity, or title keyword
• get - fetch full article content by compound key
• related - follow passage/resource/entity associations
• browse - paginate through full article catalogs for a resource (defaults to the resource's own language)
• scripture - fetch Bible verse text by reference (e.g. "Rom 3:23-25") across all translations
• entity - profile a named entity by ACAI ID (e.g. "person:David") showing all associated articles

Health endpoint:

• GET /health

MCP endpoint:

• POST /mcp

Aquifer Window Uses This Same Server

The Aquifer Window does not use a separate backend for content. It uses this exact MCP server as its content interface.

Live Window URL: https://aquifer-window.klappy.dev

Window behavior maps directly to these tool calls:

• resource discovery -> list
• passage/topic/entity discovery -> search
• article reading -> get
• related-content exploration -> related
• paginated catalog browsing (especially media/image repos) -> browse
• Bible verse reading -> scripture
• entity profiling -> entity

Both the agent experience and the Aquifer Window experience resolve through the same endpoint and the same retrieval path.

Two Paths

Path 1: Use it (recommended, most users)

Use the deployed endpoint directly:

• MCP URL: https://aquifer.klappy.dev/mcp
• Health: https://aquifer.klappy.dev/health

Cursor config:

{
  "mcpServers": {
    "aquifer-mcp": {
      "url": "https://aquifer.klappy.dev/mcp"
    }
  }
}

Path 2: Run locally (development only)

Clone this repo and run local Worker dev if you are changing server code.

Local Development

Install

npm install

Run locally

npm run dev

Check health

curl http://127.0.0.1:8787/health

Build and tests

npm run build
npm run test

Deploy

npm run deploy

Branch strategy and preview URLs (staging → https://staging-aquifer-mcp.klappy.workers.dev) are in docs/branch-and-deployment-strategy.md and DEPLOY-SETUP.md.

Deploy path: push your branch → Cloudflare builds → use the preview or production URL the dashboard shows. No GitHub secrets required for deploy in this repo.

• CLI fallback (emergency): npm run deploy — logged-in Wrangler (deploy:staging is for local Wrangler [env.staging], not the Git preview hostname)

GitHub Actions: build + test only (.github/workflows/ci.yml on PRs).

Cursor MCP Config

Default (deployed):

{
  "mcpServers": {
    "aquifer-mcp": {
      "url": "https://aquifer.klappy.dev/mcp"
    }
  }
}

Local override for development:

• http://127.0.0.1:8787/mcp

Tool Usage (JSON-RPC Examples)

These examples target the deployed endpoint, since that is the normal usage path.

Initialize

curl -X POST https://aquifer.klappy.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"initialize",
    "params":{}
  }'

List tools

curl -X POST https://aquifer.klappy.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/list",
    "params":{}
  }'

readme

curl -X POST https://aquifer.klappy.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":9,
    "method":"tools/call",
    "params":{
      "name":"readme",
      "arguments":{"refresh":false}
    }
  }'

telemetry_policy

curl -X POST https://aquifer.klappy.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":10,
    "method":"tools/call",
    "params":{
      "name":"telemetry_policy",
      "arguments":{"surface":"mcp-client"}
    }
  }'

telemetry_public

curl -X POST https://aquifer.klappy.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":11,
    "method":"tools/call",
    "params":{
      "name":"telemetry_public",
      "arguments":{"limit":10}
    }
  }'

list

curl -X POST https://aquifer.klappy.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":3,
    "method":"tools/call",
    "params":{
      "name":"list",
      "arguments":{"type":"StudyNotes","language":"eng"}
    }
  }'

search

curl -X POST https://aquifer.klappy.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":4,
    "method":"tools/call",
    "params":{
      "name":"search",
      "arguments":{"query":"Romans 3:24"}
    }
  }'

curl -X POST https://aquifer.klappy.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":5,
    "method":"tools/call",
    "params":{
      "name":"search",
      "arguments":{"query":"keyterm:Justification"}
    }
  }'

get

curl -X POST https://aquifer.klappy.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":6,
    "method":"tools/call",
    "params":{
      "name":"get",
      "arguments":{
        "resource_code":"BiblicaStudyNotes",
        "language":"eng",
        "content_id":"43895"
      }
    }
  }'

related

curl -X POST https://aquifer.klappy.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":7,
    "method":"tools/call",
    "params":{
      "name":"related",
      "arguments":{
        "resource_code":"BiblicaStudyNotes",
        "language":"eng",
        "content_id":"43895"
      }
    }
  }'

browse

curl -X POST https://aquifer.klappy.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":8,
    "method":"tools/call",
    "params":{
      "name":"browse",
      "arguments":{
        "resource_code":"FIAMaps",
        "language":"eng",
        "page":1,
        "page_size":25
      }
    }
  }'

browse defaults:

• language: eng
• page: 1
• page_size: 50
• page_size max: 100

scripture

curl -X POST https://aquifer.klappy.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":12,
    "method":"tools/call",
    "params":{
      "name":"scripture",
      "arguments":{"reference":"Rom 3:23-25"}
    }
  }'

curl -X POST https://aquifer.klappy.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":13,
    "method":"tools/call",
    "params":{
      "name":"scripture",
      "arguments":{"reference":"John 3:16","resource_code":"BereanStandardBible"}
    }
  }'

entity

curl -X POST https://aquifer.klappy.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":14,
    "method":"tools/call",
    "params":{
      "name":"entity",
      "arguments":{"id":"person:David"}
    }
  }'

curl -X POST https://aquifer.klappy.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":15,
    "method":"tools/call",
    "params":{
      "name":"entity",
      "arguments":{"id":"keyterm:Justification"}
    }
  }'

Architecture Summary

Runtime surface

• Cloudflare Worker entrypoint in src/index.ts
• MCP server created with @modelcontextprotocol/sdk and agents/mcp
• tools wired directly to handlers in src/tools.ts

Resource discovery

Resources are discovered dynamically from the BibleAquifer GitHub organization — no hardcoded list. On each index build the server queries the org API (ETag-cached), fetches eng/metadata.json from every repo, and includes any repo that has valid resource_metadata. New resources Rick adds appear automatically; repos without metadata are silently excluded.

Retrieval model

1. Discover repos from GitHub org, build/load navigability index from metadata
2. Resolve references from index for list, search, and entity
3. Fetch content files on demand for get, related, browse, and scripture
4. Return text content payloads in MCP responses

Caching

• Workers KV binding: AQUIFER_CACHE
• cache keys are content-addressed by Git commit SHA (not time-window keys)
• repo SHAs are checked against GitHub (ETag-aware) before cache reuse
• KV TTL (GC_TTL) is 30 days for garbage collection, not freshness truth

Telemetry And Sharing Policy

Aquifer MCP aims to maximize operational visibility while preserving user anonymity by default.

Telemetry should measure system behavior, not people:

• Collect aggregate operational counters (JSON-RPC method counts, tool-call totals, tool leaderboards, consumer-label leaderboards, label-source counts)
• Track all tools/call usage automatically at the server transport layer (no client opt-in required)
• Treat consumer labels as transparent self-declarations (for openness/gamification), not identity proof unless allowlisted as verified
• Apply weighted leaderboard scoring where verified clients are worth 10x per tool call
• Incentivize richer self-report metadata through a public transparency leaderboard and badge system
• Do not collect user-identifying or content-bearing data by default
• Do not collect raw prompts, raw query text, article content, model responses, names, emails, IP addresses, or fingerprint data

For in-band client guidance, call the telemetry_policy tool from your client integration. For aggregate transparency and gamified usage visibility, call telemetry_public. For a single-page governance reference, see docs/telemetry-governance-snapshot.md.

Supported surface values:

• mcp-client
• aquifer-window

If no surface is provided, telemetry_policy returns the base policy.

telemetry_public returns:

• aggregate request and tool-call totals
• top calling consumer labels
• weighted consumer leaderboard (verified clients score 10x)
• transparency leaderboard (self-report completeness + badges)
• top-used MCP tools
• method counts, consumer-label source counts, verification-class counts, and self-report field coverage counts
• explicit tracked/excluded field lists
• last telemetry update timestamp

Optional env var for weighted verification:

• TELEMETRY_VERIFIED_CLIENTS - comma-separated consumer labels treated as verified for the 10x weighted leaderboard (example: Cursor,ClaudeDesktop,AquiferWindow)

Recommended self-report headers (honor-system unless verified):

• x-aquifer-client
• x-aquifer-client-version
• x-aquifer-agent-name
• x-aquifer-agent-version
• x-aquifer-surface
• x-aquifer-contact-url
• x-aquifer-policy-url
• x-aquifer-capabilities

Data Assumptions

• Article key is always resource_code + language + content_id
• Passage references use BBCCCVVV format
• Passage range matching uses start-end BBCCCVVV strings
• Metadata source is /{language}/metadata.json
• Content source is /{language}/json/*.content.json

Source-bound media and localized catalogs (1.7.0)

Browse accepts an optional modality (audio, video, image, text), independent of collection type. Results include structured source identity, original-file and HTML hashes, explicit completeness, and a scan_cursor when further bounded scanning is needed. Counts are provisional until complete. Page numbers select among verified entries; scan_cursor advances source scanning. Omit the cursor to restart failed scans.

Get accepts include_media: true and the same scan cursor while retaining formatted article text. Media URLs are references, not proof of playback, narrator identity or asset licensing. Matching-language collection rights are reported separately when known. No audio/video asset is downloaded by these tools.

For larger source JSON files, get with include_media: true and browse accept optional scan_max_bytes (integer 1–8,000,000; default remains 2,000,000). This bounds each content-scan invocation, not the full multi-call scan or metadata/tree discovery. A delivered chunk may cross the allowance before immediate cancellation; counters include it. For example:

{"resource_code":"FIATranslationGuide","language":"spa","content_id":"spa-luk-p1-v1.1","include_media":true,"scan_max_bytes":3000000}

Repeat the same arguments plus returned scan_cursor for each continuation. If a prior scan reports oversized-file, restart without its cursor and explicitly choose a sufficient allowance (up to 8,000,000); increasing the allowance on a cursor does not retry files already classified as failures. Omitting the option on any continuation restores the 2,000,000 default. Files beyond the maximum remain explicit failures. This retrieves original JSON article content and source-bound media references; formatted text can contain the source HTML. It does not add raw Markdown-file retrieval or prove media playback.