اتصال ابزارهای AI (Connect AI Tools)

راه‌اندازی یک‌باره با agents init

پس از نصب بسته (با دو خط .npmrc بخش نصب)، در پوشهٔ اپ و در یک ترمینال معمولی:

npx --no parto-ui agents init --scope app

این فرمان کار یک نفر است: اگر درون Claude Code یا Codex اجرا شود، اجرا نمی‌شود و از عامل می‌خواهد آن را به شما بسپارد. خروجی آن این فایل‌ها را می‌سازد و همه باید در git ثبت شوند:

check با ESLint و TypeScript خود پروژه کار می‌کند؛ اگر eslint، typescript-eslint یا typescript نصب نباشد، agents init دستور نصب هر سه را در یک خط چاپ می‌کند. Claude Code را یک بار در همین پوشه باز کنید و پوشه را trusted کنید (تا آن زمان مجوزهای .claude/settings.json نادیده گرفته می‌شوند، ولی مهارت‌ها، AGENTS.md و هوک‌ها کار می‌کنند)؛ در Codex پروژه را trusted کنید و هوک‌ها را یک بار در /hooks تأیید کنید.

تأیید اتصال

• Claude Code: از عامل بپرسید «مهارت‌هایی که با parto-ui شروع می‌شوند کدام‌اند؟». باید پنج مهارت parto-ui-build-page، parto-ui-check، parto-ui-choose-component، parto-ui-migrate-page و parto-ui-report-gap را نام ببرد و پیام شروع نشست را با «Parto DS … installed» نقل کند.
• Codex: codex debug prompt-input "hi" در پوشهٔ اپ هم بلوک AGENTS.md و هم همان پنج مهارت را نشان می‌دهد.
• npx --no parto-ui check --changed روی یک صفحهٔ درست PASS می‌دهد، و روی رنگ hex، <h1> خام در قالب، دکمهٔ primary دوم یا max-w-[720px] هر مورد را با خط، قاعده و راه اصلاح گزارش می‌کند.

MCP Server — مسیر استاندارد

MCP یک پروتکل باز است که در modelcontextprotocol.io تعریف شده و توسط Claude Code، Cursor، VS Code Copilot، Windsurf، Antigravity، Cline و دیگر ابزارها پشتیبانی می‌شود.

ابزارهای موجود در MCP پرتو

@partodata/mcp-server هم مثل @partodata/ui در رجیستری خصوصی پکیج‌های گیت‌لبِ شرکت منتشر می‌شود؛ با همان دو خط .npmrc پروژه، npx -y @partodata/mcp-server@3 از آنجا دریافت می‌شود. در پروژه‌ای که @partodata/ui را نصب کرده، npx --no parto-ui agents init --mcp (پس از نصب @partodata/mcp-server در همان پروژه) مدخل سرور را برای Claude Code (.mcp.json) و Codex (.codex/config.toml) با نسخهٔ نصب‌شده می‌نویسد.

parto_component نام هر قالب صفحه (ListPage، DetailPage، FormPage و …) و هر جزء یک خانواده (مثل DropdownMenuItem) را هم می‌شناسد؛ برای جزء، کارت خانوادهٔ آن را برمی‌گرداند. متن کامل همهٔ propها همیشه npx --no parto-ui docs <Name> است.

Claude Code

فایل .mcp.json را در ریشه پروژه بسازید:

{
  "mcpServers": {
    "parto": {
      "command": "npx",
      "args": ["-y", "@partodata/mcp-server@3"]
    }
  }
}

Cursor

فایل .cursor/mcp.json را در ریشه پروژه بسازید:

{
  "mcpServers": {
    "parto": {
      "command": "npx",
      "args": ["-y", "@partodata/mcp-server@3"]
    }
  }
}

برای اعمال در همه پروژه‌ها، همان فایل را در ~/.cursor/mcp.json قرار دهید.

VS Code (GitHub Copilot)

فایل .vscode/mcp.json را بسازید. توجه کنید که VS Code کلید servers (نه mcpServers) را استفاده می‌کند:

{
  "servers": {
    "parto": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@partodata/mcp-server@3"]
    }
  }
}

Windsurf

تنظیمات MCP در ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "parto": {
      "command": "npx",
      "args": ["-y", "@partodata/mcp-server@3"]
    }
  }
}

Windsurf همچنین فایل AGENTS.md ریشه پروژه را به‌طور خودکار می‌خواند (به بخش بعدی مراجعه کنید).

Google Antigravity

از v1.20.x به بعد، Antigravity پشتیبانی per-workspace MCP دارد. تنظیمات MCP را از طریق Settings → MCP اضافه کنید یا فایل کانفیگ workspace را ویرایش کنید:

