Skip to content
Back to search

boe-insights-mcp

MCP server with analytical tools over Spain's BOE (Boletín Oficial del Estado) open data: law status, amendment analysis and legislative trends.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/davidbejar--boe-insights-mcp/badge.svg)](/listings/davidbejar--boe-insights-mcp)

HTML

<a href="/listings/davidbejar--boe-insights-mcp"><img src="/api/listings/davidbejar--boe-insights-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites: Python 3.11+ and [uv](https://docs.astral.sh/uv/). No API key is needed: the BOE open data API is public.

Run from source:

git clone https://github.com/davidbejar/boe-insights-mcp.git
cd boe-insights-mcp
uv sync

The server speaks MCP over stdio, so you normally do not start it by hand: your MCP client does.

**Claude Desktop.** Add this to `claude_desktop_config.json` and restart the app (use the absolute path of your clone):

{
  "mcpServers": {
    "boe-insights": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/boe-insights-mcp", "run", "boe-insights-mcp"]
    }
  }
}

**Claude Code:**

claude mcp add boe-insights -- uv --directory /absolute/path/to/boe-insights-mcp run boe-insights-mcp

Or commit the same server definition in a project-level `.mcp.json`:

{
  "mcpServers": {
    "boe-insights": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/boe-insights-mcp", "run", "boe-insights-mcp"]
    }
  }
}

**Without cloning**, uv can fetch and run it straight from GitHub:

uvx --from git+https://github.com/davidbejar/boe-insights-mcp boe-insights-mcp

