@lexapi/mcp 0.3.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 +54 -5
- package/README.md +75 -21
- package/dist/client.d.ts +34 -4
- package/dist/client.js +163 -24
- package/dist/credentials.d.ts +67 -0
- package/dist/credentials.js +118 -0
- package/dist/errors.d.ts +18 -0
- package/dist/errors.js +155 -6
- package/dist/http-entry.js +19 -2
- package/dist/http-server.d.ts +36 -4
- package/dist/http-server.js +417 -50
- 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 +2 -1
- package/dist/server.js +4 -1
- package/dist/shape.d.ts +54 -0
- package/dist/shape.js +444 -8
- package/dist/tools.d.ts +5 -1
- package/dist/tools.js +295 -25
- package/package.json +2 -2
package/dist/tools.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { z } from 'zod';
|
|
2
2
|
import { webhookUrlProblem } from './webhookUrl.js';
|
|
3
|
-
import { compact, creditNotice, isObj, shapeCaseLaw, shapeCitedBy, shapeCites, shapeContent, shapeDocument, shapeLegislation, shapeMetadata, shapeNetwork, shapeRecent, shapeSearch, stripEnvelope, } from './shape.js';
|
|
3
|
+
import { compact, creditNotice, isObj, nationalAllowanceOf, shapeCaseLaw, shapeCitedBy, shapeCites, shapeContent, shapeCounterparts, shapeDocument, shapeLegislation, shapeMetadata, shapeNationalCaseLaw, shapeNationalDocument, shapeNationalLegislation, shapeNationalSearchResult, shapeNetwork, shapeRecent, shapeSearch, shapeTransposition, nodeFields, stripEnvelope, } from './shape.js';
|
|
4
4
|
// ── Shared vocabularies (mirroring openapi.yaml / GET /info) ─────────
|
|
5
5
|
export const LANGUAGES = [
|
|
6
6
|
'en', 'fr', 'de', 'es', 'it', 'pl', 'nl', 'pt', 'ro', 'bg', 'cs', 'da',
|
|
@@ -31,8 +31,12 @@ export const SUBDOMAINS = [
|
|
|
31
31
|
'international', 'preparatory', 'questions', 'national-case-law',
|
|
32
32
|
];
|
|
33
33
|
export const CITATION_TYPES = [
|
|
34
|
-
'reference', 'amendment', 'repeal', 'corrigendum', 'implementation', 'legal-basis', 'proposal',
|
|
34
|
+
'reference', 'amendment', 'repeal', 'corrigendum', 'implementation', 'legal-basis', 'proposal', 'transposition',
|
|
35
35
|
];
|
|
36
|
+
/** Where an edge comes from (API 2.11.0 CitationProvenance). */
|
|
37
|
+
export const CITATION_PROVENANCES = ['notice', 'cellar', 'notice+cellar', 'cellar-nim', 'source', 'resolver'];
|
|
38
|
+
/** How a national edge's target was identified (API 2.11.0 CitationResolution). */
|
|
39
|
+
export const CITATION_RESOLUTIONS = ['id', 'key', 'abbreviation', 'text-pattern'];
|
|
36
40
|
const CONTENT_PARTS = ['metadata', 'fullText', 'articles', 'recitals', 'paragraphs', 'sections', 'tables', 'annexes'];
|
|
37
41
|
// Mirrors the API's isValidCelexToken (corrigenda `32013R0952R(04)` and
|
|
38
42
|
// consolidated `02016R0679-20180524` included), case-insensitive; an
|
|
@@ -41,6 +45,24 @@ const CELEX_RE = /^(?:CELEX:)?[0-9A-Za-z][0-9A-Za-z()._-]{4,}$/i;
|
|
|
41
45
|
const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
|
|
42
46
|
const celex = (what = 'CELEX number') => z.string().trim().regex(CELEX_RE, `${what} must look like 32016R0679, 62018CJ0311, 02016R0679-20180524 or 32013R0952R(04)`)
|
|
43
47
|
.describe(`${what}, e.g. 32016R0679.`);
|
|
48
|
+
// National-corpus ids (e.g. `AT-NOR-10001597`, `SI-JUD-UPRS-2025-I.U.727.2022.`):
|
|
49
|
+
// a two-letter jurisdiction prefix, same as middleware/jurisdiction.js's
|
|
50
|
+
// nationalIdParamGuard (`/^([A-Z]{2})-/`) uses to recognise them on the
|
|
51
|
+
// citation graph. `includeNational`-aware citation tools accept either
|
|
52
|
+
// shape; document reads stay celex()-only (lex_get_national_document /
|
|
53
|
+
// lex_list_national_documents cover national documents directly).
|
|
54
|
+
const NATIONAL_ID_RE = /^[A-Za-z]{2}-[0-9A-Za-z()./_-]+$/;
|
|
55
|
+
const celexOrNationalId = (what = 'identifier') => z.string().trim()
|
|
56
|
+
.refine((v) => CELEX_RE.test(v) || NATIONAL_ID_RE.test(v), `${what} must be a CELEX number (e.g. 32016R0679) or a national document id (e.g. AT-NOR-12345)`)
|
|
57
|
+
.describe(`${what}: a CELEX number, or (with includeNational) a national document id, e.g. "AT-NOR-12345".`);
|
|
58
|
+
// National law: jurisdiction codes
|
|
59
|
+
// are not enumerated here — the server is the single source of truth for
|
|
60
|
+
// which are registered and which are LIVE (lex_national_coverage), and the
|
|
61
|
+
// set grows over time. A two-letter code that isn't live 404s like any
|
|
62
|
+
// unmatched path, same as EU_LAW.
|
|
63
|
+
const jurisdiction = () => z.string().trim().regex(/^[A-Za-z]{2}$/, 'a two-letter country code, e.g. "at"')
|
|
64
|
+
.transform((v) => v.toLowerCase())
|
|
65
|
+
.describe('Two-letter country code, e.g. "at".');
|
|
44
66
|
// The 24-code enum used to be repeated in ~10 tools (~3k tokens of tools/list).
|
|
45
67
|
// A pattern + refine keeps the validation and lists the codes nowhere.
|
|
46
68
|
const LANG_SET = new Set(LANGUAGES);
|
|
@@ -84,6 +106,33 @@ const oneOrMany = (values, d) => {
|
|
|
84
106
|
.refine((v) => (Array.isArray(v) ? v : [v]).every((x) => set.has(x)), `allowed: ${values.join(', ')}`)
|
|
85
107
|
.describe(`${d} One or a list of: ${values.join(', ')}.`);
|
|
86
108
|
};
|
|
109
|
+
// A list filter sent comma-separated: an array, one value, or "a,b".
|
|
110
|
+
const splitList = (v) => (Array.isArray(v) ? v : v.split(',')).map((x) => x.trim()).filter(Boolean);
|
|
111
|
+
// The values are listed once, in the array's enum; a plain string ("a,b")
|
|
112
|
+
// is accepted too and checked against the same set.
|
|
113
|
+
const csvOf = (values, d) => {
|
|
114
|
+
const set = new Set(values);
|
|
115
|
+
return z.union([z.string(), z.array(z.enum(values)).min(1)])
|
|
116
|
+
.transform(splitList)
|
|
117
|
+
.refine((v) => v.length > 0 && v.every((x) => set.has(x)), `allowed: ${values.join(', ')}`)
|
|
118
|
+
.describe(d);
|
|
119
|
+
};
|
|
120
|
+
// Two-letter codes (lower-cased), e.g. ["eu","at"]. Which national codes
|
|
121
|
+
// are live is the server's call (lex_national_coverage), not listed here.
|
|
122
|
+
const codeList = (d) => z.union([z.string(), z.array(z.string()).min(1).max(30)])
|
|
123
|
+
.transform((v) => splitList(v).map((x) => x.toLowerCase()))
|
|
124
|
+
.refine((v) => v.length > 0 && v.length <= 30 && v.every((x) => /^[a-z]{2}$/.test(x)), 'two-letter codes, e.g. ["eu","at"]')
|
|
125
|
+
.describe(d);
|
|
126
|
+
/** The edge filters shared by the graph tools (API 2.11.0). */
|
|
127
|
+
const graphFilters = {
|
|
128
|
+
citationType: csvOf(CITATION_TYPES, 'Only these edge types.').optional(),
|
|
129
|
+
provenance: csvOf(CITATION_PROVENANCES, 'Edge origins (cellar-nim: a notified measure, not a finding of transposition). The last three: 400 while no country is live.').optional(),
|
|
130
|
+
jurisdictions: codeList('Neighbours in: "eu" and/or live national codes (national: BUSINESS+).').optional(),
|
|
131
|
+
resolution: csvOf(CITATION_RESOLUTIONS, 'National edges: match method.').optional(),
|
|
132
|
+
};
|
|
133
|
+
const titleLanguage = lang('Title language (default en).').optional();
|
|
134
|
+
const unresolved = z.boolean().optional()
|
|
135
|
+
.describe('National id: add references that got no edge (100 shown).');
|
|
87
136
|
const view = z.enum(['auto', 'outline', 'full']).default('auto').describe('auto: the body if it fits maxChars, else an outline. full: body up to maxChars, then offset to continue.');
|
|
88
137
|
const maxChars = (def) => z.number().int().min(2000).max(200_000).default(def)
|
|
89
138
|
.describe(`Text budget in characters (default ${def}).`);
|
|
@@ -99,6 +148,11 @@ function withNotice(res, shaped) {
|
|
|
99
148
|
const notice = creditNotice(res.body);
|
|
100
149
|
return notice ? { ...shaped, notice } : shaped;
|
|
101
150
|
}
|
|
151
|
+
/** Attach the national-law allowance (FREE/STARTER/PROFESSIONAL only), when the response carried it. */
|
|
152
|
+
function withAllowance(res, shaped) {
|
|
153
|
+
const allowance = nationalAllowanceOf(res.headers);
|
|
154
|
+
return allowance ? { ...shaped, allowance } : shaped;
|
|
155
|
+
}
|
|
102
156
|
/** API `include` for a document request — articleId alone means "metadata + that article". */
|
|
103
157
|
function apiInclude(a) {
|
|
104
158
|
if (a.include?.length)
|
|
@@ -206,7 +260,7 @@ export const tools = [
|
|
|
206
260
|
{
|
|
207
261
|
name: 'lex_resolve',
|
|
208
262
|
title: 'Resolve a legal identifier to CELEX',
|
|
209
|
-
description: 'Turn a pasted EUR-Lex URL, an ELI URI, an ECLI (e.g. ECLI:EU:C:2020:559) or a bare CELEX into the canonical CELEX number plus EUR-Lex links. Cost: 1 credit. ECLIs resolve only for case law already in the LexAPI corpus (404 otherwise).',
|
|
263
|
+
description: 'Turn a pasted EUR-Lex URL, an ELI URI, an ECLI (e.g. ECLI:EU:C:2020:559) or a bare CELEX into the canonical CELEX number plus EUR-Lex links. Cost: 1 credit. ECLIs resolve only for case law already in the LexAPI corpus (404 otherwise). resolvedVia says how: celex / url (read off the identifier), ecli-corpus / eli-corpus (corpus lookup), eli-cellar (Publications Office register), eli (derived from the ELI pattern only). verified: false is normal for CELEX and URL inputs (they are not looked up, so a mistyped CELEX also comes back); with resolvedVia "eli" the mapping itself is a guess — check it with lex_get_document before relying on it.',
|
|
210
264
|
inputSchema: {
|
|
211
265
|
identifier: z.string().trim().min(3).max(2000).describe('CELEX, EUR-Lex URL, ELI URI or ECLI.'),
|
|
212
266
|
},
|
|
@@ -462,16 +516,163 @@ export const tools = [
|
|
|
462
516
|
return withNotice(res, budgetHitTexts(shapeCaseLaw(res), a.maxChars ?? 40_000));
|
|
463
517
|
},
|
|
464
518
|
},
|
|
519
|
+
// ── National law ─────────────────────────────────────────────────
|
|
520
|
+
// Member-state legislation and case law, alongside the EU_LAW corpus
|
|
521
|
+
// above. A country can be registered on LexAPI before it is available to
|
|
522
|
+
// customers, so every tool below except lex_national_coverage says to
|
|
523
|
+
// call it first; an unavailable country answers like an unmatched path
|
|
524
|
+
// (404), never a silent empty result. Attribution (source, licence) is
|
|
525
|
+
// kept on every result — it is required, not optional, context.
|
|
526
|
+
{
|
|
527
|
+
name: 'lex_national_coverage',
|
|
528
|
+
title: 'National-law coverage',
|
|
529
|
+
description: "Countries with national-law coverage: live status, legislation/case-law coverage (counts, dates, courts), semantic-search availability, citation-graph measurements (citationGraph: methods, rates, floors; null = not measured), and sources with licence/attribution. Call this before any other national tool. Free.",
|
|
530
|
+
inputSchema: {},
|
|
531
|
+
annotations: READ,
|
|
532
|
+
handler: async (_a, client) => {
|
|
533
|
+
const res = await client.nationalCoverage();
|
|
534
|
+
return compact(res.body);
|
|
535
|
+
},
|
|
536
|
+
},
|
|
537
|
+
{
|
|
538
|
+
name: 'lex_list_national_documents',
|
|
539
|
+
title: 'Browse national documents',
|
|
540
|
+
description: 'Browse a country\'s national documents by title/type, newest-first by document date. documentKind ("act" | "decision") tells legislation from case law. Not yet live 404s — check lex_national_coverage first. Cost: 3 credits flat, not per page; counts against the national-law allowance on lower plans (see allowance). Paging: page reaches only the first 1,000 rows; beyond, pass the previous nextCursor as cursor (any depth), without page.',
|
|
541
|
+
inputSchema: {
|
|
542
|
+
jurisdiction: jurisdiction(),
|
|
543
|
+
q: z.string().trim().min(3).max(200).optional().describe('Title search, 3–200 characters.'),
|
|
544
|
+
documentType: z.string().trim().min(1).max(200).optional().describe('Document type as stored for this country.'),
|
|
545
|
+
page: z.number().int().min(1).optional().describe('1-based page, first 1,000 rows only. Omit when paging with cursor.'),
|
|
546
|
+
cursor: z.string().trim().min(1).optional().describe('Opaque cursor from a previous call\'s nextCursor — pages past the first 1,000 rows. Do not combine with page.'),
|
|
547
|
+
limit: z.number().int().min(1).max(100).default(20),
|
|
548
|
+
includeRepealed: z.boolean().optional().describe('Also list repealed/superseded acts.'),
|
|
549
|
+
},
|
|
550
|
+
annotations: { ...READ, idempotentHint: false },
|
|
551
|
+
handler: async (a, client) => {
|
|
552
|
+
const res = await client.listNationalDocuments(a.jurisdiction, compact({
|
|
553
|
+
q: a.q,
|
|
554
|
+
type: a.documentType,
|
|
555
|
+
page: a.cursor ? undefined : a.page,
|
|
556
|
+
cursor: a.cursor,
|
|
557
|
+
limit: a.limit,
|
|
558
|
+
includeRepealed: a.includeRepealed,
|
|
559
|
+
}));
|
|
560
|
+
const b = res.body;
|
|
561
|
+
const results = Array.isArray(b.results) ? b.results.map(shapeNationalSearchResult) : [];
|
|
562
|
+
// nextCursor is meaningfully `null` ("no more pages") — compact()
|
|
563
|
+
// would otherwise drop it indistinguishably from "absent", the same
|
|
564
|
+
// pitfall `content: null` has elsewhere.
|
|
565
|
+
const shaped = compact({
|
|
566
|
+
jurisdiction: b.jurisdiction,
|
|
567
|
+
total: b.total,
|
|
568
|
+
totalExact: b.totalExact,
|
|
569
|
+
page: b.page,
|
|
570
|
+
limit: b.limit,
|
|
571
|
+
includeRepealed: b.includeRepealed,
|
|
572
|
+
hasMore: b.hasMore,
|
|
573
|
+
results,
|
|
574
|
+
});
|
|
575
|
+
if (b.hasMore !== undefined)
|
|
576
|
+
shaped.nextCursor = b.nextCursor ?? null;
|
|
577
|
+
return withAllowance(res, withNotice(res, shaped));
|
|
578
|
+
},
|
|
579
|
+
},
|
|
580
|
+
{
|
|
581
|
+
name: 'lex_get_national_document',
|
|
582
|
+
title: 'Fetch a national document',
|
|
583
|
+
description: 'A national document by id, e.g. "AT-NOR-12345". Same fields in every country: documentKind ("act" | "decision"); decisions add court, chamber, caseNumbers, citedNorms; articles {number, title, section, text, inForceFrom, inForceTo} (text: null = no text for that unit). Large documents return an outline first; read on with view "full" and offset. content: null = the source publishes no machine-readable text (textAvailability says why). A document its source withdrew is a distinct error: nothing of it is served; do not retry, drop any copy held. Not yet live 404s — check lex_national_coverage first. Cost: 5 reserved, settles at 1 (an unknown id too), so a pool under 5 402s. Counts against the national-law allowance on lower plans (see allowance). Show attribution (source/licence) to the user.',
|
|
584
|
+
inputSchema: {
|
|
585
|
+
jurisdiction: jurisdiction(),
|
|
586
|
+
id: z.string().trim().min(1).max(200).describe('National document id, e.g. "AT-NOR-12345".'),
|
|
587
|
+
language: lang().optional(),
|
|
588
|
+
view,
|
|
589
|
+
maxChars: maxChars(40_000),
|
|
590
|
+
offset,
|
|
591
|
+
},
|
|
592
|
+
annotations: READ,
|
|
593
|
+
handler: async (a, client) => {
|
|
594
|
+
const res = await client.getNationalDocument(a.jurisdiction, a.id, compact({ language: a.language }));
|
|
595
|
+
const shaped = shapeNationalDocument(res.body.document, contentOpts(a));
|
|
596
|
+
return withAllowance(res, withNotice(res, shaped));
|
|
597
|
+
},
|
|
598
|
+
},
|
|
599
|
+
{
|
|
600
|
+
name: 'lex_national_semantic_case_law',
|
|
601
|
+
title: 'Semantic search over national case law',
|
|
602
|
+
description: 'Find one country\'s case law by meaning. Hits carry documentKind, ecli, dateOfDocument, and court/caseNumbers where indexed. hyde is a no-op here (no rewrite, no extra cost). Not yet live errors — check lex_national_coverage first. partial: true (partialReason SEARCH_INCOMPLETE) means the index could not complete the search: results may be incomplete — say so, and follow the hint. Cost: flat 5 credits, never 15; counts against the national-law allowance on lower plans (see allowance). Each hit\'s attribution names the source/licence — show it to the user.',
|
|
603
|
+
inputSchema: {
|
|
604
|
+
jurisdiction: jurisdiction(),
|
|
605
|
+
query: z.string().trim().min(3).max(1000).describe('Natural-language question or description of the legal issue.'),
|
|
606
|
+
limit: z.number().int().min(1).max(100).default(10).describe('Max cases (plan cap, same as lex_semantic_case_law).'),
|
|
607
|
+
min_score: z.number().min(0).max(1).optional().describe('Similarity floor (default ≈0.7).'),
|
|
608
|
+
language: lang('Optional — omit, or the country\'s own language (e.g. "de" for AT, from lex_national_coverage); any other value is a 400.').optional(),
|
|
609
|
+
hyde: z.boolean().optional().describe('No-op here; never adds cost or latency.'),
|
|
610
|
+
include: z.array(z.literal('text')).optional().describe('["text"] returns full judgment text, bounded by maxChars.'),
|
|
611
|
+
filters: z.object({
|
|
612
|
+
court: z.string().optional(),
|
|
613
|
+
date_from: isoDate('From.').optional(),
|
|
614
|
+
date_to: isoDate('To.').optional(),
|
|
615
|
+
ecli: z.string().optional(),
|
|
616
|
+
}).strict().optional().describe('No case_number nationally.'),
|
|
617
|
+
maxChars: maxChars(40_000),
|
|
618
|
+
},
|
|
619
|
+
annotations: { ...READ, idempotentHint: false },
|
|
620
|
+
handler: async (a, client) => {
|
|
621
|
+
const res = await client.nationalSemanticCaseLaw(a.jurisdiction, compact({
|
|
622
|
+
query: a.query,
|
|
623
|
+
limit: a.limit,
|
|
624
|
+
min_score: a.min_score,
|
|
625
|
+
language: a.language,
|
|
626
|
+
hyde: a.hyde,
|
|
627
|
+
include: a.include,
|
|
628
|
+
filters: a.filters,
|
|
629
|
+
}));
|
|
630
|
+
return withAllowance(res, withNotice(res, budgetHitTexts(shapeNationalCaseLaw(res), a.maxChars ?? 40_000)));
|
|
631
|
+
},
|
|
632
|
+
},
|
|
633
|
+
{
|
|
634
|
+
name: 'lex_national_semantic_legislation',
|
|
635
|
+
title: 'Semantic search over national legislation',
|
|
636
|
+
description: 'Find one country\'s legislation articles by meaning. No asOf — current text only. Not yet live errors — check lex_national_coverage first. partial: true (partialReason SEARCH_INCOMPLETE) means the index could not complete the search: results may be incomplete — say so, and follow the hint. Cost: flat 5 credits; counts against the national-law allowance on lower plans (see allowance). Each hit\'s attribution names the source/licence — show it to the user.',
|
|
637
|
+
inputSchema: {
|
|
638
|
+
jurisdiction: jurisdiction(),
|
|
639
|
+
query: z.string().trim().min(3).max(1000).describe('Natural-language description of the provision you are looking for.'),
|
|
640
|
+
limit: z.number().int().min(1).max(50).default(10).describe('Max hits (plan cap, same as lex_semantic_legislation).'),
|
|
641
|
+
min_score: z.number().min(0).max(1).optional().describe('Similarity floor (default ≈0.7).'),
|
|
642
|
+
language: lang('Optional — omit, or the country\'s own language (e.g. "de" for AT, from lex_national_coverage); any other value is a 400.').optional(),
|
|
643
|
+
include: z.array(z.literal('text')).optional().describe('["text"] returns full article text instead of a snippet.'),
|
|
644
|
+
filters: z.object({
|
|
645
|
+
id: z.string().trim().min(1).optional().describe('A specific national document id.'),
|
|
646
|
+
inForce: z.boolean().optional().describe('As of today.'),
|
|
647
|
+
documentType: z.string().trim().min(1).optional(),
|
|
648
|
+
}).strict().optional(),
|
|
649
|
+
maxChars: maxChars(40_000),
|
|
650
|
+
},
|
|
651
|
+
annotations: { ...READ, idempotentHint: false },
|
|
652
|
+
handler: async (a, client) => {
|
|
653
|
+
const res = await client.nationalSemanticLegislation(a.jurisdiction, compact({
|
|
654
|
+
query: a.query,
|
|
655
|
+
limit: a.limit,
|
|
656
|
+
min_score: a.min_score,
|
|
657
|
+
language: a.language,
|
|
658
|
+
include: a.include,
|
|
659
|
+
filters: a.filters,
|
|
660
|
+
}));
|
|
661
|
+
return withAllowance(res, withNotice(res, budgetHitTexts(shapeNationalLegislation(res), a.maxChars ?? 40_000)));
|
|
662
|
+
},
|
|
663
|
+
},
|
|
465
664
|
// ── Citation graph ──────────────────────────────────────────────────
|
|
466
665
|
{
|
|
467
666
|
name: 'lex_cited_by',
|
|
468
667
|
title: 'Documents citing a CELEX',
|
|
469
|
-
description: 'Inbound citations: documents that cite, amend, correct, repeal, implement or are based on this act, with the edge type. For legislation, amendment / corrigendum / repeal edges are read from the Publications Office (Cellar) and refreshed on read when older than 7 days; if that refresh does not finish in ~2.5 s, relationSync.status is "pending" (or "skipped") and the stored edges are served — check relationSync before calling the list complete. Other edge types cover only documents LexAPI has extracted. Cost: 1 credit.',
|
|
668
|
+
description: 'Inbound citations: documents that cite, amend, correct, repeal, implement, transpose or are based on this act, with the edge type and its provenance. For legislation, amendment / corrigendum / repeal edges are read from the Publications Office (Cellar) and refreshed on read when older than 7 days; if that refresh does not finish in ~2.5 s, relationSync.status is "pending" (or "skipped") and the stored edges are served — check relationSync before calling the list complete. Other edge types cover only documents LexAPI has extracted. Page until offset + limit >= totalEdges. includeNational adds national neighbours of live countries (BUSINESS+ only; also accepts a national id, e.g. "AT-NOR-12345"). Cost: 1 credit.',
|
|
470
669
|
inputSchema: {
|
|
471
|
-
celexNumber:
|
|
472
|
-
|
|
670
|
+
celexNumber: celexOrNationalId(),
|
|
671
|
+
...graphFilters,
|
|
473
672
|
limit: z.number().int().min(1).max(500).default(50).describe('Edges per page.'),
|
|
474
673
|
offset: z.number().int().min(0).default(0).describe('Paging offset, in edges.'),
|
|
674
|
+
includeNational: z.boolean().optional().describe('Add national documents (BUSINESS+ only).'),
|
|
675
|
+
language: titleLanguage,
|
|
475
676
|
},
|
|
476
677
|
annotations: READ,
|
|
477
678
|
handler: async (a, client) => {
|
|
@@ -483,12 +684,15 @@ export const tools = [
|
|
|
483
684
|
{
|
|
484
685
|
name: 'lex_cites',
|
|
485
686
|
title: 'Documents a CELEX cites',
|
|
486
|
-
description: 'Outbound citations: what this document references, amends, repeals, implements or is based on, with the edge type. Only populated for documents whose citations were extracted (lex_extract_citations). Cost: 1 credit.',
|
|
687
|
+
description: 'Outbound citations: what this document references, amends, repeals, implements, transposes or is based on, with the edge type and its provenance. Only populated for documents whose citations were extracted (lex_extract_citations). includeNational adds national neighbours of live countries (BUSINESS+ only; also accepts a national id, e.g. "AT-NOR-12345"). Cost: 1 credit.',
|
|
487
688
|
inputSchema: {
|
|
488
|
-
celexNumber:
|
|
489
|
-
|
|
689
|
+
celexNumber: celexOrNationalId(),
|
|
690
|
+
...graphFilters,
|
|
691
|
+
unresolved,
|
|
490
692
|
limit: z.number().int().min(1).max(500).default(50),
|
|
491
693
|
offset: z.number().int().min(0).default(0),
|
|
694
|
+
includeNational: z.boolean().optional().describe('Add national documents (BUSINESS+ only).'),
|
|
695
|
+
language: titleLanguage,
|
|
492
696
|
},
|
|
493
697
|
annotations: READ,
|
|
494
698
|
handler: async (a, client) => {
|
|
@@ -500,12 +704,15 @@ export const tools = [
|
|
|
500
704
|
{
|
|
501
705
|
name: 'lex_citation_network',
|
|
502
706
|
title: 'Citation neighbourhood of a CELEX',
|
|
503
|
-
description: 'Both directions at once — documents this one cites and documents citing it — deduplicated, with edge types per neighbour; paging.citesTotal / citedByTotal give the full counts. Cost: 20 credits (prefer lex_cited_by / lex_cites at 1 credit when one direction is enough).',
|
|
707
|
+
description: 'Both directions at once — documents this one cites and documents citing it — deduplicated, with edge types and provenance per neighbour; paging.citesTotal / citedByTotal give the full counts. includeNational adds national neighbours of live countries (BUSINESS+ only; also accepts a national id). Cost: 20 credits, refunded on a partial (timeout) answer (prefer lex_cited_by / lex_cites at 1 credit when one direction is enough).',
|
|
504
708
|
inputSchema: {
|
|
505
|
-
celexNumber:
|
|
506
|
-
|
|
709
|
+
celexNumber: celexOrNationalId(),
|
|
710
|
+
...graphFilters,
|
|
711
|
+
unresolved,
|
|
507
712
|
limit: z.number().int().min(1).max(500).default(50).describe('Edges per direction.'),
|
|
508
713
|
offset: z.number().int().min(0).default(0),
|
|
714
|
+
includeNational: z.boolean().optional().describe('Add national documents (BUSINESS+ only).'),
|
|
715
|
+
language: titleLanguage,
|
|
509
716
|
},
|
|
510
717
|
annotations: READ,
|
|
511
718
|
handler: async (a, client) => {
|
|
@@ -517,18 +724,29 @@ export const tools = [
|
|
|
517
724
|
{
|
|
518
725
|
name: 'lex_citation_path',
|
|
519
726
|
title: 'Citation path between two documents',
|
|
520
|
-
description: 'Shortest chain of outbound citations from one document to another (e.g. how a judgment reaches a directive). found: false is a normal answer, not an error. Cost: 20 credits.',
|
|
727
|
+
description: 'Shortest chain of outbound citations from one document to another (e.g. how a judgment reaches a directive), optionally over filtered edges only. found: false is a normal answer, not an error. includeNational follows national documents of live countries too (BUSINESS+ only; from/to also accept a national id). Cost: 20 credits.',
|
|
521
728
|
inputSchema: {
|
|
522
|
-
from:
|
|
523
|
-
to:
|
|
729
|
+
from: celexOrNationalId('Start identifier'),
|
|
730
|
+
to: celexOrNationalId('Target identifier'),
|
|
524
731
|
maxDepth: z.number().int().min(1).max(8).default(3).describe('Max hops.'),
|
|
732
|
+
...graphFilters,
|
|
733
|
+
includeNational: z.boolean().optional().describe('Add national documents (BUSINESS+ only).'),
|
|
734
|
+
language: titleLanguage,
|
|
525
735
|
},
|
|
526
736
|
annotations: READ,
|
|
527
737
|
handler: async (a, client) => {
|
|
528
|
-
const res = await client.citationPath(normCelex(a.from), normCelex(a.to), {
|
|
738
|
+
const res = await client.citationPath(normCelex(a.from), normCelex(a.to), {
|
|
739
|
+
maxDepth: a.maxDepth,
|
|
740
|
+
includeNational: a.includeNational,
|
|
741
|
+
citationType: a.citationType,
|
|
742
|
+
provenance: a.provenance,
|
|
743
|
+
jurisdictions: a.jurisdictions,
|
|
744
|
+
resolution: a.resolution,
|
|
745
|
+
language: a.language,
|
|
746
|
+
});
|
|
529
747
|
const b = stripEnvelope(res.body);
|
|
530
748
|
if (Array.isArray(b.path)) {
|
|
531
|
-
b.path = b.path.map((n) => (isObj(n) ? compact({
|
|
749
|
+
b.path = b.path.map((n) => (isObj(n) ? compact({ ...nodeFields(n), title: n.title }) : n));
|
|
532
750
|
}
|
|
533
751
|
return withNotice(res, compact(b));
|
|
534
752
|
},
|
|
@@ -536,18 +754,29 @@ export const tools = [
|
|
|
536
754
|
{
|
|
537
755
|
name: 'lex_related',
|
|
538
756
|
title: 'Documents related by shared citations',
|
|
539
|
-
description: 'Documents that cite the most of the same acts as this one (bibliographic coupling) — "what else deals with this". Needs the seed\'s outbound citations (lex_extract_citations). Cost: 20 credits.',
|
|
757
|
+
description: 'Documents that cite the most of the same acts as this one (bibliographic coupling) — "what else deals with this"; the edge filters narrow which shared citations count. Needs the seed\'s outbound citations (lex_extract_citations). includeNational considers national documents of live countries too (BUSINESS+ only; also accepts a national id). Cost: 20 credits.',
|
|
540
758
|
inputSchema: {
|
|
541
|
-
celexNumber:
|
|
759
|
+
celexNumber: celexOrNationalId(),
|
|
542
760
|
limit: z.number().int().min(1).max(50).default(10),
|
|
761
|
+
...graphFilters,
|
|
762
|
+
includeNational: z.boolean().optional().describe('Add national documents (BUSINESS+ only).'),
|
|
763
|
+
language: titleLanguage,
|
|
543
764
|
},
|
|
544
765
|
annotations: READ,
|
|
545
766
|
handler: async (a, client) => {
|
|
546
|
-
const res = await client.related(normCelex(a.celexNumber), {
|
|
767
|
+
const res = await client.related(normCelex(a.celexNumber), {
|
|
768
|
+
limit: a.limit,
|
|
769
|
+
includeNational: a.includeNational,
|
|
770
|
+
citationType: a.citationType,
|
|
771
|
+
provenance: a.provenance,
|
|
772
|
+
jurisdictions: a.jurisdictions,
|
|
773
|
+
resolution: a.resolution,
|
|
774
|
+
language: a.language,
|
|
775
|
+
});
|
|
547
776
|
const b = stripEnvelope(res.body, ['method']);
|
|
548
777
|
if (Array.isArray(b.related)) {
|
|
549
778
|
b.related = b.related.map((r) => (isObj(r) ? compact({
|
|
550
|
-
|
|
779
|
+
...nodeFields(r),
|
|
551
780
|
title: r.title,
|
|
552
781
|
sharedCount: r.sharedCount,
|
|
553
782
|
sharedTargets: Array.isArray(r.sharedTargets) ? r.sharedTargets.slice(0, 10) : undefined,
|
|
@@ -559,14 +788,55 @@ export const tools = [
|
|
|
559
788
|
{
|
|
560
789
|
name: 'lex_citation_stats',
|
|
561
790
|
title: 'Citation graph statistics',
|
|
562
|
-
description: 'Totals for the whole LexAPI citation graph plus the 10 most-cited and 10 most-citing documents. Cost: 20 credits.',
|
|
563
|
-
inputSchema: {
|
|
791
|
+
description: 'Totals for the whole LexAPI citation graph plus the 10 most-cited and 10 most-citing documents. includeNational counts national documents of live countries too and adds byJurisdiction, byProvenance and transposition (notified measures, and how many LexAPI holds) — BUSINESS+ only. Cost: 20 credits.',
|
|
792
|
+
inputSchema: {
|
|
793
|
+
includeNational: z.boolean().optional().describe('Add national documents (BUSINESS+ only).'),
|
|
794
|
+
},
|
|
564
795
|
annotations: READ,
|
|
565
|
-
handler: async (
|
|
566
|
-
const res = await client.citationStats();
|
|
796
|
+
handler: async (a, client) => {
|
|
797
|
+
const res = await client.citationStats({ includeNational: a.includeNational });
|
|
567
798
|
return withNotice(res, stripEnvelope(res.body));
|
|
568
799
|
},
|
|
569
800
|
},
|
|
801
|
+
{
|
|
802
|
+
name: 'lex_transposition',
|
|
803
|
+
title: 'Notified national measures for an EU act',
|
|
804
|
+
description: 'The measures member states (and the UK) notified to the Commission for an EU act (CELEX sector 3, e.g. a directive), by country, from the Publications Office\'s Cellar records. A notification is not a finding that the measure transposes the act, or transposes it completely — say so when presenting it (the result\'s note). Every plan. On BUSINESS+ it also says, for live countries only, which measures LexAPI holds (id, resolved) and adds documents whose national source records the relation (provenance "source"); below that those fields are absent. termsRequired: true = the account must accept the national-source terms in the dashboard first. Keep source.cellar.attribution with anything republished. Output is bounded (limit, ~40,000 characters): page with the offset given in more. Cost: 5 credits per call (each offset page too); not an EU act = 404, settles at 1.',
|
|
805
|
+
inputSchema: {
|
|
806
|
+
celexNumber: celex('CELEX number of the EU act'),
|
|
807
|
+
jurisdictions: codeList('Only these countries, e.g. ["es","cz"] (EL = Greece, UK = United Kingdom); default all 28.').optional(),
|
|
808
|
+
resolvedOnly: z.boolean().optional().describe('Only measures resolved to a document LexAPI holds (BUSINESS+, live countries).'),
|
|
809
|
+
limit: z.number().int().min(1).max(200).default(50).describe('Measures shown, across countries.'),
|
|
810
|
+
offset: z.number().int().min(0).default(0).describe('Skip this many measures (value given in the previous result\'s more).'),
|
|
811
|
+
language: titleLanguage,
|
|
812
|
+
},
|
|
813
|
+
annotations: READ,
|
|
814
|
+
handler: async (a, client) => {
|
|
815
|
+
const res = await client.transposition(normCelex(a.celexNumber), {
|
|
816
|
+
jurisdictions: a.jurisdictions,
|
|
817
|
+
resolvedOnly: a.resolvedOnly,
|
|
818
|
+
language: a.language,
|
|
819
|
+
});
|
|
820
|
+
return withNotice(res, shapeTransposition(res, a.limit ?? 50, a.offset ?? 0));
|
|
821
|
+
},
|
|
822
|
+
},
|
|
823
|
+
{
|
|
824
|
+
name: 'lex_counterparts',
|
|
825
|
+
title: 'Counterparts of a national act in other countries',
|
|
826
|
+
description: 'A national document\'s counterparts in the other live countries, through the EU acts it transposes or implements (via), ranked: 1 = the national source records the relation; 2 = a notified measure LexAPI holds; 3 = a notified Cellar record LexAPI does not hold (no id). An EU act (CELEX sector 3) as id groups its measures the same way. Only live countries are returned — check lex_national_coverage; a national id of a country not live 404s (nothing charged); any other 404 settles at 1 credit. A notification is not a finding that the measure transposes the act. BUSINESS, SCALE and ENTERPRISE only (403 below, refunded); the national-law allowance does not apply. Output is bounded (limit per act, up to 25 acts and ~40,000 characters): page with the offset given in more. Cost: 20 credits (each offset page too); a server timeout is refunded — narrow with jurisdictions.',
|
|
827
|
+
inputSchema: {
|
|
828
|
+
id: celexOrNationalId('National document id or EU act CELEX'),
|
|
829
|
+
jurisdictions: codeList('Only these live countries, e.g. ["si","es"]; default every live one.').optional(),
|
|
830
|
+
limit: z.number().int().min(1).max(50).default(10).describe('Counterparts shown per EU act.'),
|
|
831
|
+
offset: z.number().int().min(0).default(0).describe('Skip this many EU acts (value given in more).'),
|
|
832
|
+
language: titleLanguage,
|
|
833
|
+
},
|
|
834
|
+
annotations: READ,
|
|
835
|
+
handler: async (a, client) => {
|
|
836
|
+
const res = await client.counterparts(normCelex(a.id), { jurisdictions: a.jurisdictions, language: a.language });
|
|
837
|
+
return withNotice(res, shapeCounterparts(res, a.limit ?? 10, a.offset ?? 0, 25));
|
|
838
|
+
},
|
|
839
|
+
},
|
|
570
840
|
{
|
|
571
841
|
name: 'lex_extract_citations',
|
|
572
842
|
title: 'Extract a document\'s citations',
|
package/package.json
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@lexapi/mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"mcpName": "io.github.Lex-API/lexapi-mcp",
|
|
5
|
-
"description": "Model Context Protocol server for LexAPI — EUR-Lex legislation, CJEU case law, the citation graph and semantic search (with point-in-time asOf) from Claude, Cursor and other MCP clients.",
|
|
5
|
+
"description": "Model Context Protocol server for LexAPI — EUR-Lex legislation, CJEU case law, national law (as jurisdictions launch), the citation graph and semantic search (with point-in-time asOf) from Claude, Cursor and other MCP clients.",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"main": "dist/index.js",
|
|
8
8
|
"bin": {
|