שרת MCP

שרת ה-MCP (Model Context Protocol) של SupDesk נותן לעוזרי AI ולכלים אחרים מבוססי LLM גישה ישירה למרכז העזרה, ללוח המשוב, ליומן השינויים, לשרשורי ההודעות, לתוכניות הבטא ולרשימת ההמתנה של פרויקט.

נקודת קצה

https://mcp.supdesk.app/mcp

אימות

העבירו מפתח API כאסימון Bearer:

Authorization: Bearer sd_live_...

הפיקו מפתחות בקונסולת SupDesk תחת הגדרות סביבת העבודה ← מפתחות API.

המפתח קובע את הפרויקט, ולכן אף כלי אינו מקבל ארגומנט project_id — אין מה שמודל יוכל לנחש או לטעות בו.

מה אתם מקבלים

אילו כלים מופיעים תלוי בפרויקט. ליכולת שכובתה בהגדרות הפרויקט הכלים מושמטים לגמרי מ-tools/list, בדיוק כפי שה-REST API מחזיר 404 לנתיבים האלה.

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

מרכז עזרה

• list_articles — מאמרים, לפי העריכה האחרונה תחילה. כולל טיוטות ומאמרים בארכיון; סננו עם status כדי לקבל את מה שהלקוחות יכולים לראות.
• get_article — מאמר אחד לפי מזהה, כולל גוף ה-Markdown שלו.
• search_articles — חיפוש טקסט מלא על מאמרים שפורסמו, מדורג, עם קטע.
• create_article — יוצר טיוטה. הפרסום הוא קריאה נפרדת, כך ששום דבר אינו מגיע ללקוחות בטעות.
• update_article — עדכון כל שדה; קבעו status ל-published או ל-archived.
• delete_article — לצמיתות; העבירו לארכיון במקום כדי להוציא משימוש מאמר שברצונכם לשמור.
• list_article_categories, create_article_category, update_article_category, delete_article_category — מחיקת קטגוריה משאירה את המאמרים שלה במקומם, ללא סיווג.

גוף המאמרים הוא Markdown, לא HTML. הפורטל מציג אותם דרך מציג שלעולם אינו מריץ HTML, כך ש-HTML מגיע לקוראים כטקסט מילולי.

create_article נכשל עם limit_reached ברגע שמכסת המאמרים של התוכנית מוצתה — Free 5, Pro 50, Team ללא הגבלה.

לוח משוב

• list_feedback — פוסטים, החדשים ביותר תחילה. מכסה את כל שלושת הסוגים (bug, feature, feedback) אלא אם כן תצמצמו עם type.
• get_feedback, create_feedback, update_feedback — update_feedback הוא הדרך להעביר פוסט לאורך backlog → open → planned → in_progress → done.
• delete_feedback — מסיר את הפוסט, את ההצבעות ואת התגובות שלו.

יומן שינויים, הודעות, בטא ורשימת המתנה

זהות מלאה עם ה-REST API, על אותן שאילתות:

• יומן שינויים — list_changelog, get_changelog_entry, create_changelog_entry, update_changelog_entry, delete_changelog_entry. הרשומות הן טיוטה כברירת מחדל, כי הפרסום הוא מה ששולח מייל למנויים שלכם.
• הודעות — list_threads, get_thread (עם היסטוריית ההודעות המלאה), create_thread, reply_to_thread, update_thread.
• בדיקות בטא — list_beta_programs, get_beta_program, create_beta_program, update_beta_program, delete_beta_program, list_beta_testers, add_beta_tester, remove_beta_tester. add_beta_tester הוא אידמפוטנטי לפי אימייל ומחזיר את אסימון האישור; השרת הזה אינו שולח מייל, ולכן מסירת ההזמנה היא באחריותכם.
• רשימת המתנה — list_waitlist, add_waitlist_signup (אידמפוטנטי לפי אימייל), update_waitlist_signup, remove_waitlist_signup.

סקירה

project_stats מחזיר ספירות ברחבי הפרויקט — פוסטי משוב לפי סטטוס, שרשורים פתוחים, מאמרים שפורסמו ומאמרים בטיוטה, וההצבעות מועיל / לא מועיל שהמאמרים האלה צברו — כך שסוכן יכול לענות על “כמה נשאר לטפל?” בלי לעבור על ארבע רשימות מדופדפות.

