# ezd-puw-mcp

MCP server dla **EZD PUW** (Elektroniczne Zarządzanie Dokumentacją — Podlaski Urząd Wojewódzki) — kompletna obsługa API systemu dokumentów administracji publicznej RP przez AI.

**91 narzędzi MCP** pokrywających 100% API EZD PUW: dokumenty, sprawy, koszulki, pracownicy, korespondencja, ePUAP, eDoręczenia, blockchain i więcej.

## Funkcjonalności

- **Koszulki i sprawy** — tworzenie, edycja, przekazywanie, udostępnianie, zamykanie, wznawianie, szukanie (16 tools)
- **Dokumenty** — rejestracja, aktualizacja, akceptacja, dodawanie treści, notatki, metadane (10 tools)
- **Korespondencja** — rejestracja wychodzącej (KOPERTA/MAIL/FAX), status, zmiany statusu (29 tools w module Api3)
- **ePUAP** — rejestracja, wyszukiwanie wpływów i wypływów
- **eDoręczenia** — rejestracja PURDE/PUH
- **Pracownicy** — CRUD, przenoszenie, szablony obiegu (8 tools)
- **Jednostki organizacyjne** — pobieranie wszystkich, po ID
- **Adresaci** — dodawanie, wyszukiwanie (Podmiot publiczny, Osoba, Instytucja, Firma)
- **RWA** — numery teczek, rejestracja spraw
- **Blockchain** — utrwalanie dokumentów
- **Migracja** — import paczek migracyjnych

## Instalacja

```bash
git clone https://github.com/gacabartosz/ezd-puw-mcp.git
cd ezd-puw-mcp
npm install
npm run build
```

## Konfiguracja Claude Desktop

Dodaj do `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "ezd-puw": {
      "command": "node",
      "args": ["/absolute/path/to/ezd-puw-mcp/dist/index.js"],
      "env": {
        "EZD_HOST": "ezd.twoj-urzad.gov.pl",
        "EZD_PORT": "443",
        "EZD_APP_TOKEN": "twoj-token-aplikacji",
        "EZD_WORKER_ID": "domyslny-id-pracownika",
        "EZD_POSITION_ID": "domyslny-id-stanowiska"
      }
    }
  }
}
```

## Konfiguracja Claude Code

Dodaj do `~/.claude/mcp.json`:

```json
{
  "mcpServers": {
    "ezd-puw": {
      "command": "node",
      "args": ["/absolute/path/to/ezd-puw-mcp/dist/index.js"],
      "env": {
        "EZD_HOST": "ezd.twoj-urzad.gov.pl",
        "EZD_PORT": "443",
        "EZD_APP_TOKEN": "twoj-token-aplikacji",
        "EZD_WORKER_ID": "domyslny-id-pracownika",
        "EZD_POSITION_ID": "domyslny-id-stanowiska"
      }
    }
  }
}
```

## Zmienne środowiskowe

| Zmienna | Opis | Domyślnie |
|---------|------|-----------|
| `EZD_HOST` | Adres serwera EZD | `localhost` |
| `EZD_PORT` | Port serwera | `443` |
| `EZD_USE_HTTPS` | Użyj HTTPS | `true` |
| `EZD_APP_TOKEN` | Token aplikacji z panelu EZD | wymagany |
| `EZD_WORKER_ID` | Domyślne ID pracownika | opcjonalne |
| `EZD_POSITION_ID` | Domyślne ID stanowiska | opcjonalne |
| `EZD_LOG_LEVEL` | Poziom logów | `info` |

## Autentykacja

EZD PUW używa autentykacji tokenowej SHA256. Na każde żądanie API serwer automatycznie:

1. Generuje unikalny GUID
2. Oblicza hash: `SHA256(GUID + APP_TOKEN + yyyyMMddhh)`
3. Dodaje nagłówki: `ezdapi-authtoken-param` i `ezdapi-authtoken`

Token aplikacji (`EZD_APP_TOKEN`) uzyskujesz z panelu administracyjnego EZD.

## Lista narzędzi (91)

### Jednostka (2)
`ezd_jednostka_get_all`, `ezd_jednostka_get_by_id`

