Novamira Tchibo — ابزارهای ووکامرس

افزونه‌ی جانبی برای Novamira که مجموعه‌ای از ابزارهای MCP سفارشی برای یک فروشگاه ووکامرس ثبت می‌کند تا ایجنت‌های هوش مصنوعی بتوانند محصولات، رسانه، سفارش‌ها و سئو را از طریق ابزارهای امن و هدفمند مدیریت کنند — به‌جای اجرای مستقیم کد PHP.

ساخته‌شده برای tchibokurdeh.ir.

سلب مسئولیت: این یک افزونه‌ی جانبیِ مستقل و متن‌باز است و به‌صورت رسمی به شرکت Novamira (Dynamic.ooo) وابسته، تأییدشده یا پشتیبانی‌شده نیست. نام «Novamira» صرفاً برای اشاره به سازگاری با آن محصول به‌کار رفته است.

چرا؟

Novamira به ایجنت دسترسی کامل به وردپرس از طریق اجرای PHP می‌دهد. این قدرتمند است اما برای کارهای تکراری فروشگاه، هم پرخطر و هم کند است. این افزونه ابزارهای ساختارمند و اعتبارسنجی‌شده ارائه می‌دهد — هر کدام با اسکیمای ورودی/خروجی و بررسی دسترسی — تا ایجنت کارهای رایج ووکامرس را قابل‌اعتماد و ایمن انجام دهد.

پیش‌نیازها

• وردپرس ۶.۹+ (برای Abilities API)
• PHP ۸.۰+
• WooCommerce
• Novamira
• RankMath (فقط برای ابزارهای سئو)

افزونه این‌ها را به‌عنوان وابستگی سخت (Requires Plugins) اعلام می‌کند و اگر هرکدام نصب نباشند یک پیام هشدار در پیشخوان نشان می‌دهد و تا زمان نصب آن‌ها اجرا نمی‌شود.

ابزارها

محصولات متغیر (Variable Products)

ابزار	توضیح
tchibo/variable-product-create	ساخت محصول متغیر با ویژگی‌ها و تنوع‌ها در یک فراخوانی
tchibo/variable-product-get	خواندن محصول والد + همه‌ی تنوع‌ها (موجودی، قیمت، SKU، ویژگی‌ها)
tchibo/variable-product-update	به‌روزرسانی فیلدهای والد (نام، توضیحات، دسته‌ها، وضعیت، …)
tchibo/variation-update-stock	به‌روزرسانی گروهی موجودی هر تنوع
tchibo/variation-update-price	به‌روزرسانی گروهی قیمت عادی/حراج هر تنوع
tchibo/variation-delete	حذف یا غیرفعال‌کردن تنوع‌های مشخص
tchibo/tags-set	تنظیم برچسب‌های محصول با نام و ساخت خودکار برچسب‌های ناموجود

مثال‌های کاربردی

تنظیم تگ‌های محصول

{
  "product_id": 123,
  "tags": ["پرفروش", "جدید", "حراج"],
  "append": false
}

ساخت محصول متغیر با مقدار پیش‌فرض برای ویژگی‌ها

{
  "name": "تی‌شرت تابستانی",
  "type": "variable",
  "default_attributes": {
    "pa_size": "l",
    "pa_color": "black"
  }
}

کتابخانه‌ی رسانه (Media)

ابزار	توضیح
tchibo/media-upload-from-url	وارد کردن تصویر از URL به کتابخانه‌ی رسانه (با WP HTTP API، بدون exec/WP-CLI)
tchibo/media-upload-base64	آپلود تصویر از داده‌ی base64 (حداکثر ۸ مگابایت، بدون نیاز به دسترسی مستقیم شبکه)
tchibo/media-set-alt-text	تنظیم متن جایگزین (alt) یک پیوست
tchibo/media-attach-to-product	تنظیم تصویر شاخص و/یا گالری محصول (product_id، featured_id، gallery_ids، gallery_mode)
tchibo/media-delete-unused	یافتن/حذف تصاویر بی‌استفاده — پیش‌فرض dry_run: true

سفارش‌ها (فقط خواندنی، سازگار با HPOS)

ابزار	توضیح
tchibo/orders-query	جستجوی سفارش‌ها بر اساس وضعیت/مشتری/محصول/تاریخ با صفحه‌بندی
tchibo/orders-get	جزئیات کامل یک سفارش (آیتم‌ها، مبالغ، آدرس‌ها)

سئو (RankMath)

ابزار	توضیح
tchibo/seo-batch-get	خواندن rank_math_title / description / focus_keyword برای چند پست
tchibo/seo-batch-update	به‌روزرسانی گروهی متای سئوی RankMath روی چند پست/محصول

نصب

1. زیپ افزونه را دانلود کنید (یا این ریپو را داخل wp-content/plugins/novamira-tchibo کلون کنید).
2. در پیشخوان وردپرس ← افزونه‌ها ← افزودن ← بارگذاری افزونه، زیپ را انتخاب کنید.
3. فعال کنید. ووکامرس و Novamira باید از قبل فعال باشند.

معماری

هر بخش قابلیت، یک ماژول مستقل زیر پوشه‌ی includes/ است:

