نمای کلی

Expense Budget Tracker یک رابط میزبانی‌شدهٔ Model Context Protocol (MCP) در این نشانی ارائه می‌کند:

https://mcp.expense-budget-tracker.com/mcp

این نقطهٔ اتصال از Streamable HTTP و OAuth استفاده می‌کند. این نشانی را به کلاینت MCP بدهید که از سرورهای راه دور Streamable HTTP و کشف OAuth پشتیبانی می‌کند. جریان مجوزدهی، مرورگر را باز می‌کند تا وارد حساب شوید و دسترسی را تأیید کنید.

این رابط از کلید API استفاده نمی‌کند. توکن‌های دسترسی و نوسازی OAuth اعتبارنامه‌های MCP هستند. ApiKey بلندمدتی که در مرجع Agent API توضیح داده شده است به یک یکپارچه‌سازی مستقیم و جداگانهٔ HTTP تعلق دارد و نقطهٔ اتصال MCP آن را نمی‌پذیرد.

کشف OAuth و اتصال

رابط میزبانی‌شده فرادادهٔ منبع محافظت‌شده را در این نشانی منتشر می‌کند:

https://mcp.expense-budget-tracker.com/.well-known/oauth-protected-resource/mcp

این فراداده کلاینت را به سرور مجوزدهی هدایت می‌کند. فرادادهٔ آن سرور در این نشانی در دسترس است:

https://auth.expense-budget-tracker.com/.well-known/oauth-authorization-server

یک کلاینت سازگار این مراحل را دنبال می‌کند:

به https://mcp.expense-budget-tracker.com/mcp متصل می‌شود و فرادادهٔ منبع محافظت‌شده را پیدا می‌کند.
به‌صورت پویا به‌عنوان یک کلاینت عمومی OAuth ثبت می‌شود. از رمز کلاینت استفاده نمی‌شود.
جریان Authorization Code را شروع می‌کند و نشانی مجوزدهی را در مرورگر کاربر باز می‌کند.
برای هر درخواست مجوزدهی از PKCE استفاده می‌کند. تنها روش پشتیبانی‌شده برای code challenge، مقدار S256 است.
دامنهٔ expenses:read را درخواست می‌کند. فقط زمانی expenses:write را اضافه می‌کند که به فراخوانی sql_execute نیاز باشد.
کد مجوز را با توکن‌های دسترسی و نوسازی مبادله می‌کند و سپس در صورت نیاز دسترسی را نوسازی می‌کند.

توکن‌ها را در پرامپت‌ها، تاریخچهٔ گفتگو، فایل‌های کد منبع یا لاگ‌ها کپی نکنید. آن‌ها را فقط در محل نگهداری اعتبارنامهٔ کلاینت MCP ذخیره کنید.

دامنه‌های دسترسی

expenses:read الزامی است. این دامنه کشف فضاهای کاری، مشاهدهٔ اسکیما و اجرای کوئری‌های فقط‌خواندنی را ممکن می‌کند.
expenses:write اختیاری است. این دامنه به‌طور جداگانه ابزار تخریبی sql_execute را مجاز می‌کند.

کوچک‌ترین مجموعهٔ دامنه‌های لازم برای کار را درخواست کنید. کلاینتی که فقط داده‌ها را تحلیل یا گزارش می‌کند باید expenses:read را بدون expenses:write درخواست کند.

ابزارها

`list_workspaces`

فضاهای کاری در دسترس کاربر واردشده را فهرست می‌کند. پیش از خواندن یا تغییر داده‌ها، با شناسهٔ بازگشتی مقصد را به‌صورت صریح مشخص کنید.

`get_schema`

رابطه‌ها و ستون‌هایی را برمی‌گرداند که MCP برای فضای کاری انتخاب‌شده در دسترس قرار می‌دهد. پیش از نوشتن SQL آن را فراخوانی کنید و نام جدول‌ها یا ستون‌ها را حدس نزنید.

`sql_query`

یک کوئری SQL محدود و فقط‌خواندنی را در فضای کاری انتخاب‌شده اجرا می‌کند. مسیر کوئری علاوه بر این با یک مرز فقط‌خواندنی در پایگاه داده محافظت می‌شود. نتیجه حداکثر ۱۰۰ ردیف دارد و مهلت اجرا ۲۰ ثانیه است.

`sql_execute`

SQL محدودی را اجرا می‌کند که داده‌های فضای کاری انتخاب‌شده را تغییر می‌دهد. این ابزار تخریبی است و به دامنهٔ جداگانهٔ expenses:write نیاز دارد. پیش از تأیید فراخوانی، فضای کاری و عبارت دقیق را بررسی کنید.

کل سرور MCP فقط‌خواندنی نیست، زیرا sql_execute را ارائه می‌کند. تضمین‌های فقط‌خواندنی مشخصاً برای sql_query و مرز پایگاه دادهٔ آن اعمال می‌شوند.

استفادهٔ ایمن

list_workspaces را فراخوانی کنید و فضای کاری موردنظر را با کاربر تأیید کنید.
پیش از تولید SQL، ابزار get_schema را فراخوانی کنید.
برای بررسی، جمع‌بندی، تطبیق و گزارش از sql_query استفاده کنید.
فقط برای کاری که باید داده‌ها را تغییر دهد، expenses:write را درخواست کنید.
پیش از sql_execute، عبارت دقیق و اثر مورد انتظار آن را نمایش دهید و سپس فضای کاری را دوباره تأیید کنید.
پس از نوشتن، نتیجه را با sql_query بررسی کنید.

سرور سطح SQL و رابطه‌های در دسترس را محدود می‌کند. این کنترل‌ها مکمل بررسی دقیق SQL تولیدشده هستند، نه جایگزین آن.

محدودیت‌ها

حداکثر ۱۰۰ ردیف در نتایج SQL
مهلت اجرای ۲۰ ثانیه‌ای
دسترسی فقط به فضاهای کاری در دسترس کاربر واردشده
sql_query از سطح محدود SQL و مرز فقط‌خواندنی پایگاه داده استفاده می‌کند
sql_execute افزون بر دامنهٔ خواندن الزامی به expenses:write نیاز دارد

حریم خصوصی و میزبانی شخصی

یک کلاینت MCP مجاز می‌تواند داده‌های مالی را بخواند و با expenses:write آن‌ها را تغییر دهد. پیش از اتصال، سیاست حفظ حریم خصوصی و سیاست پردازش دادهٔ خود کلاینت را بررسی کنید.

نشانی‌های میزبانی‌شدهٔ بالا فقط برای سرویس مدیریت‌شدهٔ Expense Budget Tracker هستند. برای استقرار خودتان، از راهنمای میزبانی شخصی شروع کنید و نقطهٔ اتصال MCP و فرادادهٔ OAuth را برای دامنه‌های خود پیکربندی کنید. پیاده‌سازی در مخزن کد منبع موجود است.