内容
# MCP-CENDOJ：法官判决搜索服务器与 API
<img width="1024" height="1024" alt="MCP-CENDOJ" src="https://github.com/user-attachments/assets/4b6746ba-85af-4199-9a45-3bd0121a8b9c" />
本项目提供一个 **REST API（使用 FastAPI）** 和一个 **MCP 服务器（模型上下文协议）** ，用于搜索和查询 **CENDOJ（西班牙司法文书中心）** 的法官判决。
由于 CENDOJ 没有提供公共 API，并且其搜索功能受到 JavaScript 交互和自动完成验证的保护，该服务使用 **Playwright** 模拟实际搜索，自动化和稳健地返回干净的 JSON 结果，并抽象出从法官判决 PDF 中下载和提取文本的过程。
---
## 功能特点
* **自动搜索（Playwright）：** 自动导航，接受法律公告，模拟顺序输入以激活搜索，并选择 CENDOJ 的建议以避免搜索限制。
* **使用 FastAPI 的 REST API：**
* `GET /api/status`：验证服务的健康状况和配置。
* `GET /api/search`：使用以下参数执行高级搜索：
* `query`：可选的自由文本。
* `fecha_desde` / `fecha_hasta`：日期范围（YYYY-MM-DD 或 DD/MM/AAAA）。
* `jurisdiccion`：民事、刑事、行政争议、社会、军事。
* `roj`：ROJ 标识符（例如 `STS 2849/2026`）。
* `ecli`：ECLI 代码（例如 `ES:TS:2026:2849`）。
* `n_resolucion`：判决编号。
* `n_recurso`：资源编号。
* `ponente`：主审法官姓名。
* `norma`：相关法律法规。
* `localizacion`：地点列表或自治区（例如 `安达卢西亚`、`加泰罗尼亚`、`马德里`）。
* `GET /api/decision`：解析 CENDOJ 的文档容器，下载 PDF 文件，并提取其纯文本。
* **MCP 服务器（模型上下文协议）：**
* 支持 **_stdio** 模式（适用于 Cursor 和 Claude Desktop 等本地桌面客户端）。
* 支持 **SSE（服务器发送事件）** 模式，原生集成在 FastAPI 下，前缀为 `/mcp`（适用于远程或 Web 客户端）。
* 提供的工具：
* `buscar_jurisprudencia`：使用所有详细过滤器执行搜索（查询、ROJ、ECLI、主审法官、资源、判决、法规等）。
* `obtener_texto_resolucion`：下载 PDF 文件并提取其全文。
---
## 先决条件
* 安装 Python 3.10 或更高版本。
* 在系统上安装 Playwright 的 Chromium 浏览器。
---
## 快速安装和配置
为了简化 Windows 上的配置，我们包含了自动执行整个过程的脚本：
1. **运行自动配置：**
双击文件 **`setup.bat`** （或从控制台执行）。该脚本将负责：
* 创建虚拟环境 `.venv`。
* 安装和更新所有依赖项（`requirements.txt`）。
* 安装 Playwright 所需的 Chromium 浏览器。
* 创建默认的配置文件 `.env`。
2. **在 MCP 客户端中注册（自动）：**
完成设置后，执行自动安装实用程序，将 MCP 服务器与本地客户端绑定：
```powershell
.venv\Scripts\python.exe install_mcp.py
```
该命令将检测存储库的绝对路径并自动将 CENDOJ 服务器注册到以下全局配置中：
* **Claude Desktop** (`claude_desktop_config.json`)
* **Antigravity IDE** (`mcp_config.json`)
---
## 手动安装和配置（替代方案）
如果您不想使用自动化脚本，可以按照以下步骤手动初始化项目：
1. **创建 Python 虚拟环境：**
```powershell
python -m venv .venv
```
2. **激活虚拟环境：**
* **在 Windows（PowerShell）上：**
```powershell
.venv\Scripts\Activate.ps1
```
* **在 macOS/Linux 或 Git Bash 上：**
```bash
source .venv/bin/activate
```
3. **安装依赖项：**
```powershell
pip install --upgrade pip
pip install -r requirements.txt
```
4. **为 Playwright 安装 Chromium 浏览器：**
```powershell
playwright install chromium
```
5. **创建配置文件 `.env`：**
在项目根目录创建一个名为 `.env` 的文件，并写入以下行：
```env
CENDOJ_HEADLESS=true
```
---
## 运行指南
脚本 `run.py` 是统一的入口点：
### 1. 作为 REST API 和 SSE 服务器（FastAPI）运行
要启动 Web 服务器：
```powershell
.venv\Scripts\python.exe run.py api
```
服务器将在 **http://localhost:8000** 启动。
* **交互式文档（Swagger/OpenAPI）：** 访问 [http://localhost:8000/docs](http://localhost:8000/docs) 直接与 REST API 交互。
* **MCP SSE 端点：** 可在 [http://localhost:8000/mcp/sse](http://localhost:8000/mcp/sse) 访问。
### 2. 作为 MCP Stdio 服务器（控制台/标准输入）运行
要使用标准输入和输出启动 MCP 服务器（适用于本地桌面工具集成）：
```powershell
.venv\Scripts\python.exe run.py mcp
```
---
## 与 MCP 客户端手动集成（可选）
如果您更喜欢手动注册而不是使用 `install_mcp.py`：
### Claude Desktop
要将此 MCP 服务器与 Claude Desktop 连接，请编辑您的配置文件 `claude_desktop_config.json`（通常位于 Windows 上的 `%APPDATA%\Claude\claude_desktop_config.json`），并添加服务器配置：
```json
{
"mcpServers": {
"cendoj-jurisprudencia": {
"command": "c:/workspace-github/MCP-CENDOJ/.venv/Scripts/python.exe",
"args": ["c:/workspace-github/MCP-CENDOJ/run.py", "mcp"],
"env": {
"CENDOJ_HEADLESS": "true"
}
}
}
}
```
### Cursor
要在 Cursor 中使用服务器：
1. 进入 **设置 > 功能 > MCP**。
2. 点击 **+ 添加新 MCP 服务器**。
3. 配置以下值：
* **名称：** `CENDOJ`
* **类型：** `command`
* **命令：** `c:/workspace-github/MCP-CENDOJ/.venv/Scripts/python.exe c:/workspace-github/MCP-CENDOJ/run.py mcp`
## CENDOJ MCP 的自然语言提示指南
本指南展示了如何以自然和对话式的语言与助手交流（就像与同事或律师交谈一样），以及 AI 如何将您的请求转换为 CENDOJ 搜索器的技术查询。
### 💬 实际交互示例
1. **咨询现代情况下的事故**
* **您的自然语言提示：** *"请帮我搜索在工作时间在自己的厨房里绊倒的远程工作者的案例，以及法院是否接受这是工伤。*"
* **AI 背后处理：** 搜索诸如 `"工伤"`、`"远程工作"`、`"厨房"` 或 `"住所"` 等术语，在社会司法管辖区，下载判决文本并分析已证实的事实。
* **您收到的回复：** 关于法院是否将厨房视为工作场所以及需要什么条件才能被视为工伤的总结。
2. **调查特定地理区域的判决**
* **您的自然语言提示：** *"我需要查看 Valladolid 最近关于对在监视期间入睡的员工进行纪律处分的判决。*"
* **AI 背后处理：** 按 Valladolid (`localizacion: ["Valladolid"]`) 筛选，搜索社会司法管辖区中的 `"纪律处分"` 和 `"入睡"` 或 `"监视"` 等术语，按最近日期排序。
* **您收到的回复：** 来自瓦伦西亚自治区最高法院司法 tribunal（TSJ）的最新判决列表，以及它们是否宣布处罚有效或无效。
---
## 测试和验证
该项目在临时或草稿目录中包含快速开发测试脚本：
* **直接爬虫测试：** `test_scraper.py` 搜索一个术语并尝试下载第一个 PDF 文件。
* **REST API 和 SSE 集成测试：** `test_api.py` 验证状态，执行查询并通过正在运行的 FastAPI 服务器下载 PDF 文件。
* **MCP Stdio 客户端测试：** `test_mcp_stdio_client.py` 在子进程中启动 MCP 服务器并模拟真实客户端的 JSON-RPC 调用。
---
## 免责声明和使用条款
> [!WARNING]
> **在使用工具之前请仔细阅读**
>
> 本软件是一个开放源代码的实用程序，仅供 **教育、学术研究和个人私人查询** 使用。
### 1. 遵守 CENDOJ 和 CGPJ 的规定
CENDOJ（西班牙司法文书中心）门户网站规定了特定的访问条款。使用该软件时，用户承担全部责任，遵守这些政策：
* **个人使用：** 仅限于个人和非商业性质的查询访问 CENDOJ 搜索器。
* **禁止大规模下载和商业用途：** 根据 CGPJ 的指南，严禁使用自动化工具进行大规模司法文书提取（大规模网络抓取）和商业开发数据库。如果您需要以商业或大规模为目的重新使用数据，请直接向 CENDOJ 申请正式的再利用许可证。
* **查询频率：** 强烈建议适度并合理地使用该工具，以避免服务器超载或违反 CENDOJ 的合理服务限制。
### 2. 个人数据保护（RGPD / LOPDGDD）
CENDOJ 公布的判决已经过匿名/伪匿名处理。《通用数据保护条例》（RGPD）和《有机法律 3/2018》（LOPDGDD）严格禁止将这些信息用于重新识别司法程序中涉及的自然人。终端用户对其使用软件提取的文本承担全部法律责任。
### 3. 法律免责声明
本项目的开发者和贡献者：
* **不承担** 用户对该 API 或 MCP 服务器的滥用、欺诈或非法使用所产生的任何责任。
* **不承担** 因使用该软件而可能导致的 IP 地址封禁、法律行动、司法警告或 CGPJ 可能采取的任何措施的任何责任。
* 在没有任何类型的担保的情况下提供该工具（"as is"），关于其持续性、技术可用性或返回结果的准确性，如果 CENDOJ 网站修改其结构或设计，概不负责。
