@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/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: celex(),
472
- citationType: z.enum(CITATION_TYPES).optional().describe('Only this edge type (e.g. "amendment" for the amending acts).'),
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: celex(),
489
- citationType: z.enum(CITATION_TYPES).optional(),
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: celex(),
506
- citationType: z.enum(CITATION_TYPES).optional(),
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: celex('Start CELEX'),
523
- to: celex('Target CELEX'),
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), { maxDepth: a.maxDepth });
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({ celex: n.celexNumber, title: n.title }) : n));
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: celex(),
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), { limit: a.limit });
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
- celex: r.celexNumber,
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 (_a, client) => {
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.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": {