Pohoda MCP

Máy chủ MCP cho phần mềm kế toán Pohoda (tiếng Séc) - đọc và tạo hóa đơn, đơn hàng, hàng tồn kho, danh bạ qua mServer XML API.

GitHub

Dùng thử MCP nàyĐược tài trợ

Tài liệu

Pohoda MCP Server

MCP server pro účetní software Pohoda od Stormware. Komunikuje s Pohodou přes mServer XML API.

Propojte svého AI asistenta přímo s účetnictvím. Ptejte se na faktury, procházejte adresář, kontrolujte zásoby, vytvářejte nové doklady nebo si nechte vytisknout fakturu do PDF. Stačí napsat, co potřebujete, a MCP server se postará o komunikaci s Pohodou.

Požadavky

PHP 8.1+
ext-curl, ext-dom, ext-simplexml
Pohoda s aktivním mServerem (schéma verze 2)

Nastavení mServeru v Pohodě

Před použitím MCP serveru je potřeba v Pohodě zapnout a nakonfigurovat mServer.

1. Otevření správy mServeru

V programu Pohoda otevřete agendu Účetní jednotky, v menu zvolte Databáze > POHODA mServer.

2. Správa konfigurací

Otevře se dialogové okno se seznamem konfigurací mServeru. Pro každou konfiguraci je uveden název, port, stav spuštění, host a PID.

3. Vytvoření nové instance

Klikněte na Nový a na záložce Základní nastavte:

Název mServeru
Účetní jednotku, se kterou bude mServer komunikovat
Port pro komunikaci (výchozí 444)

Na záložce HTTPS lze zapnout zabezpečenou komunikaci:

Na záložce Monitoring lze zapnout logování komunikace:

4. Spuštění

Vyberte konfiguraci a klikněte na Spustit (nebo dvakrát klikněte na záznam). mServer začne naslouchat na nastaveném portu.

Alternativně lze mServer ovládat z příkazové řádky pomocí přepínače /HTTP nad pohoda.exe. Jako poslední parametr se uvádí název konfigurace (v uvozovkách, pokud obsahuje mezery):

& "C:\Program Files (x86)\STORMWARE\POHODA\Pohoda.exe" /HTTP start "eShop-1"
& "C:\Program Files (x86)\STORMWARE\POHODA\Pohoda.exe" /HTTP stop "eShop-1"
& "C:\Program Files (x86)\STORMWARE\POHODA\Pohoda.exe" /HTTP restart "eShop-1"
& "C:\Program Files (x86)\STORMWARE\POHODA\Pohoda.exe" /HTTP list

Další příkazy: stop /f (vynucené ukončení), list:xml (výpis konfigurací do XML). Pro automatické spuštění při startu systému Stormware doporučuje Plánovač úloh Windows (ne Windows službu).

Podrobnosti viz dokumentace Stormware.

Instalace MCP serveru

git clone https://github.com/dg/pohoda-mcp.git
cd pohoda-mcp
composer install

Konfigurace

Server se konfiguruje přes proměnné prostředí:

Proměnná	Popis	Výchozí
`POHODA_URL`	URL mServeru	`http://localhost:444`
`POHODA_ICO`	ICO účetní jednotky
`POHODA_USERNAME`	Uživatelské jméno pro mServer
`POHODA_PASSWORD`	Heslo
`POHODA_EXE_PATH`	Cesta k `Pohoda.exe` pro autostart mServeru (volitelné)
`POHODA_CONFIG_NAME`	Název konfigurace mServeru pro autostart (volitelné)

Pokud jsou nastaveny POHODA_EXE_PATH a POHODA_CONFIG_NAME, server před prvním tool callem ověří, že mServer běží — pokud ne, sám ho spustí přes pohoda.exe /HTTP start. Při ukončení MCP serveru ho zase zastaví, ale jen pokud ho sám startoval (pokud mServer už běžel, necháme ho běžet). Windows-only (mServer je součást Pohody).

Použití v agentech (např. Claude Code)

Přidejte do .mcp.json nebo do project settings:

{
    "mcpServers": {
        "pohoda": {
            "command": "php",
            "args": ["/cesta/k/pohoda-mcp/server.php"],
            "env": {
                "POHODA_URL": "http://localhost:444",
                "POHODA_ICO": "12345678",
                "POHODA_USERNAME": "Admin",
                "POHODA_PASSWORD": "",
                "POHODA_EXE_PATH": "C:\\Program Files (x86)\\STORMWARE\\POHODA\\Pohoda.exe",
                "POHODA_CONFIG_NAME": "mServer1"
            }
        }
    }
}

Poslední dvě proměnné jsou volitelné — slouží k automatickému spuštění mServeru při prvním tool callu (viz výše).

