# MCP: read-only dotazy na EMS PostgreSQL

Tento dokument je **jednotný návod pro AI agenty i lidi**. Když v projektu napíšeš **„použij MCP“** (nebo chceš živá data z EMS DB), postupuj přesně tady — **bez hádání názvů serverů** a **bez odmítání bez vyzkoušení**.

---

## 1. Který MCP server

| Co | Hodnota |
|----|-----------|
| **Identifikátor pro volání nástroje** (např. Cursor `call_mcp_tool`) | `user-postgres-ems` |
| **Zobrazovaný název** v Cursor Settings | často `postgres-ems` |
| **Konfigurace** | uživatelský `~/.cursor/mcp.json` (ne je v gitu) — spojení na konkrétní host/DB |

**Důležité:** v UI se může jmenovat `postgres-ems`, ale **programové volání** používá **`user-postgres-ems`**. Oba označují **stejný** server.

---

## 2. Který nástroj a parametry

| Položka | Hodnota |
|---------|---------|
| **Nástroj** | `query` |
| **Argument** | JSON: `{ "sql": "<jeden read-only SELECT>" }` |
| **Omezení** | jen **SELECT** (read-only server); žádné `INSERT`/`UPDATE`/`DELETE` |

Schéma argumentů (pro ověření): v Cursor profilu cesta typu  
`.cursor/projects/<název-projektu>/mcps/user-postgres-ems/tools/query.json`  
(soubor se objeví po povolení MCP serveru v Cursoru).

---

## 3. Povinné chování agenta

1. **Nejdřív zavolej** MCP `query` — **nepiš**, že „se tam stejně nepřipojíš“ nebo že MCP „neexistuje“**, dokud** volání **nepadne** s reálnou chybou.
2. Používej server **`user-postgres-ems`** a nástroj **`query`** — **nevymýšlej** varianty jako `postgres-ems` jako *server parameter*, pokud tvoje rozhraní výslovně nevyžaduje jiný identifikátor (v Cursor agent API je to typicky **`user-postgres-ems`**).
3. **Při úspěchu** — stručně shrň výsledek (tabulka / fakta), případně navazuj dalšími SELECTy.
4. **Při selhání** (timeout, connection refused, auth) — uveď přesnou chybu a **konkrétní** kroky: VPN / dostupnost hosta z prostředí kde MCP běží, že je v Cursoru zapnutý server `postgres-ems`, že uživatel má běžící Postgres.

---

## 4. Příklady dotazů (kopírovatelné)

```sql
select current_database() as db, current_timestamp as ts;
```

```sql
select id, code, name, active from ems.site order by id;
```

```sql
select pr.id, pr.site_id, pr.run_type, pr.status, pr.horizon_start, pr.horizon_end, pr.created_at
from ems.planning_run pr
where pr.status = 'active'
order by pr.created_at desc
limit 10;
```

```sql
select ems.fn_plan_explain_bundle(2, 6);
```

---

## 5. Odkud to vychází v repozitáři

- Stručná návěstí také v **[`../CLAUDE.md`](../CLAUDE.md)** (sekce MCP + tabulka „Kde hledat co“).
- Trvalé pravidlo pro agenta: **[`../.cursor/rules/mcp-postgres-ems.mdc`](../.cursor/rules/mcp-postgres-ems.mdc)** (`alwaysApply: true`).

---

## 6. Bezpečnost

- V dotazech **nevypisuj** connection stringy ani hesla z `mcp.json`.
- MCP je určený k **diagnostice a reportingu**; měnící operace přes aplikaci (API, migrace), ne přes read-only MCP.