内容
# normativa-dev
**整合西班牙立法，分類主題 — MCP Server + API REST + CLI**
[](https://pypi.org/project/normativa/)
[](LICENSE)
[](https://www.python.org/downloads/)
通过 [BOE](https://www.boe.es/)（官方公报）访问所有西班牙立法，使用针对LLMs优化的MCP工具、与ChatGPT Actions兼容的REST API或直接CLI。
**网站：** [normativa.dev](https://normativa.dev)
---
## 为什么选择normativa
现有项目是BOE API的粗糙封装。`normativa`添加了一个**主题智能层**，包括：
- **按法律领域分类** — 税务、劳动法、商法、自主经营、数据保护、数字、住房、环境、消费、刑法、民事、行政法
- **预映射关键法律**，包含重要文章和区块ID，避免LLM盲目搜索
- **优化上下文** — 永远不会加载完整的法律；按需提取个别文章（效率提高约12倍）
- **集成欧盟立法** — 与欧盟指令和法规（CELEX/ELI）的交叉引用
- **三种传输方式** — MCP（适用于Claude、Cursor、VS Code）、HTTP REST（适用于ChatGPT、Codex、任何客户端）和CLI（适用于终端）
---
## 安装
### 与Claude Code（MCP）一起使用
将以下内容添加到项目根目录的 `.mcp.json` 中：
```json
{
"mcpServers": {
"normativa": {
"command": "uvx",
"args": ["normativa"]
}
}
}
```
重启Claude Code。 11种工具将自动可用。
### 与ChatGPT / GPTs（HTTP API）一起使用
```bash
# 安装
pip install normativa
# 启动HTTP服务器
normativa serve --mode http --port 8787
```
该API在 `http://localhost:8787` 上公开，OpenAPI规范位于 `/api/openapi.json`。要创建GPT操作，请将该URL导入为规范。
### 作为CLI使用
```bash
# 使用uv（推荐）
uvx normativa buscar "proteccion datos" --dominio digital
# 使用pip
pip install normativa
normativa buscar "impuesto sociedades" --dominio fiscal
```
### 与其他编辑器（Cursor，VS Code，Windsurf，OpenCode）一起使用
**Cursor** — 在 `Settings > MCP Servers` 中：
```json
{
"normativa": {
"command": "uvx",
"args": ["normativa"]
}
}
```
**VS Code + Continue/Copilot** — 在 `.vscode/mcp.json` 中：
```json
{
"servers": {
"normativa": {
"command": "uvx",
"args": ["normativa"]
}
}
}
```
**Windsurf** — 在 `.windsurf/mcp.json` 中：
```json
{
"mcpServers": {
"normativa": {
"command": "uvx",
"args": ["normativa"]
}
}
}
```
**OpenCode** — 在 `.opencode/mcp.json` 中：
```json
{
"mcpServers": {
"normativa": {
"command": "uvx",
"args": ["normativa"]
}
}
}
```
### 从Python代码中使用
```python
from normativa.tools.search import buscar_legislacion, buscar_por_dominio
from normativa.tools.text import leer_articulo
# 搜索财政立法
resultado = await buscar_por_dominio("fiscal", subtema="iva")
# 读取特定文章
articulo = await leer_articulo("BOE-A-2014-12328", "a29")
print(articulo["texto"])
```
---
## 兼容平台
| 平台 | 传输方式 | 配置 |
|---|---|---|
| **Claude Code** | MCP（stdio） | `.mcp.json` |
| **Claude.ai web** | HTTP REST | 服务器URL |
| **ChatGPT / GPTs** | HTTP REST（OpenAPI） | 导入 `/api/openapi.json` 作为操作 |
| **Codex（OpenAI）** | HTTP REST | API URL |
| **Cursor** | MCP（stdio） | 设置 > MCP服务器 |
| **VS Code + Continue** | MCP（stdio） | `.vscode/mcp.json` |
| **VS Code + Copilot** | MCP（stdio） | `.vscode/mcp.json` |
| **Windsurf** | MCP（stdio） | `.windsurf/mcp.json` |
| **OpenCode** | MCP（stdio） | `.opencode/mcp.json` |
| **终端** | CLI | `pip install normativa` |
| **Python** | 库 | `import normativa` |
| **任何HTTP** | REST API | `curl http://host:8787/api/...` |
---
## 可用工具
| # | 工具 | HTTP端点 | 描述 |
|---|---|---|---|
| 1 | `listar_dominios` | `GET /api/dominios` | 列出主题领域及其关键法律 |
| 2 | `buscar_por_dominio` | `GET /api/buscar` | 智能搜索法律领域 |
| 3 | `buscar_legislacion` | `GET /api/buscar/texto` | 自由文本搜索综合立法 |
| 4 | `obtener_metadatos` | `GET /api/norma/{id}/metadatos` | 法律规范的元数据（标题、日期、状态） |
| 5 | `obtener_analisis` | `GET /api/norma/{id}/analisis` | 主题和交叉引用 |
| 6 | `leer_indice` | `GET /api/norma/{id}/indice` | 法律索引 |
| 7 | `leer_articulo` | `GET /api/norma/{id}/articulo/{bloque}` | Markdown格式的单个文章 |
| 8 | `leer_articulos_rango` | `GET /api/norma/{id}/articulos` | 多达20个连续文章 |
| 9 | `sumario_boe` | `GET /api/boe/sumario/{fecha}` | BOE每日摘要 |
| 10 | `sumario_borme` | `GET /api/borme/sumario/{fecha}` | BORME每日摘要 |
| 11 | `datos_auxiliares` | `GET /api/auxiliar/{tipo}` | 引用数据（主题、部门、范围） |
---
## 主题领域
| 领域 | 关键法律 | 子主题 | 欧盟引用 |
|---|---|---|---|
| `fiscal` | LIS, LIRPF, LIVA, LGT | 个人所得税, 增值税, 公司税, 一般税法 | 增值税指令, ATAD |
| `laboral` | ET, LGSS, LPRL | 合同, 解雇, 社会保障, 预防 | - |
| `mercantil` | LSC, CCom | 有限公司, 股份公司, 商事登记 | - |
| `autonomos` | LETA, LGSS-RETA | 注册, 缴费, 税收, 发票 | - |
| `proteccion_datos` | LOPDGDD | 受影响权利, 企业义务, 数字权利 | GDPR |
| `digital` | LSSI | 电子商务, Cookie, 法律公告 | 电子商务指令, ePrivacy |
| `vivienda` | 住房法, LAU | 租赁, 紧张区域, 驱逐 | - |
| `medioambiental` | LRMA, 气候变化法 | 环境评估, 废物, 排放 | EIA指令 |
| `penal` | CP, LECrim | 犯罪, 惩罚, 刑事程序 | - |
| `civil` | CC, LEC | 义务, 合同, 家庭, 继承 | - |
| `administrativo` | LPAC, LRJSP | 行政程序, 法律制度 | - |
| `consumo` | LGDCU | 保证, 投诉, 电子商务 | 消费者指令 |
---
## REST API
启动服务器：
```bash
normativa serve --mode http --port 8787
```
使用curl的示例：
```bash
# 列出主题领域
curl http://localhost:8787/api/dominios
# 按财政领域搜索
curl "http://localhost:8787/api/buscar?dominio=fiscal&subtema=iva"
# 自由文本搜索
curl "http://localhost:8787/api/buscar/texto?q=proteccion+datos&limit=5"
# 法律规范的元数据
curl http://localhost:8787/api/norma/BOE-A-2014-12328/metadatos
# 读取特定文章
curl http://localhost:8787/api/norma/BOE-A-2014-12328/articulo/a29
# 法律索引
curl http://localhost:8787/api/norma/BOE-A-2014-12328/indice
# 文章范围
curl "http://localhost:8787/api/norma/BOE-A-2014-12328/articulos?desde=a1&hasta=a5"
# BOE每日摘要
curl http://localhost:8787/api/boe/sumario/2026-04-05
# BORME每日摘要
curl http://localhost:8787/api/borme/sumario/2026-04-05
# 辅助数据（主题）
curl "http://localhost:8787/api/auxiliar/materias?buscar=tributario"
# OpenAPI规范（适用于ChatGPT操作）
curl http://localhost:8787/api/openapi.json
```
`http://localhost:8787/docs`上的交互式文档（Swagger UI）。
---
## 代理团队
`normativa`包含11个适用于Claude Code的代理（6个法律 + 5个开发）：
```
阶段1（并行）：研究员-法律 + 变更监视器
阶段2：文章提取器
阶段3（并行）：领域分析师 + 合规验证器
阶段4：报告撰写器
```
代理通过 `handoff/` 中的文件进行通信，传递**引用**（BOE ID + 区块ID）而不是完整文本。这使得令牌消耗比加载完整法律效率高约12倍。
---
## 架构
```
+---------------------------------------------------------+
| 第5层：HTTP REST API（FastAPI + OpenAPI自动） |
| GET /api/buscar, /api/norma/{id}/articulo/{bloque}... |
+---------------------------------------------------------+
| 第4层：代理团队（11个代理 .claude/agents/） |
| 研究员 -> 提取器 -> 分析师 -> 撰写者 |
+---------------------------------------------------------+
| 第3层：技能（10个软件包 .claude/skills/） |
| 延迟加载领域知识 |
+---------------------------------------------------------+
| 第2层：MCP服务器（11个工具 FastMCP） |
| 领域注册 + SQLite缓存 + XML解析器 |
+---------------------------------------------------------+
| 第1层：BOE API客户端（httpx异步） |
| /legislacion-consolidada + /sumario + /auxiliar |
+---------------------------------------------------------+
```
第5层（HTTP）封装了第2层MCP工具的相同功能，而无需重复代码。
---
## 开发
```bash
# 克隆和配置
git clone https://github.com/ioseobcn/normativa-dev.git
cd normativa-dev
uv sync
# 测试
uv run pytest -v
# 本地文档
uv run mkdocs serve
# CLI
uv run normativa buscar "despido" --dominio laboral
# 开发服务器
uv run normativa serve --mode http --port 8787
```
查看 [贡献指南](docs/contributing.md) 和 [开发文档](docs/dev/index.md) 以获取更多详细信息。
---
## 数据源
所有立法数据均来自 [BOE开放数据 API](https://www.boe.es/datosabiertos/) （Agencia Estatal Boletin Oficial del Estado）。数据是公开的，属于公共领域。
## 法律声明
该软件具有信息性质，**不构成法律咨询**。在根据获得的结果做出决定之前，请咨询专业人士。
## 许可证
[MIT](LICENSE) — [InnovaOrigen](https://innovaorigen.io) 2026
