סוכני AI ו-MCP
שרת ה-MCP של טרינג נותן לסוכן קוד (Claude Code, Cursor, כל לקוח MCP) לקרוא מסמכים ולקוחות ולהכין טיוטות. ההפקה היא כלי נפרד, והוא מסרב אם האדם לא אישר בדיוק את הטיוטה הזו.
חיבור ל-Claude Code
claude mcp add tring --env TRING_API_KEY=kbl_test_... --env TRING_ISSUER_ID=... -- npx -y tring-mcp{
"mcpServers": {
"tring": {
"command": "npx",
"args": ["-y", "tring-mcp"],
"env": {
"TRING_API_KEY": "${TRING_API_KEY}",
"TRING_ISSUER_ID": "${TRING_ISSUER_ID}"
}
}
}
}כשהקובץ .mcp.json נמצא בפרויקט, המפתח נלקח מהמעטפת (${TRING_API_KEY}), כך שאפשר לשמור את הקובץ ב-git בלי המפתח. כדי שכל הפקה תשאל אתכם קודם, מוסיפים ל-.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 לכל הפרויקטים:
{
"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_LIVE | 1 מתיר מפתח ייצור. בלעדיו מפתח kbl_live_ נדחה ולא נשלח כלום. |
הרשאות המפתח
לכל מפתח API יש הרשאות (scopes), וכל פעולה מציינת את ההרשאה שהיא צריכה (מדריך ה-API מציג אותה). תנו למפתח של הסוכן רק את מה שהוא צריך:
| הרשאה | מה הסוכן יכול |
|---|---|
read | כל כלי הרשימה והקריאה (אירועים, יומן webhook, עיצוב), ותצוגה מקדימה של טיוטה |
issue | tring_prepare_draft ו-tring_confirm_draft |
expenses | tring_attach_expense_receipt |
finance | tring_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 | מפיק את המסמך | כן, לתמיד |
איך ההפקה נשארת בטוחה
- הסוכן קורא ל-
tring_prepare_draft. התשובה היא הטיוטה בטקסט פשוט (סוג, לקוח, שורות, סכום) עם ההוראה להציג אותה ולשאול. - האדם קורא ואומר כן.
- הסוכן קורא ל-
tring_confirm_draftעם ה-draft_id, עםapproved_totalו-approved_doc_typeכמו שהאדם ראה אותם, ועם המילים שבהן אישר. השרת קורא את הטיוטה מחדש ומסרב אם הסכום או הסוג שונים. במקרה כזה לא מופק כלום. - אישור כפול מחזיר את אותו מסמך. כשהתוצאה לא ידועה, הכלי אומר לאשר שוב את אותה טיוטה, ואף פעם לא להכין חדשה.
התיאור של הכלי אומר לסוכן שהוא יוצר מסמך מס מחייב ושמותר להריץ אותו רק אחרי שהאדם אישר את הטיוטה המדויקת. כלל ה-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.