内容
<h1 align="center">
<img alt="MCP PJe-TJPI" src="https://raw.githubusercontent.com/fxbarros/MCP-PJe-TJPI/main/docs/assets/banner.svg?sanitize=true">
<br>
<small>案件、期限和法院文件，以自然语言呈现 - 无需在法庭上手动输入</small>
</h1>
<p align="center">
<img alt="Python" src="https://img.shields.io/badge/python-3.10+-3776AB?logo=python&logoColor=white">
<img alt="工具" src="https://img.shields.io/badge/工具-24-brightgreen">
<img alt="MCP" src="https://img.shields.io/badge/MCP-Claude%20Desktop-d97757">
<img alt="登录" src="https://img.shields.io/badge/登录-身份证%20%2B%20密码%20%2B%20TOTP自动-black">
<img alt="只读" src="https://img.shields.io/badge/PJe-只读-8b0000">
</p>
<p align="center">
<a href="#-功能特性"><strong>功能特性</strong></a>
·
<a href="#%EF%B8%8F-24种工具"><strong>工具</strong></a>
·
<a href="#-安装"><strong>安装</strong></a>
·
<a href="#-使用示例"><strong>示例</strong></a>
·
<a href="#-安全"><strong>安全</strong></a>
·
<a href="#%EF%B8%8F-重要通知"><strong>通知</strong></a>
</p>
[MCP](https://modelcontextprotocol.io) 服务器，允许Claude Desktop直接以自然语言查询皮亚韦州法院（PJe-TJPI）的**电子诉讼** - **1级和2级** - 无需手动输入。
> 🏛️ **一个MCP，两个级别**：所有工具都接受`grau`参数 - `"1"`（默认值，适用于法院）和`"2"`（适用于上诉和判决）。只需在对话中说“第二级”。
## ✨ 功能特性
- 🔐 **100%自动登录**：身份证+密码+TOTP（2FA）
- 🏛️ **支持1级和2级**（`grau`参数；案件文件分别存储在不同级别的文件夹中）
- 👤 **两种角色**：`advogado`（默认）和`procurador`（特指泰雷西纳市政府律师）
- 📋 **待处理案件**：通知、命令和期限
- ⏰ **紧急期限提醒**（3天）
- 🔍 **六种搜索方式**：案件编号、姓名、律师姓名、身份证、公司编号和律师编号
- 📄 **文档列表、阅读和下载**（HTML和PDF），包括完整案件文件
- 📝 **生产流程**：诉讼模板、保存诉讼和报告到案件文件夹
- 🛡️ **自动处理** CNJ第121/2010号决议的通知（第三方案件）
## 🛠️ 24种工具
**面板和期限**
| 工具 | 功能 |
|---|---|
| `expedientes_pendentes` | 待处理的通知/命令 |
| `verificar_prazos_urgentes` | 案件期限≤3天 |
| `pendencias_processo` | 案件的待处理事项（包括期限） |
| `expedientes_do_processo` | 案件的完整历史记录（包括通知、命令、期限和已过期事项） |
**查询和搜索**
| 工具 | 功能 |
|---|---|
| `consultar_processo` | 通过案件编号查询案件基本信息 |
| `ultimas_movimentacoes` | 查询最新动态 |
| `relatorio_processo` | 查询案件报告 |
| `buscar_por_nome_parte` / `buscar_por_nome_advogado` | 按姓名搜索 |
| `buscar_por_cpf` / `buscar_por_cnpj` / `buscar_por_oab` | 按身份证/公司编号/律师编号搜索 |
**文档和案件文件**
| 工具 | 功能 |
|---|---|
| `listar_documentos` | 列出案件所有文档 |
| `ler_documento` | 阅读文档全文（HTML或PDF） |
| `ultima_decisao` | 查询最新判决/命令 |
| `ultimo_despacho` | 查询最新命令 |
| `baixar_documento` | 下载单个文档 |
| `baixar_processo` | 下载完整案件文件 |
| `status_download` | 查看下载进度 |
| `preparar_processo` | 下载案件文件并准备分析 |
**诉讼文书（仅保存在本地磁盘，不在PJe上保存）**
| 工具 | 功能 |
|---|---|
| `listar_modelos_peticao` / `ler_modelo_peticao` | 诉讼文书模板 |
| `salvar_peticao_processo` | 保存诉讼文书到案件文件夹 |
| `salvar_relatorio_processo` | 保存案件报告到案件文件夹 |
所有工具都接受可选参数`persona`（`advogado`或`procurador`）和`grau`（`1`或`2`）。
## 🧰 需求
- macOS（项目使用Keychain存储凭证 - Linux/Windows可以使用`keyring`替代）
- Python 3.10+
- 已安装Claude Desktop
- 在PDPJ上激活账户并配置2FA（通过身份验证应用，如Google Authenticator、Microsoft Authenticator、Authy、FreeOTP等）
## 📦 安装
### 1）克隆仓库
```bash
git clone https://github.com/fxbarros/MCP-PJe-TJPI.git mcp-pje-tjpi-1g
cd mcp-pje-tjpi-1g
```
### 2）虚拟环境 + 依赖
```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
playwright install chromium
```
### 3）配置PJe的2FA（如果尚未配置）
1. 登录PJe-TJPI并点击**“配置新设备”**
2. 您将收到一封带有链接的电子邮件 - 打开它
3. 在二维码页面，**记下种子**（“无法扫描？使用此密钥”）- Base32字符串（A-Z，2-7）
4. 使用身份验证应用扫描二维码
5. 输入应用生成的代码进行验证
6. 将种子存放在**安全位置**（例如Keychain的安全笔记）
### 4）将凭证保存到Keychain
```bash
python3 setup_credenciais.py
```
该脚本会询问您的身份证、PDPJ密码和TOTP种子。所有信息都经过加密存储在macOS的Keychain中 - 绝不会存储在文件中。
### 5）快速测试（可选但推荐）
```bash
python3 -c "import keyring, pyotp; print('代码：', pyotp.TOTP(keyring.get_password('mcp-pje-tjpi', 'totp_seed')).now())"
```
如果代码与手机应用上的代码匹配，则说明一切正常。
### 6）在Claude Desktop上注册MCP
`~/Library/Application Support/Claude/claude_desktop_config.json`（调整路径）：
```json
{
"mcpServers": {
"pje-tjpi-1g": {
"command": "/Users/SEU_USUARIO/mcp-pje-tjpi-1g/venv/bin/python",
"args": ["/Users/SEU_USUARIO/mcp-pje-tjpi-1g/src/server.py"]
}
}
}
```
### 7）重启Claude Desktop
`Cmd+Q` 然后重新打开 - 工具应该会出现。
## 💬 使用示例
```
我有皮亚韦州法院第一级的待处理案件吗？
我的紧急期限是什么？
查询案件 0000000-00.0000.0.00.0000
为我生成案件 0000000-00.0000.0.00.0000 的报告
按我的律师编号 12345/PI 搜索案件
列出案件文件并阅读最新判决
下载完整案件文件并准备分析
以市政府律师的身份查询案件 0000000-00.0000.0.00.0000
查询第二级上诉 0000000-00.0000.0.00.0000
案件 0000000-00.0000.0.00.0000 有哪些待处理事项？ 包括科学和期限的日期
```
## 🏗️ 项目结构
```
mcp-pje-tjpi-1g/
├── README.md # 本文件
├── requirements.txt # Python依赖
├── setup_credenciais.py # 初始设置（运行1次）
└── src/
├── pje_client.py # Playwright客户端（PJe自动化，1级/2级）
├── cliente_singleton.py # 单例客户端（在工具调用之间保持活动）
├── pje_downloader.py # 文档/案件文件下载（+后台作业）
├── minutas.py # 诉讼文书保存
├── modelos.py # 诉讼文书模板
└── server.py # MCP服务器（向Claude公开工具）
```
## 🔒 安全
- **凭证**存储在macOS的Keychain中，绝不会存储在文件中
- **TOTP种子**作为机密处理 - 绝不会提交
- **不会在PJe上执行任何写入操作**：此MCP **仅读取**法院信息 - 绝不会提交、申请或更改任何内容（保存工具仅在本地磁盘上保存）
- **CNJ第121/2010号决议**：第三方案件查询由PJe自身记录，返回值中包含通知
## ⚠️ 重要通知
**凭证有效性** - PDPJ密码定期过期（~30天）；过期后，在网站上更改并重新运行`setup_credenciais.py`。如果重新配置2FA，旧种子将失效 - 在Keychain中更新。
**网页抓取的脆弱性** - 项目依赖于PJe-TJPI当前的HTML/JavaScript。如果法院更改布局：使用`headless=False`运行，查看哪里卡住，在DevTools中获取新的选择器并更新`pje_client.py`。
**负责任的使用** - 尊重PJe的使用条款；不要进行大规模抓取；第三方案件查询会被记录 - 专业使用并负责任。
## 🔄 适配其他法院
总体逻辑（CNJ单点登录，2FA，PJe结构）被多个法院共享。要适配：更改`PJeClient.url_base`中的主机（`pje_client.py`；已经参数化了级别），调整不同的选择器，使用DevTools查看屏幕布局，并使用`server.py`中的`FastMCP("pje-tjXX")`重命名MCP。
## 🚧 路线图
- [x] ~~为TJPI第二级创建单独的MCP~~ → 通过`grau`参数合并到此MCP（2026年7月）
- [ ] PDF数字化文档的OCR
- [ ] 听证会日程
## 📝 许可证和致谢
个人和专业使用，无担保 - 自担风险，遵守法院和客户的规则。由[Fábio Ximenes Barros](https://github.com/fxbarros)使用[Claude](https://www.anthropic.com/claude)构建，使用[Playwright](https://playwright.dev)、[PyOTP](https://pyauth.github.io/pyotp/)和[pdfplumber](https://github.com/jsvine/pdfplumber)。
<p align="center"><sub>横幅艺术：原创 - 作者MCP项目标志。</sub></p>
