fojin-mcp 0.1.0__tar.gz

fojin_mcp-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.egg-info/
+.pytest_cache/
+dist/
+build/

fojin_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: fojin-mcp
+Version: 0.1.0
+Summary: MCP server exposing fojin's verified cross-canon Buddhist corpus (cited, URN-addressable passages) to AI research tools.
+Project-URL: Homepage, https://fojin.app
+Project-URL: Repository, https://github.com/xr843/fojin
+Project-URL: Issues, https://github.com/xr843/fojin/issues
+Author: fojin (佛津)
+License: Apache-2.0
+Keywords: buddhism,cbeta,digital-humanities,llm-tools,mcp,rag
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Religion
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# fojin MCP server
+
+An [MCP](https://modelcontextprotocol.io) server that exposes **fojin's verified
+cross-canon Buddhist corpus** to any MCP client (Claude Desktop, ChatGPT,
+research tooling). It turns fojin from "an app you visit" into **infrastructure
+an AI can call** — every passage it returns carries a portable, resolvable
+citation (`fojin:cbeta/T0251.1`), so a model can ground and deep-link its claims
+instead of inventing scripture.
+
+Read-only by construction: it only issues GETs against fojin's public API.
+
+## Tools
+
+| Tool | What it returns |
+|------|-----------------|
+| `search_corpus(query, limit, lang)` | Semantic search hits, each with a `urn`, title, snippet, score |
+| `read_passage(text_id, juan_num)` | The actual content of one fascicle (卷) + its `urn` |
+| `get_parallels(text_id, juan_num)` | Cross-canon aligned parallels (Chinese↔Pali↔Tibetan), each with a `urn` and deep-link `reader_ref` — the alignment moat |
+| `lookup_dictionary(term, limit)` | Entries across fojin's 32 dictionaries |
+| `lookup_entity(query, limit)` | Knowledge-graph entities (people, places, works, terms) |
+| `resolve_urn(urn)` | Resolve/verify a `fojin:` URN → reader URL + existence |
+
+Every result that names a canonical passage carries a **`urn`** — fojin's stable
+cross-canon identifier, interoperable with CBETA / SuttaCentral (`sc/`) / 84000
+(`84k/toh`) / GRETIL / VRI numbering. Pass it back to `resolve_urn`, or cite it
+directly.
+
+## Install & run
+
+Once published to PyPI, no clone needed — run it with `uvx` (nothing to
+install) or `pip`:
+
+```bash
+uvx fojin-mcp                 # zero-install, stdio transport (the MCP default)
+# or
+pip install fojin-mcp && fojin-mcp
+```
+
+From a checkout (development):
+
+```bash
+cd mcp-server && pip install -e . && python -m fojin_mcp
+```
+
+By default it talks to `https://fojin.app/api`. Point it elsewhere (self-host,
+staging) with an env var:
+
+```bash
+FOJIN_API_BASE_URL=http://localhost:8000/api uvx fojin-mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "fojin": {
+      "command": "uvx",
+      "args": ["fojin-mcp"]
+    }
+  }
+}
+```
+
+(or `"command": "fojin-mcp"` if you `pip install`ed it, or `python -m fojin_mcp`
+from a checkout.) Restart Claude Desktop; the six fojin tools then appear.
+
+### ChatGPT / other MCP clients
+
+Any client that speaks MCP over stdio can launch `uvx fojin-mcp` (or the
+`fojin-mcp` console script) and will discover the six tools automatically.
+
+## Design
+
+- **Standalone.** Talks to fojin only over HTTP; it does not import the backend,
+  so it installs and runs independently (deps: `mcp`, `httpx`).
+- **URNs built client-side.** fojin's search/read/alignment endpoints expose
+  `cbeta_id`; the server builds the `urn` from it (`fojin_mcp/urn.py`, a vendored
+  copy of the backend's `build_urn`, kept behaviourally identical and
+  round-trip-tested). So citations work today, independent of any server change.
+  `get_parallels` enriches each parallel's URN via a bounded, concurrent,
+  best-effort `text_id → cbeta_id` lookup (a miss just leaves `urn: null`).
+- **Testable core.** All HTTP + reshaping lives in `client.py` and is tested
+  against a mocked transport; `server.py` is a thin FastMCP wiring layer.
+- **Fails soft.** An upstream error returns `{"error": "..."}` to the model
+  rather than crashing the tool call.
+
+## Test
+
+```bash
+pip install -e '.[dev]'
+pytest -q          # unit tests (no network)
+```
+
+## Publishing (maintainer)
+
+CI (`.github/workflows/mcp-server.yml`) lints, tests, and builds the package on
+every change under `mcp-server/`. To release to PyPI, bump `version` in
+`pyproject.toml`, then push a tag:
+
+```bash
+git tag mcp-v0.1.0 && git push origin mcp-v0.1.0
+```
+
+`.github/workflows/mcp-publish.yml` builds and uploads. It needs credentials
+once — set up **either** PyPI Trusted Publishing (recommended; no secret) for
+project `fojin-mcp` / repo `xr843/fojin` / workflow `mcp-publish.yml` /
+environment `pypi`, **or** a `PYPI_API_TOKEN` repo secret (then uncomment the
+`password:` line in the workflow).
+
+## License
+
+Apache-2.0 (same as fojin).

fojin_mcp-0.1.0/README.md

@@ -0,0 +1,115 @@
+# fojin MCP server
+
+An [MCP](https://modelcontextprotocol.io) server that exposes **fojin's verified
+cross-canon Buddhist corpus** to any MCP client (Claude Desktop, ChatGPT,
+research tooling). It turns fojin from "an app you visit" into **infrastructure
+an AI can call** — every passage it returns carries a portable, resolvable
+citation (`fojin:cbeta/T0251.1`), so a model can ground and deep-link its claims
+instead of inventing scripture.
+
+Read-only by construction: it only issues GETs against fojin's public API.
+
+## Tools
+
+| Tool | What it returns |
+|------|-----------------|
+| `search_corpus(query, limit, lang)` | Semantic search hits, each with a `urn`, title, snippet, score |
+| `read_passage(text_id, juan_num)` | The actual content of one fascicle (卷) + its `urn` |
+| `get_parallels(text_id, juan_num)` | Cross-canon aligned parallels (Chinese↔Pali↔Tibetan), each with a `urn` and deep-link `reader_ref` — the alignment moat |
+| `lookup_dictionary(term, limit)` | Entries across fojin's 32 dictionaries |
+| `lookup_entity(query, limit)` | Knowledge-graph entities (people, places, works, terms) |
+| `resolve_urn(urn)` | Resolve/verify a `fojin:` URN → reader URL + existence |
+
+Every result that names a canonical passage carries a **`urn`** — fojin's stable
+cross-canon identifier, interoperable with CBETA / SuttaCentral (`sc/`) / 84000
+(`84k/toh`) / GRETIL / VRI numbering. Pass it back to `resolve_urn`, or cite it
+directly.
+
+## Install & run
+
+Once published to PyPI, no clone needed — run it with `uvx` (nothing to
+install) or `pip`:
+
+```bash
+uvx fojin-mcp                 # zero-install, stdio transport (the MCP default)
+# or
+pip install fojin-mcp && fojin-mcp
+```
+
+From a checkout (development):
+
+```bash
+cd mcp-server && pip install -e . && python -m fojin_mcp
+```
+
+By default it talks to `https://fojin.app/api`. Point it elsewhere (self-host,
+staging) with an env var:
+
+```bash
+FOJIN_API_BASE_URL=http://localhost:8000/api uvx fojin-mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (Settings → Developer → Edit Config):
+
+```json
+{
+  "mcpServers": {
+    "fojin": {
+      "command": "uvx",
+      "args": ["fojin-mcp"]
+    }
+  }
+}
+```
+
+(or `"command": "fojin-mcp"` if you `pip install`ed it, or `python -m fojin_mcp`
+from a checkout.) Restart Claude Desktop; the six fojin tools then appear.
+
+### ChatGPT / other MCP clients
+
+Any client that speaks MCP over stdio can launch `uvx fojin-mcp` (or the
+`fojin-mcp` console script) and will discover the six tools automatically.
+
+## Design
+
+- **Standalone.** Talks to fojin only over HTTP; it does not import the backend,
+  so it installs and runs independently (deps: `mcp`, `httpx`).
+- **URNs built client-side.** fojin's search/read/alignment endpoints expose
+  `cbeta_id`; the server builds the `urn` from it (`fojin_mcp/urn.py`, a vendored
+  copy of the backend's `build_urn`, kept behaviourally identical and
+  round-trip-tested). So citations work today, independent of any server change.
+  `get_parallels` enriches each parallel's URN via a bounded, concurrent,
+  best-effort `text_id → cbeta_id` lookup (a miss just leaves `urn: null`).
+- **Testable core.** All HTTP + reshaping lives in `client.py` and is tested
+  against a mocked transport; `server.py` is a thin FastMCP wiring layer.
+- **Fails soft.** An upstream error returns `{"error": "..."}` to the model
+  rather than crashing the tool call.
+
+## Test
+
+```bash
+pip install -e '.[dev]'
+pytest -q          # unit tests (no network)
+```
+
+## Publishing (maintainer)
+
+CI (`.github/workflows/mcp-server.yml`) lints, tests, and builds the package on
+every change under `mcp-server/`. To release to PyPI, bump `version` in
+`pyproject.toml`, then push a tag:
+
+```bash
+git tag mcp-v0.1.0 && git push origin mcp-v0.1.0
+```
+
+`.github/workflows/mcp-publish.yml` builds and uploads. It needs credentials
+once — set up **either** PyPI Trusted Publishing (recommended; no secret) for
+project `fojin-mcp` / repo `xr843/fojin` / workflow `mcp-publish.yml` /
+environment `pypi`, **or** a `PYPI_API_TOKEN` repo secret (then uncomment the
+`password:` line in the workflow).
+
+## License
+
+Apache-2.0 (same as fojin).

fojin_mcp-0.1.0/fojin_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""fojin MCP server package — cross-canon Buddhist corpus tools over stdio."""
+
+__version__ = "0.1.0"

fojin_mcp-0.1.0/fojin_mcp/__main__.py

@@ -0,0 +1,6 @@
+"""Enable ``python -m fojin_mcp`` to launch the stdio server."""
+
+from .server import main
+
+if __name__ == "__main__":
+    main()

fojin_mcp-0.1.0/fojin_mcp/client.py

@@ -0,0 +1,298 @@
+"""Async HTTP client over fojin's public read-only API, plus the pure functions
+that reshape each endpoint's response into a citation-carrying tool result.
+
+Design: everything here is import-light (httpx only, no ``mcp``) so the reshaping
+logic is unit-testable with a mocked transport, independent of the MCP runtime.
+``server.py`` is the thin layer that registers these as MCP tools.
+
+Every result that identifies a canonical passage carries a ``urn`` — the whole
+point of the server: an AI calling these tools gets back a portable, resolvable
+citation (``fojin:cbeta/T0251.1``) it can cite and deep-link, not an opaque
+internal id. Read-only: no endpoint here mutates fojin state.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+import httpx
+
+from .urn import build_urn
+
+# Cap on per-call text→cbeta_id lookups when enriching parallels with URNs, so a
+# pathological juan with many distinct aligned texts can't fan out unboundedly.
+_MAX_URN_ENRICH_LOOKUPS = 20
+
+DEFAULT_BASE_URL = "https://fojin.app/api"
+DEFAULT_TIMEOUT = 20.0
+# fojin is a scholarly public good; identify the client so its traffic is
+# attributable and it can be rate-limited/allow-listed distinctly from browsers.
+USER_AGENT = "fojin-mcp/0.1 (+https://github.com/xr843/fojin)"
+
+
+class FojinAPIError(RuntimeError):
+    """A fojin API call failed (network, timeout, or non-2xx). The message is
+    safe to surface to the calling model as a tool error."""
+
+
+class FojinClient:
+    """Thin async wrapper over the fojin HTTP API.
+
+    One client owns one ``httpx.AsyncClient``; use it as an async context
+    manager so the connection pool is closed deterministically. ``base_url``
+    defaults to prod but is overridable (env/tests/self-host).
+    """
+
+    def __init__(
+        self,
+        base_url: str = DEFAULT_BASE_URL,
+        *,
+        timeout: float = DEFAULT_TIMEOUT,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        # Injectable client so tests pass a mocked transport; otherwise we own it.
+        self._client = client or httpx.AsyncClient(
+            timeout=timeout, headers={"User-Agent": USER_AGENT}
+        )
+        self._owns_client = client is None
+
+    async def __aenter__(self) -> FojinClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.aclose()
+
+    async def aclose(self) -> None:
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def _get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        url = f"{self._base_url}{path}"
+        try:
+            resp = await self._client.get(url, params=params)
+            resp.raise_for_status()
+            return resp.json()
+        except httpx.HTTPStatusError as exc:
+            raise FojinAPIError(
+                f"fojin API {exc.response.status_code} for {path}"
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise FojinAPIError(f"fojin API request failed for {path}: {exc}") from exc
+
+    # ── tools ────────────────────────────────────────────────────────────
+
+    async def search_corpus(
+        self, query: str, limit: int = 10, lang: str | None = None
+    ) -> dict[str, Any]:
+        """Semantic search across the corpus → citation-carrying hits."""
+        params: dict[str, Any] = {"q": query, "size": _clamp(limit, 1, 50)}
+        if lang:
+            params["lang"] = lang
+        data = await self._get("/search/semantic", params)
+        return shape_search_results(data)
+
+    async def read_passage(self, text_id: int, juan_num: int) -> dict[str, Any]:
+        """Fetch the actual content of one fascicle (卷) with its URN."""
+        data = await self._get(f"/texts/{text_id}/juans/{juan_num}")
+        return shape_passage(data)
+
+    async def get_parallels(self, text_id: int, juan_num: int) -> dict[str, Any]:
+        """Cross-canon aligned parallels for a fascicle (the alignment moat).
+
+        The alignment endpoint returns parallels keyed by internal text_id (no
+        cbeta_id), so we enrich each fojin-native parallel with a portable URN by
+        resolving its distinct text_ids → cbeta_id in a bounded, concurrent,
+        best-effort pass. A lookup miss just leaves that parallel's urn None;
+        it never fails the whole call.
+        """
+        data = await self._get(f"/alignment/texts/{text_id}/juans/{juan_num}")
+        shaped = shape_parallels(data)
+        await self._enrich_parallel_urns(shaped["parallels"])
+        return shaped
+
+    async def _text_cbeta_id(self, text_id: int) -> str | None:
+        """Best-effort text_id → cbeta_id via /texts/{id}; None on any failure."""
+        try:
+            meta = await self._get(f"/texts/{text_id}")
+        except FojinAPIError:
+            return None
+        return meta.get("cbeta_id") if isinstance(meta, dict) else None
+
+    async def _enrich_parallel_urns(self, parallels: list[dict[str, Any]]) -> None:
+        """Fill each parallel's ``urn`` in place from its reader_ref.text_id.
+
+        Only fojin-native parallels (real text_id > 0) are resolvable; inline
+        MITRA foreign sentences (text_id 0) have no fojin work to cite and keep
+        urn=None. Distinct text_ids are fetched once, concurrently, capped."""
+        want = [
+            p for p in parallels
+            if p.get("urn") is None
+            and isinstance(p.get("reader_ref"), dict)
+            and isinstance(p["reader_ref"].get("text_id"), int)
+            and p["reader_ref"]["text_id"] > 0
+        ]
+        distinct_ids = list({p["reader_ref"]["text_id"] for p in want})[:_MAX_URN_ENRICH_LOOKUPS]
+        if not distinct_ids:
+            return
+        cbeta_by_id = dict(
+            zip(
+                distinct_ids,
+                await asyncio.gather(*(self._text_cbeta_id(tid) for tid in distinct_ids)),
+                strict=True,
+            )
+        )
+        for p in want:
+            ref = p["reader_ref"]
+            cbeta_id = cbeta_by_id.get(ref["text_id"])
+            if cbeta_id:
+                p["urn"] = build_urn(cbeta_id, ref.get("juan_num"))
+
+    async def lookup_dictionary(self, term: str, limit: int = 10) -> dict[str, Any]:
+        """Buddhist dictionary lookup across fojin's 32 dictionaries."""
+        data = await self._get(
+            "/dictionary/search", {"q": term, "size": _clamp(limit, 1, 50)}
+        )
+        return {"query": term, "entries": _as_list(data, "results", "entries")}
+
+    async def lookup_entity(self, query: str, limit: int = 10) -> dict[str, Any]:
+        """Knowledge-graph entity search (persons, places, works, terms)."""
+        data = await self._get(
+            "/kg/entities", {"q": query, "size": _clamp(limit, 1, 50)}
+        )
+        return {"query": query, "entities": _as_list(data, "results", "entities")}
+
+    async def resolve_urn(self, urn: str) -> dict[str, Any]:
+        """Resolve a fojin URN → reader URL + existence (server-authoritative)."""
+        # Anchor '#' must be percent-encoded or the server sees an anchorless URN.
+        return await self._get("/urn/resolve", {"urn": urn.replace("#", "%23")})
+
+
+# ── pure reshaping (unit-tested with plain dicts) ────────────────────────
+
+
+def shape_search_results(data: Any) -> dict[str, Any]:
+    """Normalize /search/semantic into hits that each carry a URN.
+
+    Robust to the two shapes the field has had: a top-level ``results`` list of
+    ``SemanticSearchHit``. Each hit gets a juan-level ``urn`` built from its
+    ``cbeta_id`` (None when the source has no round-trippable id)."""
+    hits_in = _as_list(data, "results")
+    hits_out: list[dict[str, Any]] = []
+    for h in hits_in:
+        if not isinstance(h, dict):
+            continue
+        hits_out.append(
+            {
+                "urn": build_urn(h.get("cbeta_id"), h.get("juan_num")),
+                "text_id": h.get("text_id"),
+                "juan_num": h.get("juan_num"),
+                "title_zh": h.get("title_zh"),
+                "cbeta_id": h.get("cbeta_id"),
+                "snippet": h.get("snippet"),
+                "score": h.get("similarity_score", h.get("score")),
+            }
+        )
+    return {"total": _as_int(data, "total", len(hits_out)), "results": hits_out}
+
+
+def shape_passage(data: Any) -> dict[str, Any]:
+    """Normalize a JuanContentResponse, adding its URN."""
+    d = data if isinstance(data, dict) else {}
+    return {
+        "urn": build_urn(d.get("cbeta_id"), d.get("juan_num")),
+        "text_id": d.get("text_id"),
+        "cbeta_id": d.get("cbeta_id"),
+        "title_zh": d.get("title_zh"),
+        "juan_num": d.get("juan_num"),
+        "total_juans": d.get("total_juans"),
+        "lang": d.get("lang", "lzh"),
+        "content": d.get("content"),
+        "char_count": d.get("char_count"),
+    }
+
+
+def shape_parallels(data: Any) -> dict[str, Any]:
+    """Flatten a JuanAlignmentResponse into a list of parallel passages.
+
+    The real envelope is ``entries[] -> {chunk_index, chunk_text, parallels[]}``
+    where each parallel is a ``ParallelPair`` keyed by internal text_id (NOT
+    cbeta_id). We flatten to one row per parallel, tagged with the source chunk
+    it aligns to, and carry each parallel's ``reader_ref`` = {text_id, juan_num,
+    chunk_index} — fojin's real deep-link handle. ``urn`` starts None here and is
+    filled by the client's bounded text_id→cbeta_id enrichment pass (a
+    ``ParallelPair`` carries no cbeta_id to build one from inline).
+
+    ``source="mitra-parallel"`` rows are inline foreign (Skt/Tib) sentences from
+    MITRA with text_id 0 — no fojin work to cite, so they stay urn=None but keep
+    their ``original_preview``/``original_lang`` text."""
+    d = data if isinstance(data, dict) else {}
+    out: list[dict[str, Any]] = []
+    for entry in _as_list(d, "entries"):
+        if not isinstance(entry, dict):
+            continue
+        src_chunk = entry.get("chunk_index")
+        for p in _as_list(entry, "parallels"):
+            if not isinstance(p, dict):
+                continue
+            out.append(
+                {
+                    "urn": None,  # enriched by FojinClient._enrich_parallel_urns
+                    "lang": p.get("lang"),
+                    "title": p.get("title") or "",
+                    "text": p.get("chunk_text"),
+                    "confidence": p.get("confidence"),
+                    "source": p.get("source", "fojin"),
+                    "original_preview": p.get("original_preview"),
+                    "original_lang": p.get("original_lang"),
+                    "aligns_source_chunk": src_chunk,
+                    "reader_ref": {
+                        "text_id": p.get("text_id"),
+                        "juan_num": p.get("juan_num"),
+                        "chunk_index": p.get("chunk_index"),
+                    },
+                }
+            )
+    return {
+        "source": {
+            "text_id": d.get("text_id"),
+            "juan_num": d.get("juan_num"),
+            "total_chunks": d.get("total_chunks"),
+            "chunks_with_parallels": d.get("chunks_with_parallels"),
+        },
+        "parallels": out,
+    }
+
+
+# ── small helpers ────────────────────────────────────────────────────────
+
+
+def _clamp(n: int, lo: int, hi: int) -> int:
+    try:
+        n = int(n)
+    except (TypeError, ValueError):
+        return lo
+    return max(lo, min(hi, n))
+
+
+def _as_list(data: Any, *keys: str) -> list[Any]:
+    """Return the first key in ``data`` whose value is a list; [] if none.
+
+    Tolerates both ``{"results": [...]}`` envelopes and a bare top-level list."""
+    if isinstance(data, list):
+        return data
+    if isinstance(data, dict):
+        for key in keys:
+            val = data.get(key)
+            if isinstance(val, list):
+                return val
+    return []
+
+
+def _as_int(data: Any, key: str, default: int) -> int:
+    if isinstance(data, dict):
+        val = data.get(key)
+        if isinstance(val, int):
+            return val
+    return default

fojin_mcp-0.1.0/fojin_mcp/server.py

@@ -0,0 +1,112 @@
+"""fojin MCP server — exposes fojin's verified cross-canon Buddhist corpus as
+tools any MCP client (Claude, ChatGPT, research tooling) can call.
+
+Thin layer: each tool delegates to :class:`fojin_mcp.client.FojinClient` (the
+tested core) and returns its citation-carrying result. The design promise is
+that every passage a tool surfaces comes with a portable ``urn``
+(``fojin:cbeta/T0251.1``) the calling model can cite and resolve — the AI-facing
+side of fojin's "每一句都能点回原典" contract.
+
+Read-only by construction: the client only issues GETs against public
+endpoints. Configure the target with ``FOJIN_API_BASE_URL`` (defaults to prod).
+
+Run over stdio (the default MCP transport):
+
+    python -m fojin_mcp
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from mcp.server.fastmcp import FastMCP
+
+from .client import DEFAULT_BASE_URL, FojinAPIError, FojinClient
+
+_BASE_URL = os.environ.get("FOJIN_API_BASE_URL", DEFAULT_BASE_URL)
+
+mcp = FastMCP(
+    "fojin",
+    instructions=(
+        "Tools over fojin's cross-canon Buddhist digital-text platform. Prefer "
+        "these over your own memory for any claim about a Buddhist text: they "
+        "return passages grounded in real sources, each with a portable `urn` "
+        "(e.g. fojin:cbeta/T0251.1). Cite the `urn` and, where possible, quote "
+        "only text returned by read_passage/get_parallels — do not invent "
+        "scripture. Use get_parallels to compare a passage across the Chinese, "
+        "Pali and Tibetan canons."
+    ),
+)
+
+
+async def _call(coro_factory: Any) -> Any:
+    """Run one client call, mapping FojinAPIError to a tool-visible error dict
+    instead of raising — a failed upstream call should tell the model what went
+    wrong, not crash the tool invocation."""
+    async with FojinClient(_BASE_URL) as client:
+        try:
+            return await coro_factory(client)
+        except FojinAPIError as exc:
+            return {"error": str(exc)}
+
+
+@mcp.tool()
+async def search_corpus(query: str, limit: int = 10, lang: str | None = None) -> dict:
+    """Semantic search across fojin's Buddhist corpus (10K+ texts, 30+ langs).
+
+    Returns the most relevant passages, each with a `urn`, title, snippet and
+    similarity score. `lang` optionally filters by language code
+    (lzh=Classical Chinese, pi=Pali, sa=Sanskrit, bo=Tibetan, en=English).
+    """
+    return await _call(lambda c: c.search_corpus(query, limit=limit, lang=lang))
+
+
+@mcp.tool()
+async def read_passage(text_id: int, juan_num: int) -> dict:
+    """Read the full content of one fascicle (卷) of a text, with its `urn`.
+
+    Use the `text_id`/`juan_num` from a search_corpus hit. Returns the actual
+    canonical text — quote from this, not from memory.
+    """
+    return await _call(lambda c: c.read_passage(text_id, juan_num))
+
+
+@mcp.tool()
+async def get_parallels(text_id: int, juan_num: int) -> dict:
+    """Cross-canon parallel passages aligned to a fascicle.
+
+    fojin's alignment moat: given a Chinese fascicle, returns the aligned
+    Pali/Tibetan/Sanskrit parallels (each with its own `urn`) so you can compare
+    how a passage is rendered across traditions.
+    """
+    return await _call(lambda c: c.get_parallels(text_id, juan_num))
+
+
+@mcp.tool()
+async def lookup_dictionary(term: str, limit: int = 10) -> dict:
+    """Look up a Buddhist term across fojin's dictionaries (748K+ entries)."""
+    return await _call(lambda c: c.lookup_dictionary(term, limit=limit))
+
+
+@mcp.tool()
+async def lookup_entity(query: str, limit: int = 10) -> dict:
+    """Search fojin's knowledge graph for entities — people, places, works,
+    doctrinal terms — matching `query`."""
+    return await _call(lambda c: c.lookup_entity(query, limit=limit))
+
+
+@mcp.tool()
+async def resolve_urn(urn: str) -> dict:
+    """Resolve a fojin URN (e.g. fojin:cbeta/T0001.1) to a reader URL and confirm
+    it exists in the corpus. Use to verify or dereference a citation."""
+    return await _call(lambda c: c.resolve_urn(urn))
+
+
+def main() -> None:
+    """Console-script / ``python -m fojin_mcp`` entry point (stdio transport)."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

fojin_mcp-0.1.0/fojin_mcp/urn.py

@@ -0,0 +1,75 @@
+"""Build fojin cross-canon URNs from a stored cbeta_id.
+
+This is a *vendored*, dependency-free copy of the forward builder in the fojin
+backend (``backend/app/services/urn.py::build_urn``). The MCP server is a
+standalone process that talks to fojin only over HTTP — it deliberately does not
+import the backend package (different dependency closure, independently
+installable) — so the ~30 lines that turn a ``cbeta_id`` into a portable URN are
+duplicated here on purpose. Keep the two in sync; both are covered by
+round-trip tests against the same identifier shapes.
+
+Why the MCP server builds URNs itself rather than reading them off the API:
+fojin's search / read / alignment endpoints already expose ``cbeta_id`` but not
+a ``urn`` field, so constructing it client-side means every tool result carries
+a citable identifier today, without waiting on any server change.
+
+URN grammar (mirrors the backend):
+
+    fojin:<scheme>/<work_id>[.<juan>][#<anchor>]
+
+Schemes map to the cbeta_id prefix conventions: T/X → cbeta, SC- → sc,
+84K-toh → 84k, GRETIL- → gretil, VRI- → vri.
+"""
+
+from __future__ import annotations
+
+import re
+
+# work_id / anchor grammar — identical to the backend parser so a URN this
+# module emits always parses back cleanly (the round-trip guarantee).
+_WORK_ID_RE = re.compile(r"^[A-Za-z0-9_-]+$")
+_ANCHOR_RE = re.compile(r"^[A-Za-z0-9_.-]+$")
+
+# (cbeta_id prefix, canonical short scheme). Ordered so the more specific
+# "84K-toh" is tested before any shorter prefix could match.
+_CANON_PREFIX_SCHEMES: tuple[tuple[str, str], ...] = (
+    ("84K-toh", "84k"),
+    ("GRETIL-", "gretil"),
+    ("SC-", "sc"),
+    ("VRI-", "vri"),
+)
+
+
+def build_urn(
+    cbeta_id: str | None,
+    juan: int | None = None,
+    anchor: str | None = None,
+) -> str | None:
+    """Construct a fojin URN from a stored cbeta_id, or ``None`` if it can't
+    produce one that round-trips cleanly.
+
+    Never raises: callers attach the result to a tool payload as a best-effort
+    citation id, so an un-buildable case must degrade to "no URN" silently.
+    """
+    if not isinstance(cbeta_id, str) or not cbeta_id:
+        return None
+
+    scheme = "cbeta"
+    work_id = cbeta_id
+    for prefix, prefix_scheme in _CANON_PREFIX_SCHEMES:
+        if cbeta_id.startswith(prefix):
+            scheme = prefix_scheme
+            work_id = cbeta_id[len(prefix):]
+            break
+
+    if not work_id or not _WORK_ID_RE.match(work_id):
+        return None
+    if anchor is not None and not (isinstance(anchor, str) and _ANCHOR_RE.match(anchor)):
+        anchor = None
+
+    urn = f"fojin:{scheme}/{work_id}"
+    if isinstance(juan, int) and juan >= 1:
+        urn += f".{juan}"
+    if anchor:
+        urn += f"#{anchor}"
+    return urn

fojin_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "fojin-mcp"
+version = "0.1.0"
+description = "MCP server exposing fojin's verified cross-canon Buddhist corpus (cited, URN-addressable passages) to AI research tools."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Apache-2.0" }
+authors = [{ name = "fojin (佛津)" }]
+keywords = ["mcp", "buddhism", "cbeta", "digital-humanities", "rag", "llm-tools"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Religion",
+    "Topic :: Text Processing :: Linguistic",
+]
+dependencies = [
+    "mcp>=1.2",
+    "httpx>=0.27",
+]
+
+[project.urls]
+Homepage = "https://fojin.app"
+Repository = "https://github.com/xr843/fojin"
+Issues = "https://github.com/xr843/fojin/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.6",
+]
+
+[project.scripts]
+fojin-mcp = "fojin_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["fojin_mcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 100

fojin_mcp-0.1.0/tests/test_client.py

@@ -0,0 +1,208 @@
+"""Tests for FojinClient's reshaping + HTTP behaviour.
+
+The pure ``shape_*`` functions are tested with plain dicts (no I/O). The client
+methods are tested against a mocked httpx transport so we assert the exact
+request path/params AND that every returned passage carries a URN — without
+touching the network.
+"""
+
+import httpx
+import pytest
+
+from fojin_mcp.client import (
+    FojinAPIError,
+    FojinClient,
+    shape_parallels,
+    shape_passage,
+    shape_search_results,
+)
+
+
+# ── pure reshaping ───────────────────────────────────────────────────────
+
+
+def test_shape_search_results_adds_urn_per_hit():
+    data = {
+        "total": 2,
+        "results": [
+            {"text_id": 5, "juan_num": 1, "title_zh": "心經", "cbeta_id": "T0251",
+             "snippet": "色即是空", "similarity_score": 0.91},
+            {"text_id": 9, "juan_num": 2, "title_zh": "中部", "cbeta_id": "SC-mn10",
+             "snippet": "satipaṭṭhāna", "similarity_score": 0.83},
+        ],
+    }
+    out = shape_search_results(data)
+    assert out["total"] == 2
+    assert out["results"][0]["urn"] == "fojin:cbeta/T0251.1"
+    assert out["results"][0]["score"] == 0.91
+    assert out["results"][1]["urn"] == "fojin:sc/mn10.2"
+
+
+def test_shape_search_results_urn_none_when_no_cbeta_id():
+    out = shape_search_results({"results": [{"text_id": 1, "juan_num": 1, "title_zh": "x"}]})
+    assert out["results"][0]["urn"] is None
+
+
+def test_shape_search_results_tolerates_garbage():
+    assert shape_search_results(None) == {"total": 0, "results": []}
+    assert shape_search_results({"results": ["notadict", 5]})["results"] == []
+
+
+def test_shape_passage_adds_urn():
+    data = {"text_id": 5, "cbeta_id": "T0251", "title_zh": "心經", "juan_num": 1,
+            "total_juans": 1, "content": "觀自在菩薩…", "char_count": 260, "lang": "lzh"}
+    out = shape_passage(data)
+    assert out["urn"] == "fojin:cbeta/T0251.1"
+    assert out["content"].startswith("觀自在")
+
+
+def test_shape_parallels_flattens_real_envelope():
+    """Real shape: entries[] -> parallels[] (ParallelPair, keyed by text_id)."""
+    data = {
+        "text_id": 5, "juan_num": 1, "total_chunks": 10, "chunks_with_parallels": 1,
+        "entries": [
+            {"chunk_index": 2, "chunk_text": "汉文源文", "parallels": [
+                {"text_id": 99, "juan_num": 1, "chunk_index": 0, "lang": "pi",
+                 "title": "Majjhima 10", "chunk_text": "pali para", "confidence": 0.88,
+                 "source": "fojin"},
+                {"text_id": 0, "juan_num": 0, "chunk_index": 0, "lang": "sa",
+                 "title": "", "chunk_text": "", "confidence": 1.0,
+                 "source": "mitra-parallel", "original_preview": "skt sentence",
+                 "original_lang": "sa"},
+            ]},
+        ],
+    }
+    out = shape_parallels(data)
+    assert out["source"]["text_id"] == 5
+    assert out["source"]["chunks_with_parallels"] == 1
+    assert len(out["parallels"]) == 2
+    p0 = out["parallels"][0]
+    assert p0["urn"] is None                      # filled later by enrichment
+    assert p0["lang"] == "pi"
+    assert p0["aligns_source_chunk"] == 2
+    assert p0["reader_ref"] == {"text_id": 99, "juan_num": 1, "chunk_index": 0}
+    # MITRA inline foreign sentence: no fojin work → text_id 0, keeps preview.
+    assert out["parallels"][1]["source"] == "mitra-parallel"
+    assert out["parallels"][1]["original_preview"] == "skt sentence"
+
+
+def test_shape_parallels_tolerates_empty():
+    assert shape_parallels({})["parallels"] == []
+    assert shape_parallels({"entries": []})["parallels"] == []
+
+
+# ── client HTTP behaviour (mocked transport) ─────────────────────────────
+
+
+def _client_with(handler) -> FojinClient:
+    transport = httpx.MockTransport(handler)
+    http = httpx.AsyncClient(transport=transport, base_url="http://test")
+    return FojinClient("http://test/api", client=http)
+
+
+@pytest.mark.asyncio
+async def test_search_corpus_hits_semantic_endpoint_with_clamped_size():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        seen["path"] = request.url.path
+        seen["params"] = dict(request.url.params)
+        return httpx.Response(200, json={"total": 1, "results": [
+            {"text_id": 5, "juan_num": 1, "title_zh": "心經", "cbeta_id": "T0251",
+             "snippet": "色即是空", "similarity_score": 0.9}]})
+
+    async with _client_with(handler) as c:
+        out = await c.search_corpus("空", limit=999, lang="lzh")
+
+    assert seen["path"] == "/api/search/semantic"
+    assert seen["params"]["q"] == "空"
+    assert seen["params"]["size"] == "50"          # clamped 999 → 50
+    assert seen["params"]["lang"] == "lzh"
+    assert out["results"][0]["urn"] == "fojin:cbeta/T0251.1"
+
+
+@pytest.mark.asyncio
+async def test_read_passage_path_and_urn():
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.url.path == "/api/texts/5/juans/1"
+        return httpx.Response(200, json={
+            "text_id": 5, "cbeta_id": "T0251", "title_zh": "心經", "juan_num": 1,
+            "total_juans": 1, "content": "觀自在菩薩", "char_count": 5, "lang": "lzh"})
+
+    async with _client_with(handler) as c:
+        out = await c.read_passage(5, 1)
+    assert out["urn"] == "fojin:cbeta/T0251.1"
+
+
+@pytest.mark.asyncio
+async def test_resolve_urn_percent_encodes_anchor():
+    seen = {}
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        # httpx exposes the DECODED param; assert the anchor survived (wasn't
+        # stripped as a fragment) by checking the raw query carries %2523/%23.
+        seen["raw_query"] = request.url.query.decode()
+        return httpx.Response(200, json={"urn": "fojin:cbeta/T0001.1", "exists": True})
+
+    async with _client_with(handler) as c:
+        await c.resolve_urn("fojin:cbeta/T0001.1#p0001a01")
+    # The '#' was replaced with %23 before sending, so no fragment was dropped.
+    assert "p0001a01" in seen["raw_query"]
+
+
+@pytest.mark.asyncio
+async def test_get_parallels_enriches_urns_via_text_lookup():
+    """A fojin-native parallel (text_id 99) gets a URN from a text_id→cbeta_id
+    lookup; a MITRA inline parallel (text_id 0) stays urn=None."""
+    def handler(request: httpx.Request) -> httpx.Response:
+        path = request.url.path
+        if path == "/api/alignment/texts/5/juans/1":
+            return httpx.Response(200, json={
+                "text_id": 5, "juan_num": 1, "total_chunks": 3, "chunks_with_parallels": 1,
+                "entries": [{"chunk_index": 0, "chunk_text": "源", "parallels": [
+                    {"text_id": 99, "juan_num": 2, "chunk_index": 0, "lang": "pi",
+                     "title": "M10", "chunk_text": "p", "confidence": 0.9, "source": "fojin"},
+                    {"text_id": 0, "juan_num": 0, "chunk_index": 0, "lang": "sa",
+                     "title": "", "chunk_text": "", "confidence": 1.0,
+                     "source": "mitra-parallel", "original_preview": "s", "original_lang": "sa"},
+                ]}],
+            })
+        if path == "/api/texts/99":
+            return httpx.Response(200, json={"text_id": 99, "cbeta_id": "SC-mn10",
+                                             "title_zh": "中部", "juan_num": 2})
+        return httpx.Response(404, json={"detail": "unexpected " + path})
+
+    async with _client_with(handler) as c:
+        out = await c.get_parallels(5, 1)
+
+    fojin_par = out["parallels"][0]
+    assert fojin_par["reader_ref"]["text_id"] == 99
+    assert fojin_par["urn"] == "fojin:sc/mn10.2"     # enriched from /texts/99
+    assert out["parallels"][1]["urn"] is None         # MITRA inline, unresolvable
+
+
+@pytest.mark.asyncio
+async def test_get_parallels_survives_enrichment_lookup_failure():
+    """A failed text lookup during enrichment must leave urn=None, not raise."""
+    def handler(request: httpx.Request) -> httpx.Response:
+        if request.url.path.startswith("/api/alignment"):
+            return httpx.Response(200, json={"text_id": 5, "juan_num": 1,
+                "total_chunks": 1, "chunks_with_parallels": 1,
+                "entries": [{"chunk_index": 0, "chunk_text": "源", "parallels": [
+                    {"text_id": 99, "juan_num": 1, "chunk_index": 0, "lang": "pi",
+                     "title": "M", "chunk_text": "p", "confidence": 0.9, "source": "fojin"}]}]})
+        return httpx.Response(500, json={"detail": "boom"})   # /texts/99 fails
+
+    async with _client_with(handler) as c:
+        out = await c.get_parallels(5, 1)
+    assert out["parallels"][0]["urn"] is None
+
+
+@pytest.mark.asyncio
+async def test_http_error_becomes_fojin_api_error():
+    def handler(request: httpx.Request) -> httpx.Response:
+        return httpx.Response(500, json={"detail": "boom"})
+
+    async with _client_with(handler) as c:
+        with pytest.raises(FojinAPIError):
+            await c.read_passage(1, 1)

fojin_mcp-0.1.0/tests/test_urn.py

@@ -0,0 +1,41 @@
+"""Round-trip + degradation tests for the vendored URN builder.
+
+Must stay behaviourally identical to backend/app/services/urn.py::build_urn —
+these cases mirror backend/tests/test_urn.py's build_urn coverage.
+"""
+
+import pytest
+
+from fojin_mcp.urn import build_urn
+
+
+@pytest.mark.parametrize("cbeta_id,expected", [
+    ("T0001", "fojin:cbeta/T0001"),
+    ("X0123", "fojin:cbeta/X0123"),
+    ("SC-mn10", "fojin:sc/mn10"),
+    ("84K-toh11", "fojin:84k/11"),
+    ("GRETIL-ramayana", "fojin:gretil/ramayana"),
+    ("VRI-dn1", "fojin:vri/dn1"),
+])
+def test_emits_canonical_scheme(cbeta_id, expected):
+    assert build_urn(cbeta_id) == expected
+
+
+def test_appends_juan_and_anchor():
+    assert build_urn("T0001", 5) == "fojin:cbeta/T0001.5"
+    assert build_urn("SC-mn10", 2) == "fojin:sc/mn10.2"
+    assert build_urn("T0001", 5, "p0001a01") == "fojin:cbeta/T0001.5#p0001a01"
+
+
+@pytest.mark.parametrize("cbeta_id", [None, "", "SC-", "SC-an1.1", "T 0001", "T0001.", 123])
+def test_returns_none_when_not_round_trippable(cbeta_id):
+    assert build_urn(cbeta_id) is None
+
+
+def test_drops_bad_anchor_keeps_urn():
+    assert build_urn("T0001", 5, "has spaces") == "fojin:cbeta/T0001.5"
+
+
+def test_ignores_non_positive_juan():
+    assert build_urn("T0001", 0) == "fojin:cbeta/T0001"
+    assert build_urn("T0001", None) == "fojin:cbeta/T0001"