Dostupné nástroje

status

Ověří, jestli mServer běží a odpovídá. Základní volání vrací pouze stručný text z GET /status (Pohoda odpovídá prostým stringem, ne XML). S parametrem companyDetail=true navíc přes autentizovaný dotaz vrátí název účetní jednotky, název databáze a aktuální účetní rok.

Parametr	Popis
`companyDetail`	`true` / `false` — vrátit i údaje o aktivní účetní jednotce (default `false`)

list_documents, list_stock, list_contacts

Tři čtecí nástroje rozdělené podle druhu záznamu. Niche/číselníkové agendy (centre, activity, store, bankAccount, cashRegister, numericalSeries) nejsou dostupné přes dedikovaný tool, použij raw_xml.

list_documents

Doklady. Parametr agenda — jedna z následujících:

Agenda	Popis	Agenda	Popis
`invoice`	faktury*	`prijemka`	příjemky
`order`	objednávky	`vydejka`	výdejky
`voucher`	pokladní doklady	`prodejka`	prodejky
`bank`	banka	`prevodka`	převodky
`contract`	zakázky	`vyroba`	výroba
`intDoc`	interní doklady	`accountancy`	účetní deník
`offer`	nabídky
`enquiry`	poptávky

* Agenda invoice vyžaduje parametr invoiceType: issuedInvoice nebo receivedInvoice.

Filtry: id, dateFrom, dateTill, company, ico, number (přesná shoda celé hodnoty, ne substring), lastChanges (záznamy změněné od YYYY-MM-DDThh:mm:ss), limit (default 100, klientský ořez).

list_stock

Zásoby. Filtry: id, code, name, EAN, storage (cesta ve členění skladu, např. "ZBOZI/Elektro"), store (zkratka skladu), internet (true/false), lastChanges, limit.

list_contacts

Adresář. Filtry: id, company, ico, lastChanges, limit.

create_invoice

Vytvoření vydané nebo přijaté faktury. Podporuje:

adresu partnera přímo nebo vazbu na adresář (partnerId)
variabilní symbol, datum splatnosti, datum zdanitelného plnění
předkontaci, způsob platby, bankovní účet
středisko, činnost, zakázku
cizí měnu s kurzem
položky s vazbou na skladovou kartu (stockCode)

create_address

Vytvoření záznamu v adresáři (firma/kontakt).

create_stock

Vytvoření skladové karty. Kromě základních údajů (kód, název, cena) podporuje:

EAN, PLU pro pokladny
příznaky pro prodej a e-shop
popis, doplněk názvu, krátký název
minimální a maximální zásobu, hmotnost
dodavatele, záruku

create_order

Vytvoření přijaté nebo vydané objednávky s položkami.

print

Tisk nebo export do PDF libovolného záznamu. Umí:

tisk na tiskárnu (výchozí nebo konkrétní)
export do PDF souboru na serveru (pdfPath je povinný pro PDF cestu)
vrácení PDF jako Base64 přímo v odpovědi (pdfBase64=true, vyžaduje pdfPath)

Agenda se zadává česky: vydane_faktury, prijate_faktury, zasoby, adresar, pokladna, banka, interni_doklady, zakazky, vydejky, prijemky, prodejky, vydane_objednavky, prijate_objednavky, vydane_nabidky, prijate_nabidky atd.

ID tiskové sestavy (reportId) se liší podle instalace a vlastních úprav. V Pohodě ho zjistíte v Editoru tiskových sestav (menu Soubor → Tiskové sestavy), kde u každé sestavy vidíte sloupec ID, nebo přes pravé tlačítko myši na sestavě v dialogu tisku → Vlastnosti. Standardní dodávané sestavy mají ID v řádech stovek až tisíců (typicky 200–3000+).

raw_xml

Odeslání libovolného XML. Pokrývá případy, na které ostatní nástroje nestačí. XML se vloží přímo do <dat:dataPackItem> obálky, musí tedy obsahovat vlastní namespace deklarace.

Referenční zdroje (MCP resources)

Číselníky povolených hodnot jsou vystavené jako MCP resources, takže si je klient může vyzvednout bez tool callu:

URI	Obsah
`pohoda://enums/agendas`	seznam agend rozdělený podle toho, který list tool je pokrývá
`pohoda://enums/vat-rates`	povolené hodnoty `vatRate` u položek (`none`, `low`, `high`)
`pohoda://enums/payment-types`	hodnoty `paymentType` faktur (`draft`, `cash`, `card`, `compensation`)
`pohoda://enums/print-agendas`	české názvy agend přijímané `print`

Použití z PHP kódu (bez MCP)

