קטלוג כלי ה-MCP · WIZZO CMS Docs

הדף הזה הוא הרפרנס לכלים ש-admin_mcp_tools::manifest() מפרסם ב-tools/list. לכל כלי מופיעים הקלט, האם הוא קורא או כותב, באיזה מסלול הוא רץ ואיך נאכפת ההרשאה. בסוף הדף מוסבר מה עושים __dry_run, __tool_call_id ותור האישורים.

שני מסלולי ביצוע

loopback: בקשת HTTP פנימית ל-{admin}/<panel>/<page> עם session זמני של המנהל. הרשאות הקבוצה נאכפות על ידי הפאנל עצמו. ישיר: גישה ל-DB או ל-STORAGE בלי בדיקת הרשאת פאנל. מעטפת התשובה הפנימית אחידה: ["ok"=>true,"data"=>[...]] או ["ok"=>false,"error"=>"...","extra"=>[...]|null].

כלי הפאנלים והנתונים#

כלי	קלט (חובה מודגש)	סוג	מסלול	הרשאה
`list_panels`	ללא	קריאה	ישיר: `CRM_adminPanel_panels` ו-`_options`	אין בדיקה. מחזיר גם `perm_developer`
`panel_schema`	panel, page, form_page, params	קריאה	loopback כפול (גילוי טבלה וגילוי טופס)	הפאנל. הפניה (redirect) אומרת "אין הרשאה"
`list_rows`	panel, pgnm, q, filters, order_by, order_dir, page, with_actions, params	קריאה	loopback, `tbl_action=get_lines`	הפאנל
`save_record`	panel, fields, id, form_page, params	כתיבה	loopback, POST של הטופס	הפאנל וולידציית הטופס
`set_field`	panel, field, `id`+`value` או `records[{id,value}]` (עד 50), page, params	כתיבה	loopback, `tbl_action=editable_field`	הפאנל. העמודה חייבת להיות `editable`
`form_action`	panel, id, action (כותרת הכפתור), form_page, params	כתיבה	loopback: גילוי הטופס ואז הפעלת הכפתור	הפאנל
`delete_record`	panel, id, page, params	כתיבה	loopback, `tbl_action=DELETE` (רק כשיש `has_delete`)	הפאנל
`db_query`	sql	קריאה	ישיר, `DB::get_all`	קבוצה עם `perms="-1"`, או כל טוקן עם `agent_id`
`db_schema`	table	קריאה	ישיר: רשימת טבלאות, עמודות, אינדקסים ושלוש שורות דוגמה	כמו `db_query`

כלי זיכרון ותקשורת של סוכנים#

כלי	קלט	סוג	הערות
`notify_admin`	message (עד 2000 תווים)	כתיבה	כותב ל-`CRM_admin_chat` בשם המנהל של הטוקן. תקרה: 3 הודעות לריצה. אינו נכנס לתור אישורים
`remember`	key (עד 190), value (עד 5000)	כתיבה	`CRM_ai_agents_memory` מסוג `work`. רק עם `agent_id`
`recall`	key או prefix	קריאה	רק עם `agent_id`. אם נשלח גם `value` הוא מנותב ל-`remember` ושומר
`update_playbook`	playbook (עד 4000)	כתיבה	מסוג `playbook`. אינו ב-`WRITE_TOOLS`, ולכן רץ באמת גם ב-dry-run
`claim_items`	panel, ids (עד 200), minutes (1 עד 120, ברירת מחדל 10)	כתיבה	lease שפג תוקפו. lease חי של ריצה אחרת חוסם, אותה ריצה מאריכה

כלי מדיה#

כלי	קלט	סוג	הערות
`generate_image`	prompt, image_size, attach{panel,id,field}	כתיבה (קרדיטים)	יוצר תמונה דרך `wizzo_ai::ai_image`, שומר ב-`STORAGE` ומצרף דרך `save_record`
`import_media`	url או data (עם filename), attach{panel,id,field,form_page}	כתיבה	`STORAGE::add` או `addFromBase64`. ה-attach עובר דרך הפאנל
`delete_media`	storage_id	כתיבה	`STORAGE::remove`, ישיר, בלי בדיקת הרשאת פאנל
`search_media`	q, ext, limit (עד 50)	קריאה	חיפוש `LIKE` בשם, תיאור, תגיות ו-copyrights, רק קבצים שאינם מוסתרים

