# رابط MCP

## نمای کلی

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](/fa/docs/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`

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

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

توکن‌ها را در پرامپت‌ها، تاریخچهٔ گفتگو، فایل‌های کد منبع یا لاگ‌ها کپی نکنید. آن‌ها را فقط در محل نگهداری اعتبارنامهٔ کلاینت 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` و مرز پایگاه دادهٔ آن اعمال می‌شوند.

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

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

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

## محدودیت‌ها

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

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

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

نشانی‌های میزبانی‌شدهٔ بالا فقط برای سرویس مدیریت‌شدهٔ Expense Budget Tracker هستند. برای استقرار خودتان، از [راهنمای میزبانی شخصی](/fa/docs/self-hosting/) شروع کنید و نقطهٔ اتصال MCP و فرادادهٔ OAuth را برای دامنه‌های خود پیکربندی کنید. پیاده‌سازی در [مخزن کد منبع](https://github.com/kirill-markin/expense-budget-tracker) موجود است.

---
*[نسخه HTML این صفحه را ببینید](https://expense-budget-tracker.com/fa/docs/mcp-connector/)*

*کلاینت‌های راه‌دور MCP سازگار با OAuth می‌توانند به این نشانی متصل شوند `https://mcp.expense-budget-tracker.com/mcp` با دسترسی OAuth Bearer. مجوز الزامی `expenses:read` است. کلاینت همچنین می‌تواند مجوز اختیاری `expenses:write` را درخواست کند؛ این مجوز در صفحه رضایت OAuth نمایش داده می‌شود و برای تغییر داده‌ها لازم است.*

*ایجنت‌های خط فرمان و HTTP مستقیم می‌توانند با شروع از این نشانی از Agent API جداگانه استفاده کنند `GET https://api.expense-budget-tracker.com/v1/` و برای دریافت ApiKey پاسخ شناسایی سرویس را دنبال کنند.*

*نکته: برای دریافت نسخه Markdown تمیز هر صفحه، `.md` را به هر آدرس این سایت اضافه کنید.*