novamira-tchibo.php          # هدر، ثابت‌ها، راه‌اندازی
includes/
  helpers.php                # دسترسی مشترک، ساختار خطا، راهنمای discover-abilities
  variable-products/         # bootstrap.php + class-service.php + abilities/
  media/
  orders/
  seo/

هر ماژول از یک الگوی یکسان پیروی می‌کند: یک bootstrap.php که دسته‌ی قابلیت را ثبت و فایل‌های abilities/*.php را بارگذاری می‌کند، یک class-service.php برای منطق کسب‌وکار، و یک فایل برای هر ابزار. همه‌ی ابزارها یک permission callback مشترک و یک ساختار خطای یکسان { success: false, error } دارند.

ایمنی

• تا حد امکان فقط‌خواندنی — ابزارهای سفارش هرگز نمی‌نویسند؛ با readonly/idempotent علامت‌گذاری شده‌اند.
• عملیات مخرب اختیاری‌اند — media-delete-unused به‌صورت پیش‌فرض dry_run: true است.
• کنترل دسترسی — هر ابزار نیازمند manage_woocommerce (یا بررسی دسترسی خود Novamira) است.
• اعتبارسنجی اسکیما — ورودی‌ها پیش از رسیدن به PHP با JSON Schema محدود می‌شوند.

مجوز

AGPL-3.0-or-later — سازگار با لایسنس Novamira.

---

Novamira Tchibo — WooCommerce Tools

A companion plugin for Novamira that registers custom MCP abilities for a WooCommerce store, so AI agents can manage products, media, orders and SEO through safe, purpose-built tools instead of raw PHP execution.

Built for tchibokurdeh.ir.

Disclaimer: This is an independent, open-source companion plugin. It is not officially affiliated with, endorsed by, or supported by Novamira (Dynamic.ooo). The name "Novamira" is used only to indicate compatibility with that product.

Why

Novamira gives an AI agent full access to WordPress via PHP execution. That is powerful but risky and slow for repetitive store tasks. This plugin exposes structured, validated abilities — each with an input/output schema and a permission check — so the agent can do common WooCommerce work reliably and safely.

Requirements

• WordPress 6.9+ (for the Abilities API)
• PHP 8.0+
• WooCommerce
• Novamira
• RankMath (only for the SEO tools)

The plugin declares these as hard dependencies (Requires Plugins header) and shows an admin notice if any are missing — it will not run until they are present.

Abilities

Variable Products

Ability	Description
tchibo/variable-product-create	Create a variable product with attributes and variations in one call
tchibo/variable-product-get	Read parent + all variations (stock, price, SKU, attributes)
tchibo/variable-product-update	Update parent fields (name, description, categories, status, …)
tchibo/variation-update-stock	Bulk update stock per variation
tchibo/variation-update-price	Bulk update regular/sale price per variation
tchibo/variation-delete	Delete or disable specific variations
tchibo/tags-set	Set product tags by name and auto-create missing tags

Practical examples

Set product tags

{
  "product_id": 123,
  "tags": ["best seller", "new", "sale"],
  "append": false
}

Create a variable product with default attributes

{
  "name": "Summer T-Shirt",
  "type": "variable",
  "default_attributes": {
    "pa_size": "l",
    "pa_color": "black"
  }
}

Media Library

Ability	Description
tchibo/media-upload-from-url	Import a remote image into the Media Library (WP HTTP API, no exec/WP-CLI)
tchibo/media-upload-base64	Upload an image from base64 data (up to 8 MB, without direct network access)
tchibo/media-set-alt-text	Set an attachment's alt text
tchibo/media-attach-to-product	Set a product featured image and/or gallery (product_id, featured_id, gallery_ids, gallery_mode)
tchibo/media-delete-unused	Find/delete unreferenced images — dry_run: true by default

Orders (read-only, HPOS-compatible)

Ability	Description
tchibo/orders-query	Search orders by status/customer/product/date with pagination
tchibo/orders-get	Full detail of a single order (items, totals, addresses)

SEO (RankMath)

Ability	Description
tchibo/seo-batch-get	Read rank_math_title / description / focus_keyword for many posts
tchibo/seo-batch-update	Bulk update RankMath SEO meta across many posts/products

Installation

1. Download the plugin ZIP (or clone this repo into wp-content/plugins/novamira-tchibo).
2. In WP Admin → Plugins → Add New → Upload Plugin, select the ZIP.
3. Activate. WooCommerce and Novamira must be active first.

Architecture

Each feature area is a self-contained module under includes/:

novamira-tchibo.php          # header, constants, bootstrap
includes/
  helpers.php                # shared permission, error envelope, discover-abilities guidance
  variable-products/         # bootstrap.php + class-service.php + abilities/
  media/
  orders/
  seo/

Every module follows the same pattern: a bootstrap.php that registers the ability category and loads its abilities/*.php files, a class-service.php holding the business logic, and one file per ability. All abilities share one permission callback and a common { success: false, error } failure envelope.

Safety

• Read-only where possible — order tools never write; they are annotated readonly/idempotent.
• Destructive ops are opt-in — media-delete-unused defaults to dry_run: true.
• Permission-gated — every ability requires manage_woocommerce (or Novamira's own capability check).
• Schema-validated — inputs are constrained by JSON Schema before reaching PHP.

License

AGPL-3.0-or-later — compatible with Novamira's license.