@lexapi/mcp 0.2.0 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +110 -0
- package/LICENSE +1 -1
- package/README.md +128 -35
- package/dist/client.d.ts +125 -21
- package/dist/client.js +442 -97
- package/dist/credentials.d.ts +67 -0
- package/dist/credentials.js +118 -0
- package/dist/errors.d.ts +53 -0
- package/dist/errors.js +313 -0
- package/dist/http-entry.js +19 -2
- package/dist/http-server.d.ts +48 -2
- package/dist/http-server.js +544 -111
- package/dist/index.js +18 -60
- package/dist/oauth/body.d.ts +5 -0
- package/dist/oauth/body.js +35 -0
- package/dist/oauth/config.d.ts +59 -0
- package/dist/oauth/config.js +149 -0
- package/dist/oauth/exchange.d.ts +196 -0
- package/dist/oauth/exchange.js +573 -0
- package/dist/oauth/jwt.d.ts +124 -0
- package/dist/oauth/jwt.js +352 -0
- package/dist/oauth/redact.d.ts +1 -0
- package/dist/oauth/redact.js +23 -0
- package/dist/oauth/upstream.d.ts +41 -0
- package/dist/oauth/upstream.js +95 -0
- package/dist/server.d.ts +62 -0
- package/dist/server.js +100 -0
- package/dist/shape.d.ts +115 -0
- package/dist/shape.js +1043 -0
- package/dist/tools.d.ts +29 -8
- package/dist/tools.js +1071 -216
- package/dist/webhookUrl.d.ts +4 -0
- package/dist/webhookUrl.js +114 -0
- package/package.json +23 -15
- package/dist/types.d.ts +0 -43
- package/dist/types.js +0 -7
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `@lexapi/mcp`. Versions follow [semver](https://semver.org); while the package is 0.x, a minor bump can change behaviour.
|
|
4
|
+
|
|
5
|
+
## 0.5.0 — unreleased
|
|
6
|
+
|
|
7
|
+
Brings the citation-graph tools in line with LexAPI API 2.11.0 (transposition, counterparts, edge provenance and filters); **requires LexAPI API 2.11.0**. The coverage fields of API 2.12.0 / 2.13.0 are passed through unchanged.
|
|
8
|
+
|
|
9
|
+
### Added
|
|
10
|
+
- **`lex_transposition`** (5 credits, every plan): the measures the member states (and the United Kingdom) notified to the Commission for an EU act, grouped by country, from the Publications Office's Cellar records. The API's `note` — a notification is not a finding that the measure transposes the act, or transposes it completely — is always kept, and the tool description tells the model to say so. On BUSINESS, SCALE and ENTERPRISE, for live countries, the measures LexAPI holds carry `id` / `resolved` / `resolution` / `resolutionBasis`, and measures recorded by the national source itself are added (`provenance: "source"`); `termsRequired` is surfaced. `jurisdictions` and `resolvedOnly` are forwarded; the measures are bounded by `limit` (default 50, at most 200) / `offset` across countries and about 40,000 characters per result, with every country's `counts` and `source.cellar.attribution` kept; when the API truncated its answer, the result says so and where the full numbers are.
|
|
11
|
+
- **`lex_counterparts`** (20 credits, BUSINESS, SCALE and ENTERPRISE only): a national document's counterparts in the other live countries, through the EU acts it transposes or implements, ranked 1–3; an EU act as `id` lists its measures the same way. `jurisdictions` is forwarded; output is bounded to 25 EU acts and about 40,000 characters per call (`offset`) and `limit` counterparts per act (default 10, at most 50).
|
|
12
|
+
- **Edge filters** on `lex_cited_by`, `lex_cites`, `lex_citation_network`, `lex_citation_path` and `lex_related`: `citationType` now takes a list (and the new type `transposition`), plus `provenance`, `resolution` and `jurisdictions`. Lists are sent comma-separated; values are validated before the call.
|
|
13
|
+
- `language` (the language of the titles shown) on `lex_cited_by`, `lex_cites`, `lex_citation_network`, `lex_citation_path`, `lex_related`, `lex_transposition` and `lex_counterparts`.
|
|
14
|
+
- **`unresolved`** on `lex_cites` and `lex_citation_network` (national document ids): the references that could not be turned into an edge, the first 100 shown, with `unresolvedTruncated`.
|
|
15
|
+
- Citation results show each edge group's `provenance` and `resolution`, and a node's `jurisdiction` (national documents only) and `documentKind`; `lex_cited_by` / `lex_cites` keep `totalEdges` and `countsSource` (API 2.10.0), `lex_citation_network` keeps `paging.countsSource`. `lex_citation_stats` passes `byJurisdiction`, `byProvenance` and `transposition` through.
|
|
16
|
+
- `describeError`: a legacy-shape `400 INVALID_PARAMS` now shows `param` and `allowed`; `403 NATIONAL_TERMS_NOT_ACCEPTED` points at the one-time acceptance in the dashboard (`acceptUrl`); a `503 TIMEOUT` (counterparts) says it was refunded and to narrow with `jurisdictions`.
|
|
17
|
+
- `lex_national_semantic_case_law` / `lex_national_semantic_legislation` keep `partial` / `partialReason` (`SEARCH_INCOMPLETE`): the national index could not complete the search, so results may be incomplete; both descriptions say so.
|
|
18
|
+
- `describeError`: `422 NATIONAL_SEMANTIC_FILTER_UNREACHABLE` says the index cannot search that slice completely, that it is not a "no matches" answer, and to rephrase the query or change the filters (not retryable as is); a `503 NATIONAL_SEMANTIC_UNAVAILABLE` with `partialReason: "SEARCH_INCOMPLETE"` says it is not a "no matches" answer and gives the wait, or — without one — to try later or rephrase.
|
|
19
|
+
- `lex_resolve`'s description explains `resolvedVia` (incl. `eli-cellar`) and `verified` (passed through when the API sends them); it suggests checking the CELEX only for an unverified `eli` answer.
|
|
20
|
+
|
|
21
|
+
### Changed
|
|
22
|
+
- A `503` whose body says `TIMEOUT` (a server-side time budget ran out) is no longer retried automatically; other 503s are retried as before.
|
|
23
|
+
- A `503` with `partialReason: "SEARCH_INCOMPLETE"` is retried at most once, only after its wait (`Retry-After`, else the body's `retryAfter`; at most 10 s) and only when at least 15 s of the call's deadline is left after it; without a wait it is not retried. Other 503s are retried as before, and a 503 is never described as a rate limit.
|
|
24
|
+
- `lex_national_coverage`'s description mentions the `citationGraph` measurements it returns.
|
|
25
|
+
|
|
26
|
+
## 0.4.0 — unreleased
|
|
27
|
+
|
|
28
|
+
Adds national-law support (member-state legislation and case law alongside EUR-Lex; **requires LexAPI API 2.8.0**) and **Sign in with LexAPI** on the hosted server.
|
|
29
|
+
|
|
30
|
+
### National document shape (API 2.8.0)
|
|
31
|
+
- The national tools present the same fields for every country, read from the normalized contract and never from a source's raw keys (Austria's `gericht`, Germany's `aktenzeichen`, the Netherlands' `zaaknummer`, …): `documentKind` (`act` | `decision`) on listing rows, documents and semantic hits; on a decision, `lex_get_national_document` flattens `decision` into `court`, `chamber`, `caseNumbers` and `citedNorms` (`{ text, documentId }`) — also when the decision has no text; articles are `{ number, title, section, text, inForceFrom, inForceTo }` (a unit without text keeps `text: null`). The text's language facts (`textLanguages` when it differs from the document's language, `textLanguage`, `embeddedForeignText`) and a confirmed `repeal` are surfaced at the top level. Null-filled summary fields are compacted away, as before.
|
|
32
|
+
- `lex_national_semantic_case_law` hits take `documentKind`, `title`, `ecli` and `dateOfDocument` from each hit's `document` (LexAPI's own record), falling back to the index's metadata; `court` and `caseNumbers` come from the index. `lex_national_semantic_legislation` hits add `documentKind`, `documentType`, `valid_from` and `law_type`.
|
|
33
|
+
|
|
34
|
+
### Added
|
|
35
|
+
- **5 tools**: `lex_national_coverage` (which countries are live, and their legislation/case-law/semantic coverage, sources, licences and attribution — call this first), `lex_list_national_documents` (browse by title/type), `lex_get_national_document` (fetch one by id), `lex_national_semantic_case_law` and `lex_national_semantic_legislation` (separate tools, mirroring the `lex_semantic_case_law` / `lex_semantic_legislation` split — different filters and billing notes). Every tool but the coverage one states in its description that a country may be registered but not yet available to customers, and to call `lex_national_coverage` first.
|
|
36
|
+
- **National-law allowance**: `X-National-Limit` / `X-National-Remaining` / `X-National-Reset` response headers are surfaced as `allowance: { limit, remaining, resetsAt }` on every national tool's result (omitted for BUSINESS and higher, which have no separate limit). A `402 NATIONAL_ALLOWANCE_EXHAUSTED` gets its own actionable message in `describeError`, distinct from the credit-pool `CREDITS_EXHAUSTED` message: it's a separate monthly counter, a credit top-up does not help, and it resets at the start of next UTC month.
|
|
37
|
+
- `attribution` (the official source and its licence, e.g. RIS, gesetze-im-internet.de, Normattiva, Légifrance/Judilibre, the Rechtspraak open data) is kept on every national document and every semantic hit — never dropped by response shaping, since it's required legal attribution, not optional context.
|
|
38
|
+
- National legislation search has no `asOf` parameter (not supported for national law); national case-law search accepts `hyde` for schema compatibility with `lex_semantic_case_law` but it is always a no-op (the national index never rewrites, so it never costs the 15-credit premium).
|
|
39
|
+
- **`includeNational` on the citation-graph tools** (`lex_cited_by`, `lex_cites`, `lex_citation_network`, `lex_citation_path`, `lex_related`, `lex_citation_stats`): also returns/follows national neighbours of live countries (BUSINESS, SCALE and ENTERPRISE only — 403 below that). `celexNumber` and `lex_citation_path`'s `from`/`to` now also accept a national document id directly (e.g. `"AT-NOR-12345"`); `includeNational` is carried through response shaping. `lex_extract_citations` is unchanged (CELEX/EU-only).
|
|
40
|
+
- A national document its source withdrew (a takedown, a pseudonymisation fix) now answers `410 DOCUMENT_WITHDRAWN` — a dedicated `describeError` branch says it's gone for good (not retryable), to drop any cached copy, and not to try to identify who it was about. Covers both envelope shapes: the typed one (`lex_get_national_document`) and the legacy one (citation tools for a withdrawn national id). `lex_list_national_documents` gained `cursor` (pages past the first 1,000 rows that `page` reaches) and the response fields `totalExact`/`hasMore`/`nextCursor`; `q`'s minimum length is 3; its cost stays 3 credits flat.
|
|
41
|
+
- A licensing/permitted-use guardrail in `SERVER_INSTRUCTIONS`: consolidated national texts are not authentic; never re-identify anonymised/pseudonymised parties; never evaluate/compare/predict individual French judges (art. 33 loi n° 2019-222).
|
|
42
|
+
- **Sign in with LexAPI** on the hosted server (`https://mcp.lex-api.com/v1`). MCP clients that support MCP authorization (OAuth 2.1) can connect with your LexAPI account instead of a pasted API key: add the URL, sign in, approve the consent page. Calls are billed to your plan exactly as with an API key, and you can disconnect the app at any time from the LexAPI dashboard.
|
|
43
|
+
- OAuth Protected Resource Metadata (RFC 9728) at `https://mcp.lex-api.com/.well-known/oauth-protected-resource/v1`. An unauthenticated request gets `401` with `WWW-Authenticate: Bearer realm="lexapi", resource_metadata="…", scope="lex"`; a rejected or expired token gets `error="invalid_token"`, so clients refresh or re-authorize.
|
|
44
|
+
- A connection that is revoked while in use is answered with `401 invalid_token` where possible, or with a tool error asking to reconnect.
|
|
45
|
+
- `/health` reports whether sign-in is enabled.
|
|
46
|
+
### Changed
|
|
47
|
+
- `409 NATIONAL_SEMANTIC_NOT_ENABLED` and `503 NATIONAL_SEMANTIC_UNAVAILABLE` get their own `describeError` messages (point at the right country/tools, not the account); the 404 branch detects a national miss and stops pointing at `lex_resolve`/`lex_search`. `lex_national_semantic_legislation`'s `query` has a minimum length of 3 characters, matching case law. Both national semantic tools' `language` accepts the full ISO 639-1 range rather than the 10-language EU enum (national lanes are single-language and not all are in that list). `lex_get_national_document`'s cost note is "5 reserved, settles at 1" (a pool under 5 credits still 402s). `lex_list_national_documents`' `documentType` accepts up to 200 characters.
|
|
48
|
+
- `lex_get_national_document`'s outline reading hint points at `view "full"` + `offset` (that tool has no `articleId`/`include` parameter).
|
|
49
|
+
- README: how to connect from claude.ai / Claude Desktop (custom connector), Claude Code (`claude mcp add --transport http lexapi https://mcp.lex-api.com/v1`, then `/mcp` → *Authenticate*) and other MCP clients; the API-key option remains documented. The FREE-plan note now points to the pricing page instead of quoting an allowance.
|
|
50
|
+
- `server.json`: the remote's `Authorization` header is now optional (sign-in is discovered from the server's 401); version 0.4.0.
|
|
51
|
+
- Hosted server: a credential that cannot be a LexAPI API key (contains a `.` or is over 8192 characters) is answered `401` by the MCP server instead of being forwarded. No valid API key is affected.
|
|
52
|
+
- API keys (`Authorization: Bearer lex_…` or `x-api-key`) keep working on the hosted server exactly as before; when both headers are sent with sign-in enabled, `x-api-key` takes precedence.
|
|
53
|
+
|
|
54
|
+
## 0.3.0 — 2026-10-26
|
|
55
|
+
|
|
56
|
+
Brings the server in line with the current LexAPI API (API changelog up to the consolidated-text / `asOf` release).
|
|
57
|
+
|
|
58
|
+
### Added
|
|
59
|
+
- **`asOf` on `lex_semantic_legislation`** — the law as in force on a date. Hits carry `asOf`, `asOfResolved`, `asOfReason`, `asOfVersion`, `matchedVersion`; the response carries `asOf` / `asOfSummary`, plus an `asOfCaveat` when some hits could not be resolved to that date.
|
|
60
|
+
- **Consolidated-text labels** surfaced on legislation hits (`consolidated`, `consolidatedAsOf`, `baseCelex`, `consolidatedNote`, `baseAct`) and derived on documents fetched by a consolidated CELEX, with a `citing` note telling the model to cite the authentic act.
|
|
61
|
+
- 16 tools for endpoints the server did not cover: `lex_info`, `lex_resolve`, `lex_get_documents_batch`, `lex_document_versions`, `lex_get_document_version`, `lex_citation_path`, `lex_related`, `lex_citation_stats`, `lex_extract_citations`, `lex_export`, `lex_list_webhooks`, `lex_get_webhook`, `lex_create_webhook`, `lex_update_webhook`, `lex_delete_webhook`, `lex_test_webhook`.
|
|
62
|
+
- `lex_export` (API 2.3.0): `dateFrom` / `dateTo` (the API's document-date filter now works), `changedSince` (rows whose text changed) and `documentTypeCode` (type families); `documentType` is described as an exact, case-insensitive label match; `fetchedSince` / `changedSince` take a date or a date-time with a timezone, validated exactly as the API does (zone `Z`, `±HH:MM` or `±HHMM`; optional seconds; a 1–9 digit fraction; calendar-valid dates, also for `dateFrom` / `dateTo`). The result carries `truncatedBy` (`limit`, `max_rows` or `credits`) next to `truncated`. The cost is stated exactly: 1 credit per row returned, at least 1 per call — a 1-credit admission, a reservation up to `limit`, a refund of unreturned rows, and a 402 before anything is returned when the pool cannot cover the reservation.
|
|
63
|
+
- Webhook URLs are checked before the call: https, port 443/8443, no credentials, no single-label / internal / reserved hostnames, no private, loopback, link-local or other special-purpose IP literals (IPv4-mapped and NAT64 included) — the DNS-free half of the API's egress guard; the API remains authoritative.
|
|
64
|
+
- Missing parameters: `lex_get_document` `language`, `acceptLanguages`, `articleId`, `include`; `lex_get_document_by_url` `articleId`, `include`, `bypassCorpus`; `lex_get_metadata` `bypassCorpus`; `lex_search` `month`, `procedure`, `domain`, `subdomain`, `fresh`; `lex_recent_documents` `domain`, `subdomain`; `lex_citation_network` `citationType`, `limit`, `offset`; semantic tools `language`, `include`; `lex_semantic_case_law` `hyde` and typed `filters` (`court`, `date_from`, `date_to`, `case_number`, `ecli`).
|
|
65
|
+
- Server `instructions` (workflow, citing consolidated texts, `asOf` vs. version snapshots, credit awareness), tool `title`s, server `title` / `websiteUrl`.
|
|
66
|
+
- `LEXAPI_MCP_READ_ONLY` hides the webhook-changing tools; `LEXAPI_TIMEOUT_MS`.
|
|
67
|
+
- Hosted HTTP server also accepts `x-api-key`; answers `405` to GET/DELETE (stateless), `413` to oversized bodies (and closes the connection), `WWW-Authenticate` on `401`; validates `Origin` (MCP spec, DNS-rebinding defence): browser origins must be listed in `LEXAPI_MCP_ALLOWED_ORIGINS`, requests without `Origin` are allowed.
|
|
68
|
+
- Cancellation: an MCP `notifications/cancelled` (or a closed HTTP connection) aborts the upstream LexAPI request. Progress notifications every 10 s when the request carries a progress token (they do not raise the timeout: a server cannot tell whether the client resets its timeout on progress).
|
|
69
|
+
- `asOfCaveat` groups unresolved hits by reason: `notInForce` (that is the answer), `retryable`, `needsCredits`, `unavailable`, each with guidance.
|
|
70
|
+
- Long items (a giant annex, a `fullText` without blank lines) are split into parts that `offset` pages through; the outline's article list is bounded by `maxChars` and paged with `offset`; the outline hint only suggests parts the document has.
|
|
71
|
+
- Tests (vitest: unit, in-memory MCP, Streamable HTTP and stdio end-to-end against a mock API), ESLint, CI, `scripts/smoke-stdio.mjs`.
|
|
72
|
+
|
|
73
|
+
### Changed
|
|
74
|
+
- **Responses are compact and bounded.** Tool output is unindented JSON without the `subscription` / `usage` envelopes, legacy duplicate fields, opaque upstream metadata or snapshot-scoped ids. `lex_get_document` (and by-URL / batch / version snapshots) return the full body only when it fits `maxChars` (default 40,000 characters) — otherwise an outline with article ids, and `articleId` / `include` / `offset` to read on. v0.2 returned the whole document (hundreds of KB for large acts), which most clients truncate.
|
|
75
|
+
- `textAvailability` is passed through verbatim whenever text is missing (reason, languages, consolidated pointers); language fallback (`languageRequested`, `languageFallback`) and `titleLanguage` are kept.
|
|
76
|
+
- **Errors are actionable**: 402 states the credits needed, available and the reset date; 429 the wait; 401/403/404/5xx what to do. Both the typed and the legacy error envelopes are parsed.
|
|
77
|
+
- 429s from the legacy daily quota and monthly semantic quota (no `Retry-After`) say "exhausted until `usage.resetsAt` — do not retry", instead of "wait a minute".
|
|
78
|
+
- A top-level string `code` on a legacy-shape error body is now the error code, ahead of the legacy `error` text. A 429 with `code: "QUOTA_EXHAUSTED"` is never retried (even with a short `Retry-After`), carries no retry-after, exposes `resetsAt` (the body's `resetsAt`, else `usage.resetsAt`) and says "exhausted until <resetsAt> — do not retry, tell the user". Servers without the `code` are still recognised by the old shape check.
|
|
79
|
+
- `lex_export` no longer presents a partial export as the result: a stream without its `_done` trailer, a `_done` with `complete: false`, or a line whose only key is `_error` returns an error naming the rows received; an `_error` line is never returned as a row.
|
|
80
|
+
- One 55 s deadline per tool call (under the 60 s default of MCP clients), shared by all attempts, backoff and 429 waits; `LEXAPI_TIMEOUT_MS` raises it.
|
|
81
|
+
- The API key is validated at startup (no whitespace / control characters); network errors never echo runtime text (undici can quote header values).
|
|
82
|
+
- Retries: a 429 is retried once only when `Retry-After` ≤ 10 s (v0.2 slept on any Retry-After, twice); 500/502/503 and network errors once; 504 never (it already spent a 90 s upstream budget); webhook create/test/delete never. Every call has one deadline (55 s default; v0.2 had no timeout).
|
|
83
|
+
- Inputs are validated by the MCP SDK (zod) before any API call.
|
|
84
|
+
- CELEX inputs accept consolidated (`02016R0679-20180524`) and corrigendum (`32013R0952R(04)`) forms, lower case and a `CELEX:` prefix — v0.2's pattern rejected the first two.
|
|
85
|
+
- Enums synced with the API: document type `staff-working-document` added and `opinion-act` removed (the API ignores it); citation type `corrigendum`; author `civil-service-tribunal`; semantic `language` limited to the indexed languages.
|
|
86
|
+
- Defaults lowered to cut credit and token use: `lex_recent_documents` `limit` 20 (was 50, i.e. 15 credits when filtered), citation `limit` 50 (was 100).
|
|
87
|
+
- Tool descriptions rewritten: costs per call, when to use which tool, FREE plans can use semantic search (credit plans), legislation `filters` honour only `language`.
|
|
88
|
+
- `@modelcontextprotocol/sdk` ^1.0.0 → ^1.32.2 (protocol 2025-11-25), high-level `McpServer` API; `zod` added; dependency overrides removed (`npm audit`: 0 vulnerabilities).
|
|
89
|
+
- `User-Agent: lexapi-mcp/<version>` on every request.
|
|
90
|
+
|
|
91
|
+
### Breaking
|
|
92
|
+
- Tool output shape changed (compact; large documents outlined). Prompts that relied on v0.2's raw API JSON (e.g. `document.content.fullText` always present) need `include: ["fullText"]`.
|
|
93
|
+
- Inputs are validated before any call; v0.2 forwarded anything. Newly rejected:
|
|
94
|
+
- `documentType: "opinion-act"` (it never filtered anything);
|
|
95
|
+
- `lex_semantic_case_law.query` shorter than 3 characters (the semantic index rejects it; the API answered 502);
|
|
96
|
+
- semantic `language` outside the 10 indexed languages (`en, fr, de, es, it, sl, el, nl, pt, pl`); document/search `language` outside the 24 EU codes;
|
|
97
|
+
- `lex_search.maxPages` above 100 (the highest plan cap); `year` outside 1950–2100; `month` outside 1–12;
|
|
98
|
+
- malformed CELEX numbers, dates not in `YYYY-MM-DD`, unknown webhook `searchCriteria` keys.
|
|
99
|
+
- Smaller defaults: `lex_recent_documents` `limit` 20 (was 50), citation `limit` 50 (was 100).
|
|
100
|
+
- `LEXAPI_MCP_READ_ONLY` also hides `lex_extract_citations`.
|
|
101
|
+
- One 55 s deadline per tool call (v0.2: no timeout at all) unless `LEXAPI_TIMEOUT_MS` is set.
|
|
102
|
+
- Hosted HTTP: browser requests with an `Origin` not listed in `LEXAPI_MCP_ALLOWED_ORIGINS` get 403; a malformed key (whitespace inside the value) gets 401 `malformed_api_key`; an oversized body is drained (up to 16 MB / 5 s) and answered 413, then the connection closes.
|
|
103
|
+
- Webhook `url` values that are not public https URLs are rejected at validation.
|
|
104
|
+
- Tool names are unchanged.
|
|
105
|
+
|
|
106
|
+
## 0.2.0
|
|
107
|
+
- Hosted Streamable HTTP transport (`/v1`, Bearer auth) for mcp.lex-api.com; `server.json` advertises it.
|
|
108
|
+
|
|
109
|
+
## 0.1.x
|
|
110
|
+
- Initial ten tools over stdio; registry metadata; README fixes.
|
package/LICENSE
CHANGED
package/README.md
CHANGED
|
@@ -1,16 +1,44 @@
|
|
|
1
1
|
# LexAPI MCP
|
|
2
2
|
|
|
3
|
-
[Model Context Protocol](https://modelcontextprotocol.io) server for [LexAPI](https://lex-api.com/?ref=npm-mcp) —
|
|
3
|
+
[Model Context Protocol](https://modelcontextprotocol.io) server for [LexAPI](https://lex-api.com/?ref=npm-mcp) — EU law for AI assistants: EUR-Lex legislation parsed to article level, CJEU case law, the typed citation graph, and semantic search (including **the law as in force on a past date**). Works with Claude, Cursor, VS Code and any other MCP client.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
Ask your assistant *"what does Article 17 GDPR require?"*, *"which acts amended REACH?"* or *"what were the own-funds requirements for banks in June 2019?"* — the model calls LexAPI and answers from the source text, with CELEX citations.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
You need a LexAPI account. With the hosted server you just **sign in with LexAPI** from your MCP client; with the npm package (or if you prefer), use an API key from [lex-api.com/dashboard](https://lex-api.com/dashboard?ref=npm-mcp). There is a FREE plan, no card required, with enough credits to try the read tools; current allowances are on [lex-api.com/pricing](https://lex-api.com/pricing?ref=npm-mcp).
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
## Connect to the hosted server (sign in with LexAPI)
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
The server is hosted at **`https://mcp.lex-api.com/v1`** (Streamable HTTP). Add that URL to your client and sign in with your LexAPI account when it asks — no key to copy. You see a LexAPI consent page listing what the connection can do; calls are billed to your plan exactly like your own API key, and you can disconnect the app at any time under *Dashboard → Connected apps* (that revokes it immediately).
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
### claude.ai and Claude Desktop
|
|
14
|
+
|
|
15
|
+
*Settings → Connectors → Add custom connector*, name it `LexAPI`, URL `https://mcp.lex-api.com/v1`, then *Connect* and sign in. Connectors added on claude.ai are also available in Claude Desktop (same account).
|
|
16
|
+
|
|
17
|
+
### Claude Code
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
claude mcp add --transport http lexapi https://mcp.lex-api.com/v1
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
Then run `/mcp` in Claude Code and choose *Authenticate* for `lexapi`; your browser opens the LexAPI sign-in.
|
|
24
|
+
|
|
25
|
+
### Other MCP clients
|
|
26
|
+
|
|
27
|
+
Any client that implements MCP authorization (OAuth 2.1 with protected-resource discovery) connects the same way: point it at `https://mcp.lex-api.com/v1`. The server answers an unauthenticated request with `401` and `WWW-Authenticate: Bearer … resource_metadata="https://mcp.lex-api.com/.well-known/oauth-protected-resource/v1"`; the client discovers LexAPI (`https://lex-api.com`) as the authorization server from there.
|
|
28
|
+
|
|
29
|
+
### With an API key instead
|
|
30
|
+
|
|
31
|
+
Clients without OAuth support — or scripts — send a key from the dashboard as `Authorization: Bearer lex_...` (or `x-api-key: lex_...`):
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
claude mcp add --transport http lexapi https://mcp.lex-api.com/v1 --header "Authorization: Bearer lex_..."
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
## Run it locally (npm, API key)
|
|
38
|
+
|
|
39
|
+
### Claude Desktop (local)
|
|
40
|
+
|
|
41
|
+
Add to `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
|
|
14
42
|
|
|
15
43
|
```json
|
|
16
44
|
{
|
|
@@ -18,9 +46,7 @@ Add to `claude_desktop_config.json` (location: `~/Library/Application Support/Cl
|
|
|
18
46
|
"lexapi": {
|
|
19
47
|
"command": "npx",
|
|
20
48
|
"args": ["-y", "@lexapi/mcp"],
|
|
21
|
-
"env": {
|
|
22
|
-
"LEXAPI_API_KEY": "lex_..."
|
|
23
|
-
}
|
|
49
|
+
"env": { "LEXAPI_API_KEY": "lex_..." }
|
|
24
50
|
}
|
|
25
51
|
}
|
|
26
52
|
}
|
|
@@ -28,59 +54,126 @@ Add to `claude_desktop_config.json` (location: `~/Library/Application Support/Cl
|
|
|
28
54
|
|
|
29
55
|
Restart Claude Desktop.
|
|
30
56
|
|
|
31
|
-
### Claude Code
|
|
57
|
+
### Claude Code (local)
|
|
32
58
|
|
|
33
59
|
```bash
|
|
34
60
|
claude mcp add lexapi --env LEXAPI_API_KEY=lex_... -- npx -y @lexapi/mcp
|
|
35
61
|
```
|
|
36
62
|
|
|
37
|
-
### Cursor
|
|
63
|
+
### Cursor, VS Code and other stdio clients
|
|
64
|
+
|
|
65
|
+
Run `npx -y @lexapi/mcp` with `LEXAPI_API_KEY` in the environment (Cursor: `~/.cursor/mcp.json`; VS Code: `.vscode/mcp.json`; same `command` / `args` / `env` shape as above).
|
|
38
66
|
|
|
39
|
-
|
|
67
|
+
The npm package needs Node.js 20 or newer. It uses an API key; signing in with LexAPI is a feature of the hosted server.
|
|
40
68
|
|
|
41
69
|
## Tools
|
|
42
70
|
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
|
46
|
-
|
|
47
|
-
| `
|
|
48
|
-
| `
|
|
49
|
-
| `
|
|
50
|
-
| `
|
|
51
|
-
| `
|
|
52
|
-
| `
|
|
53
|
-
| `
|
|
54
|
-
| `
|
|
71
|
+
Every call is billed from your LexAPI credit pool exactly like the REST endpoint it wraps; each tool's description states its cost so the model can see it.
|
|
72
|
+
|
|
73
|
+
| Tool | What it does | Credits |
|
|
74
|
+
|---|---|---|
|
|
75
|
+
| `lex_semantic_legislation` | Find legislation articles by meaning. `asOf` returns the text in force on a date. Consolidated hits are labelled, with the authentic act to cite. | 5 (+ up to 5 per live version fetch with `asOf`) |
|
|
76
|
+
| `lex_semantic_case_law` | Find judgments, orders and AG opinions by meaning; `hyde` for terse queries; court / date / case-number filters. | 5 (15 with `hyde`) |
|
|
77
|
+
| `lex_search` | Structured EUR-Lex search: text, dates, type, author, procedure, collection. | 3 per page |
|
|
78
|
+
| `lex_recent_documents` | What was published in the last N days. | 3 per 10 results |
|
|
79
|
+
| `lex_resolve` | URL / ELI / ECLI → CELEX. | 1 |
|
|
80
|
+
| `lex_get_document` | A document by CELEX — an outline first for large acts, then `articleId` or `include` parts; language and fallback languages. | 1 corpus · 4 Cellar · 5 live |
|
|
81
|
+
| `lex_get_documents_batch` | Up to 50 documents at once (plan-capped). | per document, as above |
|
|
82
|
+
| `lex_get_metadata` | Metadata only. | 1 · 4 · 5 |
|
|
83
|
+
| `lex_get_document_by_url` | A document from a pasted EUR-Lex URL. | 1 · 4 · 5 |
|
|
84
|
+
| `lex_document_versions` | LexAPI's observed version history of a document. | 1 |
|
|
85
|
+
| `lex_get_document_version` | One observed snapshot, by version number or date. | 1 |
|
|
86
|
+
| `lex_cited_by` | Documents citing / amending / correcting / repealing / transposing an act, with each edge's provenance. `includeNational` adds national neighbours (BUSINESS+). | 1 |
|
|
87
|
+
| `lex_cites` | What a document cites. `includeNational` adds national neighbours (BUSINESS+). | 1 |
|
|
88
|
+
| `lex_citation_network` | Both directions in one call. `includeNational` adds national neighbours (BUSINESS+). | 20 |
|
|
89
|
+
| `lex_citation_path` | Shortest citation chain between two documents. `includeNational` follows national documents (BUSINESS+). | 20 |
|
|
90
|
+
| `lex_related` | Documents citing the same acts (bibliographic coupling). `includeNational` considers national documents (BUSINESS+). | 20 |
|
|
91
|
+
| `lex_citation_stats` | Citation graph totals and most-cited documents. `includeNational` counts national documents (BUSINESS+). | 20 |
|
|
92
|
+
| `lex_extract_citations` | Add a document's outbound citations to the graph. | 5 (1 if already done) |
|
|
93
|
+
| `lex_transposition` | The measures member states notified to the Commission for an EU act, by country (Cellar records; every plan). A notification is not a finding that the measure transposes the act. On BUSINESS+ it also says which measures LexAPI holds in live countries. | 5 |
|
|
94
|
+
| `lex_counterparts` | A national act's counterparts in the other live countries, through the EU acts it transposes or implements (BUSINESS+). | 20 |
|
|
95
|
+
| `lex_export` | Corpus rows by type (exact label, any case) or type family (`documentTypeCode`), author, collection, language, document date (`dateFrom`/`dateTo`), `changedSince` or `fetchedSince` (BUSINESS plans and above). | 1 per row returned, at least 1 per call (1-credit admission, rows reserved up to `limit`, unreturned rows refunded; 402 if the pool cannot cover the reservation) |
|
|
96
|
+
| `lex_national_coverage` | Which countries' national law LexAPI covers and what's live in each (sources, licences, attribution). Call first. | free |
|
|
97
|
+
| `lex_list_national_documents` | Browse a country's national legislation/case law by title or type; cursor paging past the first 1,000 rows. | 3 per call |
|
|
98
|
+
| `lex_get_national_document` | A national document by id. Always served from the corpus. | 5 → 1 |
|
|
99
|
+
| `lex_national_semantic_case_law` | Semantic search over one country's case law. | 5 |
|
|
100
|
+
| `lex_national_semantic_legislation` | Semantic search over one country's legislation. | 5 |
|
|
101
|
+
| `lex_info` | Your plan, credit balance and limits. | free |
|
|
102
|
+
| `lex_list_webhooks` · `lex_get_webhook` | Your webhooks and their deliveries. | free |
|
|
103
|
+
| `lex_create_webhook` · `lex_update_webhook` · `lex_delete_webhook` · `lex_test_webhook` | Webhooks for new documents and for changes to watched acts (paid plans). The URL must be a public https URL (port 443/8443, no internal hosts or private addresses) — checked here as well as by the API. | free |
|
|
104
|
+
|
|
105
|
+
### National law
|
|
106
|
+
|
|
107
|
+
`lex_national_coverage`, `lex_list_national_documents`, `lex_get_national_document`, `lex_national_semantic_case_law` and `lex_national_semantic_legislation` cover member-state legislation and case law alongside the EU_LAW tools above. A country can be registered on LexAPI before it is made available to customers — always call `lex_national_coverage` first; the other tools answer an error for a country that isn't live yet. The citation-graph tools (`lex_cited_by`, `lex_cites`, `lex_citation_network`, `lex_citation_path`, `lex_related`, `lex_citation_stats`) accept national document ids directly (e.g. `"AT-NOR-12345"`) and an `includeNational` option to pull in national neighbours — BUSINESS, SCALE and ENTERPRISE only, 403 below that. National results have the same fields in every country (LexAPI API 2.8.0): `documentKind` (`act` | `decision`) everywhere, and on a decision `court`, `chamber`, `caseNumbers` and `citedNorms` — whatever the source calls them. Every national result carries `attribution` (the official source and its licence, e.g. RIS, gesetze-im-internet.de, Normattiva, Légifrance/Judilibre, the Rechtspraak open data) — show it to the user alongside anything quoted. On FREE/STARTER/PROFESSIONAL plans, national-law calls also draw from a separate monthly allowance (reported as `allowance` on each response); BUSINESS and higher have no separate limit. A document its source withdrew (a takedown, a pseudonymisation fix) answers a distinct error — nothing of it is served, not even the title; the model is told not to retry and to drop any cached copy. When the national index could not complete a semantic search, the result carries `partial: true` (`partialReason: "SEARCH_INCOMPLETE"`) and a `hint` — results may be incomplete; with nothing left to return the tool answers an error instead (a `503` retried after its `Retry-After`, or a `422 NATIONAL_SEMANTIC_FILTER_UNREACHABLE`: rephrase or change the filters), never an empty "no matches".
|
|
108
|
+
|
|
109
|
+
### Citation-graph filters and provenance
|
|
110
|
+
|
|
111
|
+
`lex_cited_by`, `lex_cites`, `lex_citation_network`, `lex_citation_path` and `lex_related` take `citationType` (one type or a list, including `transposition`), `provenance` (`notice`, `cellar`, `notice+cellar`, `cellar-nim`, `source`, `resolver`), `resolution` (`id`, `key`, `abbreviation`, `text-pattern` — national edges only) and `jurisdictions` (`eu` and the codes of live countries; a national code needs BUSINESS+ like `includeNational`). Results show each edge's `provenance` and `resolution`, and a node's `jurisdiction` (national documents only) and `documentKind`. `cellar-nim` edges are measures a member state notified to the Commission — a notification, not a finding that the measure transposes the act, or transposes it completely. With a national document id, `unresolved: true` on `lex_cites` / `lex_citation_network` adds the references that could not be turned into an edge (the first 100 are shown). `lex_national_coverage` reports each country's citation-graph measurements (`citationGraph`). `lex_transposition` and `lex_counterparts` bound their output with `limit` / `offset`, applied by this MCP server to the API's answer; each further page is a new call at the tool's cost.
|
|
112
|
+
|
|
113
|
+
### How results are shaped for models
|
|
114
|
+
|
|
115
|
+
- **Compact output.** Responses drop envelopes and duplicate legacy fields. Documents keep their metadata, `textAvailability` (why text is missing, which languages exist, a pointer to the latest consolidated version) and language-fallback labels.
|
|
116
|
+
- **Large documents.** `lex_get_document` returns the whole body when it fits `maxChars` (default 40,000 characters), otherwise an outline (article ids, section tree, counts). Fetch an article with `articleId` or parts with `include`; long parts continue with `offset`.
|
|
117
|
+
- **Consolidated texts are not authentic.** Consolidated versions carry `consolidated: true`, `consolidatedAsOf`, `baseCelex` and a note: quote them, cite the act as published in the Official Journal.
|
|
118
|
+
- **`asOf`.** Each legislation hit says whether it carries the version in force on that date (`asOfResolved`, `asOfVersion`); unresolved hits keep the current text with an `asOfReason`, and the response warns about them.
|
|
119
|
+
- **Errors say what to do.** A 402 states the credits needed, the credits left and the reset date; a 429 says how long to wait.
|
|
55
120
|
|
|
56
121
|
## Configuration
|
|
57
122
|
|
|
58
123
|
| Env var | Default | Purpose |
|
|
59
124
|
|---|---|---|
|
|
60
|
-
| `LEXAPI_API_KEY` | *(required)* | Your API key
|
|
61
|
-
| `LEXAPI_BASE_URL` | `https://lex-api.com/api/v1` | Override for
|
|
125
|
+
| `LEXAPI_API_KEY` | *(required)* | Your API key from [lex-api.com/dashboard](https://lex-api.com/dashboard?ref=npm-mcp). |
|
|
126
|
+
| `LEXAPI_BASE_URL` | `https://lex-api.com/api/v1` | Override for staging or self-hosting. |
|
|
127
|
+
| `LEXAPI_MCP_READ_ONLY` | off | `true` hides (and refuses) every tool that is not read-only: webhook create / update / delete / test, and `lex_extract_citations` (it writes to the shared citation graph and costs credits). |
|
|
128
|
+
| `LEXAPI_TIMEOUT_MS` | `55000` | Deadline for one tool call towards LexAPI, retries included. Raise it only together with your MCP client's own tool timeout. |
|
|
129
|
+
| `LEXAPI_MCP_ALLOWED_ORIGINS` | *(none)* | Hosted HTTP server only: browser `Origin`s allowed to call it (comma-separated, `*` for any). Requests without an `Origin` header (all non-browser clients) are always allowed. |
|
|
62
130
|
|
|
63
|
-
|
|
131
|
+
The key is sent only as the `x-api-key` header to LexAPI; it is never logged or included in tool output. A `LEXAPI_API_KEY` containing whitespace or control characters (e.g. a multi-line paste) is rejected at startup.
|
|
132
|
+
|
|
133
|
+
### Hosting the HTTP server
|
|
134
|
+
|
|
135
|
+
`npm run start:http` (or the `Dockerfile`) runs the Streamable HTTP transport (`POST /v1`, `GET /health`). Self-hosted, it accepts LexAPI API keys (`Authorization: Bearer lex_…` or `x-api-key: lex_…`); a request without one gets `401`. A value that cannot be an API key (it contains a `.` or is longer than 8192 characters) is answered `401` and never forwarded.
|
|
136
|
+
|
|
137
|
+
| Env var | Default | Purpose |
|
|
138
|
+
|---|---|---|
|
|
139
|
+
| `PORT` | `3000` | Listen port. |
|
|
140
|
+
| `LEXAPI_BASE_URL` | `https://lex-api.com/api/v1` | LexAPI REST base. |
|
|
141
|
+
|
|
142
|
+
Sign in with LexAPI is a feature of the hosted server at `https://mcp.lex-api.com/v1`: it needs an OAuth client registered with LexAPI, so a self-hosted copy runs with API keys only. The OAuth-related settings in `src/oauth/config.ts` (`LEXAPI_OAUTH_*`, `LEXAPI_MCP_*`) are for that deployment; the server refuses to start if they are set incompletely.
|
|
143
|
+
|
|
144
|
+
**`/health`** returns `status`, `name`, `version`, `tools` and `oauth` (whether sign-in is enabled). It never contains addresses, tokens or configuration values.
|
|
64
145
|
|
|
65
|
-
|
|
146
|
+
**Timeouts.** MCP clients give up on a tool call after their own timeout (60 s by default in the official SDK; Claude Code: `MCP_TOOL_TIMEOUT`). A first, live EUR-Lex fetch can take longer. The server gives each tool call one 55 s deadline — retries and rate-limit waits included — and then returns a message the model can act on, instead of the client's generic timeout error. When the client sends a progress token, the server also sends a progress notification every 10 s; whether that keeps the call alive is up to the client (the official SDK only extends its timeout on progress when the caller opts into `resetTimeoutOnProgress`, and a server cannot detect that), so the deadline stays 55 s. If you raise your client's timeout, raise `LEXAPI_TIMEOUT_MS` to match. Cancelling a call aborts the request to LexAPI.
|
|
66
147
|
|
|
67
|
-
|
|
148
|
+
## Troubleshooting
|
|
149
|
+
|
|
150
|
+
- **`LEXAPI_API_KEY is not set`** — the variable isn't reaching the spawned process; check the `env` block of your MCP client config.
|
|
151
|
+
- **`LexAPI error 401`** — the key is wrong or revoked; create a new one at the dashboard.
|
|
152
|
+
- **Hosted server: "LexAPI sign-in expired or was revoked"** — the connection was disconnected (for example from the dashboard); reconnect LexAPI in your client to sign in again.
|
|
153
|
+
- **Hosted server: `403 Subscription inactive`** — the signed-in account's paid plan is not active; the same as with an API key.
|
|
154
|
+
- **`LexAPI error 402 (CREDITS_EXHAUSTED)`** — the monthly credit pool is used up. The message gives the reset date; top-ups and upgrades are on the dashboard.
|
|
155
|
+
- **`LexAPI error 429`** — the per-minute rate limit of your key (FREE: 15 per minute). Short waits are retried once automatically; otherwise the message says how long to wait.
|
|
156
|
+
- **`LexAPI error 403`** — the plan doesn't include the feature (e.g. export below BUSINESS, or semantic search on a legacy pre-credits FREE plan).
|
|
157
|
+
- **`LexAPI error 400` creating a webhook** — the details name the problem (unsupported criteria, a watch list over the plan limit, or the plan's webhook limit; FREE has none).
|
|
68
158
|
|
|
69
|
-
|
|
159
|
+
## Training data
|
|
70
160
|
|
|
71
|
-
|
|
161
|
+
Using LexAPI content to train, fine-tune or evaluate models needs a separate licence ([Terms §6](https://lex-api.com/terms?ref=npm-mcp#acceptable-use)). [Arieta Data](https://data.arietalabs.com/?ref=npm-mcp), a sister product from Arieta Labs, licenses datasets drawn from the same corpus for training, retrieval and evaluation.
|
|
72
162
|
|
|
73
|
-
##
|
|
163
|
+
## Development
|
|
74
164
|
|
|
75
165
|
```bash
|
|
76
166
|
git clone https://github.com/Lex-API/lexapi-mcp.git
|
|
77
167
|
cd lexapi-mcp
|
|
78
168
|
npm install
|
|
79
|
-
npm
|
|
80
|
-
|
|
81
|
-
|
|
169
|
+
npm test # build + unit and transport tests (mocked API, no network)
|
|
170
|
+
npm run typecheck && npm run lint
|
|
171
|
+
node scripts/smoke-stdio.mjs # stdio smoke test against a local mock API
|
|
172
|
+
LEXAPI_API_KEY=lex_... node scripts/smoke-stdio.mjs --live # against the real API (spends roughly 6–25 credits)
|
|
82
173
|
```
|
|
83
174
|
|
|
175
|
+
`npm run start:http` runs the hosted Streamable HTTP transport (`POST /v1`, `GET /health`, port from `PORT`, default 3000; see *Hosting the HTTP server* above); the `Dockerfile` builds it. The OAuth tests run against a local mock authorization server (`tests/oauth-mock.ts`), no network.
|
|
176
|
+
|
|
84
177
|
## License
|
|
85
178
|
|
|
86
179
|
MIT
|
package/dist/client.d.ts
CHANGED
|
@@ -1,31 +1,135 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
1
|
+
export declare const DEFAULT_BASE_URL = "https://lex-api.com/api/v1";
|
|
2
|
+
/**
|
|
3
|
+
* Deadline for one tool call (all attempts, backoff and 429 sleeps included).
|
|
4
|
+
* MCP clients give up after their own request timeout (the TypeScript SDK
|
|
5
|
+
* default is 60 s; Claude Code: MCP_TOOL_TIMEOUT), so stop a few seconds
|
|
6
|
+
* earlier and return an actionable message instead of the client's generic
|
|
7
|
+
* -32001. LexAPI's own upstream budgets (EUR-Lex fetch 90 s, semantic
|
|
8
|
+
* legislation 45 s, citation network 30 s) can exceed this on a cold live
|
|
9
|
+
* fetch; users who raise their client's timeout raise LEXAPI_TIMEOUT_MS too.
|
|
10
|
+
*/
|
|
11
|
+
export declare const DEFAULT_TIMEOUT_MS = 55000;
|
|
12
|
+
export declare function isWellFormedKey(key: string): boolean;
|
|
13
|
+
/** Response headers worth surfacing to a model; everything else is dropped. */
|
|
14
|
+
declare const KEPT_HEADERS: readonly ["x-source", "x-language", "x-language-fallback", "x-text-available", "x-warning", "x-search-source", "x-search-cache", "x-ignored-documenttypes", "x-corpus-version", "x-export-total", "x-export-truncated", "x-national-limit", "x-national-remaining", "x-national-reset"];
|
|
15
|
+
export type KeptHeader = (typeof KEPT_HEADERS)[number];
|
|
16
|
+
export type Json = Record<string, unknown>;
|
|
17
|
+
export interface LexResponse<T = Json> {
|
|
18
|
+
status: number;
|
|
19
|
+
body: T;
|
|
20
|
+
headers: Partial<Record<KeptHeader, string>>;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* How a request authenticates to LexAPI. The API-key credential sends
|
|
24
|
+
* `x-api-key`; the hosted server's OAuth credential (src/oauth/upstream.ts)
|
|
25
|
+
* sends `Authorization: Bearer <exchanged API token>` and no `x-api-key`.
|
|
26
|
+
*/
|
|
27
|
+
export interface UpstreamAuth {
|
|
28
|
+
/** Headers for one attempt (may exchange a token: throws its own typed errors). */
|
|
29
|
+
headers(ctx: {
|
|
30
|
+
signal?: AbortSignal;
|
|
31
|
+
}): Promise<Record<string, string>> | Record<string, string>;
|
|
32
|
+
/**
|
|
33
|
+
* The API answered 401. Return 'retry' to send the request once more with
|
|
34
|
+
* fresh headers, an Error to fail with it, or undefined for the normal 401.
|
|
35
|
+
*/
|
|
36
|
+
onUnauthorized?(info: {
|
|
37
|
+
wwwAuthenticate: string | null;
|
|
38
|
+
body: string;
|
|
39
|
+
}): Promise<'retry' | Error | undefined> | 'retry' | Error | undefined;
|
|
6
40
|
}
|
|
7
41
|
export interface LexAPIClientOptions {
|
|
8
|
-
|
|
42
|
+
/** API key (stdio, hosted API-key requests). Required unless `auth` is given. */
|
|
43
|
+
apiKey?: string;
|
|
44
|
+
/** Any other credential (hosted OAuth requests). Takes precedence over `apiKey`. */
|
|
45
|
+
auth?: UpstreamAuth;
|
|
9
46
|
baseUrl?: string;
|
|
10
|
-
/**
|
|
47
|
+
/** Retries on transient failures (500/502/503, network errors, short 429s). Default 1. */
|
|
11
48
|
maxRetries?: number;
|
|
49
|
+
timeoutMs?: number;
|
|
50
|
+
/** Injected for tests. */
|
|
51
|
+
fetch?: typeof fetch;
|
|
52
|
+
/** Injected for tests. */
|
|
53
|
+
sleep?: (ms: number) => Promise<void>;
|
|
54
|
+
/** Aborts every request of this client (MCP request cancellation). */
|
|
55
|
+
signal?: AbortSignal;
|
|
56
|
+
/** Injected for tests (the per-call deadline clock). */
|
|
57
|
+
now?: () => number;
|
|
58
|
+
}
|
|
59
|
+
export type Query = Record<string, string | number | boolean | string[] | undefined | null>;
|
|
60
|
+
interface RequestOptions {
|
|
61
|
+
body?: unknown;
|
|
62
|
+
query?: Query;
|
|
63
|
+
/** Parse the body as NDJSON (one JSON value per line) instead of JSON. */
|
|
64
|
+
ndjson?: boolean;
|
|
65
|
+
/** Calls whose repetition has a side effect (create, test delivery) opt out. */
|
|
66
|
+
retry?: boolean;
|
|
12
67
|
}
|
|
13
68
|
export declare class LexAPIClient {
|
|
14
|
-
private readonly
|
|
69
|
+
private readonly auth;
|
|
15
70
|
private readonly baseUrl;
|
|
16
71
|
private readonly maxRetries;
|
|
72
|
+
private readonly timeoutMs;
|
|
73
|
+
private readonly fetchImpl;
|
|
74
|
+
private readonly sleep;
|
|
75
|
+
private readonly signal?;
|
|
76
|
+
private readonly now;
|
|
77
|
+
private readonly opts;
|
|
17
78
|
constructor(opts: LexAPIClientOptions);
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
79
|
+
/** A client for one MCP request: its cancellation signal and timeout. */
|
|
80
|
+
forCall(call: {
|
|
81
|
+
signal?: AbortSignal;
|
|
82
|
+
timeoutMs?: number;
|
|
83
|
+
}): LexAPIClient;
|
|
84
|
+
get timeout(): number;
|
|
85
|
+
private credentialHeaders;
|
|
86
|
+
/** Low-level request. Throws LexAPIError (HTTP error) or LexAPITransportError. */
|
|
87
|
+
request<T = Json>(method: 'GET' | 'POST' | 'PUT' | 'DELETE', path: string, opts?: RequestOptions): Promise<LexResponse<T>>;
|
|
88
|
+
info(): Promise<LexResponse<Json>>;
|
|
89
|
+
search(body: Json): Promise<LexResponse<Json>>;
|
|
90
|
+
getDocument(body: Json): Promise<LexResponse<Json>>;
|
|
91
|
+
getDocumentsBatch(body: Json): Promise<LexResponse<Json>>;
|
|
92
|
+
getMetadata(body: Json): Promise<LexResponse<Json>>;
|
|
93
|
+
getDocumentByUrl(body: Json): Promise<LexResponse<Json>>;
|
|
94
|
+
recentDocuments(query: Query): Promise<LexResponse<Json>>;
|
|
95
|
+
resolve(body: Json): Promise<LexResponse<Json>>;
|
|
96
|
+
listVersions(celex: string, query: Query): Promise<LexResponse<Json>>;
|
|
97
|
+
getVersion(celex: string, version: number, query: Query): Promise<LexResponse<Json>>;
|
|
98
|
+
getAtDate(celex: string, date: string, query: Query): Promise<LexResponse<Json>>;
|
|
99
|
+
exportCorpus(query: Query): Promise<LexResponse<{
|
|
100
|
+
lines?: unknown[];
|
|
101
|
+
}>>;
|
|
102
|
+
semanticCaseLaw(body: Json): Promise<LexResponse<Json>>;
|
|
103
|
+
semanticLegislation(body: Json): Promise<LexResponse<Json>>;
|
|
104
|
+
extractCitations(body: Json): Promise<LexResponse<Json>>;
|
|
105
|
+
citedBy(celex: string, query: Query): Promise<LexResponse<Json>>;
|
|
106
|
+
cites(celex: string, query: Query): Promise<LexResponse<Json>>;
|
|
107
|
+
citationNetwork(celex: string, query: Query): Promise<LexResponse<Json>>;
|
|
108
|
+
citationPath(from: string, to: string, query: Query): Promise<LexResponse<Json>>;
|
|
109
|
+
related(celex: string, query: Query): Promise<LexResponse<Json>>;
|
|
110
|
+
citationStats(query?: Query): Promise<LexResponse<Json>>;
|
|
111
|
+
transposition(celex: string, query?: Query): Promise<LexResponse<Json>>;
|
|
112
|
+
counterparts(id: string, query?: Query): Promise<LexResponse<Json>>;
|
|
113
|
+
nationalCoverage(): Promise<LexResponse<Json>>;
|
|
114
|
+
getNationalDocument(jurisdiction: string, id: string, query: Query): Promise<LexResponse<Json>>;
|
|
115
|
+
listNationalDocuments(jurisdiction: string, query: Query): Promise<LexResponse<Json>>;
|
|
116
|
+
nationalSemanticCaseLaw(jurisdiction: string, body: Json): Promise<LexResponse<Json>>;
|
|
117
|
+
nationalSemanticLegislation(jurisdiction: string, body: Json): Promise<LexResponse<Json>>;
|
|
118
|
+
listWebhooks(): Promise<LexResponse<Json>>;
|
|
119
|
+
getWebhook(id: string): Promise<LexResponse<Json>>;
|
|
120
|
+
webhookDeliveries(id: string, query: Query): Promise<LexResponse<Json>>;
|
|
121
|
+
createWebhook(body: Json): Promise<LexResponse<Json>>;
|
|
122
|
+
updateWebhook(id: string, body: Json): Promise<LexResponse<Json>>;
|
|
123
|
+
deleteWebhook(id: string): Promise<LexResponse<Json>>;
|
|
124
|
+
testWebhook(id: string): Promise<LexResponse<Json>>;
|
|
31
125
|
}
|
|
126
|
+
/**
|
|
127
|
+
* The call's cancellation signal combined with this attempt's timeout.
|
|
128
|
+
* `dispose()` detaches the listeners of the pre-20.3 fallback (no
|
|
129
|
+
* AbortSignal.any), so long-lived call signals don't accumulate them.
|
|
130
|
+
*/
|
|
131
|
+
export declare function combineSignals(a: AbortSignal | undefined, b: AbortSignal): {
|
|
132
|
+
signal: AbortSignal;
|
|
133
|
+
dispose: () => void;
|
|
134
|
+
};
|
|
135
|
+
export {};
|