مستندات توسعه دهندگان
سرور MCP
MonoRanks از Model Context Protocol پشتیبانی می کند. دستیار را به یک آدرس وصل کنید تا بررسی های شما را بخواند و بر اساسشان کار کند.
Endpoint
https://app.monoranks.com/api/mcp
Streamable HTTP روی POST با پاسخ JSON، بدون session که لازم باشد نگهش دارید. کلید را به شکل Authorization: Bearer mr_ws_… بفرستید (کلید سایت mr_site_… هم کار می کند)، یا بگذارید کلاینت با OAuth 2.1 شما را وارد کند (توضیحش پایین تر آمده). scopeها، سقف ساعتی (1,200 فراخوانی برای هر کلید) و دسترسی صاحب کلید در هر فراخوانی tool چک می شوند، درست مثل REST API.
اتصال
Claude Code
claude mcp add --transport http monoranks https://app.monoranks.com/api/mcp \
--header "Authorization: Bearer mr_ws_…"
Claude.ai و Claude Desktop: آدرس بالا را به عنوان یک custom connector اضافه کنید (تأییدنشده: اسم منوها در این اپ ها زیاد عوض می شود). اگر کلاینت اجازه می دهد header تعیین کنید، کلید را به صورت bearer header بفرستید؛ اگر نه، خودش با OAuth شما را وارد می کند.
ChatGPT و بقیه کلاینت های OAuth: https://app.monoranks.com/api/mcp را به عنوان MCP server اضافه کنید. بدون کلید، endpoint با 401 جواب می دهد و کلاینت را به /.well-known/oauth-protected-resource راهنمایی می کند. کلاینت خودش را ثبت می کند (/api/oauth/register)، شما را برای ورود و تأیید دسترسی می فرستد (/oauth/authorize، با PKCE) و توکنش را از /api/oauth/token می گیرد. فقط می تواند scopeهای خواندن و issues:recheck را بخواهد؛ audits:run و actions:apply هیچ وقت از این راه داده نمی شوند، پس start_audit، toolهای apply و update_outreach_target کلید لازم دارند. جزئیات را در کلیدهای API و scopeها ببینید.
Toolها
خواندن
| Tool | کارش | Scope |
|---|---|---|
list_sites |
سایت هایی که کلید به آن ها دسترسی دارد، با id هرکدام | sites:read |
portfolio |
همه سایت ها در یک درخواست: امتیازها و تغییرشان، مشکل ها، اکشن ها، آخرین بررسی و بررسی بعدی، و کلیک های Search Console (با search:read) |
sites:read |
site_summary |
امتیازها، آخرین بررسی، مشکل های باز، دسترسی WordPress و اینکه داده هر اتصال چقدر تازه است | sites:read |
speed_results |
سرعت هر صفحه تست شده: تست آزمایشگاهی و داده بازدیدکننده های واقعی | sites:read |
audit_status |
آخرین بررسی ها، یا یک بررسی خاص با audit_id، همراه با تعداد صفحه های کراول شده و سقف صفحه |
sites:read |
list_issues |
مشکل ها، همان لیست صفحه Issues | issues:read |
issue_detail |
یک مشکل با صفحه ها، شواهد، توضیح و مقدارهای جدید پیشنهادی (هر بار 100 مورد، برای بقیه suggestions_offset) |
issues:read |
list_actions |
اکشن ها به ترتیب اولویت، با افزایش تخمینی امتیاز و مدتی که هرکدام باز مانده | issues:read |
page_findings |
یافته های یک صفحه، با id یا آدرس صفحه | pages:read |
page_history |
چه چیزی در یک صفحه از یک بررسی یا بررسی دوباره تا بعدی عوض شده، با id یا آدرس صفحه | pages:read |
search_summary |
جمع آمار Search Console، صفحه ها و عبارت های جست وجوی برتر | search:read |
search_rows |
ردیف های Search Console در یک بازه تاریخ، به تفکیک عبارت جست وجو، صفحه، عبارت و صفحه با هم، یا روز (nextCursor را به عنوان cursor برگردانید؛ خروجی CSV فقط در REST API هست) |
search:read |
near_page_one |
جفت های عبارت جست وجو و صفحه ی شما که درست پایین صفحه اول هستند (به طور پیش فرض رتبه 8 تا 20)، با بیشترین نمایش در اول، و کلیک اضافه ای که رتبه سه اول می آورد | search:read |
topics |
صفحه های سایت که در موضوع ها دسته بندی شده اند، با کلیک، عبارت های جست وجوی برتر و اینکه هر موضوع قوی است، ضعیف است یا کلیکی ندارد | search:read |
analytics_pages |
تبدیل ها و درآمد هر صفحه ورود از Google Analytics (GA4)، کنار کلیک های Search Console | analytics:read |
keywords |
کلمات کلیدی همان طور که در صفحه Keywords هستند، با حجم جست وجو، رتبه، فرصت و بررسی ارتباط با موضوع سایت؛ پیشنهادهای بی ربط حذف شده اند | search:read |
competitors |
رقبا با امتیاز تطابق، نتیجه بررسی هوش مصنوعی برای هر پیشنهاد، اینکه کدام ها مبنای شکاف ها هستند، کلمات کلیدی مشترک، کلمه هایی که در آن ها بالاتر از شما هستند، قدرت دامنه و دیده شدن | search:read |
competitor_gaps |
رتبه هر رقیب و رتبه شما برای هر کلمه کلیدی (gaps، content، lost، lead). هر ردیف صفحه ای را هم که هر رقیب با آن رتبه گرفته نشان می دهد. | search:read |
content_ideas |
شکاف های کلمه کلیدی که در موضوع ها دسته بندی شده اند، با بیشترین فرصت در اول: اینکه صفحه تازه لازم است یا باید صفحه ای را کامل تر کرد، صفحه های شما که در آن موضوع هستند، صفحه های رقبا که رتبه دارند و کلمات کلیدی اصلی | search:read |
backlinks |
خلاصه بک لینک ها و دامنه های ارجاع دهنده یک نما (all، new، lost، review، strong) | search:read |
list_outreach_targets |
صفحه ها و سایت هایی که ارزش دارد از آن ها لینک یا منشن بخواهید، به ترتیب امتیاز، با دلیل و وضعیتشان | search:read |
ai_visibility |
دستیارهای هوش مصنوعی هر هفته به سؤال هایی که دنبال می کنید چه جوابی داده اند، با صفحه هایی که هر جواب به آن ها ارجاع داده | ai:read |
answer_gaps |
سؤال هایی که در جواب هوش مصنوعی اسم سایت های دیگر می آید، ولی اسم سایت شما نه | ai:read |
geo_access |
دسترسی خزنده های هوش مصنوعی، وضعیت llms.txt و سیگنال های هویت برند و آمادگی برای ایجنت ها از آخرین بررسی | ai:read |
llms_txt |
فایل llms.txt فعلی سایت و یک پیش نویس آماده انتشار | ai:read |
ai_crawler_rules |
robots.txt همین الان به هر خزنده هوش مصنوعی چه می گوید | ai:read |
agentic_results |
نتیجه های Agentic browsing همراه با کارهایی که باید درست شوند، یا یک اجرای دوباره خاص با job_id |
ai:read |
انجام کار
| Tool | کارش | Scope |
|---|---|---|
recheck |
بررسی دوباره یک مشکل را در صف می گذارد | issues:recheck |
run_agentic_check |
تست Agentic browsing را برای یک صفحه دوباره اجرا می کند | issues:recheck |
start_audit |
همین حالا یک بررسی کامل شروع می کند، با سقف صفحه اختیاری | audits:run |
apply |
عنوان سئو، توضیحات متا، canonical یا noindex جدید یک اکشن را تأیید می کند و در WordPress می نویسد | actions:apply |
apply_llms_txt |
یک llms.txt جدید را تأیید می کند و در WordPress می نویسد | actions:apply |
apply_ai_crawler_rules |
قوانین allow یا deny برای خزنده های هوش مصنوعی را تأیید می کند و در robots.txt می نویسد | actions:apply |
update_competitors |
یک رقیب را انتخاب می کند، کنار می گذارد یا اضافه می کند؛ انتخاب یا اضافه کردن، شکاف کلمات کلیدی اش را داخل سقف داده شما می گیرد | actions:apply |
update_outreach_target |
وضعیت (to contact، contacted، added، declined) و یادداشت یک مورد جذب لینک را تعیین می کند | actions:apply |
نمونه گفت وگو
«کدام سایتم این ماه بیشتر از بقیه کلیک از دست داده، و مهم ترین اکشن برایش چیست؟»
دستیار یک بار portfolio را صدا می زند، سایتی را که بیشترین افت را داشته پیدا می کند، بعد list_actions را برای همان سایت صدا می زند و اکشن اول را با افزایش تخمینی امتیازش جواب می دهد. اگر بگویید «اعمالش کن»، مقدارهای پیشنهادی را با issue_detail می خواند و apply را صدا می زند. تغییر هم در بخش فعالیت های اپ، همراه با دکمه Undo، نمایش داده می شود.
سؤال های رایج
با کدام کلاینت ها کار می کند؟
با هر کلاینتی که MCP روی Streamable HTTP را پشتیبانی کند: Claude Code، Claude.ai، Claude Desktop، ChatGPT (connectorهای developer mode)، Cursor، Windsurf و بقیه.
ممکن است دستیار سایتم را خراب کند؟
فقط سه tool سایت شما را تغییر می دهند: apply، apply_llms_txt و apply_ai_crawler_rules. این ها دقیقاً همان قوانین دکمه های اپ را دارند: فقط روی سایت های WordPress متصل کار می کنند، صاحب کلید به عنوان تأییدکننده ثبت می شود، بعد از تغییر یک بررسی انجام می شود و تا 30 روز می توانید در اپ با Undo برش گردانید. recheck، run_agentic_check و start_audit فقط سایت شما را دوباره می خوانند. update_outreach_target و update_competitors هم فقط داده های داخل MonoRanks را عوض می کنند: وضعیت و یادداشت یک مورد، یا اینکه کدام رقبا را دنبال می کنید.
چرا ChatGPT کلید لازم ندارد؟
کلاینت هایی که خودشان روش ورود را پیدا می کنند از OAuth 2.1 استفاده می کنند: شما را به صفحه ورود می فرستند تا یک بار دسترسی را تأیید کنید، و اگر غیر از سایت های خودتان جای دیگری هم دارید، می پرسند کجا وصل شوند. توکنی که می گیرند نماینده یک کلید فضای کاری است با scopeهای خواندن و بررسی دوباره که تأیید کرده اید؛ هیچ وقت شروع بررسی کامل یا نوشتن را ندارد. این کلید در Settings → Developer access لیست می شود و می توانید باطلش کنید.