{
  "mcpServers": {
    "parto": {
      "command": "npx",
      "args": ["-y", "@partodata/mcp-server@3"]
    }
  }
}

مرجع: antigravity.google/docs/mcp

Gemini CLI

فایل ~/.gemini/settings.json را ویرایش کنید:

{
  "mcpServers": {
    "parto": {
      "command": "npx",
      "args": ["-y", "@partodata/mcp-server@3"]
    }
  }
}

Cline / Roo

از تب MCP در پنل افزونهٔ Cline، یا مستقیماً در cline_mcp_settings.json:

{
  "mcpServers": {
    "parto": {
      "command": "npx",
      "args": ["-y", "@partodata/mcp-server@3"]
    }
  }
}

ترنسپورت HTTP — برای IDEهای ابری و سلف-هاست

هیچ remote عمومی برای checkout سورس یا URL عمومی برای بستهٔ سورس تأیید نشده است. از مسئول انتشار یک approved source remote همراه شناسهٔ کامل commit تغییرناپذیر و بازبینی‌شده، یا یک verified signed source bundle مشخص‌کنندهٔ همان commit کامل دریافت کنید. پیش از استفاده، امضای بسته و manifest شناسهٔ commit را بررسی و تأیید کنید. لینک مستندات و پکیج npm، remote دریافت سورس نیست. ارجاع‌های تاریخی انتشار، دستور دریافت نسخهٔ جاری نیستند.

برای IDE ابری یا یک نمونهٔ مشترک تیمی، می‌توانید سرور را به‌صورت HTTP اجرا کنید. نمونهٔ Compose از checkout تأییدشدهٔ بالا image محلی می‌سازد:

git checkout --detach <full-reviewed-commit-sha>
git status --porcelain # نباید خروجی داشته باشد
docker compose -f packages/mcp-server/examples/docker-compose.yml up -d --build
curl http://localhost:3333/health

این دستور را از ریشهٔ checkout تأییدشدهٔ Parto UI اجرا کنید. اگر هیچ‌کدام از دو مسیر دریافت تأییدشده در دسترس نیست، تا انتشار یک digest-pinned image صبر کنید. این مسیر فعلاً image عمومی را وعده نمی‌دهد.

سپس به‌جای command/args از کلید url استفاده کنید:

{
  "mcpServers": {
    "parto": { "url": "http://localhost:3333/mcp" }
  }
}

VS Code شکل کمی متفاوت دارد:

{
  "servers": {
    "parto": { "type": "http", "url": "http://localhost:3333/mcp" }
  }
}

برای استقرار سازمانی، فایل نمونهٔ packages/mcp-server/examples/docker-compose.yml را در همان checkout یا بستهٔ امضاشدهٔ تأییدشده استفاده کنید. در این نسخه هیچ endpoint عمومی MCP با بررسی خارجی تأیید نشده است؛ نشانی استقرار خود را پس از بررسی اتصال استفاده کنید. انتشار نشانی عمومی در مستندات و metadata به تأیید خارجی استقرار توسط release owner نیاز دارد.

تأیید اتصال MCP

پس از تنظیم، ابزار را ری‌استارت کنید و بپرسید: «با ابزار parto_component کارت ListPage را بیاور». پاسخ باید مسیر @partodata/ui/templates، propهای state و title و نمونهٔ npx --no parto-ui example list-page را داشته باشد. اگر ابزار به ساختار عمومی shadcn برگشت، MCP وصل نیست.

ابزارهای بدون MCP و بدون مهارت

AGENTS.md همراه بسته (node_modules/@partodata/ui/AGENTS.md) راهنمای کامل هم‌نسخه است؛ آن را در مخزن کپی نکنید. Claude Code و Codex آن را از راه بلوکی که agents init می‌نویسد می‌خوانند. برای ابزار دیگر، از فایل قواعد همان ابزار به آن ارجاع دهید:

رابط کاربری با @partodata/ui ساخته می‌شود؛ پیش از نوشتن UI، node_modules/@partodata/ui/AGENTS.md را بخوانید و
کار را با npx --no parto-ui check --changed تمام کنید.

فایل‌های آمادهٔ Cursor (parto.mdc)، Copilot (copilot-instructions.md)، Gemini CLI (GEMINI.md) و Windsurf (windsurf-rule.md) در پوشهٔ ai-context/ مخزن سیستم طراحی‌اند، نه در بسته.

مقایسه روش‌ها

توصیه: در Claude Code و Codex همیشه agents init؛ MCP برای ابزارهای دیگر یا با --mcp در کنار آن.

مرجع سریع — تک‌خطی برای هر ابزار

دستور run یکی است: npx -y @partodata/mcp-server@3 (برای پروژهٔ روی نسخهٔ 4: @partodata/mcp-server@2؛ روی نسخهٔ 3: @1)