# xianmi-mcp

Remote [MCP](https://modelcontextprotocol.io/) server for **Xianmi Library** ([显密文库](https://www.xianmi.co/)) — a non-profit digital library of ~250,000 pages of Chinese Buddhist texts: sutras and commentaries, Chinese/Tibetan/Theravada traditions, and modern Chinese translations of the canon.

It wraps the library's already-public interfaces (full-text search API and per-page Markdown sources) in the MCP protocol, so AI assistants can search and read the library directly.

## Endpoint

```
POST https://mcp.xianmi.co/mcp
```

Transport: **Streamable HTTP** (stateless). No authentication. CORS is open.

Connect from any MCP client that supports remote servers, e.g.:

```json
{
  "mcpServers": {
    "xianmi": {
      "type": "http",
      "url": "https://mcp.xianmi.co/mcp"
    }
  }
}
```

## Tools

### `search_texts`

Full-text search over the whole library.

| param | type | default | description |
| --- | --- | --- | --- |
| `query` | string (required) | — | Search keywords, e.g. `金刚经` |
| `lang` | `zh-Hans` \| `zh-Hant` | `zh-Hans` | Simplified or Traditional Chinese edition |
| `page` | integer ≥ 1 | `1` | Result page, 10 per page |

Returns ranked titles, page URLs, snippets, and a ready-to-use `get_passage` call hint per hit.

### `get_passage`

Fetch the complete Markdown source of one article.

| param | type | default | description |
| --- | --- | --- | --- |
| `path` | string (required) | — | Article path, e.g. `p01/a/109/764` (a full page URL also works) |
| `lang` | `zh-Hans` \| `zh-Hant` | `zh-Hans` | Simplified or Traditional Chinese edition |

Typical flow: `search_texts("金刚经")` → pick a hit → `get_passage("p02/h/2186/94639")`.

### `semantic_search`

Semantic (embedding-based) search over the **p05 Buddhist Sutras collection** (~1.8k public-domain scriptures, modern Simplified Chinese) via Cloudflare AI Search. Best for natural-language conceptual queries; for exact quotes or full-library keyword search, use `search_texts`.

| param | type | default | description |
| --- | --- | --- | --- |
| `query` | string (required) | — | Natural-language query, e.g. `如何消除烦恼` |
| `max_results` | integer 1–20 | `10` | Max documents to return |

Returns matched passages with relevance scores, page URLs, and `get_passage` hints.

## Content licensing

Every response carries a source URL and a license pointer. Content on xianmi.co falls into three classes (CC0 / MIT / public domain); details and usage terms: **https://www.xianmi.co/open/**. Attribution is required when republishing.

## Fair-use limits

To keep the service free, usage is capped: `semantic_search` 800 calls/month (semantic queries are metered upstream), `search_texts` and `get_passage` 5,000 calls/day each. When a cap is reached the tool says so and suggests an alternative.

## Agent Skill

This repo also ships an [Agent Skill](https://agentskills.io) at [`skills/xianmi-library/SKILL.md`](skills/xianmi-library/SKILL.md): the methodology for AI agents to use the library well — tool selection strategy (semantic vs keyword vs full-text), the no-MCP fallback (`/api/search` + `/md/` + llms.txt), language-edition choice, citation format, and the meaning of the `<!-- verse:* -->` verse anchors found in Markdown sources. Drop the `skills/xianmi-library/` directory into any Agent-Skills-compatible client.

## Development

```sh
npm install
npm run dev      # wrangler dev (local)
npm test         # unit tests (node --test)
npm run deploy   # deploy to Cloudflare Workers
```

Built on the official [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) (`WebStandardStreamableHTTPServerTransport` + the CF-Workers-compatible validator).

## License

MIT (server code). Library **content** is licensed separately — see https://www.xianmi.co/open/.