Lira

CI Python 3.10+ MIT

An MCP server over the official Liara cloud documentation. Four read-only tools — search, page read, deployment config and build-log diagnosis — over a corpus that ships inside the package: 3,502 chunks across 1,143 pages, mostly Persian, some English.

No ingest step, no database, no vector store, and no API key required. A fresh install answers immediately.

you  ▸ my database gets wiped after every deploy on Liara. why?
      ⚙ search_docs("liara disk persistence deploy")
      ⚙ read_page("https://docs.liara.ir/paas/disks/getting-started/")

The retrieval stack and the prompt-injection defenses are lifted from lia-helper, a Persian RAG assistant over the same corpus that won Best Solution for the Liara challenge at the StartCoach hackathon in August 2026. This repository is the part of it that is useful to any assistant, not just that one.

---

Install

The server needs no configuration. Point your host at it and restart.

Claude Code

claude mcp add liara-docs -- uvx --from git+https://github.com/SalehB1/Lira-mcp liara-docs-mcp

Claude Desktop — ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows. Quit Claude fully and reopen it after editing; the config is read at launch.

{
  "mcpServers": {
    "liara-docs": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/SalehB1/Lira-mcp", "liara-docs-mcp"]
    }
  }
}

Cursor — .cursor/mcp.json

{
  "mcpServers": {
    "liara-docs": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/SalehB1/Lira-mcp", "liara-docs-mcp"]
    }
  }
}

VS Code — .vscode/mcp.json. Note the different wrapper key and the type field.

{
  "servers": {
    "liara-docs": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/SalehB1/Lira-mcp", "liara-docs-mcp"]
    }
  }
}

Then ask your assistant something it could not answer before:

دیتابیسم بعد از هر دیپلوی پاک میشه، چیکار کنم؟

---

The tools

Tool	Returns	Bounds
search_docs	Numbered snippets with their source URLs. The tool to reach for on any factual claim.	query ≤ 300 chars, k clamped to 1–8, 600 chars per snippet
read_page	One whole documentation page. No network fetch exists on this path — the URL must already be in the loaded corpus.	body ≤ 8,000 chars
platform_docs	Every canonical deployment page for one of 15 platforms, plus the complete liara.json reference, plus one search per stated need. Enough to write a correct liara.json and cite every key.	platform through an enum, ≤ 10 needs of ≤ 80 chars
diagnose_log	The error signature extracted from a failing build or runtime log, and the pages that explain that class of failure.	log ≤ 20,000 chars, last 300 lines, signature ≤ 200 chars

There is also one resource, liara://corpus, reporting which documentation snapshot answered: upstream commit, ingest date, chunk and page counts, and whether dense search is active.

Every tool is annotated read_only_hint. Nothing here writes anything.

---

How it searches

Three ranked lists, fused by reciprocal rank at equal weight. Word-level BM25 and dense cosine over 50 candidates each, character-4-gram BM25 over 20, combined as 1/(60 + rank + 1) with ties broken on raw cosine. No reranker, no cross-encoder: either one puts a model call on every query.

The n-gram list is deliberately the short one. Sub-word overlap is the weakest of the three signals, and a long tail of it outvotes the word index on literal questions. Measured on a 100-question set: at 18–22 candidates literal recall@5 holds its 51/55 baseline while paraphrase recall goes 14 → 18; at the full 50, paraphrase reaches 20 but literal drops to 49.

One Persian normalizer, hand-written, no NLP dependency. A 49-key str.translate table applied after NFC: Arabic→Persian letter unifications, both Arabic-Indic digit ranges folded to ASCII, and 19 deletions covering tatweel, diacritics and invisible bidi marks. No target is itself a key, which makes normalize idempotent by construction. ZWNJ is kept and ZWJ is deleted, because ZWNJ is load-bearing orthography: پایگاه‌داده must stay one token while Node.js splits into two. Stemming is four suffixes, additive — tokenize emits both the surface form and the stem, so a wrong cut can only ever add a term the query side produces identically.

Character n-grams buy morphology and typos, not scripts. داکر and docker share no n-gram at all. Bridging that is what the 73 bidirectional synonym groups are for, and synonym expansion is BM25-only: the dense leg embeds the untouched query.

The dense list is optional and degrades silently by design. Set AVALAI_API_KEY and each query is embedded through an OpenAI-compatible /embeddings endpoint, cached in process. Without it — or on a timeout, a bad response, or a provenance mismatch between embeddings.npz and the corpus it was built from — the query runs on the two lexical lists and nothing errors. Seven independent conditions drop the dense leg, and none of them fails a request.

---

Grounding

The corpus is public third-party markdown and demonstrably contains instruction-shaped text: one page in it is a leftover content brief telling the reader to rewrite links. Four layers assume it is hostile, and all four are enforced in code rather than asked for in a prompt.

Layer	Where
Every result carrying documents is wrapped in <docs source="untrusted">…</docs>, so a model is told the contents are data.	tools.py
_neutralize escapes any <docs> tag in corpus text so a page cannot close the envelope or forge a trusted one, and breaks a line-leading [n] so a page author cannot mint a citation header. Applied separately to URL, title, heading and body.	tools.py
A URL allowlist at load: prefix https://docs.liara.ir/ and a slug-shaped path regex, because everything after the prefix is author-chosen and a URL carrying </docs> would close the envelope from inside.	retrieval.py
Citation numbers are minted server-side by the registry, keyed by chunk id, at the moment a chunk is formatted.	citations.py