In a client configuration, use `"command": "uvx"` with `"args": ["--from", "git+https://github.com/davidbejar/boe-insights-mcp", "boe-insights-mcp"]`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 427 lines
  1. # boe-insights-mcp
  2. **English** | [Español](README.es.md)
  3. [![CI](https://github.com/davidbejar/boe-insights-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/davidbejar/boe-insights-mcp/actions/workflows/ci.yml)
  4. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  5. An [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server that gives AI assistants such as Claude analytical tools over the open data of Spain's BOE (Boletín Oficial del Estado). Instead of one tool per API endpoint, the tools are shaped around the questions people actually ask: "is this law still in force?", "what changed in this article?", "how has legislation on X evolved?".
  6. **Status:** early development. Eighteen tools are available today (law lookup, search, status overview and code lookup; amendment history and amendment chains; reading, comparing and tracing the history of single articles; checking citations against the text; a law's table of contents; trend analytics over the whole consolidated collection; and the BOE's daily gazette); everything else is on the [roadmap](#roadmap). Not yet published on PyPI: run it from source.
  7. ## What you can ask
  8. Eight worked examples, each from a real run of the server (examples 1 to 4 on 2026-11-21, examples 5 to 8 on 2026-11-22). The question comes first, then the tool calls in order and an extract of the result (long titles shortened with "…").
  9. ### 1. Read a well-known law
  10. *"Show me the structure of the data protection law (Ley Orgánica 3/2018) and read the article on the right to erasure."*
  11. ```text
  12. resolve_reference(reference="Ley Orgánica 3/2018") -> BOE-A-2018-16673
  13. get_law_structure(law_id, detail="headings", limit=12) -> chapters and titles only
  14. get_law_structure(law_id, limit=200) -> adds the article headings
  15. read_article(law_id, article="artículo 15")
  16. ```
  17. - The headings view lists 24 entries (preamble, 10 titles, 8 chapters, 5 sections), for example "TÍTULO III. Derechos de las personas". The full table of contents has 168 entries, among them 98 articles and 46 provisions.
  18. - Article headings include "Artículo 15. Derecho de supresión" and "Artículo 93. Derecho al olvido en búsquedas de Internet".
  19. - `read_article` returns article 15 (state `in_force`, in force since 2018-12-07): "1. El derecho de supresión se ejercerá de acuerdo con lo establecido en el artículo 17 del Reglamento (UE) 2016/679. …"
  20. - Article 93 (`read_article` with `article="artículo 93"`) begins: "Toda persona tiene derecho a que los motores de búsqueda en Internet eliminen de las listas de resultados …"
  21. ### 2. What changed in an article
  22. *"What changed in article 48 of Ley 40/2015 since 2017?"*
  23. ```text
  24. resolve_reference(reference="Ley 40/2015") -> BOE-A-2015-10566
  25. compare_article_versions(law_id, article="artículo 48", from_date="2017-01-01")
  26. ```
  27. - The text in force on 2017-01-01 is the version that started on 2016-10-02; the latest one started on 2021-01-01, introduced by `BOE-A-2020-17340`. There is nothing in between (`intermediate_versions` 0).
  28. - One paragraph changed (`changed` 1, `unchanged` 11, `added` 0, `removed` 0).
  29. - Inline diff of the paragraph on convenios: "resultarán eficaces una vez [-inscritos-] {+inscritos, en el plazo de 5 días hábiles desde su formalización,+} en el Registro Electrónico estatal …" and, further on, "{+en el plazo de 10 días hábiles desde su formalización+} en el «Boletín Oficial del Estado»".
  30. ### 3. A trend and its explanation
  31. *"Why were there so many decree-laws in 2020?"*
  32. ```text
  33. legislation_over_time(rank="real_decreto_ley", period="year", from_date="2010-01-01", to_date="2025-12-31")
  34. explain_spike(rank="real_decreto_ley", period_key="2020", from_date="2010-01-01", to_date="2025-12-31", max_laws=8)
  35. ```
  36. | Year | 2018 | 2019 | 2020 | 2021 | 2022 | 2023 |
  37. |---|---|---|---|---|---|---|
  38. | Real decretos-leyes in the collection (`count`) | 19 | 12 | **38** | 28 | 20 | 8 |
  39. | Highest official number seen (`highest_number`) | 28 | 18 | **39** | 32 | 20 | 8 |
  40. - 2010-2025 has 230 of them; 2020 is the strongest spike, 38 against a baseline of 11.0 (ratio 3.45).
  41. - The collection does not hold every law of a year, which is why this result also carries `highest_number`: the highest official number seen that year, a lower bound of how many were enacted. 2020 holds 38 of at least 39. The neighbouring years are thinner (2019: 12 of at least 18; 2018: 19 of 28; 2021: 28 of 32), while 2022 and 2023 look complete (20 of 20, 8 of 8).
  42. - The conclusion holds given that coverage: 2020 has the most decree-laws of any year in 2010-2025, both by the laws held (38) and by the highest number seen (39; the next is 32, in 2021). Recent years are thin (2025 holds 4 of at least 16), so do not read the fall since 2023 as a trend.
  43. - `explain_spike` for 2020 puts the baseline at 10.2 (the 5 preceding years). Its breakdown (`contributions`) is empty here: all 38 laws are state laws of Jefatura del Estado, and a dimension with a single value is not reported.
  44. - `laws` is an evenly spaced sample of the 38 in date order (`max_laws=8`, first and last included): Real Decreto-ley 1/2020 (pensions), 7/2020 (impact of COVID-19 on the economy), 13/2020 (agrarian employment), 18/2020 (social measures in defence of employment), 23/2020 (energy and economic reactivation), 28/2020 (remote work), 34/2020 (business solvency, energy and taxation) and 36/2020 (modernisation of the public administration and the Recovery Plan).
  45. - The tool lists laws and counts; the link between the spike and the pandemic is something you read from the titles.
  46. ### 4. Most-amended laws
  47. *"Which data protection laws have been amended most?"*
  48. ```text
  49. most_amended_laws(title="protección de datos", from_date="2007-01-01", limit=5, max_laws=10) -> complete false
  50. most_amended_laws(title="protección de datos", from_date="2007-01-01", limit=5, max_laws=10) -> complete true
  51. ```
  52. Each call has a 40-second budget (counted from the start of the call, so the first one includes downloading the catalogue) and reads the amendment data of at most `max_laws` laws, one request each. This tool has no default lower bound on dates: here `from_date="2007-01-01"` was added to the calls above, which leaves 14 matching laws (without it, 28 match). Run on an empty cache, the first call examined 9 (`complete` false, with a note to call again) and the second continued from the cache and examined all 14 (`complete` true). Result of the second call, laws published since 2007:
  53. | Amendments | Law |
  54. |---|---|
  55. | 5 | Ley Orgánica 3/2018, de Protección de Datos Personales y garantía de los derechos digitales |
  56. | 3 | Ley 32/2010, de la Autoridad Catalana de Protección de Datos |
  57. | 1 | Real Decreto 1720/2007, … Reglamento de desarrollo de la Ley Orgánica 15/1999 … |
  58. | 1 | Ley 2/2004, de Ficheros de Datos de Carácter Personal de Titularidad Pública y de Creación de la Agencia Vasca de Protección de Datos |
  59. | 1 | Real Decreto-ley 5/2018, … adaptación del Derecho español a la normativa de la Unión Europea en materia de protección de datos |
  60. Repeals count as amendments: Ley 32/2010 has 2 modifications and 1 repeal.
  61. ### 5. Comparing the autonomous communities
  62. *"Which autonomous communities have legislated most on housing since 2015?"*
  63. ```text
  64. top_departments(scope="regional", title="vivienda", from_date="2015-01-01")
  65. search_legislation(scope="regional", title="vivienda", department_code="8121", published_from="2015-01-01")
  66. get_law_overview(law_id="BOE-A-2018-9774")
  67. ```
  68. About 29% of the collection (3,623 of 12,477 laws when this was run) is regional. For "vivienda", 48 laws since 2015 across 12 communities (the title filter also matches the plural "viviendas"):
  69. | Community | Laws |
  70. |---|---|
  71. | Illes Balears | 8 |
  72. | Canarias, Cataluña | 7 each |
  73. | Región de Murcia | 6 |
  74. | Andalucía, Extremadura, Navarra, Madrid, Comunitat Valenciana | 3 each |
  75. | Aragón | 2 |
  76. The 2 remaining communities (3 laws) are grouped as "other". (The `search_legislation` step is only there to find an identifier among the Balearic results; it returns 7 laws, including Ley 5/2018, "de la vivienda de las Illes Balears". Its `title` filter is matched by the BOE itself on exact words, so it misses the eighth Balearic law, whose title says "viviendas".) `get_law_overview` for Ley 5/2018 shows two dates:
  77. - `first_published`: gazette BOIB, issue 78, 2018-06-26. This is where the law was first published, and it governs entry into force (`effective_from` 2018-06-27).
  78. - `published_on`: 2018-07-13, the date of its reprint in the BOE. `enacted_on` is 2018-06-19.
  79. - `status` `partially_repealed`; 20 later norms affect it (10 modifications, 3 repeals, among others).
  80. ### 6. Checking citations
  81. *"Check these citations from a memo."*
  82. ```text
  83. read_article(law_id="BOE-A-2015-10566", article="artículo 48") -> text in force
  84. read_article(law_id="BOE-A-2015-10566", article="artículo 48", as_of="2017-01-01") -> the 2016 wording
  85. verify_citation(citations=[five items: law, article, and a quote for four of them])
  86. ```
  87. All five citations were checked in one call (`checked` 5, `not_checked` 0, run on 2026-11-22):
  88. | Citation | `status` | What the result says |
  89. |---|---|---|
  90. | Ley 40/2015, art. 48, the current wording of the term for registration ("resultarán eficaces una vez inscritos, en el plazo de 5 días hábiles desde su formalización, en el Registro Electrónico …") | `matches` | `quote_match.level` `exact`. |
  91. | The same sentence as worded from 2016 ("… una vez inscritos en el Registro Electrónico …", without the 5 days) | `matches_older_version` | `other_version`: an `exact` match with a version in force from 2016-10-02 to 2020-12-31. |
  92. | The current wording with "5 días" changed to "15 días" | `text_differs` | `level` `close`, `similarity` 0.97, `flags` `["number"]`, `differences`: "… en el plazo de [-15-] {+5+} días hábiles …". |
  93. | "Las aportaciones financieras que se comprometan a realizar los firmantes (...) podrán ser superiores a los gastos derivados de la ejecución del convenio." | `matches` | `level` `exact`, but `omitted` is `["no"]` and `flags` is `["omitted_negation"]`. |
  94. | Ley 30/1992, art. 1, no quote | `not_in_force` | `state` `repealed`; note: "The whole law was repealed on 2016-10-02, so this article is no longer in force; the text shown is its last consolidated version." |
  95. The fourth row is why `omitted` exists. Every word of the quote is in the article, so it matches, but the quote skips a "no": article 48.6 says the financial contributions "no podrán ser superiores a los gastos", and the quote reads as if they may be. The tool compares words, not meaning, and reports facts, not legal correctness.
  96. ### 7. Following amendments
  97. *"What did Real Decreto-ley 8/2020 change, and has it been changed since?"*
  98. ```text
  99. explore_amendment_chain(law_id="BOE-A-2020-3824", direction="amends", depth=1)
  100. explore_amendment_chain(law_id="BOE-A-2020-3824", direction="amended_by", depth=2)
  101. ```
  102. - `amends`: the decree-law acts on 9 norms (`levels` [1, 9]): 6 modifications, 2 suspensions and 1 repeal. Edges, with the BOE's own wording in `detail`: `modifies` Real Decreto-ley 7/2020, "el art. 16 del Real Decreto-ley 7/2020, de 12 de marzo"; `suspends` `BOE-A-2015-2495`, "en la forma y con los efectos indicados la vigencia de los arts. 3.5 y 6 de la Orden IET/389/2015, de 5 de marzo".
  103. - `amended_by`, depth 2: 72 laws (`levels` [1, 23, 48]) and 142 edges, 117 `modifies` and 25 `repeals` (repeals include partial ones), all 24 laws examined (`complete` true). Two edges that touch the starting law: `repeals`, Ley 2/2021, "el art. 42, SE MODIFICA el art. 40.1 y 2, Ley 2/2021, de 29 de marzo"; `modifies`, `BOE-A-2023-6967`, "el art. 17.9, por Real Decreto-ley 2/2023, de 16 de marzo".
  104. - `court_rulings_excluded` is 3: three court rulings concerning this decree-law are left out by default because only amendments are followed; `include="all"` lists them.
  105. - Caution: the 48 laws at level 2 amended one of the 23 laws at level 1, not necessarily the parts that touch Real Decreto-ley 8/2020. Their `detail` is not shown by default.
  106. ### 8. The daily gazette
  107. *"What did the BOE publish on 14 March 2020?"*
  108. ```text
  109. get_daily_summary(date="2020-03-14", limit=5)
  110. ```
  111. - Two issues that day: number 67 (`BOE-S-2020-67`) and number 66. 419 items in all: section 1 (general provisions) 5, 2A 4, 2B 7, 3 (other provisions) 41, 4 (administration of justice) 280, 5A 22, 5B 52, 5C 8.
  112. - The first item is in issue 67, the extraordinary one: `BOE-A-2020-3692`, "Real Decreto 463/2020, de 14 de marzo, por el que se declara el estado de alarma para la gestión de la situación de crisis sanitaria ocasionada por el COVID-19."
  113. *"Anything about vivienda in the BOE this week?"*
  114. ```text
  115. scan_gazette(words="vivienda") -> default range: the last 7 days, 2026-11-16 to 2026-11-22
  116. ```
  117. - 7 days scanned, 6 with an issue (the 22nd is a Sunday, with none); 11 titles match: 2026-11-16 1, 11-17 2, 11-18 1, 11-19 2, 11-20 4, 11-21 1.
  118. - 2026-11-21, `BOE-A-2026-24487`: "Resolución de 10 de noviembre de 2026, de la Dirección General de Vivienda y Suelo, por la que se publica el Convenio con la Comunidad Autónoma de Castilla-La Mancha, …"
  119. - 2026-11-19, `BOE-B-2026-38005`: "Anuncio del concurso de proyectos de: Secretaría General de Agenda Urbana, Vivienda y Arquitectura. …"
  120. - 2026-11-20, `BOE-B-2026-38218`: "Resolución del Departamento de Territorio, Vivienda y Transición Ecológica TER/4133/2026, por la que se otorga …"
  121. ### Good to know
  122. - **Title filters match whole words, and wording matters.** The trend tools and the gazette tools match singular and plural forms ("vivienda" also finds "viviendas"); the BOE's own search (the `title` and `text` filters of `search_legislation`) matches exact words. In a title, "fumar" finds nothing since 2020, while "tabaco" finds 8 (verified on 2026-11-21). A text or subject filter that matches more than 5,000 laws is refused as too broad.
  123. - **The gazette is wider than the consolidated collection.** `get_daily_summary` and `scan_gazette` list everything the BOE prints, and most of those identifiers (appointments, announcements, many resolutions) are not in the consolidated collection, so the law and article tools will not find them.
  124. - **Citation checks compare words, not meaning.** A paraphrase does not match, and a quote that skips a word with "(...)" matches while `omitted` and `flags` say what was skipped. The result is facts about wording, not a view on legal correctness.
  125. - **Coverage is the BOE's consolidated legislation collection**, not every item printed in the BOE, and it holds only part of each year's laws, a varying part (thinner before about 2010 and for the most recent year or two). A change in a count is not by itself a change in how much was legislated. Counting one rank (Ley with `scope="state"`, Ley Orgánica, Real Decreto-ley or Real Decreto Legislativo) by year, `legislation_over_time` adds `highest_number` so you can judge the coverage. Counts say so in their `caveats`.
  126. - **Regional coverage is laws and decree-laws with the rank of law**, not regional decrees or orders, which live in each community's own gazette.
  127. - **Regional laws are dated by their BOE reprint** (which can come weeks or years after the regional publication) unless you pass `date_basis="enacted"`; under `enacted` the last three months are incomplete, because laws are published weeks after being enacted.
  128. - **Consolidated texts are informational and have no official legal value.** See the [legal notice](#data-source-attribution-and-legal-notice).
  129. ## Tools
  130. ### Finding laws
  131. | Tool | Question it answers | Key parameters |
  132. |---|---|---|
  133. | `resolve_reference` | What is the BOE identifier of "Ley 40/2015"? | `reference` (a name such as `Ley Orgánica 3/2018`, `RDL 6/2019`, an identifier, or a title fragment) |
  134. | `search_legislation` | Which laws are about X, or were published recently? | `title`, `text`, `rank`, `department_code`, `scope`, `subject_code`, `published_from`, `published_to`, `sort_by`, `descending`, `limit` (1-50), `offset` |
  135. | `get_law_overview` | Is this law in force, and how much has it changed? | `law_id` (e.g. `BOE-A-2015-10566`) |
  136. | `find_codes` | What is the code of this department, subject or rank (for the `search_legislation` filters)? | `kind` (`department`, `subject` or `rank`), `text`, `limit` (1-50) |
  137. ### Reading and tracking changes
  138. | Tool | Question it answers | Key parameters |
  139. |---|---|---|
  140. | `get_law_structure` | What is this law's table of contents, and which article deals with a matter? | `law_id`, `as_of`, `detail` (`headings` or `all`), `offset`, `limit` |
  141. | `read_article` | What does this article say, today or on a past date? | `law_id`, `article` or `block_id`, `as_of`, `max_chars` (500-20000), `offset` |
  142. | `compare_article_versions` | What changed in this article between two dates? | `law_id`, `article` or `block_id`, `from_date`, `to_date`, `max_changes` (1-200), `max_chars` (1000-30000) |
  143. | `get_article_history` | When did this article change, and which law changed it? | `law_id`, `article` or `block_id` |
  144. | `get_amendment_history` | Which norms have affected this law, by kind and by year? | `law_id`, `group` (`all`, `repeals`, `modifies`, `adds`, `corrections` or `other`), `limit` (1-100), `offset` |
  145. | `explore_amendment_chain` | Which laws did this law amend, and which laws amended it, up to three levels deep? | `law_id`, `direction` (`amended_by` or `amends`), `depth` (1-3), `include` (`amendments` or `all`), `details` (`root`, `all` or `none`), `max_laws` (1-50) |
  146. ### Checking citations
  147. | Tool | Question it answers | Key parameters |
  148. |---|---|---|
  149. | `verify_citation` | Do these citations (law, article, quoted words) exist, are they in force, and do the words match the text, the current version or an older one? | `citations` (1 to 10, each with `law`, `article` or `block_id`, optional `quote` of at most 5,000 characters, optional `as_of`) |
  150. ### The daily gazette
  151. These two tools cover everything the BOE prints (appointments, grants, announcements, every disposition) since 1960-09-01, unlike the consolidated collection the other tools use.
  152. | Tool | Question it answers | Key parameters |
  153. |---|---|---|
  154. | `get_daily_summary` | What did the BOE publish on this day? | `date` (default: the latest issue), `section`, `department_code`, `words`, `offset`, `limit` (1-100) |
  155. | `scan_gazette` | Which items in the last days have these words in the title? | `words`, `section`, `department_code`, `from_date` (default: 6 days before `to_date`), `to_date` (default: today), `offset`, `limit` (1-100); at most 31 days |
  156. All eighteen tools are read-only. `resolve_reference` returns `resolved`, `ambiguous` (with candidates and a hint) or `not_found`. `search_legislation` pages with `next_offset`, because the API gives no total count. `find_codes` returns the matching `{code, text}` pairs.
  157. **Law status.** `get_law_overview` returns a `status` (`in_force`, `partially_repealed`, `repealed`, `annulled`, `validity_exhausted` or `not_yet_in_force`) with a plain-English note, the BOE's initial note when the text has one, and counts and samples of the norms that amend the law or that it amends. The status is derived from the BOE flags and the amendment references, so it is an indication, not a legal determination. A whole repeal is also detected from the opening note of the consolidated text ("Norma derogada..."), because some wholly repealed laws carry only that note and not the metadata flag.
  158. **Article states.** `read_article` reports the article's `state` on the requested date and `get_article_history` its `current_state`: `in_force`, `repealed`, `not_yet_in_force` (text published but not yet effective) or `did_not_exist` (the date precedes the article's first version). An article of a law repealed as a whole carries no repeal marker, so the article tools also check the law (its metadata and, when the text has one, its initial note): from the repeal date on, the state is `repealed` (the last text is still returned), `law_repealed` and `law_repealed_on` say so, and `note` explains it. A repeal dated in the future is only announced, and if that check cannot be done `law_repealed` is `null` and `note` says so.
  159. **Naming an article.** The `article` argument (at most 200 characters) accepts the wording people use: `46 bis`, `art. 12`, `art. 1.902`, `artículo 48`, `disposición adicional tercera` (or `DA 3`), `anexo I`, `preámbulo`. Anything after the designation, such as a paragraph number (`46.2`, `149.1.18ª`) or a context (`14 de la Constitución`), is ignored, because the tools return whole articles; `note` says what was ignored. To pick an exact block, pass its `block_id` from `candidates` instead of `article` (exactly one of the two is required). If the wording matches several blocks (`ambiguous`) or none (`not_found`), the result is not an error: `outcome` says so and `candidates` lists blocks to retry with, using their `block_id`.
  160. ### Trends and rankings
  161. | Tool | Question it answers | Key parameters |
  162. |---|---|---|
  163. | `legislation_over_time` | How many laws on X per year, quarter or month? | `title`, `text`, `subject_code`, `rank`, `scope`, `department_code`, `from_date`, `to_date`, `period`, `date_basis`, `group_by` (`none`, `rank`, `department` or `scope`), `top_groups` |
  164. | `top_departments` | Which departments or autonomous communities have issued the most laws on X? | the same filters, plus `limit` |
  165. | `compare_topics` | How do 2 to 5 topics compare over time? | `topics` (each with `name` and `title`, `text` or `subject_code`), `rank`, `scope`, `department_code`, `from_date`, `to_date`, `period`, `date_basis` |
  166. | `explain_spike` | Why does this period have unusually many laws? | the same filters, plus `period_key` (`2020`, `2020-Q2` or `2020-03`), `period`, `baseline_periods`, `max_laws` |
  167. | `most_amended_laws` | Which laws on X have been amended most by later laws? | the same filters, plus `limit`, `max_laws` (laws examined per call) |
  168. The trend tools count over a local snapshot of the whole consolidated collection (see [How it works](#how-it-works)); the first one takes about half a minute. `from_date` defaults to 1 January of the year 19 years before `to_date` (`most_amended_laws` has no default lower bound) and `to_date` to today. A result of more than 1,500 points (series times periods) is refused with advice to use a coarser period, a shorter range or fewer groups. `date_basis` is `published` (BOE publication, the default) or `enacted`. `most_amended_laws` reads one law's amendment data per request, so each call examines at most `max_laws` laws: while `complete` is false, call again with the same arguments to continue from the cache.
  169. Every result carries a `provenance` block. Trimmed output of `compare_article_versions` for article 48 of `BOE-A-2015-10566` between 2016-10-02 and 2026-11-21 (recorded test fixtures, no live request). Long strings (`inline`, `unified_diff`) are shortened here with `…`. `[-old-] {+new+}` marks a rewording inside a paragraph: a reworded paragraph is returned as `inline` alone (`old_text` and `new_text` are `null`), except tables, which return both texts and no `inline`:
  170. ```json
  171. {
  172. "law_id": "BOE-A-2015-10566",
  173. "outcome": "found",
  174. "block_id": "a48",
  175. "block_title": "Artículo 48",
  176. "candidates": [],
  177. "hint": null,
  178. "provenance": {
  179. "source": "Agencia Estatal Boletín Oficial del Estado",
  180. "attribution": "Basado en datos de la Agencia Estatal Boletín Oficial del Estado",
  181. "source_url": "https://www.boe.es",
  182. "generated_at": "2026-11-21T12:41:13.262679Z",
  183. "data_updated_at": "2020-12-31T00:00:00Z",
  184. "notice": "Consolidated texts are provided for information only and have no official legal value. Only the texts published in the official gazette are authentic."
  185. },
  186. "law_repealed": false,
  187. "law_repealed_on": null,
  188. "note": null,
  189. "from_date": "2016-10-02",
  190. "to_date": "2026-11-21",
  191. "from_version": {
  192. "index": 1,
  193. "starts_on": "2016-10-02",
  194. "effective_from": "2016-10-02",
  195. "published_on": "2015-10-02",
  196. "introduced_by": "BOE-A-2015-10566"
  197. },
  198. "to_version": {
  199. "index": 2,
  200. "starts_on": "2021-01-01",
  201. "effective_from": "2021-01-01",
  202. "published_on": "2020-12-31",
  203. "introduced_by": "BOE-A-2020-17340"
  204. },
  205. "identical": false,
  206. "added": 0,
  207. "removed": 0,
  208. "changed": 1,
  209. "unchanged": 11,
  210. "changes": [
  211. {
  212. "op": "changed",
  213. "old_text": null,
  214. "new_text": null,
  215. "inline": "… resultarán eficaces una vez [-inscritos-] {+inscritos, en el plazo de 5 días hábiles desde su formalización,+} en el Registro Electrónico estatal de Órganos e Instrumentos de Cooperación del sector público estatal, al que se …"
  216. }
  217. ],
  218. "changes_truncated": false,
  219. "intermediate_versions": 0,
  220. "amending_laws": [
  221. "BOE-A-2020-17340"
  222. ],
  223. "unified_diff": "--- old\n+++ new\n@@ -8,5 +8,5 @@\n …",
  224. "unified_truncated": false
  225. }
  226. ```
  227. ## Quick start
  228. Prerequisites: Python 3.11+ and [uv](https://docs.astral.sh/uv/). No API key is needed: the BOE open data API is public.
  229. Run from source:
  230. ```bash
  231. git clone https://github.com/davidbejar/boe-insights-mcp.git
  232. cd boe-insights-mcp
  233. uv sync
  234. ```
  235. The server speaks MCP over stdio, so you normally do not start it by hand: your MCP client does.
  236. **Claude Desktop.** Add this to `claude_desktop_config.json` and restart the app (use the absolute path of your clone):
  237. ```json
  238. {
  239. "mcpServers": {
  240. "boe-insights": {
  241. "command": "uv",
  242. "args": ["--directory", "/absolute/path/to/boe-insights-mcp", "run", "boe-insights-mcp"]
  243. }
  244. }
  245. }
  246. ```
  247. **Claude Code:**
  248. ```bash
  249. claude mcp add boe-insights -- uv --directory /absolute/path/to/boe-insights-mcp run boe-insights-mcp
  250. ```
  251. Or commit the same server definition in a project-level `.mcp.json`:
  252. ```json
  253. {
  254. "mcpServers": {
  255. "boe-insights": {
  256. "command": "uv",
  257. "args": ["--directory", "/absolute/path/to/boe-insights-mcp", "run", "boe-insights-mcp"]
  258. }
  259. }
  260. }
  261. ```
  262. **Without cloning**, uv can fetch and run it straight from GitHub:
  263. ```bash
  264. uvx --from git+https://github.com/davidbejar/boe-insights-mcp boe-insights-mcp
  265. ```
  266. In a client configuration, use `"command": "uvx"` with `"args": ["--from", "git+https://github.com/davidbejar/boe-insights-mcp", "boe-insights-mcp"]`.
  267. ## Configuration
  268. Optional environment variables; unset or empty variables keep their defaults, and invalid values stop the server at startup with a message naming the variable.
  269. | Variable | Default | Meaning |
  270. |---|---|---|
  271. | `BOE_INSIGHTS_CACHE` | `disk` | Cache backend: `disk` (persistent) or `memory` (per process). |
  272. | `BOE_INSIGHTS_CACHE_DIR` | platform cache directory | Where the disk cache lives. |
  273. | `BOE_INSIGHTS_MIN_INTERVAL` | `1.0` | Minimum seconds between requests to boe.es (number >= 0). |
  274. | `BOE_INSIGHTS_MAX_CONCURRENCY` | `2` | Maximum simultaneous requests to boe.es (integer >= 1). |
  275. ## How it works
  276. ```text
  277. MCP tools server.py thin: parameters, descriptions, error translation
  278. |
  279. use-case functions legislation.py laws, search, amendments: plain functions returning typed pydantic models
  280. articles.py article text, comparison, history, built on locator.py and versions.py
  281. trends.py counts and rankings over the catalogue snapshot (catalogue.py, analytics.py)
  282. |
  283. BOE client client.py BOE API calls, retries; textparse.py parses the text XML
  284. |
  285. cache + rate limiter disk or memory cache; minimum interval and concurrency cap
  286. |
  287. BOE open data API https://www.boe.es/datosabiertos/
  288. ```
  289. The article tools add three pieces: an XML parser for the BOE's text blocks (`textparse.py`), an article locator (`locator.py`) and the version logic (`versions.py`: selection, repeal detection, diff and history). The last two are pure functions with no I/O.
  290. - **Trends run on a local snapshot.** The API has no aggregate endpoint, so `catalogue.py` downloads the whole collection (about 12,500 laws) in 3 requests, keeps it for a day and counts locally. `most_amended_laws` is the exception: it needs each law's amendment data, which costs one request per law, hence the `max_laws` budget per call.
  291. - **Cache-first.** Responses are cached (searches for 30 minutes; law metadata, amendment analysis and the text index for 6 hours; article text for 6 hours, or 30 days when the index's update date is known), so repeated questions do not reach the BOE.
  292. - **Articles are found by title.** The BOE's block ids are opaque (article 46 bis of Ley 40/2015 is `a4-2`), so the server reads the law's text index and matches the wording against the block titles instead of building an id.
  293. - **Versions are selected by start date.** Each version of an article starts on its effective date (the publication date when that is missing), and the text in force on a date is the latest version that started on or before it.
  294. - **Long articles come in pages.** `read_article` returns at most `max_chars` characters, with `truncated` and `next_offset` to fetch the rest; `compare_article_versions` and `get_article_history` cap their output and say so with `changes_truncated`, `unified_truncated` and `truncated`.
  295. - **Citation matching compares words and versions.** A quote and each version of the article are reduced to comparable words (case, punctuation and quotation marks ignored, accents kept); the best aligned passage is graded `exact`, `close`, `partial` or `none`, and the other versions of the article are compared too, which is how an older wording is recognised.
  296. - **Daily summaries are read as XML, and past days are cached.** The BOE's summary of a day is fetched as XML; a past day never changes, so it is kept for 30 days (today's summary for an hour).
  297. - **Polite by default.** The BOE publishes no rate limit, so the server imposes its own: at least one second between requests and at most two at a time.
  298. - **Typed, structured results.** Every tool returns a pydantic model with a declared output schema, not free text.
  299. - **Actionable errors.** Failures say what happened, whether retrying makes sense and what to do next (for example, "use `resolve_reference` to find the correct identifier").
  300. - **Provenance everywhere.** Each result states its source, the required attribution, when the result was assembled (`generated_at`; the data itself may come from the cache), the API's last-update stamp and the informational-only notice.
  301. ## Data source, attribution and legal notice
  302. The data comes from the BOE open data API: <https://www.boe.es/datosabiertos/>.
  303. Basado en datos de la Agencia Estatal Boletín Oficial del Estado ([www.boe.es](https://www.boe.es)).
  304. - Consolidated texts are informational only and have no official legal value. Only the texts published in the official gazette are authentic. Gazette summaries are a listing, and only the texts published in the BOE itself are authentic.
  305. - This project is independent. It is not affiliated with, sponsored by or endorsed by the Agencia Estatal Boletín Oficial del Estado.
  306. - Nothing here is legal advice.
  307. ## Roadmap
  308. - [x] 1. Thin slice: client, cache, rate limiter and four tools
  309. - [x] 2. Article reading and version history: read an article as of a date, article diff, change timeline, amendment history
  310. - [x] 3. Trend analytics: legislation over time, top departments, compare topics, explain a spike, most-amended laws, plus a law's table of contents
  311. - [x] 4. Citation verification, amendment chain explorer, gazette scanning
  312. - [ ] 5. MCP resources, prompts and stored watchlists
  313. - [ ] 6. Remote mode: Streamable HTTP, GitHub OAuth, Podman container
  314. - [ ] 7. Evaluation suite, documentation site, PyPI release
  315. ## Development
  316. ```bash
  317. uv sync --all-groups # install, including dev tools
  318. uv run pytest # tests; no network
  319. uv run pytest -m live # tests against the real BOE API
  320. uv run ruff check . && uv run ruff format . # lint and format
  321. uv run pyright # type check
  322. ```
  323. Live tests hit the real BOE API; run them sparingly. Logic is written tests first, and unit tests never touch the network: they use [respx](https://lundberg.github.io/respx/) with real API responses recorded in `tests/fixtures/boe/`. Verified API behaviour is documented in [`docs/api-notes.md`](docs/api-notes.md).
  324. ## License
  325. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.