مستندات توسعه دهندگان

سرور 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 لیست می شود و می توانید باطلش کنید.