read_page reads only URLs already in the loaded index. There is no HTTP client on the tool path, so it cannot be pointed at an internal host.

Two honest limits. A number can only be created here, but nothing resolves the markers back out of a finished answer, because over MCP the answer is written by the client's model and this server never sees it — the upstream project could check that and this one cannot. And the instruction that the corpus is data rather than instructions travels in the server's instructions field, which a client is free to drop; the four rows above are the part that does not depend on being read.

Runnable check: uv run pytest tests/test_untrusted_corpus.py -v drives a javascript: URL, a plain-http URL and a URL carrying </docs> through the real loader, then feeds _neutralize a forged envelope and two forged citation headers.

---

Run it as a shared service

--http serves Streamable HTTP instead of stdio, for one instance several people point at.

uvx --from git+https://github.com/SalehB1/Lira-mcp liara-docs-mcp --http --port 8000
# clients connect to http://127.0.0.1:8000/mcp
# GET /healthz answers {"status":"ok","chunks":3502,...}

The Host allowlist is the one thing to get right. The MCP SDK defaults to DNS-rebinding protection that accepts only localhost Host headers, which is correct on a laptop and returns 421 Misdirected Request to every request behind a real hostname. So:

• Set MCP_ALLOWED_HOSTS=mcp.example.com,mcp.example.com:* and the server allowlists exactly those. Entries are matched literally, so list the bare host and the :* port form both. There is no wildcard, and MCP_ALLOWED_ORIGINS on its own is refused at startup rather than left to 421 every request.
• Bind to loopback with nothing set, and the SDK default stands.
• Bind to a public interface with nothing set, and the server assumes a reverse proxy already controls Host, switches the check off, and says so in the log rather than silently refusing every caller.

Deploying to Liara, whose CLI reads the committed liara.json:

liara app:create --platform docker --name liara-docs-mcp
liara deploy

Do not set AVALAI_API_KEY on a public instance unless you accept paying for one embedding call per distinct query from anyone who can reach it. There is no authentication on the HTTP transport; this serves public documentation and nothing else.

---

Environment

Every key is optional and every default works.

Key	Default	What it does
AVALAI_API_KEY	(unset)	Turns on the dense retrieval list. The only outbound call this server makes.
AVALAI_BASE_URL	https://api.avalai.ir/v1	Any OpenAI-compatible /embeddings endpoint.
EMBED_MODEL	text-embedding-3-small	Must match what embeddings.npz was built with, or the matrix is refused at load.
EMBED_DIM	1536	Same. A different-width model is caught here; a same-width one is caught by the provenance hash.
DATA_DIR	packaged data/	Where chunks.jsonl, embeddings.npz and corpus_meta.json live.
LOG_LEVEL	INFO	Logs go to stderr; stdout is the stdio wire.
NO_PROXY_HOSTS	api.avalai.ir	Hosts to keep away from a local proxy. api.avalai.ir answers in 0.2 s directly and hangs for 30 s through one.
MCP_ALLOWED_HOSTS	(unset)	--http only. See above.
MCP_ALLOWED_ORIGINS	(unset)	--http only. Browsers, and nothing else, send Origin. Requires MCP_ALLOWED_HOSTS.

---

Development

git clone https://github.com/SalehB1/Lira-mcp && cd Lira-mcp
uv sync
uv run pytest -q            # 73 checks, no key and no network
uv run ruff check .
uv run mcp dev src/liara_docs_mcp/server.py    # the MCP Inspector

The test suite runs the real corpus through the real tools and drives the server through an in-process MCP client, so what it asserts is what a host actually sees. It forces the keyless configuration, so a real key in your shell cannot turn a test run into a spend.

---

The corpus

A frozen snapshot of public/llms/**/*.md from liara-cloud/docs, committed to this repository rather than fetched at startup — so there is no crawler in the boot path and a cold start does no work.

Upstream commit	dbb7430b1abc5bf92ccca3538f45c54bdc632fa8
Ingested	2026-08-21
Contents	3,502 chunks over 1,143 pages — 3,270 Persian, 232 English
Embeddings	3,502 × 1,536, text-embedding-3-small

corpus_meta.json carries that provenance, and embeddings.npz is stamped with the corpus hash it was built from: a matrix that disagrees with the chunks actually on disk is refused rather than multiplied. Ask the server itself by reading the liara://corpus resource.

Refreshing it means running lia-helper's ingest/ against a newer docs commit and copying the three files back into src/liara_docs_mcp/data/.

---

Limitations

• The corpus is frozen at one upstream commit. Nothing here schedules a refresh, so pages added to the documentation since August 2026 are not searchable.
• Dense retrieval has one provider and no fallback. Without a key it is simply absent, which is a quality difference a caller cannot see — /healthz reports dense_search for exactly this reason.
• The whole corpus is scored on every query. A matrix @ query dot product over 3,502 chunks with no approximate-nearest-neighbour index is right at this size and does not carry to a million.
• Persian-first. Queries work in both languages and 174 of the 375 synonym keys are Latin, but the documentation itself is overwhelmingly Persian and the answers a model composes from it will be too.
• No authentication on the HTTP transport. It serves public documentation; see the spend note above before exposing an instance with a key set.
• Retrieval quality is unmeasured against what actually ships. The numbers quoted above come from the original project's harness against raw user wording, not against queries an MCP client's model composes.

---

MIT — see LICENSE.