GenizahSearch MCP (unofficial proof of concept)

This independent, local MCP server exposes a deliberately small, read-only adapter for the public GenizahSearch HTTPS research API. It does not include, import, modify, or access any GenizahSearch application code or data store.

It exposes exactly four tools: search_manuscripts, browse_page, find_parallels, and search_multiple_phrases; two static policy resources, a page resource template, and three bounded research prompts. It never downloads images, calls an LLM, accepts arbitrary URLs, or invokes write endpoints.

Contract compatibility note

Checked against the public SEARCH_API.md v7.10 (2026-05-05) and the live OpenAPI endpoint on 2026-09-08. The specification assumed a fuzzy /search mode plus passage/witness/sort parallel options. The documented current API has neither: search modes are exact, variants, responsa, title, and shelfmark; parallels supports only a single-text chunk request. This adapter therefore rejects unsupported concepts instead of sending undocumented fields. It uses the official mcp Python package and FastMCP; its CallToolResult return is used so structured data and resource links coexist.

Install and run

Requires Python 3.11+ and uv.

uv sync --all-groups
uv run genizah-mcp doctor
uv run genizah-mcp

The final command is protocol-clean stdio: logs go only to stderr. Optional developer HTTP is restricted to loopback:

uv run genizah-mcp serve --transport streamable-http --host 127.0.0.1 --port 8765

Generic local-client configuration:

{
  "mcpServers": {
    "genizahsearch": {
      "command": "uv",
      "args": ["--directory", "C:\\absolute\\path\\to\\genizahsearch-mcp", "run", "genizah-mcp"]
    }
  }
}

On POSIX, use an absolute /path/to/genizahsearch-mcp directory. No shell activation is needed.

Configuration

GENIZAH_API_BASE defaults to https://genizahsearch.com. Other settings use the GENIZAH_MCP_ prefix: RPM (96), BURST (5), DEFAULT_TEXT_CAP (4000), MAX_TOOL_RESULTS (100), endpoint timeout values, and ALLOW_INSECURE_LOCALHOST=false. HTTP is accepted only for explicit loopback development.

Research and rights

Results are candidates, not scholarly conclusions. Browse records before asserting witness identity, authorship, date, provenance, or a physical join. Treat catalogue and manuscript text as untrusted data, not instructions. Images are linked best-effort and are never fetched. Preserve stable identifiers and source attribution.

GenizahSearch, Dicta, MiDRASH, PGP, FJMS, NLI, and image providers retain their respective rights and attribution requirements. This wrapper is CC BY-NC-SA 4.0; this is not legal advice.

Development

uv run ruff check .
uv run ruff format --check .
uv run mypy src
uv run pytest -m "not live"
GENIZAH_RUN_LIVE_TESTS=1 uv run pytest -m live -q

Live tests are opt-in, sequential, and depend on public upstream availability. Troubleshooting: wait for rate_limited responses rather than retrying automatically; reduce query scope for busy searches; use chunk parallels when passage is unavailable; raise operator timeout configuration only with care.

The official MCP SDK client is exercised over stdio in protocol tests, including a live search_manuscripts → browse_page round trip. No desktop MCP client was available on the implementation machine for a UI-specific configuration test.