פלט מובנה

כל כלי מצהיר על outputSchema ומחזיר גם structuredContent (מוקלד ומאומת) וגם בלוק טקסט content שמחזיק את אותם נתונים כ-JSON. פענחו את מה שהלקוח שלכם תומך בו.

const result = await mcpClient.callTool("get_article", { id: "8f7a..." });
 
result.structuredContent.article.title;   // typed
JSON.parse(result.content[0].text);       // same payload, fallback

הערות מטא

כל כלי נושא הערות מטא כדי שלקוח יידע מה הוא מפעיל לפני שהוא מפעיל אותו:

דפדוף

כלי הרשימה מקבלים cursor אטום ומחזירים next_cursor — העבירו אותו חזרה לעמוד הבא, ועצרו כשהוא null.

let cursor;
do {
  const page = await mcpClient.callTool("list_articles", { status: "published", cursor });
  handle(page.structuredContent.data);
  cursor = page.structuredContent.next_cursor;
} while (cursor);

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

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

משאבים

לצירוף תוכן של הפרויקט כהקשר, במקום לקרוא לכלי ולהדביק את התוצאה:

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

פרומפטים

שתי נקודות פתיחה, מחוברות לנתונים האמיתיים של הפרויקט:

• draft_article_from_thread — הופך שיחת תמיכה שנפתרה למאמר במרכז העזרה, כך שהלקוח הבא עם אותה שאלה ימצא את התשובה במקום לפתוח שרשור. דורש שמרכז העזרה וגם ההודעות הפרטיות יהיו מופעלים.
• triage_feedback — מעריך פוסט אחד וממליץ על סטטוס, עם הנימוק. הוא בודק תחילה ב-search_articles, כך שתשובה קיימת מוצפת במקום שתוצע עבודה חדשה.

שניהם משתמשים ביכולת ההשלמה של MCP עבור הארגומנטים שלהם: תוך כדי הקלדת קטגוריה, השרת עונה עם ה-slugs של הקטגוריות האמיתיות של הפרויקט במקום להשאיר אתכם לנחש.

רישום

פעולות כתיבה מרובות-שלבים שולחות התראות התקדמות דרך רישום MCP — create_article בודק את מכסת התוכנית, מחפש slug פנוי, ואז מוסיף, ומדווח על כך בכל שלב. לקוח ללא תמיכה ברישום אינו מושפע; הכתיבה מתבצעת כך או כך.

דוגמאות

Claude Desktop

הוסיפו אל ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "sup-desk": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.supdesk.app/mcp",
        "--header",
        "Authorization: Bearer sd_live_..."
      ]
    }
  }
}

לענות על שאלה, או לכתוב את התשובה

// Check whether the help center already covers it.
const hits = await mcpClient.callTool("search_articles", {
  query: "reset password",
  limit: 5
});
 
if (hits.structuredContent.data.length === 0) {
  // Nothing yet — draft one. It's created as a draft.
  const created = await mcpClient.callTool("create_article", {
    title: "How do I reset my password?",
    body: "Open **Settings**, then choose *Reset password*.",
    category_id: "3c2b..."
  });
 
  // Publishing is deliberate and separate.
  await mcpClient.callTool("update_article", {
    id: created.structuredContent.article.id,
    status: "published"
  });
}

לטפל בלוח

const open = await mcpClient.callTool("list_feedback", {
  status: "open",
  limit: 10
});
 
await mcpClient.callTool("update_feedback", {
  id: open.structuredContent.data[0].id,
  status: "planned"
});

כל מה שנותר, בקריאה אחת

const stats = await mcpClient.callTool("project_stats", {});
// { posts_by_status: { open: 12, planned: 3, ... }, open_threads: 4,
//   articles_published: 18, articles_draft: 2,
//   article_helpful: 240, article_not_helpful: 11 }

מגבלות קצב

שרת ה-MCP חולק את המגבלות של ה-REST API: 120 בקשות ב-60 שניות לכל פרויקט. ראו מגבלות קצב ושימוש.

שגיאות

קריאת כלי שנכשלת מחזירה isError: true עם אותו אוצר מילים של שגיאות שה-REST API משתמש בו:

{
  "error": {
    "code": "limit_reached",
    "message": "Your plan allows 5 help-center articles."
  }
}

הרשימה המלאה מתועדת תחת שגיאות.