טרינג למפתחים English

סוכני AI ו-MCP

שרת ה-MCP של טרינג נותן לסוכן קוד (Claude Code, Cursor, כל לקוח MCP) לקרוא מסמכים ולקוחות ולהכין טיוטות. ההפקה היא כלי נפרד, והוא מסרב אם האדם לא אישר בדיוק את הטיוטה הזו.

חיבור ל-Claude Code

sh
claude mcp add tring --env TRING_API_KEY=kbl_test_... --env TRING_ISSUER_ID=... -- npx -y tring-mcp

כשהקובץ .mcp.json נמצא בפרויקט, המפתח נלקח מהמעטפת (${TRING_API_KEY}), כך שאפשר לשמור את הקובץ ב-git בלי המפתח. כדי שכל הפקה תשאל אתכם קודם, מוסיפים ל-.claude/settings.json:

examples/claude-code/.claude/settings.json
{
  "permissions": {
    "allow": [
      "mcp__tring__tring_status",
      "mcp__tring__tring_list_businesses",
      "mcp__tring__tring_get_business",
      "mcp__tring__tring_list_documents",
      "mcp__tring__tring_get_document",
      "mcp__tring__tring_list_customers",
      "mcp__tring__tring_get_customer",
      "mcp__tring__tring_get_reference",
      "mcp__tring__tring_get_draft",
      "mcp__tring__tring_prepare_draft",
      "mcp__tring__tring_preview_draft",
      "mcp__tring__tring_get_expense_receipt"
    ],
    "ask": ["mcp__tring__tring_confirm_draft"]
  }
}

חיבור ל-Cursor

שומרים כ-.cursor/mcp.json בפרויקט, או כ-~/.cursor/mcp.json לכל הפרויקטים:

examples/cursor/mcp.json
{
  "mcpServers": {
    "tring": {
      "command": "npx",
      "args": ["-y", "tring-mcp"],
      "env": {
        "TRING_API_KEY": "${env:TRING_API_KEY}",
        "TRING_ISSUER_ID": "${env:TRING_ISSUER_ID}"
      }
    }
  }
}

משתני סביבה

משתנה
TRING_API_KEYחובה. מפתח של סביבת הניסוי, kbl_test_...
TRING_ISSUER_IDהעסק שהכלים משתמשים בו כשלא נשלח issuer_id
TRING_BASE_URLכתובת ה-API; ברירת המחדל היא סביבת הניסוי. אפשר גם את שרת הדמה המקומי.
TRING_MCP_ALLOW_LIVE1 מתיר מפתח ייצור. בלעדיו מפתח kbl_live_ נדחה ולא נשלח כלום.

הרשאות המפתח

לכל מפתח API יש הרשאות (scopes), וכל פעולה מציינת את ההרשאה שהיא צריכה (מדריך ה-API מציג אותה). תנו למפתח של הסוכן רק את מה שהוא צריך:

הרשאהמה הסוכן יכול
readכל כלי הרשימה והקריאה (אירועים, יומן webhook, עיצוב), ותצוגה מקדימה של טיוטה
issuetring_prepare_draft ו-tring_confirm_draft
expensestring_attach_expense_receipt
financetring_get_expense_receipt

מפתח עם read בלבד משאיר את הסוכן לקריאה בלבד: הכנה עונה 403 KEY_SCOPE_MISSING ושום דבר לא נעשה. אפשר גם להגביל מפתח לרשתות שלכם (אחרת KEY_ADDRESS_NOT_ALLOWED).

הכלים

כלימה עושהמשנה משהו
tring_statusסביבה, כתובת, מזהה המפתח, עסק ברירת המחדללא
tring_list_businesses, tring_get_businessהעסקים שהמפתח רשאי לפעול בשמםלא
tring_list_documents, tring_get_documentמסמכים, עם סינוןלא
tring_list_customers, tring_get_customerלקוחותלא
tring_get_referenceשיעור המע"מ וסף מספר ההקצאהלא
tring_list_eventsאירועים מאז מזהה מסוים (document.issued, delivery.downloaded ועוד)לא
tring_list_webhook_endpoints, tring_list_webhook_deliveriesכתובות ה-webhook ויומן המשלוחים שלהן, לבדיקת תקלות; אף פעם לא סודלא
tring_get_document_designהעיצוב שבו המסמכים מופקיםלא
tring_prepare_draftמחשב טיוטה. לא מפיק כלום.שומר טיוטה
tring_get_draft, tring_preview_draftקורא טיוטה; כותב את ה-PDF שלה לקובץ מקומי פרטילא
tring_attach_expense_receiptמצרף להוצאה את הקבלה של הספק (JPEG, PNG או PDF, מנתיב מקומי או ב-base64); כל דבר אחר לפי הבתים הראשונים נדחה לפני שנשלחמחליף את הקובץ התקף
tring_get_expense_receiptכותב את הקבלה של הוצאה, בית בבית, לקובץ מקומי פרטילא
tring_confirm_draftמפיק את המסמךכן, לתמיד

איך ההפקה נשארת בטוחה

  1. הסוכן קורא ל-tring_prepare_draft. התשובה היא הטיוטה בטקסט פשוט (סוג, לקוח, שורות, סכום) עם ההוראה להציג אותה ולשאול.
  2. האדם קורא ואומר כן.
  3. הסוכן קורא ל-tring_confirm_draft עם ה-draft_id, עם approved_total ו-approved_doc_type כמו שהאדם ראה אותם, ועם המילים שבהן אישר. השרת קורא את הטיוטה מחדש ומסרב אם הסכום או הסוג שונים. במקרה כזה לא מופק כלום.
  4. אישור כפול מחזיר את אותו מסמך. כשהתוצאה לא ידועה, הכלי אומר לאשר שוב את אותה טיוטה, ואף פעם לא להכין חדשה.

התיאור של הכלי אומר לסוכן שהוא יוצר מסמך מס מחייב ושמותר להריץ אותו רק אחרי שהאדם אישר את הטיוטה המדויקת. כלל ה-ask שלמעלה גורם ל-Claude Code להציג לכם כל קריאה אליו, מה שהסוכן לא יחליט.

השרת לא כותב את המפתח לתשובת כלי או ללוג (כל מה שנראה כמו מפתח מקוצר לחלק הציבורי שלו), וכותב תצוגות מקדימות רק לתיקייה פרטית של התהליך שלו.

בקשות שעובדות

  • "תראה לי את הקבלות שהפקנו השבוע ואת הסכום שלהן."
  • "תכין קבלה להזמנה 1042: ‏350.00 בהעברה בנקאית מדנה כהן, מזהה לקוח crm-88. תראה לי לפני שאתה מפיק."
  • "תכתוב route ב-Next.js שמפיק חשבונית מס / קבלה אחרי תשלום שהצליח, עם tring-sdk, ומספר ההזמנה כמפתח האידמפוטנטיות."

תיעוד לסוכנים

llms.txt הוא אינדקס קצר עם הכללים שסוכן חייב לשמור; llms-full.txt הוא כל התיעוד בקובץ אחד. הפנו אליהם את הסוכן, או הוסיפו להוראות הפרויקט (CLAUDE.md, .cursorrules):

Tring API docs: https://developers.tring.co.il/llms-full.txt
Use tring-sdk (TypeScript) or tring-sdk (Python, import tring_sdk). Prepare, show the draft, confirm only after approval.
One Idempotency-Key per document; after an unknown outcome confirm again, never prepare again.