io.github.matematicsolutions/pk-eli-mcp
MCP server for Pakistani law: search and cite federal statutes and Supreme Court judgments.
Open source Open in the app JSON README (API)
About
MCP server for Pakistani law: search and cite federal statutes and Supreme Court judgments.
Details
- Kind
- MCP servers
- Topic
- Government & public data
- Publisher
- matematicsolutions
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.4.3
- Last push
- 2026-08-24T13:57:30Z
- Repository state
- ativo
- Language
- Python
- License
- Apache-2.0
- Added
- 2026-08-29 04:00:29
- Updated
- 2026-08-29 04:00:29
- Origin id
io.github.matematicsolutions/pk-eli-mcp
README
# pk-eli-mcp
<!-- mcp-name: io.github.matematicsolutions/pk-eli-mcp -->
MCP server for Pakistani law: 967 federal statutes and 1,414 Supreme Court of
Pakistan judgments, full text, with a strict citation contract on every response.
Pakistan publishes no machine-readable legal API, so this connector is
**corpus-based**: it serves two public HuggingFace mirrors of official sources
instead of querying a government endpoint live.
| Collection | Source | Snapshot | License |
|---|---|---|---|
| Federal statutes (967) | [Pakistan_Laws_Dataset](https://huggingface.co/datasets/AyeshaJadoon/Pakistan_Laws_Dataset), collected from [pakistancode.gov.pk](https://pakistancode.gov.pk/) PDFs (Ministry of Law and Justice) | 2025-01-30 | ODC-BY 1.0 |
| Supreme Court judgments (1,414) | [supreme-court-of-pak-judgments](https://huggingface.co/datasets/Ibtehaj10/supreme-court-of-pak-judgments) | 2024-07-26 | MIT |
**Honest limits, stated up front:** both collections are static snapshots.
Amendments after 2025-01-30 and judgments after 2024-07-26 are absent, and the
judgment corpus is a subset of the Court's output. Every response repeats this
in `dataset_note`. Verify currency against [pakistancode.gov.pk](https://pakistancode.gov.pk/)
and [scp.gov.pk](https://www.scp.gov.pk/) before relying on a provision.
## Tools
| Tool | What it does |
|---|---|
| `pk_search_laws` | Keyword search over the 967 federal statutes (title-weighted). First call downloads the 47 MB corpus once, then serves from cache. |
| `pk_get_law` | Full statute text by `law_id` (truncated at ~300,000 characters). |
| `pk_case_search` | Server-side full-text search over the Supreme Court judgments. |
| `pk_get_decision` | One judgment's full text, by `row_idx` or registry `case_id`. |
| `pk_verify_citations` | Anti-hallucination check: extracts Pakistani legal citations from any text and verifies each against the corpus. |
| `pk_coverage` | Declare what this connector covers, when each family was captured, and - explicitly - what it does NOT cover. Every gap carries a fallback. |
## Citation verification (`pk_verify_citations`)
Run it on a drafted answer, memo or pleading before it reaches a reader. The tool
extracts every checkable citation and verifies it against the corpus:
- statute sections: `section 302 of the Pakistan Penal Code`,
`section 10A of the Pakistan Study Centres Act, 1976`, `sections 6 and 7 of ...`,
`sub-section (1) of section 6 of ...`;
- act coordinates: `Act No. XLV of 1860`, `Ordinance No. LII of 2000` (Roman or Arabic);
- Constitution articles: `Article 184(3) of the Constitution` (the tail is required -
a bare `Article 5` could be any instrument and is deliberately ignored);
- Supreme Court registry citations: `Crl.A. 93/2013`, `Criminal Appeal No. 93 of 2013`.
The semantics are deliberately hard:
- A cited section that does not exist makes the whole result `HALLUCINATION_DETECTED`
with `isError=true`, plus a range hint of what does exist (`section 999 does not
exist in this act; 59 sections are machine-detectable in its text, numbered
section 1-66`).
- `NO_CITATIONS_FOUND` is not a success - it means there was nothing to check.
- A parenthetical description right after a citation
(`section 302 of the Pakistan Penal Code (punishment of qatl-i-amd)`) is
content-checked against the real provision text with a character-trigram match.
A mismatch is a review signal, never a hard block.
- Everything the tool could NOT check is listed in a structured `gaps` field. The
judgment corpus is a subset and roughly half the statute PDFs carry no
machine-readable coordinate header, so an unresolvable citation is reported as
`out_of_corpus` ("existence UNKNOWN, not disproven"), never as a hallucination.
The parse-verify-report pattern is adapted from
[korean-law-mcp](https://github.com/chrisryugj/korean-law-mcp) (MIT) - see
`THIRD_PARTY.md`. The same pattern shipped first in it-eli-mcp v0.6.0; the fleet
rollout plan lives in [`docs/VERIFY-ROLLOUT.md`](docs/VERIFY-ROLLOUT.md).
## Citation contract
Pakistan has not deployed ELI. Every response still carries the fleet contract:
- `eli_uri` - a stable, resolvable URL: the canonical pakistancode.gov.pk PDF for
statutes, the dataset row URI for judgments. Never invented; see `eli_note`.
- `human_readable_citation` - e.g. `THE PRIVATISATION COMMISSION ORDINANCE, 2000`
or `Supreme Court of Pakistan, Crl.A. 93/2013`.
- `source_url` - where a human can read the same document.
## Install
```bash
uvx pk-eli-mcp # or: pip install pk-eli-mcp
```
Claude Code:
```bash
claude mcp add pk-eli-mcp -- uvx pk-eli-mcp
```
Or drop `.mcp.json.example` into your project as `.mcp.json`.
### Windows 11 with Smart App Control
Smart App Control blocks unsigned executables, which covers `uvx.exe`, `pip.exe`
and the `pk-eli-mcp.exe` launcher that pip writes at install time. The `python.exe` and
`py.exe` from the python.org installer are signed by the Python Software
Foundation, so running the module through the interpreter works:
```bash
python -m pip install pk-eli-mcp
python -m pk_eli_mcp
```
`pip.exe` is blocked for the same reason, so install with `python -m pip`, not
`pip install`. If `python` is not on PATH, use the Windows launcher: `py -3 -m pk_eli_mcp`.
```json
{ "mcpServers": { "pk-eli-mcp": { "command": "python", "args": ["-m", "pk_eli_mcp"] } } }
```
Do not turn Smart App Control off to work around this - it cannot be re-enabled
without reinstalling Windows.
## Configuration
| Env | Default | Purpose |
|---|---|---|
| `PK_ELI_CACHE_DIR` | `~/.matematic/cache/pk-eli` | Corpus file + HTTP cache |
| `PK_ELI_AUDIT_DIR` | `~/.matematic/audit` | JSONL audit log (one line per tool call) |
## Development
```bash
python -m venv .venv && .venv/Scripts/pip install -e ".[dev]" # Linux/macOS: .venv/bin/pip
ruff check src tests
pytest tests/test_instructions_drift.py tests/test_corpus.py # offline
pytest tests/test_smoke.py # live (downloads the corpus)
```
## Governance
Read-only by design: the server can search and fetch, never write. Every tool
call appends an audit line (`~/.matematic/audit/pk-eli-mcp.jsonl`) with a SHA-256
input hash, duration and status. See `CONSTITUTION.md` for the rules this
connector is built under and `DISCOVERY.md` for how the sources were chosen.
## License
Apache-2.0 for this code. The datasets keep their own licenses (ODC-BY 1.0 and
MIT); the underlying texts are Government of Pakistan public legal documents.