Content
# Horizon MCP Server
MCP (Model Context Protocol) serveris, kas nodrošina Visma Horizon ERP REST API integrāciju ar Claude AI.
## Apraksts
Horizon MCP serveris ļauj Claude (un citiem MCP-savietojamiem AI asistentiem) tieši strādāt ar Visma Horizon ERP sistēmu — veikt vaicājumus, apskatīt un rediģēt datus, ģenerēt atskaites un pārvaldīt dokumentus, izmantojot dabiskās valodas komandas.
Serveris darbojas kā stdio-bāzēts MCP process, kas tulko AI pieprasījumus Horizon REST API izsaukumos.
## Priekšnoteikumi
- **Python 3.11+**
- **Visma Horizon** ar ieslēgtu REST API moduli
- **Claude Desktop** vai cits MCP-savietojams klients
- Python pakotnes: `mcp`, `httpx`
## Uzstādīšana
### 1. Klonē repozitoriju
```bash
git clone https://github.com/YOUR_USERNAME/horizon-mcp.git
cd horizon-mcp
```
### 2. Instalē atkarības
```bash
pip install mcp httpx
```
### 3. Konfigurē vides mainīgos
Kopē `.env.example` uz `.env` un aizpildi:
```bash
cp .env.example .env
```
```env
HORIZON_BASE_URL=http://localhost:81
HORIZON_USERNAME=lietotajs
HORIZON_PASSWORD=parole
HORIZON_AUTH_METHOD=basic
HORIZON_FORMAT=json
HORIZON_VERIFY_SSL=false
```
### 4. Konfigurē Claude Desktop
Pievieno `claude_desktop_config.json` konfigurāciju (parasti atrodas `%APPDATA%\Claude\` vai `~/.config/claude/`):
```json
{
"mcpServers": {
"horizon": {
"command": "python",
"args": ["run_server.py"],
"cwd": "C:\\cels\\uz\\horizon-mcp",
"env": {
"HORIZON_BASE_URL": "http://localhost:81",
"HORIZON_USERNAME": "lietotajs",
"HORIZON_PASSWORD": "parole",
"HORIZON_AUTH_METHOD": "basic",
"HORIZON_FORMAT": "json",
"HORIZON_VERIFY_SSL": "false"
}
}
}
}
```
### 5. Startē serveri
```bash
python run_server.py
```
## Autentifikācija
Atbalstītās metodes:
| Metode | `HORIZON_AUTH_METHOD` | Apraksts |
|---|---|---|
| HTTP Basic | `basic` | Standarta lietotājvārds/parole |
| WebUser Basic | `webuser_basic` | Horizon WebUser ar paroli |
| WebUser App | `webuser_app` | Aplikāciju autentifikācija ar HMAC parakstu |
Aplikāciju autentifikācijai papildus jānorāda `HORIZON_APP_ID` un `HORIZON_APP_SECRET`.
## Projekta struktūra
```
horizon-mcp/
├── src/horizon_mcp/
│ ├── __init__.py # Pakotnes marķieris
│ ├── __main__.py # python -m horizon_mcp ieejas punkts
│ ├── client.py # REST API klients ar autentifikāciju un sesiju pārvaldību
│ └── server.py # MCP serveris ar 30 rīkiem
├── run_server.py # Servera palaišanas skripts
├── .env.example # Vides mainīgo paraugs
├── claude_desktop_config.json # Claude Desktop konfigurācijas piemērs
└── README.md
```
## Pieejamie MCP rīki (30)
### Sistēma un autentifikācija (6 rīki)
| Rīks | Apraksts |
|---|---|
| `horizon_list_resources` | Uzskaitīt visus pieejamos API resursus pa moduļiem |
| `horizon_global_info` | Iegūt sistēmas informāciju (versija, laiks) |
| `horizon_system_info` | Iegūt uzskaites parametrus (valūta, fiskālais gads) |
| `horizon_user_info` | Iegūt autentificētā lietotāja datus |
| `horizon_list_organizations` | Uzskaitīt pieejamās organizācijas |
| `horizon_switch_organization` | Pārslēgt aktīvo organizāciju |
### Resursu izpēte (4 rīki)
| Rīks | Apraksts |
|---|---|
| `horizon_get_entity_info` | Iegūt entītijas/kolekcijas metadatus, saites un operācijas |
| `horizon_get_entity_schema` | Iegūt XSD shēmu ar lauku definīcijām un datu tipiem |
| `horizon_get_entity_wadl` | Iegūt WADL aprakstu ar HTTP operācijām un procedūrām |
| `horizon_get_document_types` | Iegūt pieejamos dokumentu tipus (veidnes) |
### Entītiju operācijas (7 rīki)
| Rīks | Apraksts |
|---|---|
| `horizon_get_entity` | Iegūt entītiju pēc primārās atslēgas (ar iespēju iekļaut hierarhiju) |
| `horizon_get_template` | Iegūt jauna ieraksta veidni ar noklusējuma vērtībām |
| `horizon_create_entity` | Izveidot jaunu entītiju no XML |
| `horizon_create_from_template` | Izveidot entītiju no veidnes |
| `horizon_update_entity` | Atjaunināt esošu entītiju (ar optimistisko bloķēšanu caur COUNTER) |
| `horizon_delete_entity` | Dzēst entītiju pēc primārās atslēgas |
| `horizon_execute_procedure` | Izpildīt procedūru (iegrāmatot, atsaukt, kopēt u.c.) |
### Kolekciju vaicājumi (4 rīki)
| Rīks | Apraksts |
|---|---|
| `horizon_query_collection` | **Galvenais datu meklēšanas rīks** — vaicājumi ar filtrēšanu, kārtošanu, kolonnām |
| `horizon_get_collection_schema` | Iegūt kolekcijas XSD shēmu ar pieejamajiem lauku nosaukumiem |
| `horizon_get_collection_criteria` | Iegūt iepriekš definētus filtru kritērijus |
| `horizon_get_collection_views` | Iegūt saglabātos skatus (kolonnu izkārtojumus) |
### Izdrukas un atskaites (2 rīki)
| Rīks | Apraksts |
|---|---|
| `horizon_list_prints` | Uzskaitīt pieejamās izdrukas/atskaites entītijai |
| `horizon_get_print` | Lejupielādēt izdruku PDF formātā |
### Pielikumi (3 rīki)
| Rīks | Apraksts |
|---|---|
| `horizon_list_attachments` | Uzskaitīt pievienotos failus |
| `horizon_get_attachment` | Lejupielādēt pielikumu |
| `horizon_upload_attachment` | Augšupielādēt jaunu pielikumu (Base64) |
| `horizon_delete_attachment` | Dzēst pielikumu |
### Datu apmaiņa un sinhronizācija (2 rīki)
| Rīks | Apraksts |
|---|---|
| `horizon_data_exchange_journal` | Piekļūt datu apmaiņas žurnālam |
| `horizon_sync_classifier` | Sinhronizēt klasifikatoru ierakstus (jauni/mainīti/visi) |
### Universālais pieprasījums (1 rīks)
| Rīks | Apraksts |
|---|---|
| `horizon_raw_request` | Izpildīt patvaļīgu REST API pieprasījumu (GET/POST/DELETE) |
## Biežāk izmantotie servisu kodi
### Norēķini (Settlements)
| Kods | Tips | Apraksts | Kolonnu prefikss |
|---|---|---|---|
| `TDdmCustomer` | Entītija | Klienta kartīte | — |
| `TDdmKlSar` | Kolekcija | Klientu saraksts | `K` |
| `TDdmKDebSar` | Kolekcija | Debitoru saraksts | `K` |
| `TDdmKredSar` | Kolekcija | Kreditoru saraksts | `K` |
| `TDdmReaKlAtlik` | Kolekcija | Klientu atlikumi (realizācija) | `K`, `K.DNV` |
### Virsgrāmata (General Ledger)
| Kods | Tips | Apraksts | Kolonnu prefikss |
|---|---|---|---|
| `TdmKonApgrSar` | Kolekcija | Kontu apgrozījumi | `KON` |
| `TdmKonApgrSarKl` | Kolekcija | Kontu apgrozījumi pa klientiem | `KON`, `KL` |
| `TdmCoKonApgrSL` | Kolekcija | VG kontu apgrozījumu kopsavilkums | — |
| `TdmGramatSL` | Kolekcija | Grāmatojumu saraksts | — |
### Banka (Bank)
| Kods | Tips | Apraksts | Kolonnu prefikss |
|---|---|---|---|
| `TDdmOutMu` | Entītija | Izejošais maksājuma uzdevums | — |
| `TDdmInMu` | Entītija | Ienākošais maksājuma uzdevums | — |
| `TDdmBankas` | Kolekcija | Banku saraksts | `B` |
| `TDRekAtlik` | Kolekcija | Bankas kontu atlikumi | `REK` |
### Kase (Cash)
| Kods | Tips | Apraksts | Kolonnu prefikss |
|---|---|---|---|
| `TDdmOutKO` | Entītija | Kases izdevumu orderis | — |
| `TDdmInKO` | Entītija | Kases ieņēmumu orderis | — |
| `TDKasAtlik` | Kolekcija | Kasu atlikumi | `REK` |
### Uzņēmums / Pavadzīmes
| Kods | Tips | Apraksts | Kolonnu prefikss |
|---|---|---|---|
| `TNdmPvzSale` | Entītija | Pārdošanas pavadzīme | — |
| `TNdmPvzSar` | Kolekcija | Pavadzīmju saraksts | `D` |
| `TdmPDok` | Entītija | Pirmdokuments | — |
| `TdmPDokList` | Kolekcija | Pirmdokumentu reģistrs | `PDOK` |
## Vaicājumu sintakse
### Kolonnu formāts
Kolonnas norāda ar punktu atdalītu prefiksu: `PREFIKSS.LAUKS`
```
K.KODS — klienta kods
K.NOSAUK — klienta nosaukums
K.DNV.SUMMA_PAR — pamatparāda summa (apakšentītija)
KON.KODS — konta kods
B.NOSAUK — bankas nosaukums
```
### Filtru sintakse
```
K.KODS eq 'BDATA' — precīza atbilstība
K.TIPS ne 3 — nav vienāds
like(K.NOSAUK,'%SIA%') — meklēšana ar aizstājējzīmēm
startswith(K.KODS,'B') — sākas ar
isnull(K.REG_NR) / not isnull(K.REG_NR) — null pārbaude
between(K.TIPS,1,3) — diapazons
K.TIPS eq 3 and like(K.NOSAUK,'%SIA%') — kombinēts filtrs
```
### Ierobežošana
```
limit=10 — atgriezt līdz 10 ierakstiem
limit=-1 — atgriezt visus ierakstus (bez ierobežojuma)
```
## Lietošanas piemēri (Claude)
Pēc konfigurēšanas Claude Desktop, var izmantot dabiskās valodas komandas:
- *"Kāds ir klientu saraksts?"* — izmanto `horizon_query_collection` ar `TDdmKlSar`
- *"Kāds ir BIG DATA SIA atlikums?"* — izmanto `TDdmReaKlAtlik` ar filtru
- *"Parādī klienta BDATA kartīti"* — izmanto `horizon_get_entity` ar `TDdmCustomer`
- *"Kādas bankas ir sistēmā?"* — izmanto `TDdmBankas` ar `B.KODS,B.NOSAUK`
- *"Izdrukā pavadzīmi nr. 4"* — izmanto `horizon_get_print` ar `TNdmPvzIn`
## Horizon REST API pamati
- **Bāzes ceļš**: `/rest`
- **Entītijas**: `/rest/{Klase}/{pk}` — CRUD operācijas ar vienu ierakstu
- **Kolekcijas**: `/rest/{Klase}/query?columns=...&filter=...` — datu vaicājumi
- **Veidnes**: `/rest/{Klase}/template/{dokTipsPk}` — jaunu ierakstu veidnes
- **Izdrukas**: `/rest/{Klase}/{pk}/print` — PDF atskaites
- **Pielikumi**: `/rest/{Klase}/{pk}/attachments` — pievienotie faili
- **Autentifikācija**: HTTP Basic vai WebUser ar HMAC parakstu
- **Sesija**: `IDHTTPSESSIONID` sīkfails, automātiska pārvaldība
- **Formāts**: JSON (noklusējums) vai XML
- **Optimistiskā bloķēšana**: `COUNTER` lauks obligāts atjaunināšanai
## Licence
MIT
