内容
# COMPRASAL MCP
直接从您的AI助手查询 **萨尔瓦多公共采购数据**。
这是一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，封装了公共COMPRASAL API（`comprasal.gob.sv`）——该国的电子公共采购系统——这样您就可以询问Claude（或任何MCP客户端）诸如：
> *"2025年卫生部颁发了什么，金额是多少？*"
> *"给我展示最新的公共合同及其供应商。*"
> *"拉取流程83743的完整详细信息和阶段日历。*"
所有数据都是国家根据LACAP采购法发布的公共信息。该服务器是**只读**的。
---
## 您可以使用以下工具
连接后，您的助手将获得以下工具：
| 工具 | 功能 |
|------|--------------|
| `search_procurement` | 按机构、年份、方式或自由文本搜索已授予的流程。返回供应商、金额、日期、代码。 |
| `get_process_detail` | 一个流程的完整详细信息：金额、日期和完整的阶段日历。 |
| `get_award_report` | 丰富的视图：投标人、计划 vs 认证金额、预算代码、签名日期。 |
| `get_supplier_contracts` | 供应商的公共部门记录：按公司名称划分的已赢合同（有界近期扫描）。 |
| `list_institutions` | 将机构名称（例如“salud”）解析为其ID。 |
| `list_modalities` / `list_states` / `list_years` | 用于构建精确筛选的目录。 |
---
## 安装
需要 [Node.js](https://nodejs.org) 18+。
```bash
git clone https://github.com/glassbit/comprasal-mcp.git
cd comprasal-mcp
npm install
npm run build
npm test
```
## 连接到 Cursor
此仓库自带一个项目级MCP配置，位于 `.cursor/mcp.json`。在 `npm run build` 之后：
1. 在Cursor中打开此文件夹。
2. 进入 **设置 → MCP** 并启用 **comprasal** 服务器（或重启Cursor）。
3. 助手可以在代理模式下调用COMPRASAL工具。
该配置运行 `node dist/index.js` 对抗实时COMPRASAL API（默认关闭缓存）。要全局覆盖，请将相同的块添加到您的用户MCP设置中。
## 连接到 Claude Desktop
将以下内容添加到您的 `claude_desktop_config.json`：
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"comprasal": {
"command": "node",
"args": ["/absolute/path/to/comprasal-mcp/dist/index.js"]
}
}
}
```
重启Claude Desktop。您将看到COMPRASAL工具可用。询问它关于萨尔瓦多的公共支出。
---
## 本地缓存（可选）
默认情况下，每个请求都发送到实时COMPRASAL API - 一个全新的克隆对于每个人来说都是相同的。您可以选择使用**本地、每用户**的响应缓存来加快会话中重复查询的速度：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `COMPRASAL_CACHE_ENABLED` | `false` | 设置为 `true` 以在磁盘上缓存原始API响应 |
| `COMPRASAL_CACHE_DIR` | `.comprasal-cache` | 缓存目录（gitignored，永不提交） |
| `COMPRASAL_CACHE_TTL_MS` | `3600000` （1小时） | 条目生命周期；过期条目在读取时被删除 |
缓存是**不是**共享或提交的数据库 - 它在运行时在您的机器上创建。TTL过期后，下一个请求将再次获取实时数据。随时使用 `COMPRASAL_CACHE_ENABLED=false` 禁用它。
---
## 测试
```bash
npm test # 单元测试 + 模拟集成测试（无网络）
npm run test:live # 可选的实时测试与真实的COMPRASAL API（~7s）
```
测试涵盖客户端过滤器、Zod参数验证、文件缓存行为和模拟HTTP流程。
---
## 注意事项和限制
**上游政府API仅按机构可靠过滤。** 这是关于此工具最重要的事情：
- `id_institucion` 是**唯一**服务器端过滤器有效。年份、自由文本搜索和日期范围被 **静默忽略** 由COMPRASAL后端。
- 该服务器通过过滤 **客户端** （在实际授予日期 `fecha_adjudicacion` 和文本字段上），扫描最新页面的最新记录直到有界限。
- **后果：** 深入的历史查询不实用。询问“供应商X自2025年1月以来所有合同”或“机构Y在2024年”可能需要扫描数千条记录，速度约为7秒/页 - 因此这些工具返回 **有界近期窗口** 并在 `coverage` / `filtering` 块中明确说明。 有界结果永远不会被呈现为详尽的。
- **后端延迟约为7秒每请求** （这是政府服务器，不是MCP）。 工具每次请求一个页面，最多扫描几页，因此调用可能需要10-50秒。
- `get_supplier_contracts` 无法按供应商上游过滤，因此它扫描最近的全局记录并在本地匹配。 当您知道 `id_institucion` 时请传递它 - 扫描变得更快更深入。
- **日期过滤器** 在此服务器上适用于授予日期 (`fecha_adjudicacion`)，即使原始上游API过滤的是流程开始日期。
- `get_award_report` 使用的ID与端点不同（已知的上游怪癖）。 除非您特别需要投标人/预算明细，否则请优先使用 `get_process_detail`。
- 数据集包含约10万+已授予流程，截至2026年。 每个流程可能作为几行出现（每个批次/供应商一行）。
- 工具参数在调用上游之前使用 **Zod** 验证；无效输入返回一个清晰的错误，不会击中API。
### 为什么没有本地数据库/提交缓存？
此服务器查询 **实时** 公共API，以便 **任何克隆它的人都能得到相同的结果，无需设置** - 没有预先抓取的数据集，没有存储库中的共享状态。 提交的数据库意味着要么托管一个中央服务器（破坏了“自己运行”模型），要么要求每个用户首先抓取COMPRASAL（数小时的工作）。
一个 **可选的、选择加入的文件缓存** 可用于方便：它位于 `.comprasal-cache/` 仅在您的机器上（gitignored），1小时后过期，**默认关闭**。 它不会改变全新克隆第一次运行时返回的内容。 用于深度历史分析的完整本地数据库变体仍然是一个可能的独立、选择加入项目。
## 数据、来源和合法性
数据来自公共COMPRASAL门户（`comprasal.gob.sv`），通过其公共、无身份验证的REST API访问。 根据 **LACAP** （公共行政机构采购和合同法），公共采购行为是公开的。 公共登记册被排除在萨尔瓦多个人数据保护法（Decreto 144，2024，第三条）的范围之外。 本项目出于透明度和研究目的重新分发已经公开的信息，不对任何经过身份验证的区域进行抓取。
## 许可证
MIT。 不隶属于或得到萨尔瓦多政府的认可。
