Content
# COMPRASAL MCP
Query **El Salvador's public procurement data** straight from your AI assistant.
This is a [Model Context Protocol](https://modelcontextprotocol.io) server that wraps the public COMPRASAL API (`comprasal.gob.sv`) — the country's electronic public-purchasing system — so you can ask Claude (or any MCP client) things like:
> *"What did the Ministry of Health award in 2025, and for how much?"*
> *"Show me the latest public contracts and their suppliers."*
> *"Pull the full detail and stage calendar for process 83743."*
All data is public information published by the State under the LACAP procurement law. This server is **read-only**.
---
## What you can ask
Once connected, your assistant gains these tools:
| Tool | What it does |
|------|--------------|
| `search_procurement` | Search awarded processes by institution, year, modality, or free text. Returns supplier, amount, dates, code. |
| `get_process_detail` | Full detail of one process: amounts, dates, and the complete stage calendar. |
| `get_award_report` | Richest view: bidders, planned vs certified amounts, budget codes, signature date. |
| `get_supplier_contracts` | A supplier's public-sector track record: contracts won, by company name (bounded recent scan). |
| `list_institutions` | Resolve an institution name (e.g. "salud") into its id. |
| `list_modalities` / `list_states` / `list_years` | Catalogs for building precise filters. |
---
## Install
Requires [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
```
## Connect to Cursor
This repo ships a project-level MCP config at `.cursor/mcp.json`. After `npm run build`:
1. Open this folder in Cursor.
2. Go to **Settings → MCP** and enable the **comprasal** server (or restart Cursor).
3. The assistant can call the COMPRASAL tools in Agent mode.
The config runs `node dist/index.js` against the live COMPRASAL API (cache off by default). To override globally, add the same block to your user MCP settings.
## Connect to Claude Desktop
Add this to your `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"]
}
}
}
```
Restart Claude Desktop. You'll see the COMPRASAL tools available. Ask it about El Salvador's public spending.
---
## Local cache (opt-in)
By default every request goes to the live COMPRASAL API — a fresh clone behaves identically for everyone. You may opt in to a **local, per-user** response cache to speed up repeated queries within a session:
| Variable | Default | Description |
|----------|---------|-------------|
| `COMPRASAL_CACHE_ENABLED` | `false` | Set to `true` to cache raw API responses on disk |
| `COMPRASAL_CACHE_DIR` | `.comprasal-cache` | Cache directory (gitignored, never committed) |
| `COMPRASAL_CACHE_TTL_MS` | `3600000` (1 hour) | Entry lifetime; expired entries are deleted on read |
The cache is **not** a shared or committed database — it is created at runtime on your machine only. After TTL expiry, the next request fetches live data again. Disable it anytime with `COMPRASAL_CACHE_ENABLED=false`.
---
## Tests
```bash
npm test # unit + mocked integration only (no network)
npm run test:live # optional smoke test against real COMPRASAL API (~7s)
```
Tests cover client-side filters, Zod argument validation, file cache behaviour, and mocked HTTP flows.
---
## Notes & caveats
**The upstream government API only filters reliably by institution.** This is the single most important thing to understand about this tool:
- `id_institucion` is the **only** server-side filter that works. Year, free-text search, and date range are **silently ignored** by the COMPRASAL backend.
- This server compensates by filtering **client-side** (over the real award date `fecha_adjudicacion` and text fields), scanning newest-first pages up to a bounded limit.
- **Consequence:** deep historical queries are not practical. Asking for "all contracts from supplier X since January 2025" or "institution Y in 2024" can require scanning thousands of records at ~7s/page — so those tools return a **bounded recent window** and clearly say so in a `coverage` / `filtering` block. A bounded result is never presented as exhaustive.
- **Backend latency is ~7s per request** (this is the government server, not the MCP). Tools make one request per page and cap how many pages they scan, so a call may take 10-50s.
- `get_supplier_contracts` cannot filter by supplier upstream, so it scans the most-recent global records and matches locally. Pass `id_institucion` when you know it — the scan becomes far faster and deeper.
- **Date filters** apply to the award date (`fecha_adjudicacion`) in this server, even though the raw upstream API filters on the process start date.
- `get_award_report` uses a different id than the other endpoints (a known upstream quirk). Prefer `get_process_detail` unless you specifically need the bidder/budget breakdown.
- The dataset holds ~100k+ awarded processes, current through 2026. Each process may appear as several rows (one per lot/supplier).
- Tool arguments are validated with **Zod** before any upstream call; invalid inputs return a clear error without hitting the API.
### Why no local database / committed cache?
This server queries the **live** public API so that **anyone who clones it gets identical results with zero setup** — no pre-scraped dataset, no shared state in the repo. A committed database would mean either hosting a central server (defeating the "run it yourself" model) or asking every user to scrape COMPRASAL first (hours of work).
An **optional, opt-in file cache** is available for convenience: it lives in `.comprasal-cache/` on your machine only (gitignored), expires after 1 hour, and is **off by default**. It does not change what a fresh clone returns on first run. A full local-database variant for deep historical analysis remains a possible separate, opt-in project.
## Data, source & legality
Data comes from the public COMPRASAL portal (`comprasal.gob.sv`), accessed through its public, unauthenticated REST API. Public procurement acts are public by law under the **LACAP** (Ley de Adquisiciones y Contrataciones de la Administración Pública). Public registries are excluded from the scope of El Salvador's Personal Data Protection Law (Decreto 144, 2024, art. 3). This project redistributes already-public information for transparency and research purposes and performs no scraping of authenticated areas.
## License
MIT. Not affiliated with or endorsed by the Government of El Salvador.
