79 lines
3.2 KiB
Markdown
79 lines
3.2 KiB
Markdown
# 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);
|
|
```
|
|
|
|
Měnící funkce (**`ems.fn_delete_forecast_pv_prague_calendar_day`**, **`ems.fn_rebuild_consumption_baseline_stats`**, …) MCP přes **`query` neprovede**, pokud má server jen read-only práva na DB — použij psql aplikačním účtem.
|
|
|
|
---
|
|
|
|
## 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.
|