כלים מותנים#

seo_changes ושאר כלי seo_* מופיעים כשה-SEO המאוחסן פעיל (SeoHosted::enabled()). ראו חבילת ה-SEO.
כלי אתר שנרשמו עם AGENT_TOOLS::add_tool (ראו כתיבת כלי MCP לאתר): הם כותבים רק אם הוגדר write => true.
כלי מוצרים <product>_<tool> (למשל kama_*, poosh_*, seok_*) שמגיעים מהשער החיצוני. ראו שרתי MCP חיצוניים.

שם שמור

AGENT_TOOLS::RESERVED חוסם רק 11 שמות: list_panels, panel_schema, list_rows, save_record, set_field, delete_record, db_query, notify_admin, remember, recall, claim_items. אל תשתמשו גם בשאר שמות הליבה (form_action, db_schema, update_playbook, generate_image, import_media, delete_media, search_media, seo_*) ולא בקידומות של מוצרים.

פרטי התנהגות#

panel_schema#

מחזיר {panel, table, table_error, form, form_error, form_mode, form_note}. השדה table הוא פלט panel_table::output_table_json() והשדה form הוא פלט Form::output_form_json() עם actions מצומצם. בפאנל מסוג "צור ואז ערוך" (עמוד insert שיוצר שורה ב-GET ומפנה) הקריאה הראשונה יוצרת שורה ריקה, לומדת את עמוד העריכה ומוחקת את השורה. התוצאה נשמרת ב-cache ל-30 יום, ומהקריאה השנייה הסכמה נקראת מהרשומה האחרונה.

שורת רפאים בקריאה הראשונה

ה-probe מוחק את השורה ב-DB::delete ישיר. אם לפאנל יש content tables, ייתכנו שאריות. __dry_run אינו מכסה את panel_schema.

list_rows#

ערכים מספריים ובוליאניים בפילטרים הופכים למחרוזות. הפלט כולל tblID, paging{page,total_pages,total_results,per_page,has_more}, warning כשמפתח פילטר אינו עמודה (הפאנל התעלם ממנו), ו-rows[{id, <field>: value, actions:[...]}]. עמודות עם select_options סטטיות חוזרות כ-label ולא כמפתח, ו-HTML בתאים מופשט לטקסט.

{
  "name": "list_rows",
  "arguments": {
    "panel": "articles",
    "pgnm": 1,
    "filters": { "is_active": "1", "date_created": ["2026-01-01", "2026-03-31"] },
    "order_by": "date_created",
    "order_dir": "desc"
  }
}

save_record#

fields שמגיע כמחרוזת JSON מפוענח. מחרוזת לא תקינה מחזירה שגיאה.
שדה יכול להיות שם מהטופס, תת-שדה של שדה מורכב (למשל meta_title ב-SEO), או <file_field>_sid עם storage_id קיים. ערך ריק, 0 או null לשדה קובץ בעדכון מנתק את הקובץ.
גלריה: [12,15] להוספה, או {add:[],remove:[],order:[]}. הפעולה מתבצעת אחרי השמירה.
בהוספה, שדות מסוג עורך טקסט, צבע ומספר שלא נשלחו מקבלים מחרוזת ריקה. בעדכון, שדות סקלריים שלא נשלחו ממולאים מה-DB, כדי שעדכון חלקי לא ינקה אותם.
שומר הקטנה: טקסט ארוך מ-2000 תווים שמוקטן ליותר ממחצית מגודלו נדחה, אלא אם נשלח allow_shrink: true.
הצלחה מזוהה בכותרת התשובה AI-New-ID: <id>. כשל ולידציה חוזר ב-AI-Form-Error ומתורגם ל-extra.validation_errors, required_but_empty ו-unknown_fields.
mode בתשובה הוא insert, update או create_then_edit.

{
  "name": "save_record",
  "arguments": {
    "panel": "articles",
    "id": 1234,
    "fields": { "title": "כותרת חדשה", "is_active": 1, "image_sid": 88 }
  }
}

שדות widget מותאמים

שדה מותאם (קטגוריות, תגיות) חייב לממש mcp_skip_absent() ב-get_results(), אחרת עדכון חלקי ינקה אותו. ה-MCP משחזר סקלרים אחרי השמירה, אבל לא JSON או יחסים.