Knihovnu lze použít i přímo jako PHP klienta pro mServer, nezávisle na MCP. Hodí se pro vlastní skripty, cronjoby nebo integraci do existující aplikace.

use DG\Pohoda\PohodaClient;

$client = new PohodaClient(
    url: 'http://localhost:444',
    ico: '12345678',
    username: 'Admin',
    password: '',
);

// Najdi fakturu podle čísla dokladu
$list = $client->listRecords('invoice', ['number' => '26010192'], 'issuedInvoice');
$faId = (int) $list->items[0]->data['invoice'][0]['invoiceHeader']['id'];

// Vytiskni ji do PDF
$client->printRecord([
    'agenda' => 'vydane_faktury',
    'recordId' => $faId,
    'reportId' => 3000,
    'pdfPath' => 'C:\\tmp\\faktura.pdf',
]);

Veřejné metody PohodaClient: getStatus(), listRecords(), createInvoice(), createAddress(), createStock(), createOrder(), printRecord(), sendRawXml().

Spouštění a zastavování mServeru

Pokud skript nemůže předpokládat, že je mServer už spuštěný, hodí se třída MServerController. Je to tenký obal nad pohoda.exe /HTTP start|stop, který spouští Pohodu non-blocking a po startu polluje PohodaClient::getStatus(), dokud mServer nezačne odpovídat. Windows-only.

Nejjednodušší cesta je předat ho PohodaClient u — ten si pak sám lazy nastartuje mServer před prvním HTTP requestem a při destrukci ho zase zastaví (jen pokud ho sám startoval; pokud už běžel, necháme ho běžet):

use DG\Pohoda\MServerController;
use DG\Pohoda\PohodaClient;

$client = new PohodaClient(url: 'http://127.0.0.1:555', ico: '12345678', username: 'Admin', password: '');
$client->setController(new MServerController(
    exePath: 'C:\Program Files (x86)\STORMWARE\POHODA\Pohoda.exe',
    configName: 'mServer1',
));

// ... práce s $client — autostart se postará o sebe ...

Pokud chceš lifecycle řídit ručně, controller umí stejné věci přímo:

$ctrl = new MServerController(exePath: '...', configName: 'mServer1');

$wasRunning = false;
try {
    $client->getStatus();
    $wasRunning = true;
} catch (\RuntimeException) {
    $ctrl->start($client);  // vrátí se až když mServer odpovídá (nebo vyhodí po timeoutu)
}

// ... práce s $client ...

if (!$wasRunning) {
    $ctrl->stop();
}

Při volání HTTP endpointů používej http://127.0.0.1:555, ne http://localhost:555 — PHP resolver zkouší pro localhost nejdřív IPv6 (::1), kam mServer nenaslouchá, a čeká se zbytečně na timeout.

Veřejné metody MServerController:

start(PohodaClient $client, int $timeoutSeconds = 30) — spustí Pohodu s /HTTP start, čeká až HTTP status API odpoví. Při timeoutu vyhodí RuntimeException.
stop() — pošle /HTTP stop fire-and-forget, nečeká na ukončení.

Řešení problémů

Symptom	Pravděpodobná příčina
`Curl Error: Connection refused`	mServer neběží; spusť ho v Pohodě nebo přes `pohoda.exe /HTTP start`
`HTTP 401`	Chybné `POHODA_USERNAME` / `POHODA_PASSWORD`
Odpověď je HTML s přihlašovací stránkou	Uživatel v Pohodě nemá práva na mServer nebo je agenda otevřená jinou instancí
`state="error"` + `note="Nepodařila se validace dokumentu podle schématu"`	Špatná struktura XML — typicky zaměněný namespace nebo chybějící povinný element; text chyby ukazuje na element
`listRecords` vrací prázdný seznam	mServer je připojený na jinou účetní jednotku/rok, než kde doklad žije (zkontroluj `status` s `companyDetail=true`)
`pdfPath` je vytvořen, ale nejde otevřít (0 B)	mServer nemá práva zapisovat na dané místo — zkus výchozí `D:\Data\ucto\Tisk\` nebo dočasný adresář uživatele, pod kterým Pohoda běží
`Print` vrací OK, ale PDF nevzniká	`reportId` neexistuje v instalaci; ověř ID v Editoru tiskových sestav

Struktura projektu

server.php                 vstupní bod MCP serveru (stdio transport)
src/
    McpTools.php             tenký MCP adaptér (#[McpTool] atributy)
    PohodaClient.php         HTTP klient a doménové metody pro mServer API
    XmlBuilder.php           stavba XML požadavků přes XMLWriter
    Response.php             parsovaná odpověď z mServeru
    ResponseItem.php         jeden záznam z odpovědi
    MServerController.php    spouštění a zastavování mServeru přes pohoda.exe