الانتقال إلى المحتوى
Kin

للمطوّرين

تعاملوا مع دائرة العائلة. ولا توافقوا أبدًا.

يتصل مساعد الذكاء الاصطناعي الخاص بأحد أفراد العائلة بخادم MCP التابع لـ Kin عبر تسجيل الدخول بـ OAuth، أو برمز يمنحه هذا الفرد. ويبلّغ برنامج وكالة الرعاية المنزلية عن الزيارات عبر واجهة برمجة موقّعة. كلاهما يقرأ ويقترح، وشخص في Kin هو من يوافق.

خادم MCP

اربطوا مساعدًا

HTTP متدفق، رسالة JSON-RPC واحدة لكل طلب، بلا جلسة. إصدارات البروتوكول 2026-07-28, 2025-11-25, 2025-06-18, 2025-03-26. يسجّل العميل الدخول عبر OAuth 2.1، أو ينشئ الفرد رمزًا من شاشة المساعدون المرتبطون.

نقطة النهاية
https://mzdg4f3stk.us-east-1.awsapprunner.com/api/mcp

سجّل الدخول من عميلك

أضف عنوان Kin بلا رمز. يجد عميلك Kin من استجابة 401، ويسجّل نفسه، ويفتح Kin في متصفحك؛ فتسجّل الدخول، وتختار ما يحق له فعله ولأي مدة، ثم توافق. Kin هو خادم التفويض الخاص به وفق OAuth 2.1: PKCE بطريقة S256، ومستندات بيانات معرّف العميل أو التسجيل الديناميكي، ومؤشر المورد، ولا رمز تحديث.

Claude Code، بتسجيل الدخول
claude mcp add --transport http kin https://mzdg4f3stk.us-east-1.awsapprunner.com/api/mcp
البيانات الوصفية لخادم التفويض
https://mzdg4f3stk.us-east-1.awsapprunner.com/.well-known/oauth-authorization-server
Claude Code، برمز
claude mcp add --transport http kin https://mzdg4f3stk.us-east-1.awsapprunner.com/api/mcp --header "Authorization: Bearer <your-delegation-token>"
إعدادات عميل MCP (.mcp.json)
{
  "mcpServers": {
    "kin": {
      "type": "http",
      "url": "https://mzdg4f3stk.us-east-1.awsapprunner.com/api/mcp",
      "headers": {
        "Authorization": "Bearer <your-delegation-token>"
      }
    }
  }
}
أي عميل HTTP
curl -s https://mzdg4f3stk.us-east-1.awsapprunner.com/api/mcp \
  -H "Authorization: Bearer <your-delegation-token>" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" -H "Mcp-Method: tools/list" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

الأدوات

الأدوات نفسها والبوابة نفسها كما في اسأل Kin. لا يعرض tools/list إلا ما يسمح به دور العضو ونطاق الرمز المميّز.

  • get_poolيقرأ

    The circle's pool: its confirmed balance now, this month's money paid in, paid out and PayPal fees, and what this month's spending went on by category (bills, receipts members paid from their own pocket, and purchases). Use it for any question about how much money there is, or how much was spent on something this month.

  • list_billsيقرأ

    The circle's bills: those the family expects next, those waiting for approval, and those paid, with payee, amount and day. A caregiver sees only their own. It does not hold receipts or purchases: for what was spent on something, use get_pool.

  • get_fairnessيقرأ

    This month's fairness, as Kin's money core calculates it: each sharing member's agreed share, what they gave, and who owes whom to settle. Use it for any question about shares, fairness or who owes whom.

  • check_claimيقرأ

    Checks a demand for money against the record, with Kin's fixed rules: is the payee known, is there an open bill of that amount, was it already paid. It only reads; nobody is alerted. Use it when someone asks whether a demand, call or letter is real.

  • list_proposalsيقرأ

    The payments waiting for a yes, and who still has to say yes to each, as the approval engine decided. Kin cannot answer for anyone.

  • get_recordيقرأ

    The newest entries of the circle's ledger: what happened, to whom, how much and on which day, and whether it was simulated.

  • get_paypal_payout_statusيقرأ

    Whether someone has been paid: the payouts the record holds for a payee or caregiver, and, for a real payout, its status read from PayPal now. Simulated payouts in a demo say so.

  • get_paypal_topup_statusيقرأ

    The members' top-ups into the pool: amount, day and, for a real top-up, the status of its capture read from PayPal now. Simulated top-ups in a demo say so.

  • get_subscription_statusيقرأ

    Each member's monthly share through PayPal subscriptions: its amount, its state and its next charge, read from PayPal for a real one. Simulated shares in a demo say so.

  • get_paypal_orderيقرأ

    PayPal's own record of a top-up, read from PayPal now through the PayPal Agent Toolkit: the PayPal order behind the newest real top-up, its status, amount, times and capture. A simulated top-up has no PayPal record, and the result says so. Use it when someone asks what PayPal itself says about a top-up.

  • get_paypal_invoiceيقرأ

    PayPal's own record of an invoice Kin sent a member, read from PayPal now through the PayPal Agent Toolkit: its number, status, amount and what was paid on it. A simulated invoice has no PayPal record, and the result says so. Use it when someone asks whether an invoice was paid or where it stands at PayPal.

  • list_paypal_disputesيقرأ

    Whether anyone has disputed one of the circle's newest real top-ups with PayPal, read from PayPal now through the PayPal Agent Toolkit: each dispute's status, reason and amount. Use it when someone asks about a dispute, a chargeback or a payment someone says they did not make.

  • propose_refillيقترح

    Asks Kin to propose a refill the family's rules already allow, at the rule's own price. It buys nothing: the refill then waits for the yeses the family agreement names, unless the parent's standing permission covers it. Use it only when the person asks for a reorder or refill.

  • propose_giftيقترح

    For the parent only: asks Kin to send a small payment from her own Purse, such as a gift, a tip or a donation, to someone she names. It pays nothing: Kin reads the payment back and it waits for her own yes, and Kin's rules hold it for a day, with the family told, when the person is not in her address book, the amount is above her limit or the request looks pressured. Use it only when she asks to send, give or pay someone money from her Purse.