### Instalacje (1)
`ezd_get_installations`

### Pracownik (8)
`ezd_pracownik_add`, `ezd_pracownik_get`, `ezd_pracownik_update`, `ezd_pracownik_delete`, `ezd_pracownik_get_by_unit`, `ezd_pracownik_get_all`, `ezd_pracownik_transfer`, `ezd_pracownik_get_workflow_templates`

### Koszulka (16)
`ezd_koszulka_get`, `ezd_koszulka_create`, `ezd_koszulka_update`, `ezd_koszulka_update_attributes`, `ezd_koszulka_copy`, `ezd_koszulka_folder_status`, `ezd_koszulka_list_documents`, `ezd_koszulka_list`, `ezd_koszulka_link`, `ezd_koszulka_transfer`, `ezd_koszulka_transfer_by_template`, `ezd_koszulka_share`, `ezd_koszulka_search`, `ezd_koszulka_resume`, `ezd_koszulka_close`, `ezd_koszulka_registries`

### Dokument (10)
`ezd_dokument_accept`, `ezd_dokument_update`, `ezd_dokument_add`, `ezd_dokument_set_reminder`, `ezd_dokument_get_content`, `ezd_dokument_add_note`, `ezd_dokument_location`, `ezd_dokument_get_metadata`, `ezd_dokument_get_marked`, `ezd_dokument_register`

### Api3 (29)
`ezd_api3_add_addressee`, `ezd_api3_get_addressee`, `ezd_api3_search_addressees`, `ezd_api3_update_document`, `ezd_api3_update_case`, `ezd_api3_update_inflow_metadata`, `ezd_api3_register_edoreczenia`, `ezd_api3_register_epuap`, `ezd_api3_search_epuap_inflow`, `ezd_api3_search_epuap_outflow`, `ezd_api3_get_rwa_folder_number`, `ezd_api3_create_rwa_folder_number`, `ezd_api3_delete_rwa_folder_number`, `ezd_api3_register_correspondence`, `ezd_api3_correspondence_status`, `ezd_api3_change_correspondence_status`, `ezd_api3_search_paper_outflow`, `ezd_api3_get_last_case_changes`, `ezd_api3_get_case`, `ezd_api3_list_cases`, `ezd_api3_get_inflows`, `ezd_api3_add_letter_subject`, `ezd_api3_get_letter_subjects`, `ezd_api3_register_document`, `ezd_api3_register_case`, `ezd_api3_register_inflow`, `ezd_api3_delete_case`, `ezd_api3_search_inflow_addressee`, `ezd_api3_close_case`

### Api1 (14)
`ezd_api1_update_case_attributes`, `ezd_api1_get_worker`, `ezd_api1_create_worker`, `ezd_api1_update_worker`, `ezd_api1_delete_worker`, `ezd_api1_get_workflow_templates`, `ezd_api1_create_workflow_template`, `ezd_api1_update_workflow_template`, `ezd_api1_delete_workflow_template`, `ezd_api1_transfer_case`, `ezd_api1_transfer_case_by_template`, `ezd_api1_set_form_view`, `ezd_api1_set_transfer_view`, `ezd_api1_create_case_form`

### Addin (4)
`ezd_addin_get_doc_ids_for_print`, `ezd_addin_get_attachment_for_print`, `ezd_addin_create_print_token`, `ezd_addin_create_file_edit_token`

### Blockchain (3)
`ezd_blockchain_get_last_record`, `ezd_blockchain_get_record`, `ezd_blockchain_order_immutability`

### Formularz (2)
`ezd_formularz_set_view`, `ezd_formularz_create_case_form`

### PaczkaMigracyjna (1)
`ezd_migration_import`

### RejestrSpraw (1)
`ezd_rejestr_case_metrics`

## Technologia

- TypeScript + Node.js 20+
- [Model Context Protocol SDK](https://modelcontextprotocol.io)
- Transport: stdio (JSON-RPC 2.0)
- Autentykacja: SHA256 token (per-request)

## Licencja

MIT

## Autor

Bartosz Gaca — [bartoszgaca.pl](https://bartoszgaca.pl)