CAL-MCP

An independent, read-only Model Context Protocol (MCP) adapter for the Comprehensive Aramaic Lexicon (CAL).

Status: active pre-release development. The current v0.1 candidate exposes 36 public tools: one deterministic local CAL-code conversion tool plus 35 CAL-backed tools across lexicon, English search, texts, token analysis, concordance/KWIC, bibliography, dictionary collation, external citations, Targum Studies, and Syriac Studies. No versioned release has been published yet.

User documentation: start at docs/index.md for the dated capability matrix, getting started, tool reference, workflows, provenance/error semantics, and limitations.

CAL-MCP makes CAL's existing scholarly interfaces easier to use from agents and MCP clients without copying, mirroring, or redistributing the CAL database. Queries remain live, user-initiated requests to CAL; CAL remains the authority for lexical data, texts, citations, bibliography, dictionary collation, Targum data, Syriac data, and scholarly interpretation.

This project is not affiliated with or endorsed by the Comprehensive Aramaic Lexicon Project or Hebrew Union College.

Goals

• Provide a small, stable, typed MCP interface over CAL's public research functions.
• Preserve CAL semantics rather than reinterpret or repair CAL data.
• Accept practical Aramaic inputs using deterministic CAL-supported representation handling.
• Return CAL source URLs, retrieval timestamps, identifiers/coordinates when available, and enough provenance for reproducible scholarly use.
• Work as a standalone stdio MCP server with no dependency on Agora.
• Keep automated access conservative: bounded concurrency/retries/responses, no corpus crawl, no background extraction, no bundled CAL data.

Non-goals

• Reconstructing, mirroring, or bulk harvesting the CAL database.
• Correcting CAL lexical analyses, morphology, citations, or textual data.
• Adding AI-generated linguistic analyses and presenting them as CAL results.
• Hiding multi-stage research behind automatic result/link traversal.
• Making Agora responsible for CAL-specific behavior or depending on Agora at runtime.

v0.1 public surface

The executable tool schemas are the technical source of truth. The current v0.1 contract contains a 36-tool surface: the issue-#12 audit's 26 CAL-backed tools, the release-blocking deterministic conversion tool added by issue #52, the specialized CAL indexed gloss-field search added by issue #107, the explicit CAL text-information metadata follow-up added by issue #106, the explicit Syriac GROUP follow-up added by issue #105, the typed KWIC full-context follow-up added by issue #113, the explicit text-line comments/translations follow-up added by issue #108, the explicit linked-lexicon-citation context follow-up added by issue #127, the bounded lexicon prefix browser added by issue #112, the explicit MT/Targum reflex-example follow-up added by issue #247, and the source-group Targum concordance example follow-up added by issue #246.

See the dated capability matrix for which current CAL functions are implemented directly, intentionally composed from these tools, or explicitly deferred.

System boundary

flowchart LR
    U[Researcher / agent] --> C[MCP client]
    C --> M[CAL-MCP local stdio process]
    M -->|bounded live requests| CAL[cal.huc.edu]
    CAL -->|upstream responses| M
    M -->|typed CAL results + adapter provenance| C

    A[Agora] -. optional future discovery / install / launch .-> M
    M -. no corpus mirror .-> X[(No local CAL database)]

CAL-MCP is independently runnable. Agora integration is downstream packaging/marketplace metadata and is not part of the runtime dependency chain.

Request and data policy

The shared CAL client enforces finite timeouts, low bounded concurrency, transient-only bounded retries, redirect/origin boundaries, streaming response-size limits, duplicate in-flight request suppression, and a bounded process-local cache. Starting/importing the server does not contact CAL; live traffic begins only when a CAL-backed tool is explicitly called. The deterministic conversion tool performs no CAL network request.

Normal CI is offline and uses reduced semantic fixtures. CAL-MCP does not expose cache warming, background refresh, persistent storage, automatic corpus traversal, or a generic invented pagination layer. cal_lexicon_browse returns at most one CAL browse page per call and exposes a validated next_continuation for a later explicit call rather than traversing automatically. Lexicon citation context, KWIC full context, and text-line comments/translations are likewise available only as separate explicit calls over typed selectors/coordinates returned by prior operations; parent lexicon/text/KWIC calls do not prefetch them.

See docs/configuration.md, docs/concepts/errors-and-upstream-drift.md, and docs/limitations.md.

Current pre-release installation

Requirements: Python 3.11+.

From a repository checkout:

python -m pip install -e ".[dev]"

Run the stdio server:

cal-mcp

Equivalent module entry point:

python -m cal_mcp

No stable package-index/release command is documented yet; issue #15 owns the published v0.1 release gate. See docs/installation.md and docs/integrations/standalone-mcp.md.

Development checks

ruff check .
ruff format --check .
mypy
pytest

Development is issue-driven and test-driven. New behavior requires current-source research where relevant, a committed plan, deterministic RED before implementation, full offline GREEN, user/architecture documentation, and a logically independent adversarial review of the exact final PR head before guarded merge.

See AGENTS.md and wiki/agentic-dev-loop.md.

Maintainer documentation

• research.md — dated cross-project upstream evidence.
• plan.md — staged implementation/release plan.
• wiki/README.md — maintainer documentation index.
• wiki/architecture.md — actual system/component/request architecture.
• wiki/testing.md — TDD, fixtures, CI, and live-smoke policy.
• wiki/documentation.md — user/maintainer documentation ownership and executable docs contract.
• wiki/decisions.md — durable architecture decisions.
• wiki/backlog.md — issue/release map.

Focused issue research/plans live under docs/research/ and docs/plans/ when a ticket requires a frozen evidence/execution artifact.

Upstream and access policy

CAL describes itself as a live work in progress and asks scholarly users to cite retrieval dates. CAL exposes public research forms and server-side query handlers, but the project has not found a published CAL machine API contract or CAL-specific automated-access policy.

CAL-MCP therefore follows a deliberately narrow engineering policy: only bounded requests attributable to the current user/MCP operation; no crawl, mirror, prefetch, corpus extraction, or data redistribution. If CAL publishes explicit machine guidance, the research/architecture decisions must be updated before request behavior changes materially.

License

CAL-MCP software and repository documentation are licensed under the MIT License. This license does not grant rights to CAL data, CAL website content, underlying text editions, or third-party dictionaries. Those remain governed by their respective owners and upstream terms.