MCP сервер және SKILL.md: ЖИ-агентке арналған Qut Pay

ЖИ-агентке (Claude Code, Cursor, Windsurf, Claude Desktop, VS Code Copilot, ChatGPT) Qut Pay-мен құжаттаманы қолмен көшірмей жұмыс істеудің екі жолы:

Не	Не үшін	Адрес
SKILL.md	Агент дағдысы: «Kaspi-ді Qut Pay арқылы қалай қосу керек» деген қысқа нұсқаулық, егжей-тегжейге сілтемелермен. Тапсырма төлем туралы болса, агент оны өзі оқиды	https://api.qut.kz/SKILL.md
MCP сервер `@qutpay/mcp`	Агент құралдары: счёт құру, күйін тексеру, қайтару, sandbox-та төлемді имитациялау — сіздің API кілтіңізбен	`npx -y @qutpay/mcp`

Екеуі де сайттағы кодыңызды алмастырмайды: өндірісте счётты сіздің серверіңіз құрады, растау webhook арқылы келеді. MCP агентке интеграцияны тексеруге және операцияларға көмектесуге керек; SKILL.md — оны дұрыс жазуға.

1. SKILL.md

Пішімі — Agent Skills: qutpay/ қалтасында SKILL.md файлы (frontmatter name, description + нұсқаулық) және references/ қалтасы (webhook қолтаңбасын Node/PHP/Python-да тексеру, қате кодтары мен шектер).

Claude Code-қа орнату (тапсырма Kaspi төлемі туралы болса, дағды өзі қосылады):

mkdir -p .claude/skills/qutpay/references
curl -sSL https://api.qut.kz/SKILL.md -o .claude/skills/qutpay/SKILL.md
curl -sSL https://api.qut.kz/skill/references/webhook-verify.md -o .claude/skills/qutpay/references/webhook-verify.md
curl -sSL https://api.qut.kz/skill/references/errors.md -o .claude/skills/qutpay/references/errors.md

Дайын қалта ашық репозиторийде де бар: https://github.com/kazprose/qutpay-docs ішіндегі skills/qutpay/. Claude.ai-да дағды осы қалтаның zip-і ретінде жүктеледі (Settings → Capabilities → Skills).

Орнатусыз: агентке https://api.qut.kz/SKILL.md сілтемесін беріңіз — ол кәдімгі бет ретінде оқиды. Кабинеттен (Интеграциялар → «ЖИ-агент») ұйымыңыздың атауы мен ағымдағы режимі қойылған нұсқасы көшіріледі.

Ішінде: интеграцияның үш қадамы (счёт → payUrl → қол қойылған webhook → сәтті бетте растау), sandbox-та тексеру циклі, не істеуге болмайтыны (чатта кілт, редирект бойынша «төленді», ойдан шығарылған endpoint-тер, Kaspi атынан маркетингтік уәделер), сізге тапсыру чек-листі.

2. MCP сервер

Орнату

API кілті керек: кабинет → Интеграциялар → API кілттері → Жасау. Sandbox кілтінен (qp_test_…) бастаңыз — ақша қозғалмайды, төлем имитацияланады.

Claude Code:

claude mcp add qutpay -e QUTPAY_API_KEY=qp_test_… -- npx -y @qutpay/mcp

Cursor (.cursor/mcp.json), Windsurf, Claude Desktop (claude_desktop_config.json), VS Code (.vscode/mcp.json):

{
  "mcpServers": {
    "qutpay": {
      "command": "npx",
      "args": ["-y", "@qutpay/mcp"],
      "env": { "QUTPAY_API_KEY": "qp_test_…" }
    }
  }
}

Кілт тек орта айнымалысынан оқылады, сервер оны ешқашан шығармайды; құрал жауаптарында qp_…/whsec_… түріндегі жолдар маскаланады. Node.js 18+ керек. npm пакеті қолжетімсіз болса, https://api.qut.kz/downloads/qutpay-mcp.zip жүктеп, ашып, "command": "node", "args": ["<қалта>/bin/qutpay-mcp.js"] деп көрсетіңіз.

Құралдар

