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í:

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.

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 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:

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 PohodaClientu — 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ů

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

Licence

MIT