Skip to main content
Glama
partna-mcp

partna-mcp

Official
by partna-dev
README.md
# 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

C2.6/5.0

Scored across 9 tools

Disambiguation3/5

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.

Naming Consistency3/5

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.

Tool Count5/5

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.

Completeness4/5

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.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues