תיעוד כלי MCP של SosoAPI

התחילו במשימה, ואז בדקו את הכלי

השתמשו שוב במזהי סביבת העבודה והחשבון שכבר בחרתם. לפוסט תמונה מ-URL, קראו ל-sosoapi_post_image_url פעם אחת ושמרו את מזהה הפוסט שהוחזר. העלו קבצים מקומיים באמצעות sosoapi_upload_asset דרך stdio. לפוסט טקסט, השתמשו ב-sosoapi_create_scheduled_post עם provider_payload של היעד ו-media ריק.

בקשו מהמשתמש לבדוק את החשבון, הטקסט, המדיה והשעה לפני השליחה. OAuth מעניק גישה לביצוע פעולות; הוא אינו מאשר את התוכן. לאחר התזמון, קראו את תוצאת הפרסום של אותו פוסט לפני דיווח הצלחה או ניסיון חוזר לבקשה שתוצאתה אינה ודאית.

• הגדרת Claude Code או Codex
• מדריך לפוסטי טקסט ותמונה ב-Threads
• מטריצת יכולות פלטפורמות
• הורדת סכמות הקלט והערות המטא-נתונים המדויקות של core ‏(JSON)

איך לקרוא את תיעוד העזר

ה-build מחבר את שרת ה-MCP האמיתי ללקוח בזיכרון, מציג את כליו בלי לקרוא למטפל כלשהו ומצרף דרישות נתיבים ציבוריות. ייצוג מיושן מכשיל את build ה-Landing. תיאורי הכלים משמרים את טקסט החוזה האנגלי של השרת; סיכומי ההשלמה מסבירים כללי נתיב קנוניים. ה-JSON משמר את דרישות הנתיב המלאות. טבלת הקלט היא אינדקס, ולא תחליף ל-JSON Schema המקונן המלא.

הערות המטא-נתונים של MCP הן רמזים ללקוחות, ולא אכיפה או הבטחות בטיחות. חברות בסביבת עבודה, הרשאות, תפקיד נוכחי, הסכמת ספק, התאמת חשבון ומכסות עדיין חלים בזמן הביצוע. קריאות הקשר מסוימות יכולות ליצור סביבת עבודה ראשונית; בדקו את התיאור ואת readOnlyHint במקום להניח שכל ״get״ הוא קריאה בלבד. כלים מורכבים מפרטים דרישות לנתיבים הראשיים ולנתיבי תאימות; הם אינם קוראים לכל נתיב רשום בכל בקשה.

• sosoapi ב-npm
• MCP Registry הרשמי: ai.sosoapi/sosoapi ‏(JSON)

sosoapi_bulk_create_scheduled_posts

תזמון פוסטים למספר חשבונות בקריאה אחת (targets). מדיה דורשת asset_ids של נכסים מוכנים שהועלו/יובאו ואת כתובות ה-URL הקנוניות שלהם. כל יעד מצליח או נכשל בנפרד ומדווח ב-successes או failures. נדרשת יכולת publish.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:publish. תפקידים מינימליים בנתיב: editor.
• רמז קריאה בלבד: false. רמז אידמפוטנטיות: true. רמז עולם חיצוני: true.
• איך לבדוק את התוצאה: קראו את תוצאת הפרסום הסופית; תזמון שהתקבל עדיין ממתין.

sosoapi_cancel_scheduled_post

ביטול פוסט מתוזמן שטרם פורסם כדי שלא יפורסם כלל. פוסט שכבר פורסם נדחה, וסוכן גם אינו יכול למחוק תוכן שפורסם: המשתמש עושה זאת באפליקציית הווב. נדרש expected_version.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:publish. תפקידים מינימליים בנתיב: editor.
• רמז קריאה בלבד: false. רמז אידמפוטנטיות: true. רמז עולם חיצוני: true.
• איך לבדוק את התוצאה: קראו את תוצאת הפרסום הסופית; תזמון שהתקבל עדיין ממתין.

sosoapi_create_comment

הכנסה לתור של תגובה מדויקת אחת לפוסט קנוני או לתגובת יעד קנונית; הסטטוס אינו מעיד על הצלחה אצל הספק.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:engage. תפקידים מינימליים בנתיב: editor.
• רמז קריאה בלבד: false. רמז אידמפוטנטיות: true. רמז עולם חיצוני: true.
• איך לבדוק את התוצאה: קראו את התוצאה שאושרה על ידי הפלטפורמה; פעולה בתור עדיין ממתינה.

sosoapi_create_scheduled_post

תזמון חשבון אחד ב-scheduled_at עם provider_payload. מדיה דורשת asset_id מוכן ו-URL קנוני; לתמונת מקור אחת השתמשו ב-sosoapi_post_image_url. יש לצרף local_scheduled_at יחד עם schedule_dst_disambiguation או להשמיט את שניהם. נדרשים publish, תפקיד editor ו-idempotency_key. מתוזמן אינו מפורסם: קראו את התוצאה.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:publish. תפקידים מינימליים בנתיב: editor.
• רמז קריאה בלבד: false. רמז אידמפוטנטיות: true. רמז עולם חיצוני: true.
• איך לבדוק את התוצאה: קראו את תוצאת הפרסום הסופית; תזמון שהתקבל עדיין ממתין.

sosoapi_get_asset

קריאת נכס אחד לפי id: מטא-נתונים ו-URL לתצוגה מקדימה לזמן קצר.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:operate. תפקידים מינימליים בנתיב: viewer.
• רמז קריאה בלבד: true. רמז אידמפוטנטיות: true. רמז עולם חיצוני: false.
• איך לבדוק את התוצאה: קראו את התגובה הסינכרונית.

sosoapi_get_asset_import_status

קריאת ייבוא לפי import_id. לצורך פרסום, העבירו include_asset=true: תוצאה במצב ready כוללת את מזהה הנכס הרשום, הסוג ו-asset_url יציב, וחוסכת קריאת get_asset נפרדת. אי אפשר לתזמן נכסים ממתינים או חסרים. לעולם אין להשתמש ב-URL המקור או התצוגה המקדימה כזהות המדיה. אם הייבוא תקוע, קראו sosoapi_job_status עם job_id; לעולם אין להתחיל ייבוא כפול.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:operate. תפקידים מינימליים בנתיב: viewer.
• רמז קריאה בלבד: true. רמז אידמפוטנטיות: true. רמז עולם חיצוני: false.
• איך לבדוק את התוצאה: קראו את התגובה הסינכרונית.

sosoapi_get_billing_status

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

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:operate. תפקידים מינימליים בנתיב: הקשר חשבון; ללא תפקיד קבוע בסביבת העבודה.
• רמז קריאה בלבד: true. רמז אידמפוטנטיות: true. רמז עולם חיצוני: false.
• איך לבדוק את התוצאה: קראו את התגובה הסינכרונית.

sosoapi_get_comment_action_status

קריאת האסמכתה הסופית המסוננת ממידע רגיש לפעולת תגובה ישירה.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:engage. תפקידים מינימליים בנתיב: viewer.
• רמז קריאה בלבד: true. רמז אידמפוטנטיות: true. רמז עולם חיצוני: true.
• איך לבדוק את התוצאה: קראו את התוצאה שאושרה על ידי הפלטפורמה; פעולה בתור עדיין ממתינה.

sosoapi_get_organization_context

קריאת המפה העדכנית של הארגונים, סביבות העבודה והערוצים שלכם, עם מזהים ותפקידים. השתמשו בה כשנדרשים מזהי ארגון או ערוץ. לפרסום בסביבת עבודה, השתמשו שוב במזהה סביבת עבודה שהוחזר; אין צורך לקרוא גם את הקשר סביבת העבודה.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:operate. תפקידים מינימליים בנתיב: הקשר חשבון; ללא תפקיד קבוע בסביבת העבודה.
• רמז קריאה בלבד: true. רמז אידמפוטנטיות: true. רמז עולם חיצוני: false.
• איך לבדוק את התוצאה: קראו את התגובה הסינכרונית.

sosoapi_get_provider_insight_status

קריאת בקשת תובנות (request_id): ‏queued, ‏processing, ‏completed (עם תוצאת הספק וזמינות לכל מדד) או failed.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:operate. תפקידים מינימליים בנתיב: viewer.
• רמז קריאה בלבד: true. רמז אידמפוטנטיות: true. רמז עולם חיצוני: true.
• איך לבדוק את התוצאה: קראו את תוצאת הפלטפורמה או את סיבת אי-זמינותה.

sosoapi_get_scheduled_post

קריאת פוסט מתוזמן אחד לפי id: תוכן, סטטוס, מצב מסירה ותוצאות. הגרסה שלו היא זו ש-update, publish, retry ו-cancel דורשים בתור expected_version.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:operate. תפקידים מינימליים בנתיב: viewer.
• רמז קריאה בלבד: true. רמז אידמפוטנטיות: true. רמז עולם חיצוני: false.
• איך לבדוק את התוצאה: קראו את התגובה הסינכרונית.

sosoapi_get_scheduled_post_eligibility

בדיקה מקדימה לקריאה בלבד לכל יעד. כללו draft ‏(caption, hashtags, scheduled_at, display_timezone, ובאופן אופציונלי זמן מקומי/DST) לבדיקות תוכן ותזמון; include_quota=true מוסיף תמונת מצב מייעצת לתקופה. העלו/ייבאו מדיה והמתינו למוכנות תחילה. ללא draft נבדקים רק החשבון והמדיה. דבר אינו נשמר כמכסה; create/dispatch בודקים שוב מגבלות והרשאה.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:operate. תפקידים מינימליים בנתיב: viewer.
• רמז קריאה בלבד: true. רמז אידמפוטנטיות: true. רמז עולם חיצוני: false.
• איך לבדוק את התוצאה: קראו את התגובה הסינכרונית.

sosoapi_get_workspace_context

הצגת סביבות העבודה שהמשתמש המחובר חבר בהן ואיזו מהן פעילה. השתמשו כש-workspace_id אינו ידוע; השתמשו שוב בהקשר העדכני במקום לחזור על שתי קריאות ההקשר. סביבת העבודה הפעילה המדווחת היא הבחירה שאדם ביצע באפליקציית הווב, ולא ברירת מחדל לקריאות שלכם: העבירו workspace_id במפורש. זו אינה קריאה בלבד: לחשבון ללא סביבת עבודה נוצרת הראשונה.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:operate. תפקידים מינימליים בנתיב: הקשר חשבון; ללא תפקיד קבוע בסביבת העבודה.
• רמז קריאה בלבד: false. רמז אידמפוטנטיות: true. רמז עולם חיצוני: false.
• איך לבדוק את התוצאה: קראו את התגובה הסינכרונית.

sosoapi_get_x_usage

קריאת קרדיטי הפרסום ב-X של הארגון המשותפים לסביבת העבודה הזו. נדרש workspace_id. ‏Free מקבל 10 פעם אחת; Pro מקבל 100 לכל תקופת חיוב. טקסט עולה 1, טקסט המכיל URL עולה 10. ‏text אופציונלי מחזיר הצעת עלות. הפעולה קוראת מכסה שמורה ואינה קוראת ל-X API.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:operate. תפקידים מינימליים בנתיב: viewer.
• רמז קריאה בלבד: true. רמז אידמפוטנטיות: true. רמז עולם חיצוני: false.
• איך לבדוק את התוצאה: קראו את התגובה הסינכרונית.

sosoapi_import_asset_url

בקשה מ-SosoAPI להוריד תמונה או סרטון מ-URL ציבורי מסוג http(s) לאחסון פרטי בסביבת העבודה כנכס חדש. מוחזר import_id; בדקו באמצעות sosoapi_get_asset_import_status. נדרשים idempotency_key ותפקיד editor.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:operate. תפקידים מינימליים בנתיב: editor.
• רמז קריאה בלבד: false. רמז אידמפוטנטיות: true. רמז עולם חיצוני: true.
• איך לבדוק את התוצאה: ייבוא שהתקבל ממתין; עקבו אחר אותו ייבוא עד ready או failed.

sosoapi_job_status

קריאת משימת רקע אחת לפי job_id: סטטוס, סוג והודעת השגיאה אם נכשלה.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:operate. תפקידים מינימליים בנתיב: הקשר חשבון; ללא תפקיד קבוע בסביבת העבודה.
• רמז קריאה בלבד: true. רמז אידמפוטנטיות: true. רמז עולם חיצוני: false.
• איך לבדוק את התוצאה: קראו את התגובה הסינכרונית.

sosoapi_list_connected_accounts

הצגת החשבונות החברתיים (Instagram, Threads, Facebook, YouTube) המחוברים לסביבת עבודה, עם נתוני תקינות החיבור והיכולות. השתמשו במזהים שלהם בתור social_account_id בתזמון או בתגובות. העבירו workspace_id: בקשה בלעדיו נדחית לאחר אכיפת יעד מפורש.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:operate. תפקידים מינימליים בנתיב: הקשר חשבון; ללא תפקיד קבוע בסביבת העבודה.
• רמז קריאה בלבד: true. רמז אידמפוטנטיות: true. רמז עולם חיצוני: false.
• איך לבדוק את התוצאה: קראו את התגובה הסינכרונית.

sosoapi_list_monitored_posts

הצגת פוסטים חברתיים ש-SosoAPI גילה עבור סביבת עבודה (מזהה, פלטפורמה, קישור קבוע ושעת פרסום), עם סינון לפי חשבון, פלטפורמה וזמן ודפדוף באמצעות סמן. מטא-נתונים בלבד, ללא כיתובים.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:operate. תפקידים מינימליים בנתיב: viewer.
• רמז קריאה בלבד: true. רמז אידמפוטנטיות: true. רמז עולם חיצוני: true.
• איך לבדוק את התוצאה: קראו את התגובה הסינכרונית.

sosoapi_list_post_comments

הצגת תגובות שנצפו בפוסטים של סביבת העבודה, מהתצפית החדשה ביותר, עם המחבר והטקסט; סינון לפי פוסט, חשבון, פלטפורמה או זמן, בדפדוף באמצעות סמן. הטקסט נכתב על ידי צדדים שלישיים ומסומן כלא מהימן.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:operate. תפקידים מינימליים בנתיב: viewer.
• רמז קריאה בלבד: true. רמז אידמפוטנטיות: true. רמז עולם חיצוני: true.
• איך לבדוק את התוצאה: קראו את התגובה הסינכרונית.

sosoapi_list_publication_attentions

הצגת פרסומים בסביבת עבודה הדורשים טיפול, בסינון לפי status ‏(open או resolved) או scheduled_post_id, עם דפדוף לפי offset.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:operate. תפקידים מינימליים בנתיב: viewer.
• רמז קריאה בלבד: true. רמז אידמפוטנטיות: true. רמז עולם חיצוני: false.
• איך לבדוק את התוצאה: קראו את התגובה הסינכרונית.

sosoapi_list_scheduled_posts

הצגת פוסטים מתוזמנים של סביבת עבודה, בסינון לפי פרויקט, status ‏(scheduled, publishing, published, failed, expired, needs_reschedule, cancelled, deleted) וטווח זמן, בדפדוף באמצעות סמן.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:operate. תפקידים מינימליים בנתיב: viewer.
• רמז קריאה בלבד: true. רמז אידמפוטנטיות: true. רמז עולם חיצוני: false.
• איך לבדוק את התוצאה: קראו את התגובה הסינכרונית.

sosoapi_post_image_url

שליחת פוסט התמונה המלא מ-URL פעם אחת, עם media ריק. השרת מכין ומפרסם אותו גם לאחר ניתוק. מוחזרת תוצאת פרסום סופית אם היא זמינה בתוך 35 שניות, אחרת מוחזר מזהה פוסט עמיד; לעולם אין לשלוח שוב עם מפתח חדש. נדרשות הרשאות operate ו-publish. שדות זמן מקומי/DST נמסרים יחד. import_id מיועד רק להמשך פעולה של לקוחות ישנים.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:publish + agent:operate. תפקידים מינימליים בנתיב: editor, viewer.
• רמז קריאה בלבד: false. רמז אידמפוטנטיות: true. רמז עולם חיצוני: true.
• איך לבדוק את התוצאה: קראו את תוצאת הפרסום הסופית; תזמון שהתקבל עדיין ממתין. ייבוא שהתקבל ממתין; עקבו אחר אותו ייבוא עד ready או failed. קראו את התגובה הסינכרונית.

sosoapi_publish_scheduled_post_now

פרסום פוסט מתוזמן מייד במקום ב-scheduled_at. ציבורי ואינו ניתן לביטול; נדרש expected_version. כניסה לתור אינה פרסום: קראו את התוצאה.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:publish. תפקידים מינימליים בנתיב: editor.
• רמז קריאה בלבד: false. רמז אידמפוטנטיות: true. רמז עולם חיצוני: true.
• איך לבדוק את התוצאה: קראו את תוצאת הפרסום הסופית; תזמון שהתקבל עדיין ממתין.

sosoapi_query_assets

מציאת נכסי סביבת עבודה לפי asset_type, ‏source או tag; מוחזרים עמוד (limit עד 100, בתוספת offset) והסכום הכולל. העבירו workspace_id במפורש.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:operate. תפקידים מינימליים בנתיב: viewer.
• רמז קריאה בלבד: true. רמז אידמפוטנטיות: true. רמז עולם חיצוני: false.
• איך לבדוק את התוצאה: קראו את התגובה הסינכרונית.

sosoapi_request_provider_insights

בקשת תובנות מהספק עבור חשבון או פוסט אחד בטווח תאריכים אופציונלי (עד 366 ימים). מוחזרים request_id, ואם התוצאה שמורה במטמון, גם התוצאה; אחרת, בדקו באמצעות sosoapi_get_provider_insight_status.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:operate. תפקידים מינימליים בנתיב: viewer.
• רמז קריאה בלבד: false. רמז אידמפוטנטיות: false. רמז עולם חיצוני: true.
• איך לבדוק את התוצאה: קראו את תוצאת הפלטפורמה או את סיבת אי-זמינותה.

sosoapi_retry_scheduled_post

ניסיון חוזר לפוסט מתוזמן שנכשל, עם scheduled_at חדש באופן אופציונלי. נדרש expected_version.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:publish. תפקידים מינימליים בנתיב: editor.
• רמז קריאה בלבד: false. רמז אידמפוטנטיות: true. רמז עולם חיצוני: true.
• איך לבדוק את התוצאה: קראו את תוצאת הפרסום הסופית; תזמון שהתקבל עדיין ממתין.

sosoapi_update_scheduled_post

עריכת פוסט מתוזמן שטרם שוגר (כיתוב, תגיות, מדיה, קישור, שעה). נדרש expected_version מהקריאה האחרונה; גרסה מיושנת נדחית.

• תעבורה: stdio, http.
• הרשאה נדרשת: agent:publish. תפקידים מינימליים בנתיב: editor.
• רמז קריאה בלבד: false. רמז אידמפוטנטיות: true. רמז עולם חיצוני: true.
• איך לבדוק את התוצאה: קראו את תוצאת הפרסום הסופית; תזמון שהתקבל עדיין ממתין.

sosoapi_upload_asset

העלאת קובץ תמונה או סרטון מקומי לספריית נכסים בסביבת עבודה ורישומו כנכס. מתקבלים רק קובצי PNG/JPEG/GIF/WebP/MP4/MOV/WebM/MKV/MPEG אמיתיים עד 500 MiB מתיקיית העבודה, התיקייה הזמנית, Pictures/Movies/Videos או SOSOAPI_UPLOAD_ROOTS; קבצים ותיקיות ששמם מתחיל בנקודה נדחים. מוחזרים מזהה הנכס וה-URL לשימוש במדיה של Scheduled Post.

• תעבורה: stdio.
• הרשאה נדרשת: agent:operate. תפקידים מינימליים בנתיב: editor.
• רמז קריאה בלבד: false. רמז אידמפוטנטיות: true. רמז עולם חיצוני: true.
• איך לבדוק את התוצאה: קראו את התגובה הסינכרונית.