الحدّ

ما لا يستطيع أي طرف خارجي فعله

  • لا أداة توافق أو تدفع أو توقّع أو تنقل مالًا. الأداة التي تقترح تعيد معرّف الاقتراح والشاشة التي يوافق عليه فيها شخص، ويبقى الاقتراح بانتظار ذلك الشخص حتى لو كان التصريح الدائم للوالد يغطيه.
  • أدوات PayPal نفسها، بما فيها أدوات الكتابة، تبقى على خادم Kin ولا تُعرض هنا أبدًا.
  • نطاق الرمز المميّز لا يفعل إلا تضييق دور العضو نفسه. وإبطاله يرفض الطلب التالي مباشرة.
  • النص القادم من السجل (الأسماء والملاحظات والرسائل) يعود موسومًا على أنه بيانات، داخل وسم لا يستطيع إغلاقه.
  • الطلب بلا رمز مميّز نشط يحصل على 401 وترويسة WWW-Authenticate تشير إلى بيانات وصف المورد المحمي.

واجهة الوكالات

أبلغوا عن زيارة

أرسلوا زيارة واحدة بـ POST إلى /api/v1/visits، موقَّعة بالمفتاح الذي أنشأه منظِّم الدائرة. يحفظها Kin دليلًا بجانب المناوبة. ولا تدفع شيئًا.

وقّعوا النص الخام
BODY='{"externalId":"visit-1042","caregiver":"تقديم الرعاية","kind":"aide","startsAt":"2026-11-09T09:00:00-05:00","endsAt":"2026-11-09T13:00:00-05:00","checkedInAt":"2026-11-09T09:02:00-05:00","checkedOutAt":"2026-11-09T13:00:00-05:00"}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac 'kin_ags_…' | sed 's/^.* //')
curl -s https://mzdg4f3stk.us-east-1.awsapprunner.com/api/v1/visits \
  -H "Content-Type: application/json" \
  -H "Kin-Agency-Key: agk_…" \
  -H "Kin-Signature: t=$T,v1=$SIG" \
  -d "$BODY"

201 حُفظ · 200 محفوظ سابقًا · 401 المفتاح أو التوقيع · 409 المعرّف نفسه، نص آخر · 422 حُفظ لكنه غير مقروء

واجهة الوكالات

إرسال فاتورة

أرسل فاتورة بطلب POST إلى ‎/api/v1/invoices، موقَّعة تمامًا مثل الزيارة. يذكر كل بند زيارة أبلغت عنها الوكالة من قبل، بالسنتات الصحيحة؛ ويجمع Kin البنود بنفسه. تصبح الفاتورة فاتورة تراجعها العائلة مقابل الزيارات التي أكدتها. ولا تدفع شيئًا من تلقاء نفسها.

توقيع فاتورة وإرسالها
BODY='{"invoiceNumber":"INV-1042","periodStart":"2026-11-01","periodEnd":"2026-11-30","lines":[{"visitId":"visit-1042","minutes":240,"amountCents":11200,"currency":"USD"}],"totalCents":11200,"currency":"USD","dueOn":"2026-12-15","paypalEmail":"billing@agency.example"}'
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$BODY" | openssl dgst -sha256 -hmac 'kin_ags_…' | sed 's/^.* //')
curl -s https://mzdg4f3stk.us-east-1.awsapprunner.com/api/v1/invoices \
  -H "Content-Type: application/json" \
  -H "Kin-Agency-Key: agk_…" \
  -H "Kin-Signature: t=$T,v1=$SIG" \
  -d "$BODY"
السؤال عن حالتها (وقّع المسار)
P=/api/v1/invoices/INV-1042
T=$(date +%s)
SIG=$(printf '%s.%s' "$T" "$P" | openssl dgst -sha256 -hmac 'kin_ags_…' | sed 's/^.* //')
curl -s https://mzdg4f3stk.us-east-1.awsapprunner.com$P \
  -H "Kin-Agency-Key: agk_…" \
  -H "Kin-Signature: t=$T,v1=$SIG"

201 محفوظة للمراجعة · 200 محفوظة من قبل · 401 المفتاح أو التوقيع · 409 الرقم نفسه بمحتوى آخر · 422 محفوظة لكنها مرفوضة مع السبب · GET: received, under_review, approved, paid, declined

OpenAPI

المستند المنشور

مبني من المخططات التي يتحقق الخادم من الطلبات على أساسها، فلا يمكن أن ينحرف عنها.

افتحوا مستند OpenAPI

حزم تطوير لـ TypeScript وPython، أنشأتها APIMatic من هذا المستند نفسه. تتضمن كل منها مثالًا موقّعًا لواجهة الوكالات.

ابدأوا بحديث واحد مع عائلتكم.