partna-mcp
Official# partna-mcp
MCP-сервер партнёрской программы Partna: агент заводит участников, сообщает об
оплатах и возвратах, выдаёт ссылки партнёрам и читает сводку. Деньги через сервер
не проходят: он только передаёт факты и читает цифры.
Обзор, установка и глоссарий — в документации: https://partna.dev/docs/
## Что внутри
Пакет с портом и адаптерами:
```
MCP-инструменты
│
▼
порт PartnerApi — операции повторяют сервисные функции ядра
├── HttpBackend — по публичному контракту фактов (этот пакет)
└── LocalBackend — в закрытом репозитории ядра, вызывает use cases
```
Инструменты не знают, куда именно они ходят: `PARTNA_BACKEND=http` говорит с
мостом или ядром по HTTP. Локальный адаптер ставится отдельно и доступен только
там, где есть доступ к базе.
## Инструменты
| Инструмент | Что делает |
|---|---|
| `status` | доступность сервиса, режим, задан ли ключ |
| `partner_link` | ссылка партнёра для его клиентов |
| `claim` | привязать клиента к коду партнёра |
| `member` | участник программы и от кого пришёл |
| `order` | клиент оплатил |
| `refund` | клиенту вернули деньги |
| `referral_status` | привязан ли клиент и к какому коду |
| `dashboard` | сводка партнёра |
| `payouts` | история выплат |
Пишущие инструменты принимают `dry_run`: он показывает тело запроса и ничего не
отправляет.
## Запуск
```bash
export PARTNA_BRIDGE_URL=https://partna.client.com
export PARTNA_BRIDGE_TOKEN=... # токен моста, если он задан
export PARTNA_ENGINE_URL=https://networks.partna.dev
export PARTNA_API_KEY=... # ключ тенанта для чтения
uvx partna-mcp
```
Транспорт — stdio. Подключение в клиенте:
```json
{
"mcpServers": {
"partna": {
"command": "uvx",
"args": ["partna-mcp"],
"env": {
"PARTNA_BRIDGE_URL": "https://partna.client.com",
"PARTNA_ENGINE_URL": "https://networks.partna.dev",
"PARTNA_API_KEY": "..."
}
}
}
}
```
Если моста нет, задайте только `PARTNA_ENGINE_URL` и `PARTNA_API_KEY`: факты
пойдут прямо в ядро его путями.
## Правила
- `eventId` уникален навсегда: один факт — один идентификатор, повтор не должен
давать второе начисление.
- Ключи берутся только из окружения; инструменты не принимают их аргументами и
не печатают в ответах.
- Ошибки возвращаются текстом сервиса без стеков и без секретов.
## Контракт
Пять операций описаны в
[partna-bridge/spec](https://github.com/partna-dev/partna-bridge/blob/main/spec/README.md).
Golden-кейсы лежат в пакете (`src/partna_mcp/golden/`) и доступны через
`partna_mcp.golden.load_cases()` — общий эталон для HTTP- и локального адаптера:
одинаковый вход должен давать одинаковый ответ.
## Лицензия
MIT — см. [LICENSE](LICENSE).
TDQS
Scored across 9 tools
Most tools target distinct actions or resources, but claim, member, and referral_status all touch client-to-partner attribution and could be confused without reading descriptions closely. partner_link, order, refund, dashboard, and payouts are clearer.
All names are lowercase snake_case or single words, which is readable, but the set mixes nouns (member, dashboard), actions (claim, refund), and event-like names (order), without a predictable verb_noun convention.
Nine tools is well-scoped for a partner/referral program integration. Each tool appears to cover a meaningful operation or query without excessive surface area.
The surface covers service status, partner links, attribution, orders, refunds, referral status, dashboard summaries, and payout history. Minor gaps may exist around listing/managing members or payouts, but core lifecycle operations are represented.