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).
