87 lines
3.9 KiB
Markdown
87 lines
3.9 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);
|
||
```
|
||
|
||
```sql
|
||
-- Diagnostika posledního běhu plánovače (run_id z planning_run)
|
||
select ems.fn_planning_run_debug(8107);
|
||
```
|
||
|
||
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`).
|
||
- **Agent skills (Cursor):**
|
||
- Vysvětlení plánu (sloty, proč nabíjí/exportuje): **[`.cursor/skills/ems-plan-explain/SKILL.md`](../.cursor/skills/ems-plan-explain/SKILL.md)** — `fn_plan_explain_bundle`.
|
||
- **Triáž bugů plánovače** (422 Infeasible, degradovaný relaxed solve, večerní export, BA81/KV1): **[`.cursor/skills/ems-planner-bug-triage/SKILL.md`](../.cursor/skills/ems-planner-bug-triage/SKILL.md)** — MCP dotazy na `solver_params.inputs`, klasifikace A–E, fix větve; SQL šablony v [`reference.md`](../.cursor/skills/ems-planner-bug-triage/reference.md).
|
||
|
||
---
|
||
|
||
## 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.
|