set_field, form_action, delete_record#

set_field בודק שהעמודה קיימת ו-editable (אם לא נשלח tblID). הפאנל מחזיר action_result, ובמצב batch התשובה היא {updated, failed, results[]}. form_action מתאים את כותרת הכפתור (בלי רגישות לאותיות) לכפתורי הטופס במצב הנוכחי של הרשומה ומפעיל רק את ה-func של הכפתור, בלי לשמור שדות. delete_record פועל רק כשהפאנל מגדיר has_delete.

db_query ו-db_schema#

db_query מקבל SELECT, SHOW, DESCRIBE, DESC ו-EXPLAIN בלבד, בלי ; ובלי INTO OUTFILE או DUMPFILE. אין LIMIT כפוי. שם טבלה בלי CRM_ שנכשל מנוסה שוב עם הקידומת (note: auto-corrected). התשובה מוגבלת ל-500 שורות, תא ארוך מ-400 תווים נחתך, ו-payload מעל 20KB מצומצם.

{ "name": "db_query", "arguments": { "sql": "SELECT id, title FROM CRM_articles WHERE is_active = 1 ORDER BY id DESC LIMIT 20" } }

אזהרה

db_query פתוח לכל סוכן הכלי זמין לכל טוקן עם agent_id, לא רק לסופר-אדמין. אל תניחו שסוכן "רואה רק את הפאנל שלו". תכננו את מטרת הסוכן ואת רשימת הכלים שלו בהתאם, והגבילו עם allowed_tools או הסירו את cms:db_query.

הארגומנטים __dry_run ו-__tool_call_id#

שני מפתחות meta מוסרים מהארגומנטים לפני ה-dispatch:

__dry_run: true: כלי כתיבה (WRITE_TOOLS, כלי אתר עם write, כלי מוצר כותב) מדמה את הפעולה בלי לבצע אותה. קריאות רצות באמת. save_record בלי id מחזיר id שלילי סינתטי, ופעולות המשך עליו נשארות מדומות.
__tool_call_id: "<id>": בריצת סוכן, לפני ביצוע כתיבה נבדקת הטבלה CRM_ai_agents_tool_ledger לפי (run_id, tool_call_id). אם הקריאה כבר בוצעה, התוצאה השמורה חוזרת (idempotency לניסיון חוזר ברשת). בלי run_id (טוקן אנושי) אין ledger.

מה dry-run לא מכסה

panel_schema (שורת הרפאים), update_playbook, ו-recall שנשלח עם value (שומר באמת) רצים גם ב-dry-run. attach של generate_image ו-import_media כן מדומה.

תור האישורים approve_writes#

כשלסוכן מוגדר approval_mode = 'approve_writes', הכלים save_record, set_field, delete_record, form_action, delete_media, כלי אתר עם write=true וכלי מוצר כותבים לא מבוצעים. נכתבת שורה ב-CRM_ai_agents_approvals עם הארגומנטים (payload), הערכים הנוכחיים (__before) וחתימת md5 של הרשומה, והכלי מחזיר {queued_for_approval:true, approval_id, note}. ריצה עם אישורים ממתינים נסגרת בסטטוס waiting_approval.

אישור מתבצע ב-ai_agents_lib::decide_approval($id, $approve, $reason, $decided_by). דחייה מסמנת rejected ושומרת זיכרון feedback. אישור מריץ את הכלי בזהות מנהל-הבוט של הסוכן, אבל רק אם הרשומה לא השתנתה מאז (אחרת הסטטוס stale). ראו סוכני AI.

ה-loopback בפירוט#

ה-session נוצר ב-CRM_adminPanel_sessions לתקופה של 600 שניות.
הכתובת: env_url + admin_url + <panel>[/<page>][/<id>][?params]. ב-params מותרים סקלרים בלבד, ומפתחות בתווים [a-zA-Z0-9_].
כותרות: Cookie: CRM_admin_session=<token>, AI-Client: mcp, ועוד אחת מ-AI-Table-Discovery, AI-Form-Discovery, AI-Form-Insert.
cURL ללא מעקב redirect (הפניה אומרת שאין הרשאה או שהפאנל לא קיים), timeout של 60 שניות.
שגיאה חוזרת כ-HTTP <code> עם הסיבה מהכותרת AI-Error, מגוף JSON, או כ-"Call to undefined method".