# smsOn-MCP

Serwer MCP pod API SMPP **smsOn / mobileOn** (mobileOn sp. z o.o.). Pozwala wysyłać SMS-y
i sprawdzać ich status bezpośrednio z Claude Code - bez klikania w panelu i bez własnego skryptu.

Wersja API: 1.0 (dokumentacja z 2025-08-05). Oba endpointy producenta obsługują to samo API:

- `https://smppapi.smson.pl` (domyślny)
- `https://smppapi.mobileon.pl`

## Jak to działa

Serwer to jeden plik (`index.js`), stdio, zero magii. Wystawia dwa narzędzia mapowane 1:1
na endpointy API:

| Narzędzie | Endpoint | Co robi |
| --- | --- | --- |
| `send_sms` | `POST /createShipment` | Zleca wysyłkę jednej lub wielu wiadomości |
| `get_sms_status` | `GET /getShipmentStatus` | Zwraca stan doręczenia wysyłki |

Autoryzacja: nagłówek `Authorization: Bearer <SMSON_TOKEN>`, gdzie tokenem jest login klienta.

### `send_sms`

| Parametr | Wymagany | Opis |
| --- | --- | --- |
| `messages[].msisdn` | tak | Numer w formacie międzynarodowym bez `+`, np. `48600600600` |
| `messages[].content` | tak | Treść wiadomości |
| `messages[].externalId` | nie | Własny identyfikator; domyślnie kolejny numer w tablicy |
| `sender` | nie | Identyfikator nadawcy; domyślnie `SMSON_SENDER` |
| `ttl` | nie | Ważność wiadomości, np. `1_HOUR` |
| `normalize` | nie | `true` usuwa polskie znaki z treści |
| `timestamp` | nie | Wysyłka zaplanowana, np. `2025-08-02T13:45:00` |

`transactionId` generuje serwer (UUID) - API go nie nadaje.

W odpowiedzi dostajesz `shipmentUid` **i** `transactionId` - obie wartości są potrzebne
do sprawdzenia statusu, więc warto je zachować.

### `get_sms_status`

Przyjmuje `shipmentUid` + `transactionId` z odpowiedzi `send_sms`. Zwraca listę elementów
wysyłki ze stanem (`DELIVERED` itd.), numerem odbiorcy i `externalMessageId`.

Uwaga: `system` (env `SMSON_SYSTEM`) musi być identyczny przy wysyłce i przy odpytaniu
o status - dlatego jest zmienną środowiskową, a nie parametrem narzędzia.

## Instalacja

```bash
git clone https://github.com/devsjony/smson-mcp.git
cd smson-mcp
npm install
```

Wymagany Node 18+ (wbudowany `fetch`). Testowane na Node 22.

## Podłączenie do Claude Code

```bash
claude mcp add smson -s user \
  --env SMSON_TOKEN=TWOJ_LOGIN_KLIENTA \
  --env SMSON_ENDPOINT=https://smppapi.smson.pl \
  --env SMSON_SENDER=smsOn \
  --env SMSON_SYSTEM=ClaudeMCP \
  -- node /sciezka/do/smson-mcp/index.js
```

Albo ręcznie w `~/.claude.json` (na Windows ukośniki w JSON trzeba podwoić):

```json
"smson": {
  "type": "stdio",
  "command": "node",
  "args": ["/sciezka/do/smson-mcp/index.js"],
  "env": {
    "SMSON_TOKEN": "TWOJ_LOGIN_KLIENTA",
    "SMSON_ENDPOINT": "https://smppapi.smson.pl",
    "SMSON_SENDER": "smsOn",
    "SMSON_SYSTEM": "ClaudeMCP"
  }
}
```

## Konfiguracja

Serwer czyta **wyłącznie** zmienne środowiskowe - nie ładuje żadnego pliku `.env`.
Ustaw je w konfiguracji klienta MCP (`claude mcp add --env ...`) albo w powłoce.
`.env.example` to tylko ściąga z listą zmiennych.

Wszystkie cztery są **wymagane** - serwer nie ma wbudowanych wartości domyślnych i kończy
się z kodem 1, wypisując, których brakuje.

| Zmienna | Przykład | Opis |
| --- | --- | --- |
| `SMSON_TOKEN` | `login123` | Login klienta (token Bearer) |
| `SMSON_ENDPOINT` | `https://smppapi.smson.pl` | Adres API (albo `https://smppapi.mobileon.pl`) |
| `SMSON_SENDER` | `smsOn` | Domyślny identyfikator nadawcy (można nadpisać w `send_sms`) |
| `SMSON_SYSTEM` | `ClaudeMCP` | Nazwa systemu zlecającego wysyłkę |