Құрал	Не істейді
`qutpay_account`	Ұйым, режим (sandbox/live), тариф пен шектер, кассирлер, провайдер күйі. Агент бірінші осыны шақырады
`qutpay_create_invoice`	Счёт құру (QR немесе `kind: "phone"` — сатып алушының Kaspi.kz қосымшасына счёт). `payUrl`, `qrImageUrl`, `deepLink`, `expiresAt` қайтарады. Әрқашан тапсырысқа `idempotencyKey`-мен
`qutpay_get_invoice`	Счёт күйі; `live: true` — Kaspi-ден дәл қазір сұрау
`qutpay_list_invoices`	Тізім: күй, `externalOrderId`, кезең, 50-ге дейін
`qutpay_cancel_invoice`	Ашық счётты жабу
`qutpay_refund_invoice`	Толық немесе ішінара қайтару (scope `refunds:write`). Live кілтпен `confirm: true` талап етеді
`qutpay_simulate_payment`	Тек sandbox: счётты paid / failed / expired деп белгілеу; webhook-тар шын жіберіледі. Live кілтпен бас тартады
`qutpay_list_subscriptions`, `qutpay_get_subscription`	Жазылымдарды оқу (scope `subscriptions:manage`)

Ресурстар (агент құжат ретінде оқиды): qutpay://skill, qutpay://docs/integration, qutpay://docs/webhook-verify, qutpay://docs/errors, qutpay://docs/openapi. Prompt-тар: integrate-checkout — интеграцияға қадамдық тапсырма, verify-sandbox — sandbox циклін тексеру.

MCP-де әдейі жоқ нәрсе: API кілттері мен webhook жасау. Оларды кабинетте өзіңіз жасайсыз; агент .env-ке қоюды сұрайды.

Әдеттегі сессия

«Дүкеніме Kaspi төлемін қос» → агент qutpay://skill оқиды, qutpay_account шақырады (sandbox), код жазады.
Агент qutpay_create_invoice арқылы сынақ счёт құрады, qutpay_simulate_payment арқылы төлемді имитациялайды, webhook-іңіз іске қосылғанын тексеріп, нәтижені көрсетеді.
Ұйымды live-қа ауыстырып, кілтті qp_live_…-ге өзгертесіз. Операцияларда («бүгін қанша төлем», «1001 тапсырысқа 500 ₸ қайтар») агент qutpay_list_invoices және qutpay_refund_invoice қолданады — қайтару тек сіздің нақты растауыңыздан кейін.

Қауіпсіздік

Интеграция тексерілгенше агентке sandbox кілтін беріңіз. Live кілт — тек шектеулі scope-пен (қайтару керек болмаса refunds:write-сіз) және сенімді ортада ғана.
Кілт ұйымға байланған: агент тек сол ұйымның счёттарын көреді.
Шектер — API-дікімен бірдей (кілтке минутына 200 жазу және 600 оқу, тарифтің счёт шегі).
Кілтті кез келген сәтте қайтарып алуға болады: кабинет → Интеграциялар → API кілттері.

Жиі қойылатын сұрақтар

Әзірлеуші болмасам, бұл керек пе? Жоқ. WooCommerce, OpenCart, Tilda үшін дайын модульдер бар. MCP мен SKILL.md — Qut Pay-ді ЖИ-агент арқылы қосатындарға немесе агентке операцияларға қол жеткізетіндерге.

Агент сатып алушыдан ақша шеше ала ма? Жоқ. Счётты сатып алушы Kaspi.kz-те өзі төлейді. Агент тек счёт құрып, күйін оқиды; live кілтпен қайтару растауды талап етеді.

ChatGPT-мен істей ме? Иә, developer mode-та (connectors / MCP). MCP-сіз ChatGPT-ге https://api.qut.kz/for-ai сілтемесін беріңіз.

Бастапқы коды қайда? https://github.com/kazprose/qutpay-docs (examples/mcp қалтасы, MIT). Пакет: npm-де @qutpay/mcp.

Көмек керек пе? WhatsApp +77788813333 · kazprose@gmail.com · 09:00–21:00 (Алматы)
Кабинеттен де жазуға болады: Қолдау.

Qut Pay — тәуелсіз сервис, «Kaspi Bank» АҚ-мен аффилирленбеген. Kaspi және Kaspi Pay — құқық иесінің тауар белгілері.