# راهنمای استفاده
پنل **استودیوی MCP** از دو تب تشکیل شده است — «کاتالوگ» برای پیدا کردن و نصب سرور، و «نصب‌شده‌ها» برای
مدیریت سرورهایی که داری. بالای هر دو تب یک سرصفحه با دکمه‌های **برون‌ریزی patch** و **تازه‌سازی**، و
یک نوار تشخیص محیط اجرا داری. کشوی جزئیات هر سرور سه تب «ابزارها»، «لاگ‌ها» و «تنظیمات» دارد، و کارت
**رازها** پایین تب «نصب‌شده‌ها» است.
## باز کردن پنل
۱. Harness را اجرا کن: `dsh web`
۲. را باز کن.
۳. روی آیکن **استودیوی MCP** در نوار کناری کلیک کن.
افزونه خودش یک بستهٔ زبان به نام **فارسی** ثبت می‌کند. اگر Harness روی زبانی دیگر است، از تنظیمات زبان
همان را انتخاب کن؛ بعد از آن پنل راست‌به‌چپ و فارسی می‌شود.
## تب کاتالوگ
هر ردیف یک سرور قابل نصب است. بالای فهرست یک کادر جست‌وجو، یک فیلتر دسته و یک فیلتر منبع داری:
- **همراه** — ۳۴ سروری که همراه خود افزونه می‌آیند و بدون اینترنت کار می‌کنند.
- **رجیستری** — نتیجهٔ جست‌وجو در رجیستری رسمی MCP. اگر اینترنت نباشد، پنل همان فهرست همراه را نشان
می‌دهد و در ردیف وضعیت می‌گوید رجیستری در دسترس نبوده است.
نشان «بدون اینترنت» یعنی آن ردیف از فهرست همراهِ افزونه می‌آید. نشان «{n} ورودی لازم» یعنی پیش از نصب
باید چند مقدار را وارد کنی.
روی **نصب** بزن تا فرم باز شود.
## فرم نصب (اول آزمایش، بعد نصب)
فرم همان چیزی را می‌پرسد که آن سرور لازم دارد:
- ورودی‌های **لازم** تا پر نشوند، دکمهٔ نصب فعال نمی‌شود.
- ورودی‌های **حساس** به‌جای `servers.json` در انبار راز ذخیره می‌شوند و در پاسخ‌ها فقط نامشان می‌آید.
- در هر ورودی می‌توانی به‌جای مقدار خام، `${env:NAME}` یا `${secret:NAME}` بنویسی.
ترتیب کار پیشنهادی: فرم را پر کن، **آزمون اتصال** را بزن، و اگر سبز شد **نصب** کن. هر دو دکمه یک مسیر
را می‌روند: قالب‌بندی نهایی را خود میزبان انجام می‌دهد و یک پیش‌نویس می‌سازد؛ آزمون آن پیش‌نویس را یک‌بار
واقعاً وصل می‌کند و نصب همان را ذخیره می‌کند.
آزمون یک نمونهٔ واقعی از سرور را راه می‌اندازد (فرایند `stdio` یا یک درخواست HTTP) و نام و نسخهٔ خودش،
نسخهٔ پروتکل، فهرست ابزارهای کشف‌شده و مدت زمان را می‌گوید. اگر خطا بدهد، همان‌جا دلیلش را می‌بینی؛ چیزی
ذخیره نمی‌شود. آزمون با یک نام موقت اجرا می‌شود، پس نمی‌تواند سرور زندهٔ هم‌نام را جابه‌جا کند.
وقتی نصب را تأیید کنی، سرور در انبار افزونه ذخیره و بی‌درنگ سوار می‌شود — نیازی به ریاستارت Harness نیست.
## تب نصب‌شده‌ها
بالای تب دو دکمه داری: **افزودن دستی** و **تازه‌سازی**. اگر میزبان پاسخ ندهد، یک یادداشت هشدار می‌دهد که
وضعیت‌ها ممکن است کهنه باشند.
هر ردیف نام، نشان وضعیت، خلاصهٔ مقصد اتصال (مثلاً `npx -y @modelcontextprotocol/server-memory`)،
فضای نام `mcp__<نام سرور>__*`، تعداد ابزارها و در صورت لزوم برچسب «از رازهای ذخیره‌شده استفاده می‌کند»
را نشان می‌دهد. اگر اتصال خطا داده باشد، متن آخرین خطا زیر همان ردیف می‌آید.
| وضعیت | معنی |
| --- | --- |
| وصل | اتصال برقرار است و ابزارها ثبت شده‌اند |
| در حال اتصال | نمونهٔ سرور در حال راه‌اندازی است |
| خطا | اتصال برقرار نشد؛ متن خطا زیر ردیف می‌آید |
| غیرفعال | پیکربندی هست ولی سوار نشده است |
| متوقف | سرور از طرف خودش یا به‌دلیل خطا کنار رفته است |
کارهای هر ردیف:
- **فعال‌کردن / غیرفعال‌کردن** — بدون حذف پیکربندی، سرور را سوار یا پیاده می‌کند.
- **راه‌اندازی دوباره** — اتصال را قطع و از نو برقرار می‌کند. وقتی سروری خطا داده، همین کار راه‌حل است.
- **ویرایش** — کشوی سرور را باز می‌کند، روی تب «تنظیمات»؛ تب‌های «ابزارها» و «لاگ‌ها» هم همان‌جا هستند.
- **حذف** — سرور را پیاده می‌کند و پیکربندی‌اش را پاک می‌کند؛ پیش از حذف یک تأیید درون‌خطی نشان داده می‌شود.
## کشوی جزئیات
کشو سه تب دارد:
- **ابزارها** — فهرست ابزارهای خام سرور. هر ابزار با `mcp__<نام سرور>__<نام ابزار>` صدا زده می‌شود.
- **لاگ‌ها** — خطوط این سرور، تازه‌به‌تازه و با پیمایش خودکار وقتی در انتهای فهرست باشی. حافظهٔ لاگ در RAM
است و برای هر سرور سقف دارد (پیش‌فرض ۵۰۰ خط)؛ خطوط قدیمی‌تر حذف می‌شوند. اگر میزبان پاسخ ندهد، پنل
هر دو ثانیه دوباره تلاش می‌کند و پیام «در انتظار میزبان…» را نشان می‌دهد. «پاک‌کردن نما» فقط چیزی است
که می‌بینی.
- **تنظیمات** — عنوان، توضیح، دو تنظیم رفتاری و خلاصهٔ خواندنی پیکربندی. مقدار رازها همیشه ستاره‌دار
نشان داده می‌شود و فقط نام کلیدها می‌آید.
- **Fail activation on startup error** — اگر روشن باشد، شکست اتصال هنگام بالا آمدن Harness افزونه را
متوقف می‌کند؛ خاموش باشد، سرور فقط با وضعیت خطا نشان داده می‌شود.
- **Tool-call timeout** — سقف زمانی هر فراخوانی ابزار، به میلی‌ثانیه.
## مدیریت رازها
پایین تب «نصب‌شده‌ها» یک کارت **رازها** هست:
- مقدارها در `$DSH_HOME/mcp-studio/secrets.json` می‌مانند، نه در `servers.json`.
- در پیکربندی فقط `${secret:NAME}` نوشته می‌شود. روی ویندوز مجوز فایل به کاربر جاری محدود می‌شود؛
روی سیستم‌های دیگر فایل با مجوز `0600` نوشته می‌شود.
- فقط **نام** رازها نمایش داده می‌شود؛ مقدار هرگز از میزبان به مرورگر خوانده نمی‌شود.
- یک راز را می‌توانی اضافه، جایگزین یا حذف کنی — یکی‌یکی. یک کادر صاف هم برای پیدا کردن نام‌ها هست.
- حذف رازی که سروری هنوز به آن ارجاع می‌دهد با خطای `secret-in-use` رد می‌شود؛ اول آن سرور را اصلاح یا
حذف کن.
## تشخیص محیط اجرا
بالای هر دو تب یک نوار هست. اگر همه‌چیز در دسترس باشد، یک خط سبز همین را می‌گوید. اگر چیزی نباشد، فقط
موارد نبود را فهرست می‌کند — `node`، `npx`، `npm`، `pnpm`، `bunx`، `uvx`، `python` و `docker` — هر کدام
با یک فرمان نصب یک‌خطی.
## افزودن سرور به‌صورت دستی
اگر سروری در کاتالوگ نیست، از «افزودن دستی» استفاده کن. فرم چهار بخش دارد: **حمل‌ونقل**، **شناسه**،
**اجرا** و **پیشرفته**.
- **فرایند محلی (stdio)** — `command` (مثل `npx`، `uvx`، `docker`)، `args`، متغیرهای محیطی و پوشهٔ کاری.
- **Streamable HTTP** — `url` و در صورت نیاز سرآیندها، مثلاً
`Authorization: Bearer ${secret:GITHUB_TOKEN}`.
- در هر ردیف متغیر محیطی یا سرآیند می‌توانی تیک **راز** را بزنی؛ آن مقدار مستقیم در انبار راز ذخیره
می‌شود و در `servers.json` نمی‌نشیند.
- قاعدهٔ نام‌گذاری: نام سرور باید با `[A-Za-z0-9_-]` نوشته شود و حداکثر ۳۲ نویسه باشد. نام بلندتر یا
نامعتبر **رد** می‌شود (خطای `invalid-server-name`) و هرگز خودکار کوتاه نمی‌شود — چون همین نام در فضای
نام ابزارها می‌آید، و کوتاه‌کردن خودکار یعنی فضای نامی که تو انتخابش نکرده‌ای. اگر نام را خالی بگذاری،
افزونه یکی از روی عنوان می‌سازد.
- اگر نام انتخابی‌ات از قبل روی سرور دیگری باشد، با خطای `duplicate-server-name` رد می‌شود.
- نوع حمل‌ونقل فقط `stdio` یا `streamable-http` است. مقدار ناشناخته با خطای `invalid-transport` رد
می‌شود و به‌جای آن `stdio` فرض نمی‌شود.
- دکمهٔ پایانی **افزودن و اتصال** است: سرور ذخیره و بی‌درنگ سوار می‌شود.
## برون‌ریزی patch
دکمهٔ **برون‌ریزی patch** در سرصفحه، کل وضعیت سرورهای تو را به‌صورت یک بلوک `cordis.patch.yml` می‌سازد
و در یک پنجرهٔ رویی با دکمهٔ **کپی** نشان می‌دهد. کاربردش وقتی است که می‌خواهی افزونه را کنار بگذاری و
سرورها را مستقیم با `@deepseek-ai/dsh-mcp-client` در لایهٔ پروفایل خودت تعریف کنی.
توجه: خود پنل هیچ‌وقت `cordis.patch.yml` را نمی‌نویسد. این دکمه فقط متن می‌سازد.
## تنظیمات پیشرفتهٔ افزونه
اگر لازم شد، می‌توانی رفتار افزونه را در لایهٔ خودت تنظیم کنی. `patch.yml` چهار مقدار زیر را صریحاً
می‌گذارد و `dsh --profile web --dump-config` هم همان‌ها را در ردیف `mcp-studio` نشان می‌دهد.
`storeDir` و `logLinesPerServer` پیش‌فرض خود افزونه‌اند و در `patch.yml` نیامده‌اند:
```yaml
- id: mcp-studio
name: '@mfallah/dsh-mcp-studio'
config:
storeDir: '' # پیش‌فرض: $DSH_HOME/mcp-studio
catalogEnabled: true # جست‌وجو در رجیستری رسمی
registryUrl: https://registry.modelcontextprotocol.io
probeTimeoutMs: 60000 # سقف آزمون اتصال
mountTimeoutMs: 90000 # سقف سوار کردن هر سرور در زمان بالا آمدن
logLinesPerServer: 500 # تعداد خطوط لاگ نگه‌داشته‌شده برای هر سرور
```
این دو مهلت عمداً سخاوتمندانه‌اند: نخستین اجرای یک سرور `npx -y <بسته>` باید بسته را دانلود کند و همین
کار معمولاً از ۱۵ ثانیه رد می‌شود؛ با مهلت تنگ، یک سرور سالم «در دسترس نیست» گزارش می‌شد. اگر سروری
واقعاً کند است، عددها را بالاتر ببر (سقف هر دو ۶۰۰۰۰۰ میلی‌ثانیه است).
## محدودیت‌های شناخته‌شده
- فقط دو گونهٔ انتقال پشتیبانی می‌شود: `stdio` و `streamable-http`. انتقال قدیمی SSE و جریان‌های OAuth
پشتیبانی نمی‌شوند؛ برای سرورهایی که OAuth می‌خواهند باید توکن را خودت به‌صورت راز بدهی.
- اتصال خودکار دوباره وجود ندارد. اگر سروری بعد از وصل شدن بمیرد، در وضعیت خطا می‌ماند تا
«راه‌اندازی دوباره» را بزنی.
- لاگ‌ها فقط در حافظه‌اند و با ریاستارت Harness پاک می‌شوند.
- فهرست رجیستری تا ۵ دقیقه از حافظهٔ نهان خوانده می‌شود؛ برای دیدن نتیجهٔ تازه، کمی صبر کن یا پنل را نو کن.
- پنل سرورها را با نام فضای نام صدا می‌زند؛ اگر ابزار میان‌راهی ثالثی هم‌نام سرور تو باشد، تضاد پیش می‌آید.
---
## English recap
MCP Studio has two tabs plus a header and a detail drawer. **Catalog** browses the 34 bundled offline
entries and the official MCP registry, filters by category/source, and opens an install sheet shaped by
the entry's inputs: fill the form, press **Test connection** (a real instance runs under a temporary
server name), then **Install**. **Installed** lists live rows with a status dot, the namespace
(`mcp____*`), the tool count, an inline last-error line, and per-row actions — enable/disable,
restart, edit (opens the drawer on **Settings**), and delete with an inline confirm. The drawer's tabs are
**Tools**, **Logs** (in-memory, 500 lines per server by default, auto-scrolling, retries while the host is
silent) and **Settings** (title, description, fail-on-startup, per-call timeout, redacted config). The
**secrets** card sits under the Installed tab: names only, add/rotate/delete one at a time. A runtime
banner above the tabs lists any of `node`, `npx`, `npm`, `pnpm`, `bunx`, `uvx`, `python`, `docker` that is
missing, with a one-line install command. **Export patch** renders the current state as a
`cordis.patch.yml` block in a copyable overlay — the panel never writes the file itself. Known gaps: no
SSE/OAuth transports, no automatic reconnection, logs are memory-only, and the registry result is cached
for five minutes.